Client Mode vs Server Mode in TencentDB Agent Memory: Context Offload Architecture Explained

Client mode delegates all L1-L3 memory processing to a remote offload server via HTTP API calls, while server mode runs the full compression and retrieval pipeline locally within the agent process.

TencentDB Agent Memory supports two distinct operational modes for context offloading that determine where the heavy lifting of memory processing occurs. Understanding the difference between client mode and server mode is critical for optimizing resource utilization, latency, and deployment architecture in the TencentCloud/TencentDB-Agent-Memory repository.

Core Architectural Differences

The primary distinction lies in where the L1-L3 memory processing—including ingestion, compression, embedding generation, and persona creation—is executed.

Client Mode: Stateless Forwarding

In client mode, the agent acts as a thin, stateless forwarder. It captures raw conversation data (L0) and immediately delegates all processing to a remote offload server.

According to the configuration in MemoryCore/src/config.ts, setting mode: "client" transforms the agent into a stateless client that forwards data to an external HTTP endpoint. The agent performs no local compression, embedding calculations, or storage operations. Instead, it relies entirely on the remote server's API endpoints (/v2/offload/ingest and /v2/offload/compact) to handle the full pipeline.

This architecture minimizes local CPU and RAM consumption on the agent host, making it ideal for edge deployments with limited resources. However, it introduces network latency for every memory operation, as data must travel to and from the remote offload server.

Server Mode: Stateful Local Processing

Server mode embeds the full offload server within the agent's runtime environment. When configured with mode: "server"—the default setting—the agent executes the complete L1-L3 pipeline locally through internal modules like offload-l1, offload-l2, and offload-l15.

As implemented in the MemoryCore/src/offload_server/ directory, the server mode processes capture data through local pipelines for extraction, deduplication, and embedding generation. The results are stored directly in the configured backend (SQLite or Tencent Cloud Vector Database) without external network calls.

Server mode requires significantly higher local resources, including CPU for compression algorithms and disk space for temporary JSONL files. However, it eliminates network round-trips, providing deterministic low-latency access to memory operations.

Configuration and Deployment Patterns

Enabling Client Mode

To activate client mode, modify the configuration TypeScript file:

// MemoryCore/src/config.ts
export const config = {
  mode: "client",               // Stateless client mode
  offloadServerUrl: "https://offload.example.com/v2",
  // No local compression code executed
};

In this configuration, the agent invokes the HTTP API implemented in MemoryCore/src/offload_server/router.ts for all memory operations. The Python SDK provides a convenient wrapper for these calls:

from tencentdb_agent_memory.v2 import client

mem_client = client.MemoryClient(
    base_url="https://offload.example.com",
    api_key="YOUR_OFFLOAD_API_KEY"
)

# Delegated to remote server

mem_client.offload_ingest(session_id="sess-123", messages=[...])
context = mem_client.offload_compact(session_id="sess-123")

Enabling Server Mode

Server mode requires additional validation and environment configuration. The installation script scripts/install-openclaw-plugin.sh enforces strict prerequisites, aborting if required secrets are missing:

# Required environment variables for server mode

export TDAI_MEMORY_MODE=server
export TDAI_MEMORY_API_KEY=YOUR_SECRET_KEY
export TDAI_MEMORY_SERVICE_ID=prod-instance
export TDAI_MEMORY_INSTANCE_ID=instance-01

A typical Docker Compose deployment for server mode looks like this:

services:
  memory-core:
    image: tencentdb/agent-memory:latest
    environment:
      - TDAI_MEMORY_MODE=server
      - TDAI_MEMORY_API_KEY=${API_KEY}
      - TDAI_MEMORY_SERVICE_ID=svc-001
    volumes:
      - ./data:/var/lib/memory  # Local persistence

Performance and Resource Characteristics

Client mode offers minimal local footprint because all L1-L3 compression, embedding generation, and MMD (Multi-Modal Dialogue) processing occur remotely. The agent only maintains network connections and basic state, consuming negligible CPU and memory. The trade-off is dependency on network stability and added latency for each memory operation.

Server mode consumes substantial local resources, including CPU cycles for running the compression pipelines and disk I/O for managing temporary JSONL files during processing. The benefit is zero external network dependency for memory operations and significantly faster retrieval times, as data never leaves the local process.

Security and Isolation Considerations

Client mode relies on token-based authentication against the remote offload server. The agent only needs the server endpoint URL and a valid bearer token, minimizing the attack surface on the client host. This model centralizes sensitive data processing on hardened infrastructure.

Server mode requires strict validation of TDAI_MEMORY_API_KEY, service IDs, and instance IDs as enforced by install-openclaw-plugin.sh. It also mandates a non-default isolation bucket configuration. This mode is preferable when compliance requirements dictate that memory processing must occur within a specific trusted environment or when network egress must be minimized for security reasons.

Summary

• Client mode acts as a stateless HTTP client, delegating all compression and retrieval to a remote server via /v2/offload/* endpoints, ideal for resource-constrained edge devices.
• Server mode runs the full offload server locally, executing L1-L3 pipelines internally without network calls, suitable for low-latency or air-gapped deployments.
• Configuration occurs in MemoryCore/src/config.ts via the mode property, with server mode requiring additional environment validation in scripts/install-openclaw-plugin.sh.
• Client mode minimizes local resource usage but adds network latency; server mode maximizes performance at the cost of CPU, memory, and disk requirements.
• Security models differ: client mode uses remote token validation, while server mode requires local API keys and isolation configuration.

Frequently Asked Questions

What configuration file controls the mode selection in TencentDB Agent Memory?

The operational mode is controlled in MemoryCore/src/config.ts through the mode property, which accepts either "client" or "server" (default) values. This setting determines whether the agent delegates processing to a remote endpoint or executes pipelines locally.

Does client mode require the same environment variables as server mode?

No. Client mode only requires the offloadServerUrl configuration and appropriate API tokens for the remote server. Server mode strictly enforces additional variables—including TDAI_MEMORY_API_KEY, TDAI_MEMORY_SERVICE_ID, and TDAI_MEMORY_INSTANCE_ID—through validation logic in scripts/install-openclaw-plugin.sh.

Can the Python SDK be used with both operational modes?

Yes. The Python SDK in sdk/memory-core/python/tencentdb_agent_memory/v2/client.py supports both modes. In client mode, it sends HTTP requests to the configured remote server. In server mode, when running locally, the SDK can interact with the internal server instance, though direct internal API calls are more common in server deployments.

Which mode should I choose for a multi-agent deployment with centralized memory management?

Choose client mode. This architecture allows numerous lightweight agents to forward memory operations to a single, centrally managed offload server. This consolidation reduces per-agent resource costs and simplifies maintenance by centralizing the L1-L3 processing pipeline and storage backend.

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