How to Enable Remote Embedding for TencentDB Agent Memory: A Complete Configuration Guide

To enable remote embedding for TencentDB Agent Memory, add a complete embedding configuration block to your ~/.openclaw/openclaw.json file with your provider details, API key, and model specifications, then restart the OpenClaw gateway.

TencentDB Agent Memory (TD-AI) supports three retrieval strategies—keyword (BM25), embedding, and hybrid—but defaults to BM25 when remote embedding is disabled. To activate vector-based retrieval, you must configure the OpenClaw plugin (memory-tencentdb) with an OpenAI-compatible embedding endpoint. This guide walks through the exact configuration steps and source code implementation details from the TencentCloud/TencentDB-Agent-Memory repository.

Understanding the Retrieval Architecture

The system selects its retrieval mode based on the presence of a valid embedding client. According to MemoryCore/src/utils/stateful-pipeline-manager.ts, the recall pipeline checks for an active embedding configuration before executing vector similarity search. If the configuration is missing or invalid, the system silently falls back to BM25 keyword search.

The embedding client initialization occurs in MemoryCore/src/utils/env-config.ts, which parses the JSON configuration and constructs an HTTP client targeting your specified endpoint. This design allows the agent to support any OpenAI-compatible provider—including OpenAI, DeepSeek, or self-hosted models—without modifying core logic.

Step-by-Step Configuration

Locate the OpenClaw Configuration File

The memory-tencentdb plugin reads its settings from ~/.openclaw/openclaw.json. Create this file if it does not exist. All embedding parameters reside within the memory-tencentdb object under the embedding key.

Define the Embedding Block

Add a complete embedding configuration object to enable remote vectorization. The following fields are required:

• enabled: Set to true to activate the service.
• provider: Identifier for your vendor (e.g., "openai", "deepseek").
• baseUrl: The API endpoint URL (e.g., "https://api.openai.com/v1").
• apiKey: Your authentication token, referenced via environment variable syntax ${VAR_NAME}.
• model: The specific embedding model name (e.g., "text-embedding-3-small").
• dimensions: Vector output size matching your chosen model (e.g., 1536).

Optional fields include conflictRecallTopK, which specifies how many non-vector results to retain during hybrid search.

Example minimal configuration:

{
  "memory-tencentdb": {
    "enabled": true,
    "embedding": {
      "enabled": true,
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${EMBEDDING_API_KEY}",
      "model": "text-embedding-3-small",
      "dimensions": 1536
    }
  }
}

Secure Your API Key

Never commit raw API keys to version control. Export the key as an environment variable before starting the gateway:

export EMBEDDING_API_KEY="sk-your-actual-key-here"

The ${EMBEDDING_API_KEY} placeholder in the JSON file automatically resolves to this environment variable at runtime.

Restart the OpenClaw Gateway

Configuration changes require a gateway restart to take effect:

openclaw gateway restart

Upon startup, verify the logs for entries prefixed with [memory-tdai] indicating "Embedding client ready."

Selecting Retrieval Strategies

The recall.strategy parameter in your configuration determines how the system queries memory:

• keyword: Uses BM25 only, ignoring the embedding client even if configured.
• embedding: Performs pure vector similarity search using the remote service.
• hybrid: Combines BM25 and vector results, with conflictRecallTopK controlling the overlap buffer.

As documented in MemoryCore/v3-api-memorycore-doc.md, the pipeline automatically validates the embedding client availability before attempting vector queries. An invalid or unreachable endpoint triggers an immediate fallback to BM25 for that specific request.

Programmatic Usage

Within custom plugins or extensions, access the configured embedding client directly through the utility layer:

import { getEmbeddingClient } from '@tencentdb-agent-memory/memory-tencentdb/utils';

async function generateEmbeddings(texts: string[]) {
  const client = getEmbeddingClient(); // Reads from openclaw.json
  const vectors = await client.embed({ input: texts });
  return vectors;
}

This approach ensures consistency with the gateway's configuration without hardcoding endpoint details.

Full Production Configuration

For production deployments, include the embedding block alongside other memory management settings:

{
  "memory-tencentdb": {
    "enabled": true,
    "capture": {
      "enabled": true,
      "l0l1RetentionDays": 90,
      "cleanTime": "03:00"
    },
    "extraction": {
      "enabled": true,
      "enableDedup": true,
      "maxMemoriesPerSession": 10,
      "model": "provider/model"
    },
    "pipeline": {
      "everyNConversations": 5,
      "enableWarmup": true,
      "l1IdleTimeoutSeconds": 600,
      "l2DelayAfterL1Seconds": 10,
      "l2MinIntervalSeconds": 900,
      "l2MaxIntervalSeconds": 3600,
      "sessionActiveWindowHours": 24
    },
    "recall": {
      "enabled": true,
      "maxResults": 5,
      "scoreThreshold": 0.3,
      "strategy": "hybrid"
    },
    "persona": {
      "triggerEveryN": 50,
      "maxScenes": 15,
      "backupCount": 3,
      "sceneBackupCount": 10,
      "model": "provider/model"
    },
    "embedding": {
      "enabled": true,
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${EMBEDDING_API_KEY}",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "conflictRecallTopK": 5
    }
  }
}

Summary

• Remote embedding is disabled by default in TencentDB Agent Memory, falling back to BM25 keyword search.
• Configuration lives in ~/.openclaw/openclaw.json under the memory-tencentdb.embedding object.
• Required fields include enabled, provider, baseUrl, apiKey, model, and dimensions.
• Environment variable substitution (e.g., ${EMBEDDING_API_KEY}) keeps credentials secure.
• Retrieval strategy is controlled via recall.strategy and supports keyword, embedding, or hybrid modes.
• Source files MemoryCore/src/utils/env-config.ts and MemoryCore/src/utils/stateful-pipeline-manager.ts handle client initialization and pipeline selection.

Frequently Asked Questions

What happens if the embedding configuration is missing or incomplete?

If any required field is omitted or the endpoint is unreachable, the system automatically falls back to BM25 keyword retrieval. The stateful-pipeline-manager.ts logic validates the embedding client before each vector query, ensuring the agent remains functional even when the remote service fails.

Which embedding providers work with TencentDB Agent Memory?

Any provider implementing the OpenAI embedding API specification is compatible. This includes OpenAI, DeepSeek, Azure OpenAI Service, and self-hosted solutions like Ollama or Text Generation Inference. Set the provider name and baseUrl to match your vendor's requirements.

How do I verify that remote embedding is active?

Check the OpenClaw gateway logs for initialization messages containing [memory-tdai] and "Embedding client ready." Additionally, execute a memory search after storing test conversations; vector-based results will show similarity scores distinct from BM25 rankings, and the vectors.db file will populate with generated embeddings.

How do I switch between keyword and hybrid retrieval?

Modify the recall.strategy value in your openclaw.json file to "keyword", "embedding", or "hybrid", then restart the gateway. The change takes effect immediately for subsequent queries without requiring re-indexing existing memories.

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