# How to Query Atomic Memories by Type Using the TypeScript SDK

> Query atomic memories by type in your TypeScript app with the TencentDB SDK. Learn how to use MemoryClient.queryAtomic() and V3AtomicQueryRequest for efficient filtering.

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

---

**Use the `MemoryClient.queryAtomic()` method from the `@tencentdb/memory-core` package to filter atomic memories by passing a `type` string in the `V3AtomicQueryRequest` payload.**

The **TencentDB Agent Memory** platform stores individual notes as atomic memories (L1 layer) tagged with arbitrary type strings for categorization. When building applications with the **TypeScript SDK**, you retrieve specific memory categories using the `queryAtomic` method, which sends a `POST /v3/atomic/query` request and automatically handles session isolation. This guide demonstrates the exact implementation details found in the `TencentCloud/TencentDB-Agent-Memory` repository.

## Initializing the Client and Querying by Type

The `MemoryClient` class in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) provides the `queryAtomic` method as the primary entry point for retrieving filtered atomic memories. According to the source code at lines 79-88, the method accepts a `V3AtomicQueryRequest` object, automatically injects the current `session_id` for session isolation, and removes undefined fields before transmission.

To filter by type, populate the `type` field with your specific tag string:

```typescript
import { MemoryClient, V3AtomicQueryRequest } from '@tencentdb/memory-core';

// Initialise the client – assumes you have set up credentials elsewhere.
const memClient = new MemoryClient({
  baseUrl: 'https://api.tencentyun.com',
  credential: { secretId: 'YOUR_ID', secretKey: 'YOUR_KEY' },
});

// Example: fetch the first 20 atomic memories of type "meeting-notes".
async function fetchMeetingNotes() {
  const query: V3AtomicQueryRequest = {
    type: 'meeting-notes',   // ← filter by atomic memory type
    limit: 20,               // pagination: max items per page
    offset: 0,               // start from the first result
  };

  const result = await memClient.queryAtomic(query);
  console.log('Total matches:', result.total);
  result.items.forEach(item => {
    console.log(`- ${item.id}: ${item.content}`);
  });
}

fetchMeetingNotes().catch(console.error);

```

## Request Schema and Available Parameters

The request payload structure is defined in [`sdk/memory-core/typescript/src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/types.ts) at lines 111-119. The `V3AtomicQueryRequest` interface includes:

- **type**: The arbitrary string tag filtering criterion (e.g., `"todo"`, `"meeting-notes"`)
- **limit** and **offset**: Pagination controls
- **time_start** and **time_end**: Optional ISO 8601 timestamps for time-window filtering

Because the SDK is written in TypeScript, the interface provides compile-time safety for these parameters before the request reaches the transport layer.

## Server-Side Validation and Routing

When the SDK transmits the request, the TencentDB Agent Memory gateway validates the payload using Zod schemas. The core gateway registers the endpoint in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) at line 159, while the strict validation schema resides in [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts) at line 131.

This validation ensures that malformed type strings or incorrect date formats are rejected before the database query executes, returning a typed error response that the SDK propagates back through the `HttpTransport` layer defined in [`http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/http.ts).

## Advanced Filtering with Time Windows

Combine the `type` filter with temporal constraints to retrieve recent memories. The following example queries for `"todo"` items created within the last seven days:

```typescript
// Advanced: combine type filter with a time window (last 7 days)
import { subDays } from 'date-fns';

async function recentTodoItems() {
  const now = new Date();
  const weekAgo = subDays(now, 7);
  const query = {
    type: 'todo',
    time_start: weekAgo.toISOString(),
    time_end: now.toISOString(),
    limit: 50,
  };

  const { total, items } = await memClient.queryAtomic(query);
  console.log(`Found ${total} todo items from the past week.`);
}

```

The server returns a `V3AtomicQueryData` object containing the `total` count and the `items` array of matching atomic memories.

## Summary

- **Use `MemoryClient.queryAtomic()`** to execute filtered queries against the atomic memory layer.
- **Specify the `type` parameter** in `V3AtomicQueryRequest` to categorize results by arbitrary string tags.
- **Leverage automatic session isolation**—the SDK injects `session_id` in [`client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.ts) (lines 79-88) without manual configuration.
- **Combine filters** by adding pagination (`limit`, `offset`) or time range (`time_start`, `time_end`) parameters defined in [`types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/types.ts).
- **Trust server-side validation** via Zod schemas in [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts) to enforce data integrity.

## Frequently Asked Questions

### What string values are valid for the `type` parameter?

The `type` field accepts any arbitrary string tag you define when creating atomic memories. Common examples include `"todo"`, `"meeting-notes"`, or custom application-specific identifiers. The server treats this as an exact match filter without predefined enum constraints.

### Does the SDK automatically handle pagination for large result sets?

No, the SDK returns a single page of results based on the `limit` and `offset` values you provide in `V3AtomicQueryRequest`. You must implement client-side pagination logic by incrementing `offset` and making subsequent calls until you've retrieved the `total` count indicated in `V3AtomicQueryData`.

### How does the SDK maintain session isolation during queries?

The `queryAtomic` implementation in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) automatically extracts the current `session_id` from the client's internal state and injects it into the request payload. This ensures that queries only return atomic memories belonging to the active user session without requiring manual session configuration.

### What error response format does the SDK return for invalid type queries?

When the gateway validation fails—defined in [`MemoryCore/src/gateway/generated/schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/generated/schemas.ts)—or the transport layer encounters network issues, the SDK throws standard JavaScript `Error` objects with descriptive messages. For schema validation failures specifically, the error includes details about which `V3AtomicQueryRequest` fields violated the Zod constraints, allowing precise debugging of malformed type strings or invalid date formats.