`/v3/atomic/*` Endpoints for CRUD Operations on L1 Atomic Memory in TencentDB Agent Memory

The L1 Atomic Memory layer exposes five HTTP POST endpoints under /v3/atomic for create, read, update, delete, count, and search operations, with up-sert semantics via POST /v3/atomic/update and filter-based queries via POST /v3/atomic/search.

The TencentDB-Agent-Memory repository implements a tiered memory architecture where L1 Atomic Memory provides structured, key-value storage for discrete data units. This guide covers the complete v3 API surface for atomic operations, referencing the official implementation in MemoryCore/v3-api-memorycore-doc.md and SDK documentation in both TypeScript and Python client libraries.

Complete /v3/atomic/* Endpoint Reference

All endpoints follow the POST /v3/atomic/{operation} pattern and accept JSON-encoded request bodies. Authentication requires platform-standard headers including Authorization: Bearer <TOKEN>.

Create and Update: POST /v3/atomic/update

The update endpoint implements up-sert semantics—it inserts a new record if the key does not exist, or overwrites the existing record if it does.

// TypeScript SDK
await client.updateAtomic({
  key: 'session:12345',
  value: { content: 'Hello world', meta: { ttl: 3600 } },
});

# Python SDK

client.update_atomic(
    key='session:12345',
    value={'content': 'Hello world', 'meta': {'ttl': 3600}}
)

The key parameter serves as the unique identifier. The value field accepts arbitrary JSON-serializable objects, enabling flexible schema design.

Read and Query: POST /v3/atomic/query

Retrieve single or batch records by key.

const result = await client.queryAtomic({ key: 'session:12345' });

result = client.query_atomic(key='session:12345')

For batch retrieval, pass an array of keys in the request body.

Search: POST /v3/atomic/search

Execute filter-based queries using WHERE-style clauses against record attributes.

const searchRes = await client.searchAtomic({
  where: "meta.ttl > 0",
  limit: 10,
});

search_res = client.search_atomic(where="meta.ttl > 0", limit=10)

This endpoint enables bulk retrieval without prior knowledge of specific keys, supporting pagination via limit and offset parameters.

Delete: POST /v3/atomic/delete

Remove records by key with confirmation of deletion count.

const delRes = await client.deleteAtomic({ key: 'session:12345' });
console.log('Deleted count:', delRes.deleted_count);

del_res = client.delete_atomic(key='session:12345')
print('Deleted count:', del_res['deleted_count'])

Count: POST /v3/atomic/count

Return matching record totals for pagination or health-check scenarios.

const cnt = await client.countAtomic({ where: "meta.ttl > 0" });

cnt = client.count_atomic(where="meta.ttl > 0")

Architecture and Isolation

The /v3/atomic/* endpoints are strongly isolated from lower-level data planes (L0, L2, L3) as implemented in the MemoryCore service. This separation provides:

• Clean API versioning — v3 guarantees stable contracts for client integrations
• Independent scaling — atomic operations route through dedicated gateway configurations
• Simplified client SDKs — TypeScript and Python libraries expose typed methods matching each endpoint

Gateway routing is configured in MemoryCore/tdai-gateway.yaml, which maps /v3/atomic/* traffic to the Atomic Memory service backend.

SDK Implementation Details

TypeScript SDK Reference

The endpoint table in sdk/memory-core/typescript/README.md (lines 70–74) documents the complete operation matrix for TypeScript consumers. The MemoryClient class provides async methods: updateAtomic, queryAtomic, searchAtomic, deleteAtomic, and countAtomic.

Python SDK Reference

The corresponding documentation in sdk/memory-core/python/README.md (lines 117–120) mirrors the TypeScript structure. The Python client uses snake_case naming: update_atomic, query_atomic, search_atomic, delete_atomic, and count_atomic.

Both SDKs handle request serialization, authentication header injection, and response parsing automatically.

Request and Response Format

Aspect	Specification
HTTP Method	POST (all endpoints)
Content-Type	application/json
Authentication	Authorization: Bearer <TOKEN> header required
Key field	String, unique per record
Value field	Arbitrary JSON object
Filter syntax	SQL-like WHERE clauses for search/count
Response envelope	JSON object with result data and metadata

Summary

• The L1 Atomic Memory /v3/atomic/* endpoints provide full CRUD plus search and count functionality
• Up-sert semantics via POST /v3/atomic/update eliminate separate create vs. update logic
• Filter-based operations via /v3/atomic/search and /v3/atomic/count enable flexible data access patterns
• Strong isolation from other memory tiers ensures stable, versioned API contracts
• Official documentation resides in MemoryCore/v3-api-memorycore-doc.md with SDK guides in sdk/memory-core/typescript/README.md and sdk/memory-core/python/README.md

Frequently Asked Questions

What is the difference between /v3/atomic/query and /v3/atomic/search?

/v3/atomic/query retrieves records by exact key match—use it when you know the specific identifier. /v3/atomic/search executes attribute-based filtering with WHERE clauses—use it for discovery when keys are unknown. Query is optimized for latency; search provides flexibility.

Does POST /v3/atomic/update support partial updates?

No—the update endpoint implements full up-sert semantics. The provided value completely replaces any existing record. For partial modifications, clients must read the existing record, modify the desired fields, and submit the complete updated value.

How are the /v3/atomic/* endpoints authenticated?

All requests require the platform-standard Authorization: Bearer <TOKEN> header. The SDKs automatically inject this header when initialized with valid credentials. Token validation occurs at the gateway layer configured in MemoryCore/tdai-gateway.yaml.

What data types can I store in L1 Atomic Memory?

The value field accepts any JSON-serializable object, including nested structures. However, the where filter syntax in search/count operations works best with primitive fields (strings, numbers, booleans) and shallow object paths like meta.ttl. Complex nested queries may require client-side filtering.

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