How to Set Up TencentDB Agent Memory in Standalone Mode

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

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

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

This process installs dependencies, compiles the gateway server (defined in 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 inside the container.

cp tdai-gateway.standalone.yaml tdai-gateway.yaml

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

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) 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 file:

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:

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

Verify the Installation

Confirm the service is healthy by querying the health endpoint:

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

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

{
  "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) are operational.

Key Source Files and Architecture

Understanding the core files helps with troubleshooting and customization:

• 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: 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: 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: 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 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.
• 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 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 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 before mounting it into the container. The gateway server defined in 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. 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.

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