How Atoms (L1) Are Extracted and Used in TencentDB Agent Memory

Atoms (L1) in TencentDB Agent Memory are structured key-value records extracted from raw conversation logs via an LLM-driven pipeline, stored as Atomic objects in Redis and PostgreSQL, and accessed through REST APIs to bootstrap agent context, generate skills, and drive retrieval-augmented decisions.

TencentDB Agent Memory organizes experience into four hierarchical layers—L0 Conversation, L1 Atom, L2 Scenario, and L3 Persona. As the first-level structured memory items (also referenced as LI in internal documentation), Atoms represent the atomic units of facts, preferences, constraints, and events distilled from unstructured chat logs. This article examines the complete lifecycle of L1 Atoms, from asynchronous extraction in the Memory Hub to consumption via the TypeScript SDK and REST APIs.

Understanding the L1 Atomic Memory Layer

In the TencentDB Agent Memory architecture, Atoms serve as the foundational structured layer that bridges raw conversational data and high-level agent reasoning. Each atom is an immutable or versioned record capturing a discrete piece of information discovered during agent interactions.

The storage schema defines an L1 Atomic object with the following key fields:

• id: Unique identifier for the atom
• session_id: Optional session scope; omitted atoms are globally aggregated across sessions
• type: Semantic category tag (e.g., preference, fact, constraint)
• content: The extracted key-value or textual data
• metadata: Provenance information including confidence scores and extraction origins
• Timestamps for creation and updates

According to the source code in [sdk/memory-core/typescript/src/types.ts](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/types.ts), these fields map to TypeScript interfaces including AtomicDetail, AtomicUpdateRequest, and AtomicSearchHit, providing type safety across the SDK.

Extraction Pipeline: From Raw Conversations to Structured Atoms

Async Processing in the Memory Hub

Raw chat logs (L0) flow into an asynchronous processing pipeline implemented in the Memory Hub service (written in Go). This pipeline handles ingestion, deduplication, and normalization before persisting data to the Memory Core service.

The extraction process operates on each conversation turn independently, analyzing dialogue context to identify salient information worthy of long-term retention.

LLM-Driven Normalization

A large-language model (LLM) analyzer within the pipeline scans conversation turns to detect four primary categories of atomic information:

• Facts: Objective statements about the user or environment
• Preferences: User likes, dislikes, and stylistic choices
• Constraints: Hard limitations or boundaries (e.g., "never use tool X")
• Events: Time-bound occurrences with significance

The LLM converts these into normalized key-value records, which the pipeline then enriches with metadata such as extraction confidence and source provenance. The resulting structured data is persisted through the Memory Core service to the underlying Redis and PostgreSQL stores.

REST API Operations for Atom Management

The Memory Core exposes a REST-style API under the /v3/atomic/* namespace, as defined in [MemoryKnowledge/openapi.yaml](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryKnowledge/openapi.yaml). Client implementations in [sdk/memory-core/typescript/src/v3/client.ts](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts) wrap these endpoints with strongly-typed methods.

Core CRUD Endpoints

The API supports five primary operations:

• POST /v3/atomic/update (updateAtomic): Insert new atoms or upsert existing records by ID
• POST /v3/atomic/query (queryAtomic): Retrieve specific atoms by their unique identifiers
• POST /v3/atomic/search (searchAtomic): Hybrid BM25 and vector retrieval against the content field
• POST /v3/atomic/delete (deleteAtomic): Batch removal of atoms by ID list
• POST /v3/atomic/count (countAtomic): Statistical aggregation of atom collections

Search and Retrieval Patterns

The searchAtomic method implements hybrid retrieval, combining BM25 text matching with vector similarity search on embedded representations of the content field. Agents typically call this method with a natural language query and limit parameters to obtain the most relevant context for prompt injection.

Practical Usage Patterns in Downstream Agents

Bootstrapping Chat Context

When an agent initializes a new session, the Memory Hub automatically pulls relevant L1 Atoms—particularly user preferences and persistent facts—to pre-populate the conversation context. This Chat Memory pattern reduces repetitive prompting by surfacing previously established constraints and preferences without requiring the user to restate them.

Skill Generation and Tool Calls

Extracted atoms provide the factual backbone for auto-generated Skills (capability definitions). A skill definition may reference specific atoms that establish pre-conditions, parameter constraints, or environmental facts required for tool execution. During runtime, agents call client.searchAtomic({ query, limit }) to obtain relevant atoms that inform tool-selection decisions.

Lifecycle Updates and Maintenance

After task completion, agents programmatically update the memory store via client.updateAtomic({ items }) to reflect newly discovered facts or to overwrite stale information with corrected values. This lifecycle management ensures the knowledge base remains current as user requirements evolve.

Implementation Examples

The following examples demonstrate atom manipulation using the TypeScript SDK, importing from @tencentdb-agent-memory/memory-core.

Updating or Inserting Atoms

import { MemoryCoreClient } from '@tencentdb-agent-memory/memory-core';

const client = new MemoryCoreClient({ baseURL: 'http://localhost:8125/api' });

async function addUserPreference() {
  await client.updateAtomic({
    items: [
      {
        id: 'atom-12345',
        type: 'preference',
        content: 'prefers dark mode',
        session_id: 'session-abc',   // Optional: omit for global aggregation
        metadata: { origin: 'chat', confidence: 0.96 },
      },
    ],
  });
}

addUserPreference();

Querying Specific Atoms by ID

const result = await client.queryAtomic({
  ids: ['atom-12345', 'atom-67890'],
});
console.log(result.items); // → Array of AtomicDetail objects

Searching Atoms with Free-Text Queries

const hits = await client.searchAtomic({
  query: 'dark mode',
  limit: 5,
});
console.log(hits.items.map(hit => hit.content));

Batch Deletion

await client.deleteAtomic({ ids: ['atom-12345', 'atom-67890'] });

Key Source Files and Architecture References

The following files illustrate how Atoms are defined, stored, and accessed throughout the TencentDB Agent Memory ecosystem:

• sdk/memory-core/typescript/src/types.ts: Defines TypeScript interfaces (AtomicDetail, AtomicUpdateRequest, AtomicSearchHit) representing the L1 data model
• sdk/memory-core/typescript/src/v3/client.ts: Implements the SDK wrapper methods (updateAtomic, queryAtomic, searchAtomic, deleteAtomic, countAtomic) for REST API interaction
• MemoryKnowledge/openapi.yaml: OpenAPI specification documenting the /v3/atomic/* endpoint contracts
• MemoryPanel/web/src/pages/memory/ChatMemoryPage/components/types.ts: Frontend type definitions (AtomicItem) and UI logic for hierarchical L1→L2→L3 visualization

The backend extraction pipeline resides in the Memory Hub service (Go) and is described architecturally in the repository's technical overview documentation.

Summary

• Atoms (L1) are structured key-value records representing facts, preferences, constraints, and events extracted from raw L0 conversation logs
• An LLM-driven pipeline in the Memory Hub asynchronously processes chat logs to identify, normalize, and deduplicate atomic information before persistence
• Atoms are stored in Redis and PostgreSQL through the Memory Core service, with optional session_id scoping for global or session-specific aggregation
• The /v3/atomic/* API provides CRUD and search operations (updateAtomic, queryAtomic, searchAtomic, deleteAtomic, countAtomic) accessible via TypeScript SDK or direct HTTP calls
• Downstream agents consume L1 Atoms to bootstrap chat context, generate skills, and drive retrieval-augmented decision making during task execution

Frequently Asked Questions

What is the difference between L0 and L1 memory in TencentDB Agent Memory?

L0 (Conversation) represents the raw, unstructured chat logs and message history between users and agents. L1 (Atoms) consists of structured, extracted key-value records created by processing L0 data through an LLM-driven pipeline. While L0 captures ephemeral dialogue, L1 persists discrete facts and preferences in a queryable format for long-term retrieval.

How does the Memory Hub determine which conversation elements become Atoms?

The extraction pipeline uses a domain-specific LLM prompt to classify and extract four categories: facts, preferences, constraints, and events. The model analyzes each conversation turn for salient information that exceeds a confidence threshold, then normalizes this content into atomic records. Duplicate information across turns is merged during the deduplication phase before storage.

Can L1 Atoms be shared across multiple sessions, or are they isolated?

Atoms support both scoping models. When created with a session_id, atoms are associated with specific conversation sessions. When the session_id is omitted, atoms become globally aggregated and available across all sessions for the same user or tenant. This design allows agents to access persistent user preferences while maintaining session-specific contextual facts.

What storage backends does the Memory Core use for L1 Atomic data?

The Memory Core service utilizes a hybrid storage architecture with Redis for high-speed caching and hot retrieval paths, and PostgreSQL for persistent, transactional storage of atomic records. This combination supports both low-latency search queries via the searchAtomic method and durable persistence for long-term memory retention.

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