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

> Learn how to query and search L1 atomic data in TencentDB Agent Memory using /v3/atomic/query for type and time filtering, or /v3/atomic/search for keyword and type searches.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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

```typescript
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

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/memory/memory-bridge.ts) (line 47) under the `atomic/search` sub-path.

### Code Example: TypeScript SDK

```typescript
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

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-router.ts) handles request routing and schema validation before forwarding to store implementations like [`sqlite-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sqlite-store.ts) or [`code-graph-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.