What Storage Adapters Are Available for Context Offload in TencentDB Agent Memory?

TencentDB Agent Memory provides four concrete storage adapters for context offload: Tencent Cloud Object Storage (COS) for distributed production deployments, SQLite for local persistence, Filesystem (fs) for shared POSIX directories, and in-memory for ephemeral debugging sessions.

The TencentDB Agent Memory system persists contextual data—including session states, embeddings, and MMD files—to a pluggable storage backend. Developers select the appropriate storage adapter via the storage.backend configuration field, with implementations located in MemoryProxy/src/storage/ according to the source repository structure.

The Four Storage Adapters for Context Offload

TencentDB Agent Memory ships with four backend implementations that satisfy the storage-adapter interface. Each adapter serves distinct operational requirements, from cloud-native durability to lightweight local testing.

COS (Tencent Cloud Object Storage)

CosStorage (MemoryProxy/src/storage/cos-storage.ts) provides remote object storage backed by Tencent Cloud Object Storage (COS). This adapter offers durable, cross-node persistence and serves as the preferred backend for production multi-instance deployments behind load balancers.

SQLite (Local Database)

SqliteStorage (MemoryProxy/src/storage/sqlite-storage.ts) implements a local SQLite database using the native better-sqlite3 driver. This adapter provides a simple file-based database with automatic TTL-based cleanup, making it ideal for development, CI pipelines, or single-node testing scenarios.

Filesystem (FS)

FsStorage (MemoryProxy/src/storage/fs-storage.ts) stores each offload entry as a separate file under a configurable root directory. This adapter suits environments where the runtime already provides a shared POSIX directory (such as NFS mounts) and requires no external database dependencies.

Memory (Ephemeral)

MemoryStorage (MemoryProxy/src/storage/memory-storage.ts) maintains data in a pure in-memory map that lives only for the process lifetime. This adapter provides no persistence—all data is lost on restart—making it suitable for fast local debugging or unit tests that do not require durability.

How the Storage Factory Wires Adapters

The storage factory (MemoryProxy/src/storage/factory.ts) instantiates the concrete adapter based on the storage.backend configuration value. The factory implements a hardcoded selection logic:

// Excerpt from MemoryProxy/src/storage/factory.ts
switch (backend) {
  case "cos":    return new CosStorage(config.cos);
  case "sqlite": return new SqliteStorage(config.sqlite);
  case "fs":     return new FsStorage(config.fs);
  case "memory": return new MemoryStorage();
  default:       throw new Error(`Unsupported storage backend: ${backend}`);
}

If the requested backend fails to initialize (for example, due to a missing optional native dependency), the factory automatically degrades through the chain cos → sqlite → fs → memory to ensure the service remains operational. The effective backend is exposed via the /health endpoint.

Configuring Storage Adapters for Context Offload

Global configuration occurs in MemoryProxy/config.example.yaml or a custom YAML supplied at runtime. The storage section controls offload behavior:

storage:
  enabled: true               # turn the offload storage on/off

  backend: sqlite             # one of: cos | sqlite | fs | memory

  cos:
    bucket: "tdai-memory-proxy"
    region: "ap-beijing"
  sqlite:
    dbPath: "~/.tdai-memory-proxy/proxy.db"
  fs:
    rootDir: "/data/offload"

Changing the backend field switches the adapter instantly, subject to the degradation chain. The following TypeScript example demonstrates proxy initialization with configuration loading:

// server.ts – start the MemoryProxy
import { loadConfig } from "./config.js";
import { createProxy } from "./proxy.js";

const cfg = await loadConfig("/data/config.yaml");
const proxy = await createProxy(cfg);   // factory picks the configured adapter
await proxy.start();

The Python SDK automatically communicates with whichever backend the proxy uses, requiring no client-side storage configuration:

from tencentdb_agent_memory.v2 import Client

client = Client(base_url="http://localhost:8080")
client.offload_ingest(
    session_id="sess-123",
    messages=[{"role": "user", "content": "How to reset my password?"}],
)

Runtime Verification and Health Checks

Verify the effective storage backend at runtime using the health endpoint:

curl http://localhost:8080/health | jq .storage.effective

This returns the active adapter name (e.g., "sqlite"), confirming which implementation currently handles context offload after any degradation decisions.

Summary

• Four adapters implement context offload in TencentDB Agent Memory: COS (CosStorage), SQLite (SqliteStorage), Filesystem (FsStorage), and Memory (MemoryStorage).
• The storage factory (MemoryProxy/src/storage/factory.ts) instantiates adapters based on the storage.backend configuration field.
• A graceful degradation chain (cos → sqlite → fs → memory) ensures service continuity when primary backends fail to initialize.
• Runtime configuration occurs via YAML, with the active backend exposed through the /health endpoint for monitoring.

Frequently Asked Questions

Which storage adapter should I use for production deployments?

Use the COS adapter (backend: cos) for production multi-instance deployments. According to the TencentDB Agent Memory source code, COS provides durable, cross-node persistence required for agent fleets behind load balancers, while SQLite and Memory adapters suit development or single-node scenarios only.

What happens if my selected storage backend fails to initialize?

The storage factory implements automatic degradation. If COS fails to initialize (for example, due to missing credentials), the factory falls back through sqlite, then fs, then memory, ensuring the MemoryProxy service remains operational even with reduced durability.

How do I verify which storage backend is currently active?

Query the /health endpoint on your running instance. The response includes a storage.effective field indicating the active adapter (e.g., "sqlite" or "cos"), allowing you to confirm whether degradation occurred during startup.

Can I change the storage adapter without restarting the MemoryProxy?

No. While the configuration YAML accepts changes to the storage.backend field, the factory instantiates the adapter during proxy initialization in server.ts. To switch backends, you must restart the service so the factory can re-evaluate the configuration hierarchy and initialization chain.

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