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

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

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:

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

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