How to Configure L1 Atomic Memory Extraction: Deduplication and Session Limits

L1 Atomic Memory extraction is configured through the V3AtomicUpdateRequest interface in the TencentDB-Agent-Memory TypeScript SDK, where developers control cross-session deduplication via the dedupe boolean flag, scope memories to specific conversations using the optional session_id parameter, and enforce retrieval caps through the limit field that restricts the number of atomic items returned per request.

The TencentCloud TencentDB-Agent-Memory repository implements L1 Atomic Memory as the foundational structured memory layer that extracts factual snippets from user prompts through LLM-based processing. Configuring this system requires precise manipulation of request parameters defined in sdk/memory-core/typescript/src/v3/types.ts and enforced by both client-side utilities and server-side storage adapters in the MemoryCore module.

Configuring Session Boundaries

L1 Atomic Memories can exist either as global user records or as session-isolated entries. This behavior is controlled through the session_id field in V3AtomicUpdateRequest, defined in sdk/memory-core/typescript/src/v3/types.ts.

When session_id is omitted from the request payload, the extracted atomic items are stored across all sessions for that specific user_id, creating a persistent cross-conversation memory. When provided, the memory is isolated to that specific session identifier, allowing for temporary or context-specific fact retention. The extraction logic in MemoryCore/src/core/l1-extractor.ts attaches this identifier during the AtomicDetail construction phase.

Enforcing Retrieval Limits

The limit parameter controls the maximum number of atomic items returned by query operations. Defined in the request interfaces within sdk/memory-core/typescript/src/v3/types.ts, this parameter defaults to 10 items per request if not specified.

Both the client SDK and the server enforce hard ceilings on this value. The client validates the parameter before transmission, while the server implementation maintains a MAX_ITEMS_PER_REQUEST constant to protect database resources. Exceeding these limits results in a truncated response or a ParamError exception during client-side preprocessing.

Enabling Deduplication

Deduplication prevents redundant storage of identical atomic memories and operates at two layers: client-side preprocessing and server-side query execution.

Client-Side Deduplication in client.ts

Before transmitting data to the MemoryCore API, the TypeScript SDK removes duplicate identifiers locally. In sdk/memory-core/typescript/src/v3/client.ts (lines 140-144), the implementation uses a Set-based filtering approach:

const deduped = [...new Set(raw.map(id => id.trim()))];

If the deduplicated array exceeds the SDK-defined maximum length, the client throws a ParamError immediately, preventing invalid requests from reaching the server.

Server-Side Deduplication in sqlite-adapter.ts

When the dedupe boolean flag is set to true in a query request (defined in sdk/memory-core/typescript/src/v3/metadata-types.ts), the server executes a distinct selection query. In MemoryCore/src/metadata/store/sqlite-adapter.ts (lines 1208-1219), the storage adapter performs a SELECT DISTINCT operation on the user_id dimension, collapsing duplicate rows before returning results to the client.

Complete Configuration Examples

The following patterns demonstrate practical configuration of L1 Atomic Memory extraction with session scoping, deduplication, and limits.

Store atomic memories with session isolation:

await client.updateAtomic({
  session_id: "sess_42",   // Omit to aggregate across all user sessions
  items: [
    { content: "User prefers dark mode", type: "preference" },
    { content: "Project deadline is 2026-12-31", type: "fact" },
  ],
});

Query with deduplication and strict limits:

const result = await client.queryAtomic({
  dedupe: true,           // Enable user_id deduplication (default: false)
  limit: 5,               // Return maximum 5 items
  session_id: "sess_42", // Restrict to specific session only
});

Perform full-text search with configuration flags:

const hits = await client.searchAtomic({
  query: "deadline",
  dedupe: true,
  limit: 10,
});

Summary

• Session Scoping: Use the optional session_id parameter in V3AtomicUpdateRequest to isolate memories to specific conversations; omitting the field creates global user memories persistent across all sessions.
• Deduplication Control: Enable the dedupe boolean flag to collapse duplicate records on the user_id dimension, processed via Set filtering in client.ts (lines 140-144) and SELECT DISTINCT queries in sqlite-adapter.ts (lines 1208-1219).
• Retrieval Limits: Configure the limit parameter (default 10) to cap returned atomic items, protected by client validation and server-side MAX_ITEMS_PER_REQUEST enforcement.
• Source Locations: Configuration structures reside in sdk/memory-core/typescript/src/v3/types.ts and metadata-types.ts, with extraction logic implemented in MemoryCore/src/core/l1-extractor.ts.

Frequently Asked Questions

How do you scope L1 Atomic Memory to a specific session?

Supply the session_id string parameter in your updateAtomic request. When included, the L1 extractor stores the memory entries under that specific session identifier only, making them retrievable exclusively through queries targeting the same session_id. If omitted, the memories persist across all sessions for that user according to the implementation in MemoryCore/src/core/l1-extractor.ts.

What is the maximum number of items retrievable in a single atomic memory request?

The default retrieval cap is 10 items per request, configurable via the limit parameter in queryAtomic or searchAtomic calls. The system enforces an absolute ceiling defined by MAX_ITEMS_PER_REQUEST on the server side, while the client SDK validates limits before transmission to prevent parameter errors.

How does deduplication work across multiple sessions?

When dedupe: true is specified, the system removes duplicate entries based on the user_id dimension regardless of session boundaries. The client first deduplicates ID arrays using JavaScript's Set object in client.ts, then the server executes distinct queries in sqlite-adapter.ts to ensure only unique atomic memories return in the result set.

Where is the L1 Atomic Memory extraction configuration defined?

Core configuration types including V3AtomicUpdateRequest, the dedupe flag, and limit parameters are defined in sdk/memory-core/typescript/src/v3/types.ts and metadata-types.ts. The runtime extraction logic that utilizes these configurations resides in MemoryCore/src/core/l1-extractor.ts, while the storage-layer deduplication is handled in MemoryCore/src/metadata/store/sqlite-adapter.ts.

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