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

> Explore four storage adapters for context offload in TencentDB Agent Memory: COS, SQLite, Filesystem, and in-memory. Choose the best fit for your deployment needs.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/factory.ts)) instantiates the concrete adapter based on the `storage.backend` configuration value. The factory implements a hardcoded selection logic:

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml) or a custom YAML supplied at runtime. The `storage` section controls offload behavior:

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

```typescript
// 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:

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

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/server.ts). To switch backends, you must restart the service so the factory can re-evaluate the configuration hierarchy and initialization chain.