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

> Deploy TencentDB Agent Memory with Docker Compose. Follow our guide to clone the repo, set env vars, and run the setup for a seamless deployment. Get started now!

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

---

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

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

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

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

```bash
curl http://localhost:8421/health

```

Expected response:

```json
{"status":"ok"}

```

Check container status:

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/docker-compose.full.yml) in the `MemoryKnowledge` directory:

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

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

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

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

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