# What Is the L1 Atom Layer in TencentDB Agent Memory? Architecture and API Guide

> Discover the L1 Atom layer in TencentDB Agent Memory. This guide explains how it extracts key facts and preferences from logs for efficient, precise information recall. Learn its architecture and API.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: architecture
- Published: 2026-09-04

---

**The L1 Atom layer is the first-level structured memory component in TencentDB Agent Memory that extracts discrete facts, user preferences, constraints, and events from raw conversation logs, enabling precise recall of actionable information without re-parsing entire dialogues.**

The **L1 Atom layer** serves as the foundational structured memory tier in the TencentDB Agent Memory architecture, sitting directly above unstructured conversation data. According to the repository's architecture documentation, this layer transforms raw conversational text into searchable, deduplicated atomic records that bridge the gap between ephemeral chat logs and higher-level semantic understanding.

## Architecture and Purpose of the L1 Atom Layer

### Position in the Memory Hierarchy

The TencentDB Agent Memory system implements a four-tier hierarchy where **L1 Atom** occupies the critical first processing level above **L0 Conversation** (raw dialogue storage). As defined in the repository's [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md), the L1 layer specifically handles "facts, preferences, constraints, and events extracted from conversations"【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/README.md】.

This positioning allows the system to isolate granular, actionable data points—such as a user's preferred UI theme or specific deadlines—from the noise of unstructured natural language. The atomic items then feed into higher semantic layers (**L2 Scenario** and **L3 Persona**), providing the structured foundation required for contextual reasoning.

### Data Extraction and Storage

After a conversation is recorded in L0, an asynchronous pipeline processes the raw text to identify and extract discrete memory units. These **atomic items** are stored with unique identifiers, keys, and values, enabling **deduplication** and **precise retrieval** without requiring expensive re-parsing of historical dialogues.

The storage implementation leverages [`MemoryKnowledge/src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/llm-binding-store.ts), which persists atomic data for efficient vector and BM25 retrieval【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/MemoryKnowledge/src/store/llm-binding-store.ts】. This design ensures that frequently accessed preferences and constraints remain immediately available to the LLM inference layer.

## Working with the L1 Atom Layer via TypeScript SDK

The official TypeScript SDK exposes a complete **L1 Atomic API** through the `MemoryCoreClient` class, enabling programmatic management of atomic memory items. All examples below assume an authenticated `client` instance.

### Updating and Inserting Atomic Items

Use the `updateAtomic` method to store or overwrite discrete facts and preferences. Each atom requires a unique ID, key-value pair, and optionally a `session_id` to scope the memory to specific conversation sessions.

```typescript
// Store a user preference as an atomic item
await client.updateAtomic({
  items: [
    {
      id: "pref-123",
      key: "ui_theme",
      value: "dark",
      session_id: "session-abc", // Optional scoping
    },
  ],
});

```

This operation maps to the `AtomicUpdateRequest` type 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)【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/sdk/memory-core/typescript/src/v3/types.ts】.

### Querying and Searching Atoms

The SDK supports both exact retrieval and full-text search across the atomic memory store. For precise lookups, use `queryAtomic` with specific IDs:

```typescript
// Retrieve specific atoms by ID
const result = await client.queryAtomic({
  ids: ["pref-123"],
});
console.log(result.items[0].value); // → "dark"

```

For broader discovery, the `searchAtomic` method enables semantic queries across keys and values:

```typescript
// Full-text search for theme-related preferences
const hits = await client.searchAtomic({
  query: "theme",
  limit: 5,
});
hits.items.forEach((hit) => console.log(hit.key, hit.value));

```

### Managing Atomic Data Lifecycle

Complete CRUD operations are available through the `MemoryCoreClient`. Use `deleteAtomic` for bulk cleanup of deprecated records, and `countAtomic` for analytics and validation:

```typescript
// Bulk deletion of obsolete preferences
await client.deleteAtomic({ ids: ["pref-123", "old-pref-456"] });

// Count atoms matching specific criteria
const count = await client.countAtomic({ 
  filter: { key: "ui_theme" } 
});
console.log("Theme preferences stored:", count);

```

These methods are implemented 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)【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts】, which provides the underlying HTTP client logic for the L1 Atom API surface.

## Implementation Details and Source Code Structure

The L1 Atom layer's functionality spans multiple core modules within the TencentDB Agent Memory repository:

- **[`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)**: Defines TypeScript interfaces including `AtomicDetail`, `AtomicUpdateRequest`, and response schemas for type-safe atomic operations【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/sdk/memory-core/typescript/src/v3/types.ts】.

- **`MemoryCore/src/api-trace/*`**: Provides tracing utilities that instrument L1 Atom API calls, enabling debugging and performance monitoring of atomic memory operations【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/MemoryCore/src/api-trace】.

- **[`MemoryKnowledge/src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/llm-binding-store.ts)**: Implements the persistence layer that stores atomic data for vector embedding and BM25 retrieval, ensuring efficient access patterns for LLM context construction【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/MemoryKnowledge/src/store/llm-binding-store.ts】.

## Summary

- The **L1 Atom layer** converts unstructured L0 Conversation logs into structured, discrete memory units containing facts, preferences, constraints, and events.
- It enables **precise recall** of actionable information through unique identifiers and key-value storage, eliminating the need to re-parse historical dialogues.
- The **TypeScript SDK** provides complete CRUD capabilities via `updateAtomic`, `queryAtomic`, `searchAtomic`, `deleteAtomic`, and `countAtomic` methods.
- Atomic data persists in specialized stores ([`llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/llm-binding-store.ts)) optimized for both vector similarity search and traditional text retrieval.
- This layer serves as the critical bridge between raw conversation data and higher-level semantic layers (L2 Scenario, L3 Persona) in the memory hierarchy.

## Frequently Asked Questions

### What types of data are stored in the L1 Atom layer?

The L1 Atom layer stores **facts, user preferences, constraints, and events** extracted from raw conversations. These are stored as discrete key-value pairs with unique identifiers, enabling the system to remember specific details like UI themes, deadlines, or user constraints without retaining the full conversational context.

### How does L1 Atom differ from L0 Conversation memory?

**L0 Conversation** stores raw, unstructured dialogue logs, while **L1 Atom** stores processed, structured discrete items extracted from those logs. L0 requires parsing entire conversations to find information, whereas L1 enables immediate lookup of specific facts through unique IDs or key-based queries, significantly improving retrieval performance.

### Can I query atomic items across multiple sessions?

Yes. While you can scope atoms to specific sessions using the `session_id` parameter, the `searchAtomic` and `countAtomic` methods support cross-session queries by omitting session filters or using broad filter criteria. This allows the agent to maintain persistent user preferences across different conversation sessions.

### Where is the atomic data physically stored?

According to the source code in [`MemoryKnowledge/src/store/llm-binding-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/llm-binding-store.ts), atomic data is persisted in storage systems optimized for LLM retrieval, supporting both vector embeddings for semantic search and BM25 indexing for full-text search capabilities【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/MemoryKnowledge/src/store/llm-binding-store.ts】.