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

> Learn to set up TencentDB Agent Memory with Docker Compose. Deploy the full stack locally to orchestrate core services, Redis, and mock dependencies efficiently.

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

---

**Deploy the full TencentDB Agent Memory stack locally using [`MemoryCore/docker-compose.local.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/docker-compose.local.yaml) to orchestrate the core service, Redis, and mock dependencies on port 8420.**

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

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

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

```

### 3. Create the Environment File

Copy the example environment file to create your local configuration:

```bash
cp docker/env.example docker/env.docker

```

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

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

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

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

```

A successful deployment returns JSON similar to:

```json
{ "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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/docker-compose.yml) configuration:

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/docker-compose.yml)**: Provides a standalone "knowledge" microservice listening on port **8421**, designed for one‑shot local mode operations.
- **[`README.docker.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/docker-compose.local.yaml).
- **Port 8421**: Used by the knowledge service when running [`MemoryKnowledge/docker-compose.yml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.