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

> Learn how to enable remote embedding for TencentDB Agent Memory. Configure your openclaw.json file with provider details, API key, and model specs to integrate seamlessly. Restart the gateway to apply changes.

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

---

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

```json
{
  "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:

```bash
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:

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

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

```json
{
  "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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/env-config.ts) and [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.