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

> Configure L1 Atomic Memory extraction using the V3AtomicUpdateRequest interface. Control deduplication, session limits, and memory scoping with simple parameters in the TencentDB-Agent-Memory SDK.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) (lines 140-144), the implementation uses a Set-based filtering approach:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts)), the server executes a distinct selection query. In [`MemoryCore/src/metadata/store/sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) (lines 140-144) and `SELECT DISTINCT` queries in [`sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/types.ts) and [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts), with extraction logic implemented in [`MemoryCore/src/core/l1-extractor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts), then the server executes distinct queries in [`sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/types.ts) and [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts). The runtime extraction logic that utilizes these configurations resides in [`MemoryCore/src/core/l1-extractor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/l1-extractor.ts), while the storage-layer deduplication is handled in [`MemoryCore/src/metadata/store/sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/store/sqlite-adapter.ts).