# Isolation Context Fields (teamId, agentId, userId, sessionId, taskId) in the TencentDB Agent Memory v3 SDK

> Understand IsolationContext fields like teamId, agentId, userId, and sessionId in the TencentDB Agent Memory v3 SDK. Learn how these fields enforce multi-dimensional tenancy and enhance data filtering for your applications.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-31

---

**The v3 SDK uses an IsolationContext to enforce multi-dimensional tenancy for all L0/L1/Profile data, requiring `userId`, `agentId`, and `sessionId` as mandatory fields while treating `teamId` and `taskId` as optional dimensions for additional filtering.**

The **Isolation Context** is the cornerstone of data separation in the TencentDB Agent Memory v3 SDK. Every write operation to conversational memory (L0), extracted records (L1), or user profiles must carry a complete context that binds the data to specific organizational boundaries. This article explains each field's purpose, validation rules, and practical usage patterns based on the actual source implementation.

## Core IsolationContext Fields Explained

The `IsolationContext` interface in [[`MemoryCore/src/core/store/isolation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/isolation.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/isolation.ts#L25-L31) defines five primary identifier fields that establish a three-dimensional tenancy model:

| Field | Type | Purpose | Required |
|-------|------|---------|----------|
| `teamId` | `string` | Organizational boundary for multi-team deployments | Optional |
| `userId` | `string` | End-user who generated the interaction data | **Yes** |
| `agentId` | `string` | Agent or service processing the request | **Yes** |
| `sessionId` | `string` | Unique conversation token grouping related exchanges | **Yes** |
| `taskId` | `string` | Cross-session business identifier (e.g., support ticket) | Optional |

The `userId`, `agentId`, and `sessionId` combination creates the fundamental isolation boundary. The `sessionId` is particularly critical because all L1 extraction operations in the v3 SDK are session-based—omitting this field breaks the memory chaining mechanism.

## Optional Dimensions: teamId and taskId

### teamId

The `teamId` field enables **multi-tenant deployments** where a single memory store serves multiple organizational units. When provided, it adds an additional filter layer to all data operations. The field accepts any string identifier and integrates cleanly with enterprise identity systems.

### taskId

Unlike `sessionId`, which is ephemeral and conversation-scoped, `taskId` serves as a **persistent business identifier** that can span multiple sessions. Use this field when you need to correlate memory records across separate conversations—for example, tracking a multi-day support ticket or a long-running workflow. The `taskId` never substitutes for `sessionId`; both can coexist in the same context.

## Validation with assertIsolation

The SDK validates isolation contexts through the [`assertIsolation`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/isolation.ts#L73-L99) function. This utility enforces field requirements and normalizes missing values when legacy compatibility mode is active:

- **Strict mode (`enforce: true`, legacy mode off)**: Throws `IsolationError` if any mandatory field is empty
- **Legacy mode (`legacyCompatMode: true`)**: Substitutes missing mandatory fields with placeholder values (`default` or legacy identifiers)

```typescript
import { IsolationContext, assertIsolation } from '@tencentdb/memory-core';

// Strict validation for production writes
const strictContext: IsolationContext = assertIsolation({
  teamId: 'org-engineering',      // optional
  userId: 'user-48291',
  agentId: 'agent-copilot-v3',
  sessionId: 'sess-a7f3e9d2',
  taskId: 'ticket-INF-2024-0892', // optional
}, { enforce: true, legacyCompatMode: false });

// Legacy mode for migrating existing data
const legacyContext = assertIsolation({
  userId: 'legacy-user-001',
  // agentId and sessionId omitted
}, { legacyCompatMode: true });
// Results in agentId='default', sessionId derived from legacy sessionKey

```

## Query Filtering with IsolationFilter

For data retrieval, the SDK provides **IsolationFilter**—a parallel type where all fields are optional. Omitted fields mean "match any value for this dimension," enabling flexible query scopes:

```typescript
import { IsolationFilter, buildIsolationWhere } from '@tencentdb/memory-core';

// Filter: all sessions for a specific user-agent pair
const filter: IsolationFilter = {
  userId: 'user-48291',
  agentId: 'agent-copilot-v3',
  // sessionId omitted: search across all sessions
  // teamId omitted: search across all teams
};

const { clause, params } = buildIsolationWhere(filter, 'm.');
// clause: "m.user_id = ? AND m.agent_id = ?"
// params: ['user-48291', 'agent-copilot-v3']

```

The [`buildIsolationWhere`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/isolation.ts#L20-L27) function constructs parameterized SQL `WHERE` clauses, preventing injection while maintaining query performance. The optional `prefix` parameter (shown as `'m.'` above) handles table aliasing in complex joins.

## Runtime Verification with rowMatchesIsolation

After retrieval, the [`rowMatchesIsolation`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/isolation.ts) function performs post-query validation to ensure database records conform to the requested isolation boundaries. This defense-in-depth approach catches any edge cases where query construction might not fully enforce tenant separation.

## Field Usage Patterns by Data Layer

| Data Layer | Typical Isolation Pattern |
|------------|---------------------------|
| **L0 (Raw Conversations)** | Full context with `sessionId` as primary key component |
| **L1 (Extracted Records)** | `userId` + `agentId` + `sessionId` for session-scoped facts; `taskId` for cross-session aggregation |
| **Profile (User Models)** | `userId` + `agentId` with `teamId` for organizational segmentation |

## Summary

- **IsolationContext** in the v3 SDK mandates `userId`, `agentId`, and `sessionId` for all write operations to ensure proper data segmentation
- **`teamId`** enables multi-tenant deployments while **`taskId`** supports cross-session business correlation
- Use **`assertIsolation`** for input validation with configurable strictness and legacy compatibility
- Query operations use **IsolationFilter** with **`buildIsolationWhere`** to construct safe, parameterized SQL
- Post-retrieval verification via **`rowMatchesIsolation`** provides additional security guarantees

## Frequently Asked Questions

### What happens if I omit a mandatory IsolationContext field?

The SDK throws an `IsolationError` when `enforce: true` and `legacyCompatMode: false`. With legacy mode enabled, missing fields receive placeholder values (`default` or derived from `sessionKey`), allowing gradual migration of existing data without breaking changes.

### Can I use taskId instead of sessionId for session-scoped queries?

No. The `taskId` field is designed for **cross-session** identification—it never replaces `sessionId`. When you need session-specific memory retrieval, always include `sessionId` in your context or filter.

### How does teamId interact with other isolation fields?

The `teamId` operates as an **optional organizational boundary** that works orthogonally to user-agent-session isolation. Records with matching `userId`, `agentId`, and `sessionId` but different `teamId` values are treated as distinct entities, enabling true multi-tenant separation within a shared database.