API Endpoints for Managing Atomic Memory in TencentDB Agent Memory

TencentDB Agent Memory exposes five POST endpoints under the /v3/atomic/* namespace that enable creating, querying, hybrid searching, bulk deleting, and counting atomic (L1) memory records.

The TencentDB Agent Memory repository provides a RESTful gateway for manipulating atomic memory through a standardized HTTP interface. These API endpoints for managing atomic memory are defined in the core router and represent the sole public access layer for L1 storage operations. All requests require tenancy headers and utilize the ApiResponseEnvelope format for consistent request and response handling.

Available Endpoints for Atomic Memory Operations

The atomic memory interface exposes five distinct operations, all using the POST method to support complex query bodies and large vector payloads.

Operation	Path	Primary Function
Update	/v3/atomic/update	Creates new records or overwrites existing ones by record_id
Query	/v3/atomic/query	Retrieves paginated lists filtered by metadata, type, or time ranges
Search	/v3/atomic/search	Executes hybrid vector-plus-keyword similarity searches with scores
Delete	/v3/atomic/delete	Removes up to 5,000 records atomically per request
Count	/v3/atomic/count	Returns the total number of records matching filter criteria

Updating and Overwriting Records

The /v3/atomic/update endpoint accepts a JSON payload containing the record_id and updated fields such as content, tags, or version. This operation is idempotent and mapped to the handleAtomicUpdate function within the gateway router.

Querying versus Hybrid Search

Use /v3/atomic/query for traditional filtering with pagination parameters. For semantic retrieval combined with keyword matching, the /v3/atomic/search endpoint performs hybrid similarity searches, returning results that include scored items arrays.

Bulk Deletion Constraints

The /v3/atomic/delete endpoint processes arrays of record IDs with a hard limit of 5,000 identifiers per request. This ensures atomic removal operations while preventing payload size violations.

Request Format and Tenancy Isolation

All atomic memory endpoints enforce strict multi-tenancy through required HTTP headers. You must include x-tdai-service-id (representing the service boundary) along with optional team and user identifiers to isolate data boundaries. Request bodies must conform to the ApiResponseEnvelope structure, with endpoint-specific payloads nested within the standardized wrapper.

Source Code Architecture

According to the TencentDB Agent Memory source code, the routing logic resides in MemoryCore/src/gateway/v2-router.ts. Lines 59-63 define the V3-allowed sub-paths list that authorizes the /v3/atomic/* routes, while lines 419-423 map each path to its concrete handler implementation:

• handleAtomicUpdate processes /v3/atomic/update requests
• handleAtomicQuery processes /v3/atomic/query requests
• handleAtomicSearch processes /v3/atomic/search requests
• handleAtomicDelete processes /v3/atomic/delete requests
• handleAtomicCount processes /v3/atomic/count requests

Runtime payload validation relies on Zod schemas defined in MemoryCore/src/gateway/generated/schemas.ts. TypeScript interfaces for client SDKs are exported from MemoryCore/src/gateway/generated/types.ts.

Practical Code Examples

The following TypeScript examples demonstrate authenticated requests to the atomic memory endpoints using standard fetch:

// Update or create an atomic memory record
await fetch('https://your-host/v3/atomic/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tdai-service-id': 'svc-123',
  },
  body: JSON.stringify({
    record_id: 'rec-456',
    content: { title: 'New title', body: 'Updated text' },
  }),
});

// Perform hybrid vector + keyword search
await fetch('https://your-host/v3/atomic/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tdai-service-id': 'svc-123',
  },
  body: JSON.stringify({
    query: 'machine learning',
    top_k: 10,
  }),
});

Summary

• Five POST endpoints under /v3/atomic/* provide complete lifecycle management for atomic memory records in TencentDB Agent Memory.
• Bulk deletion supports up to 5,000 record IDs per request via /v3/atomic/delete.
• Hybrid search capabilities combine vector similarity and keyword matching through /v3/atomic/search, returning scored results.
• Tenancy isolation requires x-tdai-service-id headers parsed by the gateway in MemoryCore/src/gateway/v2-router.ts.
• Request validation relies on Zod schemas in MemoryCore/src/gateway/generated/schemas.ts.

Frequently Asked Questions

What is the maximum number of records I can delete in a single API call?

The /v3/atomic/delete endpoint accepts an array of record IDs with a maximum limit of 5,000 identifiers per request. Exceeding this threshold will result in a validation error, requiring you to batch deletions across multiple calls.

Are there GET endpoints available for querying atomic memory?

No, all API endpoints for managing atomic memory use the POST method exclusively, including query and count operations. This design supports complex JSON filter bodies and large vector payloads that exceed URL length limitations.

How does the hybrid search endpoint differ from standard query?

The /v3/atomic/search endpoint executes vector similarity searches combined with keyword filtering, returning results with relevance scores. In contrast, /v3/atomic/query performs traditional metadata filtering by type, time range, or tags without semantic similarity calculation.

Where are the TypeScript types for these endpoints defined?

TypeScript interfaces and client contracts reside in MemoryCore/src/gateway/generated/types.ts. Runtime validation schemas are located in MemoryCore/src/gateway/generated/schemas.ts adjacent to the router implementation in v2-router.ts.

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