How to Manage Team Roles and Permissions in TencentDB Agent Memory

TencentDB Agent Memory implements a fine-grained role-based access control (RBAC) system that defines three distinct TeamRole levels (admin, member, reviewer) and six Permission types, enforcing access through ACL rules stored in the metadata service.

Managing team roles and permissions in TencentDB Agent Memory relies on a type-safe RBAC model defined in the TypeScript SDK's metadata definitions. The system distinguishes between role assignment (who belongs to a team) and permission grants (what actions users can perform on specific assets), with all enforcement handled by the V3 metadata service according to the logic implemented in TencentCloud/TencentDB-Agent-Memory.

Understanding the RBAC Type System

The foundation of access control resides in sdk/memory-core/typescript/src/v3/metadata-types.ts, which exports the enums and interfaces used across the platform's security layer.

TeamRole and Permission Definitions

According to the source code at line 8 of metadata-types.ts, the TeamRole enum restricts users to one of three hierarchical levels:

• admin: Full team management capabilities, including role assignment
• member: Standard participation rights for collaboration
• reviewer: Read-only access with evaluation privileges

The Permission enum (line 17) defines six possible actions: read, write, delete, assign, share, and use. These permissions are not assigned directly to users; instead, they are bound to assets through Access Control Lists (ACLs) that reference these enum values.

ACL Subject Types and Entities

Line 18 of metadata-types.ts defines AclSubjectType, which determines the scope of an ACL rule. A subject can be a concrete user ID, a team role (applying to all members holding that role), or an agent entity.

The TeamMemberEntity interface (line 103) represents the database record linking users to teams, storing the assigned TeamRole alongside membership metadata. This entity is the source of truth for the metadata service when resolving a caller's effective privileges.

Managing Team Members

Team lifecycle operations flow through the V3 REST API, with SDK methods in client.ts and client.py providing typed wrappers around these endpoints.

Creating Teams and Assigning Initial Roles

When you invoke client.createTeam(), the authenticated caller automatically receives the admin role for that team. To onboard additional users, call addTeamMember with the role parameter set to your desired TeamRole value.

// Create a team - creator becomes admin automatically
const team = await client.createTeam({
  name: "Analytics Team",
  description: "Team for data-driven insights",
});
console.log(`Team created, ID = ${team.team_id}`);

// Add a member with specific role
await client.addTeamMember({
  team_id: team.team_id,
  user_id: "u-12345",
  role: "member",  // Valid options: admin | member | reviewer
});

Python implementation using the generated client:

# Create a team

team = client.create_team(name="Analytics Team", description="Data-driven insights")

# Add a member as a reviewer

client.add_team_member(
    team_id=team.team_id,
    user_id="u-12345",
    role="reviewer"
)

Updating Member Roles

Role modifications require the caller to hold the admin role. The updateTeamMember method (wrapping PATCH /team/member/{id}) modifies the TeamMemberEntity.role property in the metadata store.

// Promote a member to admin - requires caller to be admin
await client.updateTeamMember({
  member_id: "tm-67890",
  role: "admin",
});

# Promote to admin

client.update_team_member(member_id="tm-67890", role="admin")

Configuring Asset-Level Permissions

While role management controls team membership, permission management occurs through ACL entries attached to assets such as skills, agents, or code graphs. The metadata service persists these rules and evaluates them against incoming requests.

Granting Permissions via ACL Rules

Use updateAssetAcl to bind permissions to subjects. Setting subject_type to "team_role" applies the rule broadly to all members holding that role, as implemented in the V3 endpoints defined in openapi.yaml.

await client.updateAssetAcl({
  asset_id: "skill-abcde",
  acl: [
    {
      subject_type: "team_role",
      subject_id: "member",
      permission: "read",
      effect: "allow",
    },
    {
      subject_type: "team_role",
      subject_id: "admin",
      permission: "write",
      effect: "allow",
    },
  ],
});

Python equivalent:

client.update_asset_acl(
    asset_id="codegraph-xyz",
    acl=[
        {
            "subject_type": "team_role",
            "subject_id": "member",
            "permission": "read",
            "effect": "allow",
        },
        {
            "subject_type": "team_role",
            "subject_id": "admin",
            "permission": "write",
            "effect": "allow",
        },
    ],
)

Server-Side Validation Flow

When a request reaches the metadata service, the core server performs a three-step validation process:

1. Role Resolution: Retrieves the caller's TeamRole from TeamMemberEntity records for the target team
2. ACL Retrieval: Fetches ACL entries matching the requested asset and AclSubjectType (user, team role, or agent)
3. Effect Evaluation: Checks if the requested Permission is present with an allow effect and no overriding deny effect

If the caller lacks the required permission, the server returns HTTP 403 Forbidden. This enforcement applies uniformly across all V3 endpoints, ensuring that both SDK calls and direct REST API usage adhere to the same security policies defined in the source type definitions.

Summary

• TeamRole hierarchy: The system supports admin, member, and reviewer roles defined in metadata-types.ts (line 8), with no implicit permissions attached to these labels by default
• Permission granularity: Six distinct permissions (read, write, delete, assign, share, use) control asset access (line 17) and must be explicitly granted via ACLs
• Role assignment: Use addTeamMember and updateTeamMember (wrapping POST /team/member/add and PATCH /team/member/{id}) to manage team composition; only admins can modify existing member roles
• Permission grants: Configure ACL rules via updateAssetAcl, binding Permission values to AclSubjectType targets to enforce fine-grained access control
• Enforcement: The metadata service validates every request against the caller's resolved role and asset ACLs, returning 403 for unauthorized operations

Frequently Asked Questions

What are the default permissions for each TeamRole in TencentDB Agent Memory?

The RBAC system does not hard-code implicit permissions for roles. Instead, admin, member, and reviewer function as labels used in ACL rules. By default, new assets have no ACL entries, meaning only the creating user (implicitly granted admin rights) can access them until explicit allow rules are created for specific TeamRole values in the metadata store.

Can a user hold different roles in different teams?

Yes. The TeamMemberEntity structure (line 103 in metadata-types.ts) binds a TeamRole to a specific team membership record. A user can be an admin in one team and a reviewer in another, with the server resolving the appropriate role context based on the team ID present in the request path.

How do I restrict a specific agent from accessing an asset while allowing team members?

Set the subject_type to "agent" in the ACL entry with an effect of "deny" for that specific agent ID, while maintaining allow entries for team_role subjects. The server evaluates deny rules before allow rules, ensuring the explicit restriction takes precedence over role-based grants defined in the metadata service.

Where are the OpenAPI specifications for team management endpoints located?

The REST API contracts are defined in MemoryKnowledge/openapi.yaml at the repository root. This file describes the HTTP endpoints for POST /team/member/add, PATCH /team/member/{id}, and ACL management operations that the TypeScript and Python SDKs wrap with methods like addTeamMember and updateAssetAcl.

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