How to Deploy TencentDB Agent Memory Using Docker Compose: Complete Setup Guide

Deploy TencentDB Agent Memory by cloning the repository, configuring environment variables from the docker/env.example template, and running docker compose --env-file docker/env.docker up -d from the MemoryKnowledge directory.

TencentDB Agent Memory is an open-source knowledge-augmented memory system for LLM agents, maintained by TencentCloud. The repository provides production-ready Dockerfiles and a Docker Compose configuration that lets you launch the entire stack—or individual components—in minutes. This guide walks through the exact steps to deploy using Docker Compose, based on the source code in the feat/server_team branch.

Architecture of the Docker Deployment

The system consists of four containerized services, each with its own build context and Dockerfile:

Service	Purpose	Key Source File
Knowledge Service	HTTP API (/v3) for storing and querying tool-call logs	MemoryKnowledge/docker-compose.yml
Core Gateway	Request/response router for the LLM-memory pipeline	MemoryCore/Dockerfile
Web Panel	Management UI for knowledge visualization and agent monitoring	MemoryPanel/web/Dockerfile
Proxy Service	Optional reverse-proxy for custom LLM endpoints (LLM_MODE=custom)	MemoryProxy/Dockerfile

Each service builds independently. The provided docker-compose.yml in MemoryKnowledge targets the Knowledge service as the primary entry point, with optional ClickHouse integration for persistent storage.

Prerequisites

Before deploying TencentDB Agent Memory with Docker Compose, ensure you have:

• Docker Engine 20.10+ and Docker Compose 2.0+
• Git for cloning the repository
• (Optional) jq for parsing JSON responses during verification

The repository assumes Linux/amd64 or Linux/arm64 hosts. No additional dependencies are required on the host system—all runtime requirements are containerized.

Step-by-Step Deployment

1. Clone the Repository

Navigate into the Knowledge service directory where the Docker Compose file resides:

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

2. Configure Environment Variables

The repository provides a template at docker/env.example. Copy this to docker/env.docker and customize for your deployment:

cp docker/env.example docker/env.docker

# Edit docker/env.docker with your preferred editor

The minimal required variables for a functional deployment are:

Variable	Purpose	Example
PUBLIC_URL	External URL where the Knowledge API is accessible	http://203.0.113.10:8421/v3
TMC_CALLBACK	Callback URL for TencentDB Agent integration (optional)	http://203.0.113.10:8123
LLM_MODE	LLM routing mode: proxy (default) or custom	custom
LLM_API_KEY	API key when using LLM_MODE=custom	sk-your-key-here
LLM_BASE_URL	Base URL for custom LLM provider	https://api.openai.com/v1

The MemoryKnowledge/docker-compose.yml uses env_file: docker/env.docker to inject these values into the container.

3. Launch with Docker Compose

From the MemoryKnowledge directory, run:

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

This command:

• Builds the team-knowledge image using the local Dockerfile (via build: .)
• Creates a named volume knowledge-data mounted at /app/data for persistence
• Exposes port 8421 by default (configurable via TEAM_KNOWLEDGE_HOST_PORT)
• Applies health-check monitoring on the /health endpoint

The --build flag ensures the image reflects any local changes. Subsequent starts can omit it unless the source changes.

4. Verify the Deployment

Confirm the container is healthy:

curl http://localhost:8421/health

Expected response:

{"status":"ok"}

Check container status:

docker compose ps
docker compose logs -f team-knowledge

Deploying the Full Stack

To run Core Gateway, Web Panel, and Proxy alongside Knowledge, extend the compose configuration. Create a docker-compose.full.yml in the MemoryKnowledge directory:

services:
  knowledge:
    extends:
      file: docker-compose.yml
      service: team-knowledge

  core:
    build: ../MemoryCore
    image: ${TEAM_CORE_IMAGE:-team-core:latest}
    ports:
      - "${TEAM_CORE_HOST_PORT:-8123}:8123"
    restart: unless-stopped
    env_file: docker/env.docker

  panel:
    build: ../MemoryPanel/web
    image: ${TEAM_PANEL_IMAGE:-team-panel:latest}
    ports:
      - "${TEAM_PANEL_HOST_PORT:-3000}:3000"
    restart: unless-stopped
    env_file: docker/env.docker

  proxy:
    build: ../MemoryProxy
    image: ${TEAM_PROXY_IMAGE:-team-proxy:latest}
    ports:
      - "${TEAM_PROXY_HOST_PORT:-8080}:8080"
    restart: unless-stopped
    env_file: docker/env.docker

Launch with:

docker compose -f docker-compose.full.yml --env-file docker/env.docker up -d

Each service references the same docker/env.docker file for consistent configuration.

Configuration Examples

Enable ClickHouse Persistence

Add to docker/env.docker for production-grade storage of tool-call logs:

KNOWLEDGE_CLICKHOUSE_ENABLED=true
KNOWLEDGE_CLICKHOUSE_URL=jdbc:clickhouse://clickhouse:9000
KNOWLEDGE_CLICKHOUSE_DATABASE=tool_call_logs
KNOWLEDGE_CLICKHOUSE_USER=default
KNOWLEDGE_CLICKHOUSE_PASSWORD=secure_password

You'll also need to add a ClickHouse service to your compose file or use an external instance.

Custom LLM Provider Setup

cat > docker/env.docker << 'EOF'
PUBLIC_URL=http://203.0.113.10:8421/v3
TMC_CALLBACK=http://203.0.113.10:8123
LLM_MODE=custom
LLM_API_KEY=sk-abcdef123456789
LLM_BASE_URL=https://api.anthropic.com/v1
EOF

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

Complete One-Line Deployment

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git && \
cd TencentDB-Agent-Memory/feat/server_team/MemoryKnowledge && \
cp docker/env.example docker/env.docker && \
sed -i 's|PUBLIC_URL=.*|PUBLIC_URL=http://'$(hostname -I | awk '{print $1}')':8421/v3|' docker/env.docker && \
docker compose --env-file docker/env.docker up -d --build && \
curl -s http://localhost:8421/health | jq .

Key Source Files Reference

File Path	Description
MemoryKnowledge/docker-compose.yml	Primary compose definition with build instructions, port mapping, volume, and health-check
MemoryKnowledge/Dockerfile	Node.js-based image; copies source and sets npm run start:prod entrypoint
MemoryCore/Dockerfile	Core gateway container build
MemoryPanel/web/Dockerfile	React-based web UI container build
MemoryProxy/Dockerfile	Proxy service for custom LLM routing
docker/env.example	Environment variable template with all configurable options

Production Considerations

• Port conflicts: The default ports (8421, 8123, 3000, 8080) can be overridden via TEAM_*_HOST_PORT variables
• Volume persistence: The knowledge-data named volume survives container restarts; back this volume for disaster recovery
• Secrets management: For production, migrate from env.docker to Docker Secrets or an external vault
• ClickHouse: The default deployment uses in-memory or file-based storage; enable ClickHouse for high-throughput scenarios
• Health monitoring: The built-in health-check in docker-compose.yml uses curl -f http://localhost:8421/health with 30s intervals

Summary

• Clone to feat/server_team/MemoryKnowledge and use the provided docker-compose.yml for single-command deployment
• Copy docker/env.example to docker/env.docker and set PUBLIC_URL plus LLM_MODE at minimum
• Run docker compose --env-file docker/env.docker up -d --build to start the Knowledge service
• Verify with curl http://localhost:8421/health before integrating with agents
• Extend the compose file to add Core, Panel, and Proxy services for a complete deployment
• Enable ClickHouse via environment variables when persistence requirements exceed local volume capacity

Frequently Asked Questions

Does TencentDB Agent Memory require all four services to run?

No. The Knowledge service functions independently and is the recommended starting point. The Core Gateway, Web Panel, and Proxy are optional components that add routing, UI, and custom LLM capabilities respectively. Deploy only what your use case requires.

What is the difference between LLM_MODE=proxy and LLM_MODE=custom?

proxy (default) routes LLM requests through Tencent's infrastructure. custom directs requests to your own LLM endpoint configured via LLM_BASE_URL and LLM_API_KEY. Set LLM_MODE=custom when using providers like OpenAI, Anthropic, or self-hosted models.

Where is data persisted in a Docker Compose deployment?

By default, data persists in a Docker named volume knowledge-data mounted at /app/data inside the Knowledge container. For production deployments, enable ClickHouse by setting KNOWLEDGE_CLICKHOUSE_ENABLED=true and providing JDBC connection details in your environment file.

Can I use an external ClickHouse instance instead of containerized storage?

Yes. Set KNOWLEDGE_CLICKHOUSE_URL to any accessible JDBC endpoint (e.g., jdbc:clickhouse://your-host:9000). The application connects via the ClickHouse JDBC driver; no additional compose service is required for external databases.

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