# How to Implement Access Control with Private, Team, and Restricted Visibility Levels in TencentDB Agent Memory

> Learn to implement access control in TencentDB Agent Memory using private, team, and restricted visibility levels. Secure your data with this team-centric ACL model.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-26

---

**TencentDB Agent Memory enforces data isolation through a team-centric ACL model where every logical object carries an `AssetVisibility` field—supporting `private`, `team`, and `restricted` levels—to determine read and write permissions based on team membership and explicit whitelists.**

The TencentDB-Agent-Memory repository provides a type-safe framework for securing AI agent assets through granular access controls. When you implement access control with private, team, and restricted visibility levels, you configure the `AssetVisibility` enum and optional ACL lists to govern who can access knowledge bases, skills, and other digital resources.

## Understanding the AssetVisibility Enum

The visibility classification system is defined in [[`sdk/memory-core/typescript/src/v3/metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/metadata-types.ts):

```typescript
export type AssetVisibility = "private" | "team" | "restricted" | "agent" | "task";

```

This enum supports five distinct isolation levels:

- **`private`**: Only members of the owning team may access the object.
- **`team`**: All members of the team (including sub-teams) can view and modify the object.
- **`restricted`**: Access is limited to a specific whitelist of **ACL subjects** (users, team roles, or agents).
- **`agent`**: Visible only to the specific owning agent.
- **`task`**: Visible only within the lifecycle of a specific task.

For team-based collaboration, the `private`, `team`, and `restricted` levels form the core access control matrix that prevents unauthorized cross-team data leakage.

## Core Access Control Flow

The SDK and server coordinate to enforce permissions through four validation stages.

### Team Identification

Every request that manipulates an object must include the `team_id`. The SDK injects this automatically from the client configuration via the `SkillClient` constructor in [[`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts).

### ACL Subject Types

The system recognizes three subject classes for fine-grained permissions, declared in [[`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/metadata-types.ts):

```typescript
export type AclSubjectType = "user" | "team_role" | "agent";

```

### Server-Side Enforcement

The request handler extracts the object's `visibility` field. For `restricted` assets, the server looks up the attached **ACL list** and verifies that the caller's subject (derived from the authentication token) matches an entry. For `private` and `team` visibility, the handler validates that the caller is a member of the supplied `team_id`.

### SDK Validation

Before transmitting requests, the SDK validates that mandatory isolation fields (`team_id`, `agent_id`, `user_id`) are present via `validateRequiredStrings` in [[`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts). This prevents malformed calls that could bypass ACL checks.

## Implementing Private Team Access

A **private team** isolates assets by defaulting new objects to `visibility: "private"`. According to the API documentation in [[`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/v3-api-memorycore-doc.md), the default visibility for newly created teams is `"private"`.

First, create the team and add members:

```typescript
// Create a new team with private isolation
await client.createTeam({
  team_id: "team-42",
  name: "Secret Research",
  description: "Only internal members may view",
});

// Add members who can access this team's private assets
await client.addTeamMember({
  team_id: "team-42",
  user_id: "alice",
  role: "member",
});
await client.addTeamMember({
  team_id: "team-42",
  user_id: "bob",
  role: "member",
});

```

All assets created with `team_id: "team-42"` automatically inherit the `private` restriction, limiting access to Alice and Bob only.

## Implementing Restricted Visibility Levels

When you need to share an asset with only a subset of team members (such as a confidential report), set the visibility to `"restricted"` and provide an explicit ACL list:

```typescript
// Create an asset with restricted visibility
await client.createKnowledge({
  knowledge_id: "confidential-doc-001",
  team_id: "team-42",
  visibility: "restricted",
  acl: [
    { subject_type: "user", subject_id: "alice" },
    { subject_type: "team_role", subject_id: "admin" }
  ],
  content: "Top-secret design details …"
});

```

The server stores the ACL array and validates every read or write request against this whitelist. To modify access later, update the ACL explicitly:

```typescript
// Add Charlie to the access list
await client.updateKnowledgeAcl({
  knowledge_id: "confidential-doc-001",
  team_id: "team-42",
  acl: [
    { subject_type: "user", subject_id: "alice" },
    { subject_type: "user", subject_id: "charlie" },
    { subject_type: "team_role", subject_id: "admin" }
  ],
});

```

## Summary

- **Team-centric isolation**: Every asset requires a `team_id` that the SDK injects automatically via the `SkillClient` constructor.
- **Five visibility levels**: The `AssetVisibility` enum in [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts) supports `private`, `team`, `restricted`, `agent`, and `task` isolation.
- **Default private teams**: New teams default to `private` visibility, requiring explicit membership management through `addTeamMember`.
- **Explicit ACLs**: The `restricted` level uses an `acl` array containing `AclSubjectType` entries to whitelist specific users, roles, or agents.
- **Double validation**: The SDK validates required fields client-side via `validateRequiredStrings`, while the server enforces permissions by matching caller subjects against ACL lists or team membership.

## Frequently Asked Questions

### What is the difference between private and restricted visibility in TencentDB Agent Memory?

**Private** visibility grants access to all current and future members of the owning team, while **restricted** visibility limits access to a specific whitelist of subjects defined in the asset's `acl` array. Use `private` for internal team resources and `restricted` for confidential assets that only specific users or roles should access.

### How does the SDK enforce team isolation automatically?

The `SkillClient` class constructor in [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts) extracts the `teamId` from the client configuration and injects it into every request. The `validateRequiredStrings` method ensures that `team_id` and other mandatory isolation identifiers are present before the request reaches the server, preventing malformed calls that could bypass access controls.

### Can I change an asset's visibility from private to restricted after creation?

Yes. You can update an asset's visibility field using the appropriate update method (such as `updateKnowledge` or `updateKnowledgeAcl`). When changing to `restricted`, you must provide a valid `acl` array containing at least one entry; otherwise, the server will reject the request to prevent accidental lockout.

### What happens if I omit the team_id when creating an asset?

The SDK's `validateRequiredStrings` function in [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts) will throw a validation error before the request is transmitted. If somehow bypassed, the server would reject the request because the access control logic requires a `team_id` to determine whether the caller belongs to the owning team or matches a restricted ACL entry.