# How to Configure the memory-tencentdb Plugin: Complete Environment and File Settings

> Configure the memory-tencentdb plugin using environment variables and YAML JSON files. Learn the priority order for settings to optimize your TencentDB agent performance.

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

---

**The memory-tencentdb plugin is configured through environment variables, YAML/JSON gateway configuration files, and OpenClaw plugin manifests, with settings resolving in a specific priority order from explicit file paths to environment overrides.**

The **memory-tencentdb** plugin serves as the core memory backend for the TencentDB Agent, persisting conversation history and contextual data for AI-driven database operations. According to the TencentCloud/TencentDB-Agent-Memory source code, the plugin supports multiple configuration layers that allow you to customize everything from network binding to LLM integration. Understanding these configuration settings ensures secure deployment across development, staging, and production environments.

## Core Configuration Methods

The plugin accepts configuration through three primary channels: environment variables for runtime overrides, structured configuration files for persistent settings, and plugin registry entries for OpenClaw and Hermes integration.

### Environment Variables

The MemoryCore gateway reads several environment variables to control runtime behavior. These variables override file-based configurations and are essential for containerized deployments.

- **`TDAI_GATEWAY_HOST`**: Bind address for the HTTP gateway. Default is `127.0.0.1`. Set to `0.0.0.0` for external exposure.
- **`TDAI_GATEWAY_PORT`**: TCP port for the gateway listener. Default is `8420`.
- **`TDAI_GATEWAY_API_KEY`**: Bearer token required when binding to non-loopback addresses. No default value; must be set for secure remote access.
- **`TDAI_CORS_ORIGINS`**: Comma-separated list of allowed origins for cross-origin requests. Empty by default.
- **`TDAI_DATA_DIR`**: Root directory for persisted memory files including SQLite databases and binary blobs. Defaults to `~/.memory-tencentdb/memory-tdai`.
- **`TDAI_LLM_API_KEY`**: API key for the OpenAI-compatible LLM service used for embeddings and generation. Empty by default.
- **`TDAI_LLM_BASE_URL`**: Base URL for the LLM endpoint. Default is `https://api.openai.com/v1`.
- **`TDAI_LLM_MODEL`**: Model identifier for memory-related LLM calls. Default is `gpt-4o`.
- **`TDAI_GATEWAY_CONFIG`**: Explicit path to a YAML or JSON configuration file. If unset, the gateway auto-discovers [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) or [`tdai-gateway.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.json) in the current or data directories.

### Gateway Configuration Files

In [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml), you define persistent gateway settings including TLS certificates, logging levels, and storage backends. The gateway resolves configuration files in the following priority order as implemented in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts):

1. File specified by `TDAI_GATEWAY_CONFIG` environment variable
2. [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) or [`tdai-gateway.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.json) in the current working directory
3. Same configuration files in the data directory (`TDAI_DATA_DIR`)
4. Environment variables (which override any file values)

### Plugin Registration

The plugin registers in OpenClaw through the manifest defined in [`MemoryCore/openclaw-plugin/openclaw.plugin.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/openclaw-plugin/openclaw.plugin.json). The canonical slot name is `memory-tencentdb-client` for v3 implementations, while `memory-tencentdb` remains supported for backward compatibility.

For Hermes integration, configure the provider in `~/.hermes/config.yaml` under the `memory` key, referencing the same gateway endpoint and API key used by MemoryCore.

## Installation and Setup Examples

Configure the gateway and install the plugin using the provided installation script and environment exports.

```bash

# Set up the gateway environment

export TDAI_GATEWAY_HOST="0.0.0.0"
export TDAI_GATEWAY_API_KEY="my-strong-token"
export TDAI_DATA_DIR="${HOME}/.memory-tencentdb/memory-tdai"
export TDAI_LLM_API_KEY="sk-xxxxxxxxxxxx"
export TDAI_LLM_MODEL="gpt-4o-mini"

# Start the MemoryCore gateway

node --import tsx MemoryCore/src/gateway/server.ts

```

Install the plugin into OpenClaw using the automated script:

```bash
bash MemoryCore/scripts/install-openclaw-plugin.sh

```

The [`install-openclaw-plugin.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/install-openclaw-plugin.sh) script performs three operations: it downloads the npm package `@tencentdb-agent-memory/memory-tencentdb`, builds the TypeScript sources, and registers the plugin in `~/.openclaw/openclaw.json` under the `plugins.slots.memory` key.

Verify the installation via CLI:

```bash
openclaw plugins list | grep memory-tencentdb

```

Configure Hermes to use the memory provider:

```yaml

# ~/.hermes/config.yaml

memory:
  provider: memory-tencentdb
  endpoint: "http://127.0.0.1:8420"
  api_key: "my-strong-token"

```

## Key Configuration Files

These source files define the complete configuration surface for the memory-tencentdb plugin:

| File Path | Purpose |
|-----------|---------|
| [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md) | Documents all runtime environment variables and quick-start procedures |
| [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml) | Default gateway configuration template with bind addresses and storage paths |
| [`MemoryCore/openclaw-plugin/openclaw.plugin.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/openclaw-plugin/openclaw.plugin.json) | Declares plugin ID (`memory-tencentdb`) and capability slots |
| [`MemoryCore/scripts/install-openclaw-plugin.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/scripts/install-openclaw-plugin.sh) | Automates npm installation and OpenClaw registry updates |
| [`MemoryCore/hermes-plugin/memory/memory_tencentdb/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/hermes-plugin/memory/memory_tencentdb/README.md) | Documents Hermes provider aliases and default data locations |
| [`MemoryCore/SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/SKILL.md) | Defines OpenClaw skill triggers for automatic plugin configuration |

## Summary

- The memory-tencentdb plugin uses **environment variables** for runtime overrides and **YAML/JSON files** for persistent configuration.
- Configuration resolution follows a strict priority order: explicit config file → discovered config files → environment variables.
- All persistent data defaults to `~/.memory-tencentdb/memory-tdai` but is configurable via `TDAI_DATA_DIR`.
- The [`install-openclaw-plugin.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/install-openclaw-plugin.sh) script automates registration in `~/.openclaw/openclaw.json` using the slot name `memory-tencentdb-client`.
- Hermes integration requires specifying the `memory_tencentdb` provider with matching endpoint and API key credentials.

## Frequently Asked Questions

### What is the default port for the memory-tencentdb gateway?

The default port is **8420**, controlled by the `TDAI_GATEWAY_PORT` environment variable. You can override this in [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) or via the environment variable before starting the gateway in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts).

### How do I secure the gateway when binding to external interfaces?

Set `TDAI_GATEWAY_HOST` to `0.0.0.0` for external access, but you **must** configure `TDAI_GATEWAY_API_KEY` with a strong bearer token. The gateway rejects unauthenticated requests when bound to non-loopback addresses, as enforced by the authentication middleware in the MemoryCore source.

### Where does the plugin store conversation history and embeddings?

All persisted data including SQLite databases, binary blobs, and index files reside in the directory specified by `TDAI_DATA_DIR`, defaulting to `~/.memory-tencentdb/memory-tdai`. This path is created automatically during the first run if it does not exist.

### Can I use a local LLM instead of OpenAI for embeddings?

Yes. Override `TDAI_LLM_BASE_URL` to point to your local OpenAI-compatible endpoint (such as Ollama or vLLM) and set `TDAI_LLM_MODEL` to your local model identifier. The plugin uses standard OpenAI SDK calls, so any API-compatible service works without code changes.