# How to Start the TencentDB Agent Memory Service

> Easily start the TencentDB Agent Memory service stack with interactive Docker scripts. Orchestrate containers and configure environments automatically for a seamless launch.

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

---

**Launch the complete TencentDB Agent Memory stack using the interactive Docker scripts in [`deploy/global-images/start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

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

```bash
./start-all.sh

```

This script performs the following sequence:

1. **Memory Core initialization** – Executes [`start-memory-core.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/start-memory-core.sh) to launch the backend container on port `8420`.
2. **Memory Hub startup** – Runs [`start-memory-hub.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/start-memory-hub.sh) to deploy the Panel UI and Knowledge service.
3. **Proxy deployment** – Calls [`start-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

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

```bash

# 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/start-all.sh) handles the full stack, individual components can be managed using their respective scripts:

- **Memory Core only**: [`./start-memory-core.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./start-memory-core.sh)
- **Memory Hub only**: [`./start-memory-hub.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./start-memory-hub.sh)
- **Proxy only**: [`./start-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./start-proxy.sh)

To stop services while preserving volumes and the admin key:

```bash
./stop-all.sh

```

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

```bash
./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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./start-all.sh) and stored in `deploy/global-images/.admin-key`. If you lose this key, stop the services using [`./stop-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.