# How to Set Up TencentDB Agent Memory in Standalone Mode

> Learn how to set up TencentDB Agent Memory in standalone mode. Deploy a single-process service in a Docker container using SQLite for efficient operation without external dependencies.

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

---

**TencentDB Agent Memory can deploy as a single-process service inside one Docker container using SQLite storage and in-process queues, eliminating the need for external Redis, Shark, or vector databases.**

Standalone mode packages the entire memory stack—gateway, memory engine, and optional skill module—into a self-contained runtime. This configuration is ideal for local development, rapid prototyping, or lightweight production deployments where minimizing infrastructure complexity is critical. The setup relies on the [`tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.standalone.yaml) configuration file and a Node.js-based Docker image built from the `MemoryCore/` directory.

## What Is Standalone Mode?

In standalone mode, TencentDB Agent Memory (TD AI Memory) operates as a solitary process without networked dependencies. According to the source code in [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts), the system uses an internal **stateful pipeline manager** to handle the complete L0→L3 memory lifecycle—capture, extraction, and persona generation—entirely within the application memory and a local SQLite database.

Key characteristics of this deployment model include:

- **Zero external dependencies**: No Redis, Shark, or external vector databases required.
- **SQLite backing store**: All persistent state resides in a local SQLite file managed by the gateway.
- **In-process message queues**: The pipeline uses internal queues rather than distributed message brokers.
- **Single HTTP endpoint**: The gateway exposes port `8420` by default, handling all API requests directly.

## Prerequisites

Before starting, ensure you have the following:

- **Docker Engine** (version 20.10 or later) installed and running.
- **Git** to clone the repository.
- **LLM API credentials**: An API key for OpenAI, Anthropic, or compatible providers (set via environment variables).

## Step-by-Step Deployment Guide

### 1. Clone the Repository

Download the source code to access the Docker build context and configuration templates.

```bash
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/MemoryCore

```

The `MemoryCore/` directory contains the `Dockerfile`, the standalone configuration template, and the TypeScript source code compiled into the container image.

### 2. Build the Docker Image

The official `Dockerfile` uses `node:22-slim` as the base image and compiles the TypeScript source located in `MemoryCore/src/`.

```bash
docker build -t tencentdb-agent-memory:latest .

```

This process installs dependencies, compiles the gateway server (defined in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)), and prepares the runtime environment.

### 3. Configure the Gateway

Copy the standalone configuration template to the required filename. The gateway reads the file path specified by the `TDAI_GATEWAY_CONFIG` environment variable, defaulting to [`/data/config/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main//data/config/tdai-gateway.yaml) inside the container.

```bash
cp tdai-gateway.standalone.yaml tdai-gateway.yaml

```

The [`tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.standalone.yaml) file specifies:
- **State backend**: `local` mode using the in-process implementation.
- **Storage**: SQLite database path and connection settings.
- **LLM integration**: References to environment variables for API keys and model selection.

You may edit [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) to adjust logging levels or SQLite paths, but the defaults are sufficient for most standalone deployments.

### 4. Supply LLM Credentials

Set the required environment variables for your language model provider. The configuration file uses `${TDAI_LLM_API_KEY}` syntax to inject these values at runtime.

Required variables:
- `TDAI_LLM_API_KEY`: Your API key (e.g., `sk-...` for OpenAI).
- `TDAI_LLM_BASE_URL` (optional): Custom endpoint for compatible APIs.
- `TDAI_LLM_MODEL` (optional): Specific model identifier (defaults to GPT-4 if unspecified).

### 5. Run the Container

Launch the container with the configuration file mounted and ports exposed. The following command binds the local configuration to the container's expected path and exposes the gateway on localhost port 8420.

```bash
docker run -d --name tdai-memory \
  -v "$(pwd)/tdai-gateway.yaml:/data/config/tdai-gateway.yaml:ro" \
  -e TDAI_LLM_API_KEY=sk-your-key-here \
  -p 8420:8420 \
  tencentdb-agent-memory:latest

```

The gateway process (initialized in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)) initializes the local state backend, starts the HTTP server, and begins listening for memory operations.

## Docker Compose Configuration (Optional)

For easier management, use the following [`docker-compose.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/docker-compose.standalone.yaml) file:

```yaml
version: "3.9"
services:
  memory:
    image: tencentdb-agent-memory:latest
    ports:
      - "8420:8420"
    volumes:
      - ./tdai-gateway.yaml:/data/config/tdai-gateway.yaml:ro
    environment:
      TDAI_LLM_API_KEY: ${TDAI_LLM_API_KEY}

```

Deploy with:

```bash
docker compose -f docker-compose.standalone.yaml up -d

```

## Verify the Installation

Confirm the service is healthy by querying the health endpoint:

```bash
curl http://localhost:8420/health | jq .

```

A successful standalone deployment returns JSON indicating the local services are active:

```json
{
  "status": "ok",
  "services": {
    "timerScanner": { "isLeader": true },
    "pipelineWorker": { "workerId": "worker-..." },
    "stateBackend": "connected"
  }
}

```

The `stateBackend` field reports `connected` when the SQLite store and in-process pipeline manager ([`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts)) are operational.

## Key Source Files and Architecture

Understanding the core files helps with troubleshooting and customization:

- **[`MemoryCore/tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.standalone.yaml)**: Defines the standalone deployment mode, local state backend, SQLite storage configuration, and LLM environment variable mappings.
- **[`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)**: Main HTTP server entry point that wires the standalone adapter, registers API routes, and initializes the state backend.
- **[`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts)**: Implements the in-process memory pipeline exclusive to standalone mode, managing the capture, extraction, and generation worker threads without external queue services.
- **[`MemoryCore/README.docker.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.docker.md)**: Contains the official quick-start guide and Docker build instructions referenced in this setup.

## Summary

- **Standalone mode** runs TencentDB Agent Memory as a single Docker container without Redis, Shark, or external vector databases.
- The deployment uses **[`tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.standalone.yaml)** to configure local SQLite storage and in-process queue management.
- Build the image from **`MemoryCore/Dockerfile`** (Node.js 22 base) and mount your configuration to [`/data/config/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main//data/config/tdai-gateway.yaml).
- Expose port **8420** and provide **`TDAI_LLM_API_KEY`** via environment variables to enable the memory pipeline.
- Verify operation via the **`/health`** endpoint, which confirms the `stateBackend` and `pipelineWorker` are active.

## Frequently Asked Questions

### What external dependencies are required for standalone mode?

None. Standalone mode requires only the Docker container itself. It uses an internal SQLite database for persistence and the [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts) implementation for in-process message queuing, eliminating the need for Redis, Shark, or external vector stores.

### How do I configure LLM credentials in standalone mode?

Set the `TDAI_LLM_API_KEY` environment variable when running the container. The [`tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.standalone.yaml) file references this variable using `${TDAI_LLM_API_KEY}` syntax. Optionally, set `TDAI_LLM_BASE_URL` and `TDAI_LLM_MODEL` to customize the provider endpoint and model selection.

### Can I change the default port 8420?

Yes. While the default configuration exposes port 8420, you can modify the port mapping in your Docker run command (e.g., `-p 8080:8420`) or adjust the internal port by editing the server configuration in [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) before mounting it into the container. The gateway server defined in [`server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/server.ts) respects the port configuration provided in the YAML file.

### What is the difference between standalone and service mode?

Standalone mode runs all components—gateway, pipelines, and storage—in a single process using SQLite and in-memory queues, as implemented in [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts). Service mode (distributed deployment) requires external dependencies like Redis for state management and Shark or external vector databases for storage, enabling horizontal scaling across multiple instances. Standalone is optimized for simplicity and local development; service mode is designed for production scale.