How to Start the TencentDB Agent Memory Service

Launch the complete TencentDB Agent Memory stack using the interactive Docker scripts in deploy/global-images/start-all.sh, which orchestrates the Memory Core, Memory Hub, and Proxy containers with automatic environment configuration.

The TencentDB Agent Memory service provides a persistent memory layer for LLM agents, enabling long-term context retention across conversations. According to the TencentCloud/TencentDB-Agent-Memory source code, the system deploys as three tightly-coupled containerized components that must run together. The repository provides automated shell scripts that handle the entire bootstrap process, from environment generation to LLM connectivity validation.

Component Architecture

Before starting the service, understand the three core components that comprise the architecture:

• Memory Core – The backend service that stores raw conversations, manages assets, and executes the L0→L3 memory processing pipeline. Exposes port 8420.
• Memory Hub – The web panel (Panel UI) for creating teams, configuring agents, and browsing knowledge assets. Runs on ports 8125 (UI) and 8424 (Knowledge service).
• Proxy – The LLM request gateway that intercepts upstream calls (e.g., Claude Code, CodeBuddy) and injects relevant memory, skills, and knowledge context. Listens on port 8096.

All three components are defined in the deployment scripts located at deploy/global-images/ in the repository root.

One-Click Docker Deployment

The recommended installation path uses the provided Docker-based startup scripts that automate dependency checks, environment file creation, and ordered container initialization.

Clone and Navigate

First, clone the repository and enter the global images deployment directory:

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images

Environment Configuration

The startup script automatically handles environment initialization. If .env does not exist, ./start-all.sh copies the template from .env.example and prompts for required values. The environment file configures two distinct LLM groups:

1. Memory LLM – Used by the Memory Core for embedding generation and memory processing.
2. Proxy LLM – Used by the Proxy component for upstream request handling.

Review .env.example to see all required variables, including API keys, endpoint URLs, and image tags.

Run the Interactive Starter

Execute the main orchestration script to launch the full stack:

./start-all.sh

This script performs the following sequence:

1. Memory Core initialization – Executes start-memory-core.sh to launch the backend container on port 8420.
2. Memory Hub startup – Runs start-memory-hub.sh to deploy the Panel UI and Knowledge service.
3. Proxy deployment – Calls start-proxy.sh to start the gateway on port 8096.

During execution, the script validates LLM connectivity, writes configuration values back to .env, and generates an admin authentication key stored in deploy/global-images/.admin-key.

Upon successful startup, the terminal prints a ready-to-use configuration block for Claude Code integration:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8096/claude-code/default
export ANTHROPIC_AUTH_TOKEN='sk-mem-<random-32-chars>'
claude --model <your-upstream-model>

Access the Web Panel

Once the containers report healthy status, open http://localhost:8125 in your browser. Log in using the user_key printed during startup (stored in the .admin-key file). From the Memory Hub interface, create your Team, Agent, and Task hierarchy to begin persisting conversation context.

Verify the Stack

Confirm all services are operational using the verification script or direct health checks:

# Run optional sanity check (skips LLM probing)

./verify.sh --skip-llm

# Check Memory Core health directly

curl -s http://localhost:8420/health | jq .

Manual Component Control

While start-all.sh handles the full stack, individual components can be managed using their respective scripts:

• Memory Core only: ./start-memory-core.sh
• Memory Hub only: ./start-memory-hub.sh
• Proxy only: ./start-proxy.sh

To stop services while preserving volumes and the admin key:

./stop-all.sh

To completely purge all data, including volumes and generated configuration:

./stop-all.sh --purge

Connecting Your LLM Client

Configure your local LLM client to route requests through the Proxy gateway. Set the base URL to http://127.0.0.1:8096/claude-code/default and use the authentication token format sk-mem-<random-32-chars> generated during startup. This ensures all agent interactions automatically leverage the persistent memory layer managed by the Memory Core.

Summary

• The TencentDB Agent Memory service requires three concurrent components: Memory Core (port 8420), Memory Hub (port 8125), and Proxy (port 8096).
• Use ./start-all.sh in deploy/global-images/ for automated, interactive deployment that handles .env creation and LLM validation.
• Access the administration panel at http://localhost:8125 using the key stored in .admin-key.
• Connect Claude Code or similar clients via http://127.0.0.1:8096/claude-code/default with the generated sk-mem-* token.
• Use ./stop-all.sh to halt services or ./stop-all.sh --purge for complete data removal.

Frequently Asked Questions

What are the minimum system requirements for running the TencentDB Agent Memory service?

The service runs in Docker containers and requires a system capable of running modern containerized workloads. You need Docker and Docker Compose installed, along with sufficient memory to run three concurrent containers (Memory Core, Memory Hub, and Proxy). The specific resource requirements depend on your LLM model sizes and conversation volumes processed through the L0→L3 pipeline.

Can I run the Memory Core, Memory Hub, and Proxy on different machines?

While the components communicate via HTTP, the provided start-all.sh script and the default .env.example configuration assume localhost deployment for simplified startup. For distributed deployment, you must manually update the endpoint URLs in .env to reflect the actual host addresses of each component, then start the services individually using their respective scripts.

How do I reset the admin key if I lose access to the Memory Hub panel?

The admin key is generated during the first run of ./start-all.sh and stored in deploy/global-images/.admin-key. If you lose this key, stop the services using ./stop-all.sh, delete the .admin-key file, and restart the stack. The initialization script will generate a new administrative credential automatically.

Why does the Proxy component use port 8096 instead of the standard Anthropic API port?

The Proxy acts as a local gateway that sits between your LLM client and upstream providers. Port 8096 is the default listening port defined in start-proxy.sh and .env.example. The Proxy intercepts requests at this port, enriches them with memory context from the Memory Core, and forwards them to your configured upstream LLM endpoint. You must configure your client (e.g., Claude Code) to use http://127.0.0.1:8096/claude-code/default rather than the standard Anthropic API endpoint.

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