Atomic Memory Types in L1: Complete Technical Guide to the LI Layer in TencentDB Agent Memory

The L1 (LI) layer in TencentDB Agent Memory defines six atomic memory types—AtomicDetail, AtomicUpdateRequest, AtomicQueryRequest, AtomicSearchRequest, AtomicDeleteRequest, and AtomicCountRequest—that handle CRUD operations, semantic search, and optimistic concurrency through the /v3/atomic/* API family.

The TencentDB Agent Memory system organizes knowledge into hierarchical layers, with L1 (also called LI) serving as the foundational tier for raw atomic memory items. These atomic memory types in L1 represent individual pieces of knowledge or notes, all interacting through the /v3/atomic/* endpoints defined in the TencentCloud/TencentDB-Agent-Memory repository.

Core Atomic Memory Types in L1

The schema definitions in MemoryCore/src/gateway/v2-schemas.ts establish the complete type system for atomic memory operations. All types extend generated schemas from MemoryCore/src/gateway/generated/schemas.ts and TypeScript definitions in MemoryCore/src/gateway/generated/types.ts.

AtomicDetail

AtomicDetail represents the concrete manifestation of a single atomic note returned by read-type endpoints. It extends the base generated schema with critical versioning and ownership metadata.

Key fields include:

• record_id: Unique identifier for the memory item
• type: Categorical classification of the note
• content: The actual knowledge payload
• version: Monotonically increasing integer starting at 0, incremented on every update
• created_at / updated_at: Temporal metadata
• Optional ownership dimensions: team_id, user_id, agent_id, task_id

AtomicUpdateRequest and AtomicUpdateData

These types handle the payload structure for /v3/atomic/update, which creates new atomic notes or modifies existing ones. When the id field is omitted, the system creates a new record; when provided, it performs an update operation against that specific record_id.

The structure includes type, content, and the optional ownership fields mentioned above.

AtomicQueryRequest and AtomicQueryData

For paginated retrieval via /v3/atomic/query, these types define filtering parameters including type, time_start, time_end, and pagination controls (page, pageSize). The endpoint returns an array of AtomicDetail objects plus a total count.

AtomicSearchRequest and AtomicSearchData

The hybrid search interface (/v3/atomic/search) supports semantic similarity queries through the AtomicSearchRequest type. It accepts the same filter fields as the query type plus vector and text parameters for embedding-based or text-based similarity search.

The response returns AtomicSearchHit[], where each hit wraps an AtomicDetail with an additional score field indicating relevance.

AtomicDeleteRequest and AtomicDeleteData

Bulk deletion operations utilize /v3/atomic/delete, accepting up to 5,000 ids in a single request. The system performs automatic de-duplication before processing the deletion.

AtomicCountRequest

For simple aggregation without retrieving full records, /v3/atomic/count accepts optional filters (type, time_start, time_end) and returns a total count.

Key Architectural Features of L1 Atomic Memory

Beyond the type definitions, the L1 layer implements specific patterns for data integrity and isolation.

Monotonic Versioning

The version field in AtomicDetail serves as an optimistic concurrency control mechanism. Starting at 0, it increments atomically with every successful update request, enabling clients to detect conflicts and implement safe concurrent access patterns.

Ownership Dimensions

Atomic memory types support multi-dimensional isolation through mandatory and optional identifiers:

• Mandatory: team_id, user_id, agent_id, and session_id define security boundaries
• Optional: task_id provides business-level filtering for task-specific recall scenarios

Atomic Write Semantics

All mutation operations implement crash-safe persistence through a temporary file plus rename pattern in fs-storage.ts. This guarantees that data remains consistent even if the process crashes during write operations.

Working with Atomic Memory Types

The following TypeScript examples demonstrate interaction with L1 atomic memory types using the official SDK. All operations route through the /v3/atomic/* endpoints mapped in MemoryCore/src/gateway/v2-router.ts.

import { MemoryCoreClient } from "@tencentcloud/memory-core";

const client = new MemoryCoreClient({
  baseURL: "http://127.0.0.1:8420",
  apiKey: "YOUR_MEMORY_CORE_API_KEY",
});

// Create a new atomic note (no ID provided)
const createResponse = await client.http.post("/v3/atomic/update", {
  type: "idea",
  content: "Design a new L1 knowledge graph schema"
});
// Response includes generated record_id and version 0

// Query with pagination
const queryResult = await client.http.post("/v3/atomic/query", {
  type: "idea",
  page: 1,
  pageSize: 20
});
// Returns { items: AtomicDetail[], total: number }

// Hybrid semantic search
const searchResult = await client.http.post("/v3/atomic/search", {
  text: "graph schema",
  type: "idea"
});
// Returns AtomicSearchHit[] with score and AtomicDetail

// Update existing record (requires ID)
await client.http.post("/v3/atomic/update", {
  id: "rec-12345",
  content: "Revise the schema to include edge_type"
  // version automatically increments
});

// Bulk delete (maximum 5000 IDs)
await client.http.post("/v3/atomic/delete", {
  ids: ["rec-12345", "rec-67890"]
});

// Count records without retrieval
const count = await client.http.post("/v3/atomic/count", {
  type: "idea"
});

Summary

• The L1 layer defines six atomic memory types in MemoryCore/src/gateway/v2-schemas.ts handling CRUD, search, and aggregation operations.
• AtomicDetail provides the core representation with monotonic versioning starting at 0 for optimistic concurrency control.
• The /v3/atomic/update endpoint handles both creation (absent ID) and updates (present ID) with crash-safe atomic write semantics.
• Ownership dimensions (team_id, user_id, agent_id, task_id) enforce multi-tenant isolation and business-context filtering.
• Bulk operations support up to 5,000 records per request for efficient data management at scale.

Frequently Asked Questions

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

L1 and LI refer to the same architectural layer—the raw atomic memory tier. LI is simply an alternative abbreviation used interchangeably with L1 throughout the codebase to represent the foundational storage layer for individual knowledge items.

How does versioning work for atomic memory items?

Each AtomicDetail maintains a version field as a monotonically increasing integer beginning at 0. The system increments this value automatically on every successful /v3/atomic/update operation, enabling optimistic concurrency control where clients can verify they are updating the latest version of a record.

What is the maximum number of items that can be deleted in a single request?

The AtomicDeleteRequest type supports bulk deletion of up to 5,000 IDs in a single /v3/atomic/delete call. The implementation automatically de-duplicates the ID list before processing the deletion operation.

Which source files define the atomic memory types?

The primary schema definitions reside in MemoryCore/src/gateway/v2-schemas.ts, which extends auto-generated types from MemoryCore/src/gateway/generated/types.ts and validation schemas from MemoryCore/src/gateway/generated/schemas.ts. Route handlers are mapped in MemoryCore/src/gateway/v2-router.ts.

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