When Is `sessionId` Required or Optional in TencentDB Agent Memory? Session Resolution Rules Explained

In TencentDB Agent Memory, sessionId is optional for L0/L1 (conversation and atomic data) layers and ignored entirely for L2/L3 (profile, scenario, and core) layers, with its presence determining whether operations target a single session or aggregate across all sessions for a user-agent pair.

The TencentDB Agent Memory system implements a four-tuple isolation model that governs how data is scoped and retrieved. Understanding when sessionId is required, optional, or irrelevant is essential for correctly architecting memory operations. This article breaks down the Session Resolution Rules as implemented in the TencentCloud/TencentDB-Agent-Memory repository, with direct references to the source code and SDK behavior.

How the Four-Tuple Isolation Model Works

The v3 strict-isolation data-plane uses four identifiers to scope memory operations:

• teamId – Required, identifies the organization
• agentId – Required, identifies the AI agent
• userId – Required, identifies the end user
• sessionId – Optional, identifies a specific conversation

The MemoryClient constructor in the TypeScript SDK always requires teamId, agentId, and userId. The sessionId can be supplied at construction time or modified later via withIsolation().

L0/L1 Layers: Optional sessionId with Aggregation Behavior

For L0 (conversation) and L1 (atomic data) operations, sessionId controls the scope of data access:

sessionId State	Behavior
Provided	Restricts query or write to the single session identified by that sessionId
Omitted or withIsolation({ sessionId: null })	Disables per-session isolation, causing L0/L1 calls to aggregate across all sessions belonging to the same (team, agent, user) triple

This design enables both fine-grained conversation tracking and holistic user analysis within the same API.

Code Example: Single-Session vs. Cross-Session Queries

// Restrict to a single session (session-scoped query)
const client = new MemoryClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "your-user-key",
  serviceId: "mem-instance-id",
  teamId: "team-xxx",
  agentId: "agt-xxx",
  userId: "usr-xxx",
  sessionId: "sess-42",          // <-- per-session isolation
});
const singleSession = await client.queryConversation({ limit: 10 });

// Aggregate across all sessions for the same user-agent pair
const clientAll = client.withIsolation({ sessionId: null });
const aggregated = await clientAll.queryConversation({ limit: 10 });

The withIsolation({ sessionId: null }) helper explicitly clears the per-session filter, triggering cross-session aggregation as documented in sdk/memory-core/typescript/README.md lines 29-57.

L2/L3 Layers: sessionId Is Ignored

For L2 (profile, scenario) and L3 (core) operations, sessionId is not part of the isolation criteria. These layers operate on:

• (team, agent) isolation for L3 core data
• (team, agent, user) isolation for L2 profile and scenario data

The same profile or scenario applies to every session under the same team-agent pair. Supplying a sessionId to these operations has no effect.

Code Example: Session-Agnostic L2/L3 Operations

// L2/L3 operations ignore sessionId (same profile regardless of session)
await client.readScenario({ path: "work.md" });   // sessionId has no effect
await client.readCore();                         // session-agnostic

Implementation in Source Code

The Session Resolution Rules are enforced across several key files:

File	Role
sdk/memory-core/typescript/README.md	Documents the SDK's isolation model and optional sessionId semantics
MemoryCore/src/utils/session-filter.ts	Implements the runtime filter that applies sessionId when present and falls back to cross-session aggregation when null
MemoryCore/src/offload_server/session-utils.ts	Contains server-side session resolution logic ensuring L0/L1 respect sessionId while L2/L3 ignore it
MemoryCore/src/offload_server/router.ts	Routes API calls and passes isolation parameters to the session filter

Summary

• L0/L1 layers: sessionId is optional — provide it for single-session isolation, omit or set to null for cross-session aggregation
• L2/L3 layers: sessionId is ignored — data is shared across all sessions for the same team-agent(-user) scope
• Use withIsolation({ sessionId: null }) to explicitly switch from single-session to aggregated mode without reconstructing the client
• The four-tuple model (teamId, agentId, userId, sessionId) is implemented in the v3 strict-isolation data-plane across the SDK and server components

Frequently Asked Questions

What happens if I omit sessionId for an L0 query?

The operation aggregates across all sessions belonging to the same teamId, agentId, and userId. This is useful for building a complete conversation history or analytics dashboard that spans multiple sessions.

Can I change sessionId after creating a MemoryClient?

Yes. The withIsolation({ sessionId: ... }) method returns a new client instance with modified isolation parameters. Pass null to remove session-level filtering, or provide a specific session ID to narrow the scope.

Why doesn't sessionId affect L2/L3 operations?

L2 (profile, scenario) and L3 (core) data represents persistent agent configuration and user profiles that must remain consistent across all conversations. Session-scoped isolation would fragment this shared state, so the system intentionally ignores sessionId for these layers.

Where are the Session Resolution Rules documented in the source?

The primary documentation is in sdk/memory-core/typescript/README.md at lines 29-57, with additional implementation details in MemoryCore/src/utils/session-filter.ts and the server-side session utilities.

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