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

> Explore the six atomic memory types in TencentDB Agent Memory L1. Understand how AtomicDetail, UpdateRequest, QueryRequest, SearchRequest, DeleteRequest, and CountRequest power CRUD, semantic search, and concurrency.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts) and TypeScript definitions in [`MemoryCore/src/gateway/generated/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts).

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-schemas.ts), which extends auto-generated types from [`MemoryCore/src/gateway/generated/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/types.ts) and validation schemas from [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts). Route handlers are mapped in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts).