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

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/feat/server_team/sdk/memory-core/typescript/src/v3/metadata-types.ts):

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/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/feat/server_team/sdk/memory-core/typescript/src/v3/metadata-types.ts):

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/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/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:

// 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:

// 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:

// 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}