# How to Perform Keyword Search on L0 Conversations in TencentDB Agent Memory

> Learn to perform keyword search on L0 conversations in TencentDB Agent Memory using HTTP POST, SDKs, or OpenClaw. Retrieve semantically matching chat turns efficiently.

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

---

**Use the Conversation Search API via HTTP POST to `/v3/conversation/search`, the TypeScript or Python SDK `searchConversation` method, or the OpenClaw `tdai_conversation_search` tool to retrieve semantically matching raw chat turns from L0 memory layers.**

The TencentDB-Agent-Memory repository implements a hierarchical memory architecture where **L0 Conversations** represent the foundational layer of raw, unprocessed chat history. To retrieve specific messages from these raw turns, the platform exposes a unified **Conversation Search** interface that combines vector embeddings with optional session filtering.

## Architecture Overview: L0 Conversation Search

L0 (Level 0) conversations store every raw chat turn as individual memory records according to the "Memory isn't flat records — it grows in layers" design philosophy. When you perform keyword search on L0 conversations, the system embeds your query, compares it against stored vectors, and returns the top-N matching messages with relevance scores.

The search pipeline flows through four distinct layers:

- **Gateway Handler**: Parses incoming HTTP requests in `handleSearchConversations`
- **Core Logic**: Executes vector retrieval via `searchConversations` in the memory core
- **SDK Wrappers**: Provide language-specific client methods
- **OpenClaw Tools**: Expose LLM-friendly interfaces for agent integration

## HTTP API Endpoint

The primary entry point for keyword search on L0 conversations is the `POST /v3/conversation/search` endpoint implemented in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts).

In [`server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/server.ts) (lines 1484–1496), the `handleSearchConversations` function validates the request body and forwards it to the core processing layer:

```bash
curl -X POST http://localhost:8125/v3/conversation/search \
  -H "Content-Type: application/json" \
  -d '{"query":"database timeout","limit":5}'

```

The JSON response contains concatenated message texts and match metadata:

```json
{
  "results": "…",
  "total": 12
}

```

## Core Search Implementation

The actual retrieval logic resides in [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts) (lines 560–574). Here, the `searchConversations` method constructs a vector-store query, invokes the embedding service, and formats the ranked results.

This implementation supports **semantic similarity matching** rather than exact string matching, enabling you to find conceptually related messages even when keywords don't match exactly.

## SDK Client Methods

### TypeScript SDK

The TypeScript client 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) (lines 212–221) wraps the HTTP API with the `searchConversation` method:

```typescript
import { MemoryClient } from '@tencentdb-agent-memory/memory-sdk-ts-v2';

async function searchDemo() {
  const resp = await client.searchConversation({
    query: 'credential leak',
    limit: 3,
    session_id: 'sess-abc'
  });
  console.log('Found messages:', resp.messages);
}

```

### Python SDK

The Python implementation provides equivalent functionality through `search_conversation`:

```python
from tencentdb_agent_memory.v3.client import MemoryClient

client = MemoryClient(team_id='team1', agent_id='agentX')
result = client.search_conversation(query='timeout error', limit=4)
print(result.messages)  # Contains role, content, timestamp, score

```

Both SDKs accept three key parameters:

- `query`: The search keyword or phrase
- `limit`: Maximum results to return (optional, defaults vary by client)
- `session_id`: Optional filter to restrict search to a specific conversation session

## OpenClaw Tool Integration

For LLM agents, the `tdai_conversation_search` tool in [`MemoryCore/openclaw-plugin/src/tools/conversation-search.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/openclaw-plugin/src/tools/conversation-search.ts) (lines 12–30) provides a structured interface. The `handleConversationSearch` function wraps the SDK call and formats results for consumption by large language models.

Configure the tool in your agent manifest:

```yaml
tools:
  - name: tdai_conversation_search
    args:
      query: "memory overflow"
      limit: 2

```

The tool returns formatted output including message role, timestamp, and similarity score:

```

Found 2 matching message(s):

---
**[assistant]** [2024‑07‑12T08:15:23Z] (score: 0.987)
Memory overflow detected while processing large payloads.

---
**[user]** [2024‑07‑12T08:15:25Z] (score: 0.912)
Can we increase the vector store capacity?

```

## Summary

- **L0 conversations** represent raw, unprocessed chat history in the TencentDB Agent Memory hierarchy
- **Keyword search** uses semantic vector similarity rather than exact text matching via `POST /v3/conversation/search`
- **Four implementation layers** exist: HTTP gateway (`handleSearchConversations`), core logic (`searchConversations`), SDK clients (`searchConversation` method), and OpenClaw tools (`handleConversationSearch`)
- **Session filtering** allows restricting searches to specific conversation threads using the `session_id` parameter
- **Rich metadata** including relevance scores and timestamps accompanies all search results

## Frequently Asked Questions

### What is the difference between L0 and other memory layers in TencentDB Agent Memory?

L0 (Level 0) stores raw, unprocessed conversation turns exactly as they occurred, while higher layers (L1, L2) contain processed, summarized, or structured memory representations. Keyword search on L0 conversations retrieves the original message text with full context preservation, whereas searches on upper layers return condensed information.

### Can I filter L0 conversation searches by specific time ranges?

The current implementation in [`MemoryCore/src/core/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/tdai-core.ts) focuses on semantic similarity via vector search with optional `session_id` filtering. Time-based filtering is not explicitly implemented in the core search logic shown in lines 560–574, though timestamp metadata is returned in results for client-side filtering.

### How does the semantic search handle typos or synonyms in keywords?

The search system uses vector embeddings generated by the embedding service referenced in [`tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-core.ts). This enables semantic matching where conceptually similar terms (synonyms) or minor typos align closely in embedding space, returning relevant results even when exact keyword matches do not exist.

### Is there a rate limit for the conversation search API?

The source code analysis does not reveal specific rate limiting logic within the `handleSearchConversations` gateway handler (lines 1484–1496) or the core implementation. Rate limiting would typically be enforced at the gateway or load balancer level upstream from these functions.