# What Is Stored in the L1 Atom Layer? Inside TencentDB-Agent-Memory

> Discover what the L1 Atom layer stores in TencentDB Agent Memory. It holds verbatim session conversation history, forming the immutable base for memory aggregations.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: internals
- Published: 2026-08-29

---

**The L1 Atom layer stores the verbatim, session-level conversation history keyed by team, user, agent, and session identifiers, serving as the immutable foundation from which higher-level memory aggregations are derived.**

The TencentDB-Agent-Memory repository implements a tiered memory architecture for AI agents, where the **L1 Atom layer** functions as the granular storage tier for individual chat interactions. Unlike the semantic summaries stored in L2 or the long-term knowledge in L3, the L1 layer maintains the raw conversation logs required for precise context retrieval and compliance auditing.

## Anatomy of the L1 Atom Layer

### The Four-Dimensional Key Structure

According to the technical operations documentation in [[`docs/tdai-v2-technical-ops.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/docs/tdai-v2-technical-ops.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/docs/tdai-v2-technical-ops.md#L78-L86) (lines 78-86), every record written to the L1 Atom layer is uniquely identified by a composite key consisting of four mandatory dimensions: `team_id`, `user_id`, `agent_id`, and `session_id`. This quadruple-key enforcement ensures strict data isolation between different organizational boundaries and conversation contexts.

### Session Records and Task Labels

Each entry in the L1 layer encapsulates a single conversation turn—referred to as the **L0 payload**—containing the raw message content and metadata. Additionally, records may carry an optional `task_id` label. As implemented in [[`MemoryCore/src/core/store/isolation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/isolation.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/isolation.ts), this label functions purely as a filtering mechanism during recall operations and does not alter the underlying storage key structure.

## Writing Data to the L1 Atom Layer

When an agent processes user input, the system persists the interaction through the `/v3/atomic/write` endpoint. The [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts) utility orchestrates this flow, ensuring that L0 conversation fragments are atomically committed to the L1 store before any downstream processing occurs.

```bash

# Persist a conversation turn to the L1 Atom layer

curl -X POST "$TDAI_PROXY_URL/pi/default/v1/v3/atomic/write" \
  -H "Authorization: Bearer $TDAI_USER_KEY" \
  -H "Content-Type: application/json" \
  -H "x-team-id: $TDAI_TEAM_ID" \
  -H "x-agent-id: $TDAI_AGENT_ID" \
  -H "x-conversation-id: $SESSION_ID" \
  -d '{
        "messages": [{"role":"user","content":"Analyze Q3 revenue trends"}],
        "task_id": "financial-analysis-001"
      }'

```

The [[`MemoryCore/src/utils/checkpoint.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/checkpoint.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/utils/checkpoint.ts) module then handles the durable persistence of these session states, creating recoverable checkpoints that guarantee data survives system interruptions.

## Querying the L1 Atom Layer

Retrieval from the L1 Atom layer occurs via the `/v3/atomic/search` endpoint, which supports filtering by the optional `task_id` label. When `task_id` is omitted, the search scans all records matching the mandatory four-dimensional key; when provided, the recall scope narrows to only those entries tagged with the specific task identifier.

```bash

# Query session history with optional task filtering

curl -X POST "$TDAI_PROXY_URL/pi/default/v1/v3/atomic/search" \
  -H "Authorization: Bearer $TDAI_USER_KEY" \
  -H "Content-Type: application/json" \
  -H "x-team-id: $TDAI_TEAM_ID" \
  -H "x-agent-id: $TDAI_AGENT_ID" \
  -d '{
        "query": "Q3 revenue",
        "task_id": "financial-analysis-001",
        "session_id": "sess-2024-Q3-001"
      }'

```

## Core Implementation Files

### Isolation Enforcement in isolation.ts

The [[`MemoryCore/src/core/store/isolation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/isolation.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/isolation.ts) file defines the core isolation mechanisms that enforce the four-dimensional keying strategy. This module validates that every write operation includes the mandatory team, user, agent, and session identifiers before allowing persistence to the L1 Atom layer.

### Pipeline Management in stateful-pipeline-manager.ts

Located at [[`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/utils/stateful-pipeline-manager.ts), this utility manages the stateful transformation of L0 conversation fragments into durable L1 records. It ensures atomicity by coordinating between transient memory buffers and the permanent L1 storage backend.

### Checkpoint Durability in checkpoint.ts

The [[`MemoryCore/src/utils/checkpoint.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/checkpoint.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/utils/checkpoint.ts) module implements the durability guarantees for the L1 Atom layer by periodically flushing in-memory conversation buffers to persistent storage.

## Summary

- The **L1 Atom layer** stores immutable, session-level conversation records (**L0 payloads**) keyed strictly by `team_id`, `user_id`, `agent_id`, and `session_id`.
- Optional **`task_id`** labels enable filtered recall without modifying the underlying storage structure or key composition.
- The **isolation.ts** module enforces mandatory multi-tenancy keys, while **stateful-pipeline-manager.ts** and **checkpoint.ts** handle the atomic ingestion and durable persistence pipeline.
- Data enters via `/v3/atomic/write` and exits via `/v3/atomic/search`, with the latter supporting optional task-based filtering while requiring the four mandatory dimensional headers.

## Frequently Asked Questions

### Does the L1 Atom layer store aggregated summaries like the L2 layer?

No. The L1 Atom layer exclusively maintains the raw, unaggregated conversation history. Aggregated semantic summaries and extracted entities reside in the L2 layer, which derives its data from the L1 records through background processing pipelines.

### What happens if I omit the task_id when writing to the L1 layer?

Omitting the `task_id` creates a record that is retrievable across all task contexts for that specific session. According to the isolation logic in [`isolation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/isolation.ts), the record is still keyed by the four mandatory dimensions, but recall operations performed without a `task_id` filter will return this record alongside other session data.

### How does the L1 Atom layer ensure data isolation between different teams?

The isolation is enforced at the storage level through the composite key implementation in [`MemoryCore/src/core/store/isolation.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/isolation.ts). Every API request must provide valid `team_id`, `user_id`, `agent_id`, and `session_id` headers; the storage backend rejects any write or read operation missing these mandatory dimensions, preventing cross-tenant data leakage.

### Can I directly query L1 Atom layer records by timestamp ranges?

The current implementation, as documented in the technical operations guide and reflected in the `/v3/atomic/search` endpoint, primarily supports querying by the four-dimensional key and optional `task_id`. Time-based filtering would need to be implemented at the application layer or through additional indexing strategies not exposed in the core atomic storage interface.