# How to Configure TencentDB Agent Memory: Complete Setup Guide

> Learn to configure TencentDB Agent Memory with this complete setup guide. Deploy Memory Core, Hub, and Proxy using Docker Compose for unified AI agent collaboration.

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

---

**TencentDB Agent Memory provides a unified Memory Hub where multiple AI agents share chat history, skills, documentation, and code‑graph knowledge through three containerized services—Memory Core (port 8420), Memory Hub (port 8125), and Proxy (port 8096)—deployed via a single Docker Compose bootstrap.**

TencentDB Agent Memory is an open‑source project by TencentCloud that eliminates repetitive context‑setting in LLM workflows. By configuring this system, you create a persistent knowledge layer that multiple frameworks—such as Claude Code, CodeBuddy, or DeepSeek Harness—can access without modifying core agent logic.

## Architecture Overview

The platform consists of three distinct containers that run as a unified stack. Understanding each component helps you configure the system correctly and troubleshoot connectivity issues.

- **Memory Core** (port `8420`): The data plane service that stores raw conversations in SQLite and runs an asynchronous extraction pipeline. According to the source code in `MemoryCore/`, this service transforms L0 raw chat turns into L1 atomic facts, L2 scenarios, and L3 composite personas.
- **Memory Hub** (port `8125`): A React‑based web dashboard where you create the **Team → Agent → Task** hierarchy. You attach assets (Chat Memory, Skills, Wiki pages, CodeGraph symbols) to this triple, governed by ACLs (`private`, `team`, or `restricted`).
- **Proxy** (port `8096`): A thin HTTP gateway implemented in `MemoryProxy/`. It validates tokens, executes the *session‑init picker* (Team → Agent → Task selection), and injects selected L2/L3 memory assets into each LLM request before forwarding to upstream providers.

## Initial Configuration

Before launching services, ensure Docker Compose is available and you have cloned the repository locally.

### Environment Preparation

Copy the example environment file and edit credentials for your upstream LLM provider. The `deploy/global-images/.env.example` template contains all required variables, including `MEMORY_*` and `PROXY_*` settings for endpoint URLs and API keys.

```bash
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
cp .env.example .env

# Edit .env to add your LLM credentials

```

### Launching the Stack

Run the bootstrap 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 single command launches all three containers, creates an admin user, and generates an `admin-key` token.

```bash
./verify.sh        # Optional: runs sanity checks

./start-all.sh     # Boots Core, Hub, and Proxy

```

After execution, the script prints an `export` block containing your `admin-key` (formatted as `sk-mem-…`). Capture this value immediately, as it grants full administrative access to the Memory Hub.

```bash
ADMIN_KEY=$(cat .admin-key)

```

## Integrating LLM Clients

Once the core services run, configure your LLM clients to route through the **Proxy** on port `8096`. The proxy intercepts requests, attaches the appropriate memory context, and forwards them to the upstream model.

### Claude Code Configuration

Set environment variables to point Claude Code at your local proxy. The path `/claude-code/default` triggers the session‑init picker, allowing you to select a Team, Agent, and optional Task at startup.

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN="$ADMIN_KEY"
claude --model <PROXY_UPSTREAM_MODEL>

```

### CodeBuddy Configuration

For CodeBuddy, create a model definition in `~/.codebuddy/models.json` that references the proxy endpoint. The `apiKey` field accepts either the admin key or a business user token.

```json
{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "name": "proxy-memory-agent",
      "vendor": "claude",
      "apiKey": "<business-user-sk-mem-…>",
      "maxInputTokens": 200000,
      "url": "http://127.0.0.1:8096/codebuddy/default",
      "supportsToolCall": true,
      "supportsImages": true
    }
  ]
}

```

When the client starts, the proxy automatically presents the session‑init picker:

1. Choose Team
2. Choose Agent
3. (Optional) Choose Task

After selection, every request receives injected Skills, Wiki pages, and CodeGraph data via the system prompt.

### Creating Business Users

For production workflows, avoid using the admin key directly. Instead, create scoped business users via the Memory Core API at `localhost:8420`. The Python SDK available in [`sdk/memory-core/python/tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py) wraps these calls, or you can use raw HTTP:

```bash
curl -X POST http://localhost:8420/v3/meta/user/create \
  -H "x-tdai-user-key: $ADMIN_KEY" \
  -H "x-tdai-service-id: default" \
  -H "Content-Type: application/json" \
  -d '{"username":"developer-one"}' | jq .

```

Save the returned `sk-mem-…` token as the business user’s credential. This token respects the ACLs (`private`, `team`, `restricted`) defined in the Memory Hub for fine‑grained asset access.

## Memory Pipeline and Data Flow

Understanding how data moves through the system ensures you configure retention and extraction policies correctly. As implemented in `MemoryCore/`, the pipeline processes chat history through four levels:

- **L0**: Raw conversation turns stored immediately upon receipt
- **L1**: Atomic fact extraction from raw logs
- **L2**: Scenario building that contextualizes facts within task workflows
- **L3**: Persona composition that aggregates scenarios into agent‑level memory profiles

The Proxy injects L2 and L3 assets into the system prompt of every LLM request, enabling the model to "remember" previous work without token‑heavy history replay.

## Summary

- **Three‑service architecture**: Memory Core (8420), Memory Hub (8125), and Proxy (8096) run as a single Docker Compose stack via [`deploy/global-images/start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/start-all.sh).
- **Single bootstrap**: The [`start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/start-all.sh) script creates an admin user and prints a ready‑to‑use `sk-mem-…` token for immediate client configuration.
- **Hierarchical organization**: Assets attach to **Team → Agent → Task** triplets in the Memory Hub, governed by ACLs.
- **Universal client support**: Any HTTP‑compatible LLM client (Claude Code, CodeBuddy, DeepSeek Harness) connects through the Proxy on port `8096` and receives contextual memory injection automatically.
- **Security best practice**: Create business users via the Core API at `localhost:8420` instead of distributing the admin key.

## Frequently Asked Questions

### What ports need to be open for TencentDB Agent Memory to function?

You must expose three ports: **8420** for the Memory Core API, **8125** for the Memory Hub web dashboard, and **8096** for the Proxy gateway that LLM clients connect to. These are hardcoded in the Docker Compose configuration within `deploy/global-images/`.

### Can I use TencentDB Agent Memory with custom agent frameworks?

Yes. The Proxy implements a standard HTTP protocol, so any client capable of setting a custom `base_url` and `api_key` can connect. The repository includes integration examples in [`MemoryCore/hermes-plugin/memory/memory_tencentdb/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/hermes-plugin/memory/memory_tencentdb/client.py) for Hermes agents and [`MemoryProxy/scripts/qa/codex-tui-smoke.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/scripts/qa/codex-tui-smoke.py) for OpenAI Codex.

### How does the system handle data migration between versions?

The repository includes a migration utility at [`MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py) for upgrading older data formats to the current v3 schema. Always back up your SQLite files (stored in the Core container) before running migration scripts.

### What is the difference between L2 and L3 memory levels?

**L2 (Scenario)** memory represents contextualized facts tied to specific task workflows, while **L3 (Persona)** represents aggregated, agent‑level profiles composed from multiple scenarios. The Proxy injects both levels into the system prompt, but L3 provides higher‑level strategic context whereas L2 provides tactical, task‑specific details.