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

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.

In server.ts (lines 1484–1496), the handleSearchConversations function validates the request body and forwards it to the core processing layer:

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:

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

Core Search Implementation

The actual retrieval logic resides in 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 (lines 212–221) wraps the HTTP API with the searchConversation method:

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:

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 (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:

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 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. 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.

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