How to Query and Search L1 Atomic Data by Type and Keyword in TencentDB Agent Memory

Use the /v3/atomic/query endpoint to filter L1 atomic records by type and time range, or the /v3/atomic/search endpoint to perform hybrid full-text + vector search by keyword, with optional type filtering on both.

The TencentDB Agent Memory repository implements a hierarchical memory architecture (L0 → L1 → L2 → L3) where L1 atomic records store single pieces of content with metadata including type, timestamps, and ownership fields. The TypeScript SDK and REST API expose two primary methods for retrieving these records based on structured filters or natural language queries.

Query L1 Atomic Data by Type

The query endpoint returns paginated L1 atomic records that match exact type criteria and optional time boundaries.

Endpoint Specification

Property	Value
HTTP method	POST
Path	/v3/atomic/query
SDK method	queryAtomic()

Request Parameters

Parameter	Type	Required	Description
type	string	No	Exact match on atomic type (e.g., "meeting_notes")
time_start	ISO 8601 string	No	Lower bound for updated_time filter
time_end	ISO 8601 string	No	Upper bound for updated_time filter
limit	integer	No	Page size (default: 20)
offset	integer	No	Pagination offset (default: 0)

Implementation Details

In MemoryCore/src/gateway/v2-router.ts, the handleAtomicQuery function (lines 13–68) processes incoming requests. The handler first validates the payload against atomicQueryRequestSchema defined in MemoryCore/src/gateway/v2-schemas.ts (line 33), then checks whether the backing store implements queryL1Paginated.

If queryL1Paginated is available, the router issues a database-level paginated query that respects isolation context (teamId, userId, agentId, taskId). Otherwise, it falls back to queryL1Records with in-memory filtering.

Code Example: TypeScript SDK

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

const client = new MemoryCoreClient({ baseURL: 'https://your-proxy/v3' });

const result = await client.queryAtomic({
  type: 'meeting_notes',
  time_start: '2024-01-01T00:00:00Z',
  time_end: '2024-12-31T23:59:59Z',
  limit: 10,
  offset: 0,
});
console.log(result.items); // Array of L1 atomic records

Code Example: cURL

curl -sSf -X POST https://your-proxy/v3/atomic/query \
  -H "Content-Type: application/json" \
  -d '{
    "type": "meeting_notes",
    "time_start": "2024-01-01T00:00:00Z",
    "time_end": "2024-12-31T23:59:59Z",
    "limit": 10,
    "offset": 0
  }'

Search L1 Atomic Data by Keyword

The search endpoint executes hybrid full-text and vector similarity search across L1 atomic records, with optional type and time constraints.

Endpoint Specification

Property	Value
HTTP method	POST
Path	/v3/atomic/search
SDK method	searchAtomic()

Request Parameters

Parameter	Type	Required	Description
query	string	Yes	Keyword or phrase for full-text + vector search
type	string	No	Restrict results to specific atomic type
time_start	ISO 8601 string	No	Start of temporal window
time_end	ISO 8601 string	No	End of temporal window
limit	integer	No	Maximum results (default: 5)

Implementation Details

The handleAtomicSearch function in MemoryCore/src/gateway/v2-router.ts (lines 92–178) delegates to executeMemorySearch, which performs three operations:

1. Builds isolation filter from team, user, agent, and task context — notably excluding sessionId so search spans all sessions for the same agent
2. Dispatches to vector store (ClickHouse or Milvus) with the supplied keyword
3. Returns ranked hits with relevance score and background metadata

The public API surface is registered in MemoryProxy/src/memory/memory-bridge.ts (line 47) under the atomic/search sub-path.

Code Example: TypeScript SDK

const searchResult = await client.searchAtomic({
  query: 'project kickoff',
  type: 'meeting_notes',  // Optional: narrow by type
  limit: 5,
});
console.log(searchResult.items); // Hits with score and background

Code Example: cURL

curl -sSf -X POST https://your-proxy/v3/atomic/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project kickoff",
    "type": "meeting_notes",
    "limit": 5
  }'

Key Differences: Query vs. Search

Aspect	Query (/v3/atomic/query)	Search (/v3/atomic/search)
Primary filter	Exact type match	Keyword/phrase relevance
Search mechanism	Database filter + pagination	Hybrid full-text + vector similarity
Required parameter	None (can list all)	query string
Default limit	20	5
Use case	Browse records of known type	Find semantically relevant content
Cross-session scope	Respects full isolation context	Excludes sessionId, spans agent sessions

Access Control and Availability

Both endpoints enforce store availability checks but rely on higher layers (e.g., UI panel proxies) for additional ACL validation. The V2 API gateway in v2-router.ts handles request routing and schema validation before forwarding to store implementations like sqlite-store.ts or code-graph-service.ts.

Summary

• /v3/atomic/query — Paginated type-based retrieval with optional time filtering; uses queryL1Paginated when available
• /v3/atomic/search — Hybrid keyword search across agent sessions; leverages executeMemorySearch with vector store backends
• Isolation context — Both endpoints respect teamId, userId, agentId, and taskId; search deliberately omits sessionId for broader recall
• SDK convenience — queryAtomic() and searchAtomic() methods in MemoryCoreClient encapsulate HTTP logic and schema validation

Frequently Asked Questions

What is the difference between L1 atomic query and search in TencentDB Agent Memory?

Query performs exact filtering on metadata fields like type with database-level pagination. Search executes hybrid full-text + vector similarity matching on content, returning ranked results by relevance score. Query is optimized for browsing; search is optimized for discovery.

Can I combine type filtering with keyword search?

Yes. The /v3/atomic/search endpoint accepts an optional type parameter that pre-filters the result set before vector similarity ranking. This allows targeted semantic search within specific atomic categories such as "meeting_notes" or "code_snippets".

Why does L1 search exclude sessionId from the isolation filter?

The executeMemorySearch implementation deliberately omits sessionId so that keyword search spans all sessions belonging to the same agent. This design enables cross-session memory recall while maintaining boundaries at the team, user, and agent levels.

What vector stores does the L1 search support?

The repository abstracts vector storage through configurable backends. The source code references ClickHouse and Milvus as concrete implementations in MemoryCore/src/store/, though the interface allows additional providers via the store abstraction layer.

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