TencentDB Agent Memory Deployment Modes: Standalone vs Service Configuration

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

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 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 loads Redis adapters for pub/sub and distributed locking when this mode is detected, as demonstrated in 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:

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

# 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 and expose identical REST APIs, enabling seamless development-to-production workflows.
• Configuration files including 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.

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) can switch between modes by changing only the base URL and authentication headers.

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