How to Implement Custom Memory Isolation with teamId, agentId, and userId in TencentDB Agent Memory

Isolate memory contexts in TencentDB Agent Memory by initializing SkillClient with team_id, agent_id, and user_id defaults, which are automatically merged into every API request and validated before execution.

TencentDB-Agent-Memory enforces strict memory isolation through a four‑tuple identifier system comprising team, agent, user, and optional task scopes. The Python SDK implements this through _SkillDefaults container and per‑call merging logic in skill_client.py, ensuring each conversation and memory segment remains partitioned by tenant and identity boundaries. Understanding how to configure these isolation identifiers at client initialization—and when to override them per request—is essential for building secure multi‑tenant agent applications.

Understanding the Isolation Identifier Model

The TencentDB Agent Memory service isolates every request using a mandatory three‑field tuple plus optional extensions. According to the source code in tencentdb_agent_memory/v3/skill_client.py, the system requires:

• team_id: The organizational or tenant identifier
• agent_id: The specific agent or service instance identifier
• user_id: The end‑user identity
• task_id (optional): Session or task‑specific scoping

These fields form the boundary that prevents memory leakage between different teams, agents, or users sharing the same memory service endpoint.

Configuring Global Defaults with _SkillDefaults

The SDK encapsulates isolation defaults within the _SkillDefaults internal container. Located at lines 85–102 in skill_client.py, this class stores the identifiers passed during SkillClient construction.

When you instantiate the client, these values become the default context for every subsequent operation:

from tencentdb_agent_memory.v3 import SkillClient

client = SkillClient(
    endpoint="https://memory.tencentyun.com",
    api_key="sk-...",
    service_id="mem-abc",
    team_id="team-42",      # Global team isolation

    agent_id="agent-dev",   # Global agent isolation

    user_id="user-alice",   # Global user isolation

)

As implemented in _SkillClient.__init__ (lines 167–188), these keyword arguments populate the internal _SkillDefaults instance, ensuring the team_id, agent_id, and user_id propagate to all API calls unless explicitly overridden.

Merging Per‑Call Overrides

The merge method (lines 103–115 in skill_client.py) combines the stored defaults with per‑call keyword arguments. This mechanism allows temporary context switching without reconstructing the client.

Default behavior: Uses the identifiers supplied at initialization.

Override behavior: Pass explicit identifiers to any method call to replace defaults for that single request.

# Uses default team_id="team-42", agent_id="agent-dev", user_id="user-alice"

skill = client.create(
    name="global-skill",
    content="---\nname: global-skill\n---\n# shared content\n"

)

# Overrides user_id only for this specific call

skill = client.create(
    name="user-specific-skill",
    content="---\nname: user-specific-skill\n---\n# private content\n",

    user_id="user-bob"  # Temporarily switches to Bob's isolation context

)

The merge method produces a dictionary that injects the final isolation values into the HTTP request body sent via _v3_http.py.

Validation Requirements for Isolation Fields

The SDK validates isolation completeness before transmitting requests. Two distinct validation patterns exist in skill_client.py:

Extraction Validation

The _validate_extract method (lines 61–70) requires non‑empty team_id, agent_id, and user_id for memory extraction operations. If any identifier is missing or empty, the SDK raises ParamError (defined in errors.py) before the HTTP request is dispatched.

Force‑Archive Validation

The conversation_force_archive endpoint implements stricter validation in _validate_force_archive (lines 72–81). This operation requires all five fields:

• session_id
• space_id
• team_id
• agent_id
• user_id

Unlike other endpoints, conversation_force_archive does not treat these as optional defaults; they must be present either in the global defaults or the per‑call arguments.

# Valid call using global defaults for team/agent/user

client.conversation_force_archive(
    session_id="sess-001",
    space_id="space-01",
    # team_id, agent_id, user_id inherited from client defaults

)

Implementation Architecture and Key Files

The isolation mechanism spans several core files in the TencentDB-Agent-Memory SDK:

File	Purpose	Key Components
skill_client.py	Core client for /v3/skill/* endpoints	_SkillDefaults, merge(), validation methods
metadata_client.py	Metadata API client	Parallel isolation handling for metadata operations
_http.py / _v3_http.py	Low‑level transport	Transports isolation payload in request bodies
errors.py	Exception definitions	ParamError raised for missing isolation fields

Summary

• Initialize once: Set team_id, agent_id, and user_id when constructing SkillClient to establish global isolation defaults.
• Override strategically: Pass identifiers to individual method calls to temporarily switch contexts without creating new client instances.
• Validate carefully: Ensure extract operations have the three core identifiers, while conversation_force_archive requires all five fields including session_id and space_id.
• Source locations: _SkillDefaults and merge() logic reside in skill_client.py lines 85–115; validation occurs in lines 61–81.

Frequently Asked Questions

What happens if I omit team_id or user_id when creating a SkillClient?

The SDK will raise ParamError from errors.py during the first API call that requires isolation validation. According to _validate_extract in lines 61–70 of skill_client.py, team_id, agent_id, and user_id are mandatory for memory extraction operations.

Can I isolate memory by task_id alone without specifying team_id?

No. The TencentDB-Agent-Memory source code treats team_id, agent_id, and user_id as mandatory isolation fields. While task_id is supported for additional granularity, it cannot replace the three‑tuple requirement enforced in the validation methods.

How does conversation_force_archive differ from other endpoints regarding isolation?

The conversation_force_archive method requires explicit validation of all five identifiers: session_id, space_id, team_id, agent_id, and user_id. As implemented in lines 72–81 of skill_client.py, this endpoint validates the complete set of isolation fields, whereas other endpoints may only require the core three‑tuple.

Is it possible to switch team contexts for a single API call without affecting the global client?

Yes. The merge method (lines 103–115) combines your global _SkillDefaults with per‑call arguments. Simply pass team_id="different-team" to any method like create() or extract(), and that specific request will use the overridden value while the client retains the original defaults for future calls.

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