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

> Easily install TencentDB Agent Memory using Docker. Follow our complete setup guide to clone the repository and run the start script for automated deployment.

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

---

**To install TencentDB Agent Memory using Docker, clone the TencentCloud/TencentDB-Agent-Memory repository and run the [`deploy/global-images/start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/start-all.sh) script for automated full-stack deployment, or deploy individual components using pre-built images or custom Dockerfiles.**

TencentDB Agent Memory is an open-source memory layer for LLM agents that provides persistent context, skills injection, and knowledge retrieval. According to the TencentCloud/TencentDB-Agent-Memory source code, the system is delivered as a set of Docker images that can be deployed independently or as an integrated stack.

## Architecture Overview

The platform consists of three containerized services defined in separate Dockerfiles:

| Service | Purpose | Dockerfile Location | Default Port |
|---------|---------|-------------------|--------------|
| **Memory Core** | KV store and pipeline worker for memory operations | `MemoryCore/Dockerfile` | 8420 |
| **Memory Hub** | Web panel UI and knowledge service | `MemoryKnowledge/Dockerfile` | 8125 (UI), 8424 (API) |
| **Memory Proxy** | LLM request gateway that injects memory context | `MemoryProxy/Dockerfile` | 8096 |

## Full Stack Installation (Recommended)

The quickest way to install TencentDB Agent Memory using Docker is the automated helper script located at [`deploy/global-images/start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/start-all.sh). This script orchestrates the build process, environment configuration, and container startup.

```bash
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
./start-all.sh

```

The **[`start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/start-all.sh)** script performs the following actions:

1. Generates a `.env` file from the `.env.example` template
2. Prompts for LLM endpoint credentials for both internal services and upstream LLM forwarding
3. Validates LLM connectivity before launching containers
4. Builds the three Docker images and starts containers with `docker run -d`
5. Creates an admin user and outputs a `sk-mem-...` token for agent authentication

Upon completion, the services are available at:
- **Memory Core**: `http://localhost:8420`
- **Memory Hub UI**: `http://localhost:8125`
- **Knowledge API**: `http://localhost:8424`
- **Memory Proxy**: `http://localhost:8096`

**Verification mode**: Run [`./verify.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./verify.sh) to check configuration without starting containers, or `./verify.sh --skip-llm` to bypass LLM connectivity checks.

## Deploying Individual Components

For scenarios requiring custom builds or partial deployments, build and run each service independently.

### Building Memory Core from Source

The **Memory Core** provides the underlying storage and processing layer. Build from the repository root using the `MemoryCore/Dockerfile`:

```bash
cd MemoryCore
docker build -t tencentdb-agent-memory:latest .
docker run -d --name tdai-memory-core \
  -p 8420:8420 \
  -v tdai-core-data:/data/tdai-memory \
  tencentdb-agent-memory:latest

```

### Running Memory Hub Only

When connecting to an existing Memory Core instance, deploy only the **Memory Hub** using the pre-built image from Docker Hub:

```bash
docker pull docker.io/agentmemory/memory-hub:latest

docker run -d --name tdai-memory-hub \
  --add-host=host.docker.internal:host-gateway \
  -p 8125:8125 -p 8424:8424 \
  -v tdai-panel-data:/data/knowledge \
  -e REMOTE_INSTANCE_URL=http://host.docker.internal:8420 \
  -e REMOTE_INSTANCE_KEY=local \
  -e KNOWLEDGE_PUBLIC_BASE_URL=http://host.docker.internal:8424/v3 \
  -e LLM_MODE=custom \
  -e LLM_BASE_URL=https://api.openai.com/v1 \
  -e LLM_API_KEY=sk-your-api-key \
  -e LLM_MODEL=gpt-4o \
  docker.io/agentmemory/memory-hub:latest

```

Access the web panel at `http://localhost:8125`. The hub requires the `REMOTE_INSTANCE_URL` pointing to your Memory Core endpoint.

### Building Memory Proxy

The **Memory Proxy** handles LLM request interception and context injection. Build from the `MemoryProxy` directory:

```bash
cd MemoryProxy
docker build -t memory-proxy:latest .
docker run -d --name tdai-memory-proxy \
  -p 8096:8096 \
  memory-proxy:latest

```

## Configuring LLM Clients

After installation, configure supported LLM clients to route requests through the Memory Proxy.

### Claude Code Integration

Set the following environment variables to redirect Claude Code through the proxy:

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN="sk-mem-your-token"
claude --model claude-3-5-sonnet-20240620

```

The proxy reads the `user_key` from the request header, queries the Memory Core for associated Teams/Agents/Tasks, and automatically enriches prompts with L2/L3 memory, skills, and knowledge.

### Other Supported Agents

Configuration examples for additional agents (CodeBuddy, WorkBuddy, etc.) are located in the `agents/` directory of the repository. Each agent subdirectory contains specific routing configuration and environment variable examples.

## Managing the Deployment

Stop containers while preserving data and configuration:

```bash
./stop-all.sh

```

Complete removal including volumes, admin keys, and generated configuration:

```bash
./stop-all.sh --purge

```

## Summary

- Use **[`deploy/global-images/start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/start-all.sh)** to install TencentDB Agent Memory using Docker with automated builds, configuration generation, and LLM validation
- **Memory Core** exposes port **8420** for data persistence and pipeline operations
- **Memory Hub** serves the web panel on port **8125** and knowledge API on **8424**
- **Memory Proxy** intercepts LLM requests on port **8096** to inject memory context
- Pre-built Hub images are available at `docker.io/agentmemory/memory-hub:latest` for standalone deployments
- Execute **`./stop-all.sh --purge`** to completely remove containers, volumes, and environment files

## Frequently Asked Questions

### What are the system requirements for running TencentDB Agent Memory in Docker?

You need Docker Engine installed with support for volume mounts and host networking. The full stack exposes four ports (8420, 8125, 8424, 8096), so ensure these are available on your host machine. The containers require minimal CPU resources for basic operation, though LLM inference performance depends on your upstream provider.

### How do I connect the Memory Hub to an existing Memory Core instance?

Set the `REMOTE_INSTANCE_URL` environment variable to the Core's HTTP endpoint (e.g., `http://host.docker.internal:8420` for local Docker networks or `http://core-host:8420` for external hosts). Specify `REMOTE_INSTANCE_KEY` to authenticate the connection. These values are defined in the Hub's runtime configuration and documented in [`deploy/global-images/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/README.md).

### Can I use a custom LLM provider instead of OpenAI?

Yes. Set `LLM_MODE=custom` when launching the Hub or Proxy, then provide `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL` pointing to any OpenAI-compatible API endpoint. The [`start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/start-all.sh) script supports this configuration during the interactive setup phase, or you can manually edit the generated `.env` file before starting containers.

### Where is the configuration stored when using the start-all.sh script?

The script generates a `.env` file in the `deploy/global-images` directory based on the `.env.example` template. This file contains LLM credentials, port mappings, and service endpoints. Keep this file secure, as it stores API keys in plain text. Run `./stop-all.sh --purge` to delete this configuration along with container volumes.