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

> Explore client mode vs server mode in TencentDB Agent Memory. Understand context offload architecture and how each mode processes memory, choose the best for your needs.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: architecture
- Published: 2026-09-04

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/router.ts) for all memory operations. The Python SDK provides a convenient wrapper for these calls:

```python
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/scripts/install-openclaw-plugin.sh) enforces strict prerequisites, aborting if required secrets are missing:

```bash

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

```yaml
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts) via the `mode` property, with server mode requiring additional environment validation in [`scripts/install-openclaw-plugin.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.