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

> Understand when sessionId is required or optional in TencentDB Agent Memory. Discover session resolution rules for L0 L1 L2 L3 layers to optimize your data operations.

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

---

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

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

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md) | Documents the SDK's isolation model and optional `sessionId` semantics |
| [`MemoryCore/src/utils/session-filter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/README.md) at lines 29-57, with additional implementation details in [`MemoryCore/src/utils/session-filter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/session-filter.ts) and the server-side session utilities.