# Storage Backends for MemoryProxy: COS, SQLite, Filesystem, and In-Memory Options Explained

> Explore MemoryProxy storage backends: COS for persistence, SQLite for queries, filesystem for key-value, and in-memory for caching. Choose the best option for your needs.

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

---

**MemoryProxy supports four concrete storage backends: Tencent Cloud Object Storage (COS) for durable global persistence, SQLite for embedded relational queries, local filesystem (fs) for simple key-value files, and pure in-memory maps for ultra-fast transient caching.**

The MemoryProxy layer in the TencentDB-Agent-Memory repository sits between client applications and LLM core services, handling persistence for memory instances across different durability, performance, and cost requirements. Choosing the right storage backend depends on whether you need long-term archival, rapid prototyping, or temporary caching that tolerates data loss on restart.

## Available Storage Backends for MemoryProxy

MemoryProxy abstracts four distinct persistence mechanisms, each implemented to match specific operational constraints. According to the API documentation in [[`MemoryProxy/v3-api-memoryproxy-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/v3-api-memoryproxy-doc.md)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryProxy/v3-api-memoryproxy-doc.md), these backends are referenced by the `storage_backend` configuration key.

### COS (Cloud Object Storage)

**COS** provides durable, globally accessible object storage ideal for large binary blobs and long-term artifacts. Use this backend when you need uploaded assets, persistent knowledge bases, or archive snapshots to survive restarts andremain available across regions. The implementation stores data in Tencent COS buckets, making it suitable for production workloads requiring high durability.

### SQLite

**SQLite** offers an embedded relational database stored on disk without requiring a separate database server. This backend excels in environments where you need structured query capabilities but lack access to a full Database-as-a-Service. Choose SQLite for moderate-size structured datasets, quick prototyping scenarios, or on-premise deployments where external dependencies must be minimized.

### Filesystem (fs)

The **fs** backend uses a plain local directory tree for simple key-value file storage. This option works best for development environments, debugging sessions, or low-throughput workloads where durability is not critical. Files are stored as standard OS files, making them easy to inspect and manipulate using standard command-line tools.

### Memory

The **memory** backend maintains data in a pure in-memory map, providing ultra-fast read and write operations at the cost of complete data loss on process restart. This backend suits transient caches, unit test isolation, and workloads that explicitly tolerate volatility. Data exists only for the lifetime of the proxy process.

## Configuring the Storage Backend

MemoryProxy instances declare their storage backend via the gateway configuration file. As shown in [[`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/tdai-gateway.yaml), the `storage_backend` field accepts one of four string values: `cos`, `sqlite`, `fs`, or `memory`.

```yaml

# Example fragment from tdai-gateway.yaml

instance:
  id: mem-example001
  storage_backend: cos   # options: cos | sqlite | fs | memory

  storage_ttl: 86400     # seconds; items older than this are auto-purged

```

The `storage_ttl` parameter defines automatic expiration in seconds. When entries exceed this age, MemoryProxy purges them during routine maintenance cycles, regardless of the selected backend.

## Cleaning Up Storage During Instance Destruction

When a MemoryProxy instance is destroyed, the system executes cleanup logic defined in [[`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryProxy/src/tdai/client.ts). The `proxy-destroy` endpoint returns detailed statistics about which backend was cleaned and how many entries were removed.

Send a destruction request to the administrative API:

```http
POST /v3/instance/proxy-destroy HTTP/1.1
Authorization: Bearer <admin.apiKey>
Content-Type: application/json

{
  "instance_id": "mem-example001"
}

```

The response includes the `cleaned` object showing backend-specific metrics:

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "instance_id": "mem-example001",
    "cleaned": {
      "storage_backend": "cos",
      "storage_ttl_deleted": 3,
      "storage_nottl_deleted": 5,
      "cos_pool_evicted": "evicted",
      "redis_skipped": "per-session-ttl-only"
    }
  }
}

```

To programmatically inspect the backend type from client code:

```typescript
import axios from 'axios';

async function destroyInstance(instanceId: string) {
  const resp = await axios.post(
    'http://localhost:8096/v3/instance/proxy-destroy',
    { instance_id: instanceId },
    { headers: { Authorization: `Bearer ${process.env.ADMIN_API_KEY}` } }
  );

  const backend = resp.data.data.cleaned.storage_backend;
  console.log(`Instance ${instanceId} used ${backend} storage`);
  
  // Follow-up actions based on backend type:
  // cos → verify object presence in COS bucket
  // sqlite → run sqlite vacuum if needed
  // fs → clean up local temp directory
  // memory → nothing to persist (data already lost)
}

```

## Session Store vs. Persistent Backends

Beyond the four persistent backends, MemoryProxy employs a **Redis session store** for per-session TTL data using keys prefixed with `cg:sess:*`. As implemented in [[`MemoryProxy/src/session/store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/session/store.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryProxy/src/session/store.ts), this store is managed by the `SessionStore` class and is explicitly excluded from the destroy flow.

Because session keys lack a space identifier and rely on Redis's native expiration (default 1800 seconds), they are allowed to expire naturally rather than being force-deleted during instance destruction. This design prevents premature invalidation of active user sessions while ensuring memory eventually frees itself through TTL mechanisms.

## Summary

- **COS** provides durable, globally accessible storage for production artifacts and large binary data.
- **SQLite** delivers embedded relational capabilities without external database dependencies.
- **Filesystem (fs)** offers simple key-value persistence suitable for development and debugging.
- **Memory** delivers maximum speed for transient caches but sacrifices durability.
- Configuration occurs through the `storage_backend` key in [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml).
- The `proxy-destroy` endpoint reports cleanup statistics including TTL and non-TTL entry counts.
- Redis session storage operates independently and is not cleared during proxy destruction.

## Frequently Asked Questions

### What is the default storage backend for MemoryProxy?

The default storage backend depends on your [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) configuration. If unspecified, deployments typically fallback to `memory` for safety, though production templates in the TencentDB-Agent-Memory repository explicitly set `cos` or `sqlite` to prevent accidental data loss. Always verify your instance configuration before deploying to production.

### How do I migrate data between storage backends?

MemoryProxy does not provide built-in migration tools between backends. To migrate, export your data using the appropriate client libraries for your current backend (COS SDK, SQLite client, or filesystem utilities), then import into the new backend after updating the `storage_backend` field in [`tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.yaml) and restarting the instance.

### Why is Redis not cleaned when I destroy a MemoryProxy instance?

The Redis session store uses a separate key namespace (`cg:sess:*`) without space identifiers, as documented in the API reference. These keys are designed to expire naturally via Redis TTL (typically 1800 seconds) rather than being force-deleted during destruction. This preserves active user sessions while ensuring eventual cleanup, preventing disruption to clients during proxy maintenance.

### Which storage backend offers the best performance?

The **memory** backend provides the lowest latency and highest throughput since it avoids disk I/O or network round-trips. However, for persistent data requirements, **SQLite** offers faster query performance than **fs** for structured data, while **COS** prioritizes durability and availability over raw speed. Choose memory for unit tests and caches, SQLite for medium-scale local storage, and COS for distributed production workloads.