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

> Implement custom memory isolation in TencentDB Agent Memory using teamId, agentId, and userId. Learn how to initialize SkillClient for secure API requests.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```python
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.

```python

# 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/_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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.

```python

# 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill_client.py) | Core client for `/v3/skill/*` endpoints | `_SkillDefaults`, `merge()`, validation methods |
| [`metadata_client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata_client.py) | Metadata API client | Parallel isolation handling for metadata operations |
| [`_http.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/_http.py) / [`_v3_http.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/_v3_http.py) | Low‑level transport | Transports isolation payload in request bodies |
| [`errors.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/errors.py) during the first API call that requires isolation validation. According to `_validate_extract` in lines 61–70 of [`skill_client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.