How to Configure TencentDB Agent Memory: Complete Setup Guide

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.

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

./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.

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.

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.

{
  "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 wraps these calls, or you can use raw HTTP:

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.
• Single bootstrap: The 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 for Hermes agents and 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 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.

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