How to Set Up TencentDB Agent Memory with Docker Compose: Complete Guide

Deploy the full TencentDB Agent Memory stack locally using MemoryCore/docker-compose.local.yaml to orchestrate the core service, Redis, and mock dependencies on port 8420.

TencentDB Agent Memory provides a four‑layer progressive memory service (L0 → L1 → L2 → L3) for AI agent frameworks. According to the TencentCloud/TencentDB-Agent-Memory source code, the recommended approach for local development is a TencentDB Agent Memory Docker Compose setup that automatically provisions the core service alongside its Redis dependency. This guide walks through the exact file paths, environment variables, and verification steps required to get the system running.

Prerequisites

Before starting the TencentDB Agent Memory Docker Compose setup, ensure your environment meets the following requirements:

• Docker version 20.10 or later and Docker Compose v2 installed.
• A clone of the repository, specifically the feat/server_team branch.
• (Optional) An OpenAI‑compatible LLM API key if you plan to run in custom LLM mode instead of the default proxy mode.

Step‑by‑Step Setup

Follow these sequential steps to launch the memory service using the provided compose templates.

1. Clone the Repository

First, obtain the source code from the feat/server_team branch:

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory
git checkout feat/server_team

2. Copy the Compose Template

The MemoryCore/docker-compose.local.yaml file contains a ready‑to‑run definition that includes Redis and the core service. Copy it to the repository root:

cp MemoryCore/docker-compose.local.yaml docker-compose.yaml

3. Create the Environment File

Copy the example environment file to create your local configuration:

cp docker/env.example docker/env.docker

Edit docker/env.docker to set the minimum required variables:

TDAI_LLM_API_KEY=sk-your-key
PUBLIC_URL=http://127.0.0.1:8420/v3

The core service reads these environment variables at startup, overriding defaults defined in tdai‑gateway.yaml.

4. Launch with Docker Compose

Start the stack by referencing your environment file:

docker compose --env-file docker/env.docker up -d --build

This command builds the images and starts the core memory service, Redis, and any optional mock services (such as mock‑Shark) defined in the compose file.

5. Verify the Deployment

Confirm the service is healthy by calling the health endpoint:

curl http://localhost:8420/health

A successful deployment returns JSON similar to:

{ "status":"ok", "version":"0.1.0" }

Alternative One‑Liner Setup

If you prefer inline environment variables rather than a separate .env file, you can launch the stack directly. This pattern is used in the MemoryKnowledge/docker-compose.yml configuration:

PUBLIC_URL=http://127.0.0.1:8420/v3 \
TMC_CALLBACK=http://127.0.0.1:8123 \
LLM_MODE=custom \
LLM_API_KEY=sk-your-key \
LLM_BASE_URL=https://api.example.com/v1 \
docker compose up -d --build

Core Compose Files Explained

The repository provides distinct compose files for different deployment scenarios:

• MemoryCore/docker-compose.local.yaml: Spawns the core service together with Redis and optional mock‑Shark dependencies. This is the primary file for local development.
• MemoryKnowledge/docker-compose.yml: Provides a standalone "knowledge" microservice listening on port 8421, designed for one‑shot local mode operations.
• README.docker.md: Contains detailed Docker usage guidelines and advanced configuration examples.

Configuration Details

Understanding the configuration system ensures stable production deployments.

Environment Variables

The core service consumes environment variables that override tdai‑gateway.yaml settings. Key variables include:

• TDAI_LLM_API_KEY: Required when using custom LLM mode.
• PUBLIC_URL: The external URL endpoint (e.g., http://127.0.0.1:8420/v3).
• REDIS_HOST: Points to the Redis instance (default: redis:6379 in the local compose setup).
• SCANNER_INTERVAL_MS: Controls background scanning frequency.

LLM Modes

• Proxy Mode (LLM_MODE=proxy): Uses the built‑in context proxy; no external API key required. This is the default.
• Custom Mode (LLM_MODE=custom): Requires valid LLM_API_KEY and optionally LLM_BASE_URL for OpenAI‑compatible endpoints.

Port Mapping

• Port 8420: Exposed by the core memory service defined in MemoryCore/docker-compose.local.yaml.
• Port 8421: Used by the knowledge service when running MemoryKnowledge/docker-compose.yml.

Common Pitfalls

Avoid these typical errors during setup:

• Missing Required Variables: The compose files use strict variable validation such as ${PUBLIC_URL:?set PUBLIC_URL}. Docker will fail immediately if PUBLIC_URL or TDAI_LLM_API_KEY (in custom mode) are undefined.
• Port Conflicts: Ensure ports 8420 and 8421 are free on the host machine before starting the containers.
• Redis Connectivity: When deployMode is set to service, the core expects a Redis instance at redis:6379. The local compose file automatically provisions this, but external deployments must provide their own Redis connection.

Summary

• TencentDB Agent Memory delivers a four‑layer memory architecture for AI agents.
• Use MemoryCore/docker-compose.local.yaml for standard local deployments, which includes Redis and health checks on port 8420.
• Configure the system via docker/env.docker or inline variables; critical settings include PUBLIC_URL and TDAI_LLM_API_KEY.
• Choose between proxy (default, no key needed) and custom (requires API key) LLM modes.
• Verify deployment by curling /health and checking for the status: ok response.

Frequently Asked Questions

What is the difference between MemoryCore and MemoryKnowledge compose files?

MemoryCore/docker-compose.local.yaml launches the full progressive memory service (L0‑L3) with Redis and mock dependencies on port 8420, designed for agent integration. MemoryKnowledge/docker-compose.yml runs a standalone knowledge microservice on port 8421 for isolated knowledge‑base operations without the full memory stack.

Why does my container fail with "set PUBLIC_URL" error?

The compose files enforce required environment variables using shell syntax ${VAR:?set VAR}. This error indicates the PUBLIC_URL variable is undefined. Create and populate docker/env.docker based on docker/env.example, or export the variable inline before running docker compose up.

Can I use a custom LLM instead of the built‑in proxy?

Yes. Set LLM_MODE=custom and provide TDAI_LLM_API_KEY (or LLM_API_KEY for the knowledge service) along with optional LLM_BASE_URL. When LLM_MODE is set to proxy (default), the system uses internal context handling and requires no external API credentials.

How do I check if the memory service is running correctly?

Execute curl http://localhost:8420/health. The core service, as implemented in the TencentCloud/TencentDB-Agent-Memory repository, returns a JSON object containing "status":"ok" and version information when healthy. If this endpoint is unreachable, verify that the container started successfully and that port 8420 is not blocked by a firewall.

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