# TencentDB Agent Memory Deployment Modes: Standalone vs Service Configuration

> Discover TencentDB Agent Memory deployment modes: Standalone for local dev and Service for cloud production. Easily switch using the TDAI_DEPLOY_MODE environment variable.

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

---

**TencentDB Agent Memory supports two mutually exclusive deployment modes—Standalone for local development and Service for cloud-native production—selected via the `TDAI_DEPLOY_MODE` environment variable.**

The TencentCloud/TencentDB-Agent-Memory repository provides a unified Gateway binary that adapts its storage backend and state management based on your operational requirements. Whether you are running a single-agent sidecar on a laptop or deploying a multi-tenant memory hub across Kubernetes clusters, the deployment mode determines how vectors, documents, and state are persisted. Both modes expose identical HTTP APIs, ensuring seamless migration from local development to production without client-side changes.

## Overview of Deployment Architecture

The Gateway entry point at [`src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/server.ts) reads the `TDAI_DEPLOY_MODE` environment variable (defaulting to `standalone`) during initialization to select the appropriate adapter stack. This design allows the same binary to serve both lightweight edge deployments and enterprise-grade distributed systems.

| Mode | Storage Backend | State Backend | Multi-Tenant | External Dependencies |
|------|----------------|---------------|--------------|----------------------|
| **Standalone** | SQLite + local filesystem | In-process `Map`/`Timer` | Single `spaceId` only | None |
| **Service** | TCVDB (vector DB) + COS | Redis (distributed locks) | Per `service_id` isolation | TCVDB, COS, Redis |

## Standalone Mode

Standalone mode provides a zero-dependency deployment ideal for local development, Docker all-in-one containers, and offline environments. All data remains local to the host machine.

### Architecture and Storage Backend

In Standalone mode, the Gateway stores vector embeddings in a local SQLite database (`vectors.db`) and persists scene definitions, persona documents, and L0/L1 data in the local filesystem under `~/.memory-tencentdb/memory-tdai/`. State management—including memory caches and task timers—runs entirely in-process using JavaScript `Map` and `Timer` objects, eliminating network latency but limiting the deployment to a single instance.

As documented in [`README.deployment.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.deployment.md), this mode supports only one `spaceId`, making it suitable for single-agent sidecars or development workstations where external cloud services are unavailable.

### Configuration and Startup

No external services are required. The Gateway automatically creates necessary directories and databases on first launch.

```bash
cd MemoryCore
export TDAI_LLM_API_KEY="sk-xxx"
export TDAI_LLM_BASE_URL="https://api.deepseek.com/v1"
export TDAI_LLM_MODEL="deepseek-chat"

# TDAI_DEPLOY_MODE defaults to standalone if omitted

npx tsx src/gateway/server.ts

```

The default configuration in [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) specifies local ports and storage paths used by this mode. Since all state is in-process, terminating the process drops active timers but preserves persisted vectors and documents in the SQLite and filesystem stores.

## Service Mode

Service mode transforms the Gateway into a stateless, horizontally scalable service suitable for Kubernetes deployments and SaaS platforms. This mode requires external Tencent Cloud services for persistence and coordination.

### Cloud-Native Architecture

When `TDAI_DEPLOY_MODE=service`, the Gateway delegates storage responsibilities to **TCVDB** (Tencent Cloud Vector Database) for vector search and **COS** (Cloud Object Storage) for long-term document retention. Distributed state management—including task queues and locks—moves to **Redis**, allowing multiple Gateway replicas to coordinate without race conditions.

The initialization logic in [`src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/server.ts) loads Redis adapters for pub/sub and distributed locking when this mode is detected, as demonstrated in [`deploy/global-images/start-memory-core.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/start-memory-core.sh).

### Multi-Tenant Support

Service mode enables true multi-tenancy through the `x-tdai-service-id` HTTP header (or `TDAI_MEMORY_SERVICE_ID` environment variable). Each unique `service_id` represents an isolated tenant with dedicated namespaces in TCVDB and COS, preventing data leakage between different agent teams or customers.

### Configuration Requirements

Unlike Standalone mode, Service mode requires explicit configuration of cloud service endpoints:

```bash
docker run -d \
  -e TDAI_DEPLOY_MODE=service \
  -e TDAI_LLM_API_KEY="sk-xxx" \
  -e STATE_BACKEND=redis \
  -e REDIS_HOST=redis.internal \
  -e VDB_ENDPOINT="http://vdb.internal:8100" \
  -e COS_URL="https://my-bucket.cos.ap-guangzhou.myqcloud.com" \
  -e TDAI_MEMORY_SERVICE_ID="agent-code-assistant" \
  -p 3100:3100 \
  agentmemory/hermes-memory:latest

```

Refer to [`MemoryCore/hermes-plugin/memory/memory_tencentdb_v2/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/hermes-plugin/memory/memory_tencentdb_v2/README.md) for client-side configuration when connecting Hermes agents to a Service-mode Gateway.

## Switching Between Modes

Migration between modes requires only environment variable changes, though data is not automatically migrated between local SQLite and TCVDB. To switch modes:

```bash

# Stop existing Gateway

pkill -f "gateway/server.ts"

# Launch in Service mode

export TDAI_DEPLOY_MODE=service
export REDIS_HOST=redis.example.com
npx tsx src/gateway/server.ts

```

Both modes expose identical **v1/v2 HTTP APIs** (including `/health`, `/search/memories`, and `/v2/atomic/add`), ensuring that Hermes plugins and SDK clients require no code changes—only endpoint and credential updates.

## Summary

- **TencentDB Agent Memory** offers **Standalone** (local) and **Service** (distributed) deployment modes controlled by the `TDAI_DEPLOY_MODE` environment variable.
- **Standalone mode** uses SQLite and local filesystem storage with in-process state, requiring zero external dependencies.
- **Service mode** requires TCVDB, COS, and Redis backends, supporting horizontal scaling and multi-tenant isolation via `service_id`.
- Both modes share the same Gateway binary at [`src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/server.ts) and expose identical REST APIs, enabling seamless development-to-production workflows.
- Configuration files including [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) and deployment scripts in `deploy/global-images/` provide ready-to-use templates for both scenarios.

## Frequently Asked Questions

### What is the default deployment mode for TencentDB Agent Memory?

The default mode is **Standalone**. If you do not set the `TDAI_DEPLOY_MODE` environment variable, the Gateway initializes with SQLite storage and in-process state management, as implemented in the server initialization logic at [`src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/gateway/server.ts).

### Can I run multiple Gateway instances in Standalone mode?

No. Standalone mode maintains state in-process using JavaScript `Map` and `Timer` objects and locks to a single `spaceId`. For concurrent multi-instance deployments, you must switch to **Service** mode with Redis as the state backend to enable distributed coordination.

### How do I configure multi-tenancy in Service mode?

Set the `TDAI_MEMORY_SERVICE_ID` environment variable (or pass the `x-tdai-service-id` header in requests) to isolate tenant data. Each unique identifier maps to separate namespaces in TCVDB and COS, ensuring complete data segregation between different agents or customer organizations.

### Are the HTTP APIs identical between Standalone and Service modes?

Yes. Both modes expose the same **v1/v2 HTTP API surface**, including endpoints like `/health`, `/search/memories`, and `/v2/atomic/add`. Clients such as Hermes plugins (documented in [`MemoryCore/hermes-plugin/memory/memory_tencentdb_v2/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/hermes-plugin/memory/memory_tencentdb_v2/README.md)) can switch between modes by changing only the base URL and authentication headers.