# When Is the COS Backend Required for Cache Coherence in TencentDB MemoryProxy?

> Discover when the COS backend is required for cache coherence in TencentDB MemoryProxy. Learn about durable state needs for multi-instance deployments, Kernel-STS, TTL entries, and eviction.

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

---

**The COS backend becomes required for cache coherence in MemoryProxy whenever you need durable, globally visible state across multiple pods—including production multi-instance deployments, Kernel-STS authentication, TTL-based cache entries, or explicit cache eviction operations.**

The MemoryProxy component of TencentCloud/TencentDB-Agent-Memory uses a pluggable **ProxyStorage** abstraction that supports Redis, COS, SQLite, file system, or in-memory storage. While several backends work for single-instance scenarios, the COS (Cloud Object Storage) backend specifically ensures cache coherence when the proxy runs in distributed environments or requires shared state guarantees. Understanding when COS is mandatory helps architects choose the correct storage provider for production workloads.

## Production Multi-Instance Deployments

When running MemoryProxy across multiple Kubernetes pods or VM instances, COS serves as the default and required storage backend.

According to the source code in [`MemoryProxy/src/storage/factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/factory.ts), COS is explicitly documented as the preferred production backend at line 31. Unlike in-memory or file-based storage, COS provides a single, durable object store that all pods can read from and write to simultaneously. This guarantees that cached injection data—such as hook-cache entries and L2a bindings—remains visible and consistent across the entire fleet.

Without COS, each pod would maintain isolated state, leading to cache fragmentation where one pod cannot see writes performed by another.

## Kernel-STS Authentication Requirements

The COS backend is strictly required when your proxy configuration uses **Kernel-STS (Security Token Service)** authentication instead of static Access Key/Secret Key pairs.

As noted in [`factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/factory.ts) lines 31-33, static AK/SK credentials have been removed for security reasons. The COS implementation is the only storage backend that supports refreshing temporary STS credentials on-the-fly. When `storage.enabled: true` is configured with kernel-STS, the factory automatically instantiates the COS provider because other backends lack the credential rotation mechanisms required for secure production environments.

## Cache Eviction and Cleanup Operations

Any scenario requiring explicit cache removal across all replicas mandates the COS backend.

The `evictCosSpace` function implemented in [`factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/factory.ts) (lines 218-227) directly deletes COS objects belonging to a service’s namespace. When you invoke the `proxy-destroy` API to clear a service’s cache, this routine ensures no stale data remains across any pod in the cluster. File-based or SQLite backends cannot provide this atomic, cluster-wide eviction capability, making COS essential for clean teardown scenarios.

## TTL-Based Cache Management

When creating cache entries with time-to-live (TTL) values, COS becomes necessary to enforce expiration semantics uniformly.

The proxy writes TTL-bound entries to dedicated COS paths (`proxy_cache/ttl/...`) as documented in [`types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/types.ts) lines 54-61. COS lifecycle rules handle the actual expiration at day-level granularity. Without COS, TTL enforcement would be local to individual pods, causing inconsistent cache behavior where expired entries persist in some replicas but not others.

## Cross-Pod Cache Coherence Notifications

For scenarios requiring immediate visibility of writes across pods—such as hook-cache updates—COS acts as the single source of truth.

The design documented in [`storage/factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/storage/factory.ts) (lines 129-131) specifically addresses preventing race conditions where one pod writes to storage but another pod cannot see the data. By centralizing state in COS, MemoryProxy eliminates "write-to-storage-but-other-pod-cannot-see" issues that plague distributed systems using local caches.

## Configuration and Code Examples

### Enabling COS Backend in Configuration

To activate the COS backend for cache coherence, configure [`config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.example.yaml) with the following structure:

```yaml
storage:
  enabled: true                # Activate ProxyStorage

  provider: "cos"              # Choose COS backend (default)

  cos:
    url: "https://your-bucket.cos.ap-guangzhou.myqcloud.com"
    secret_id: "${COS_SECRET_ID}"
    secret_key: "${COS_SECRET_KEY}"
    token: "${COS_TOKEN}"      # Optional STS token

    path_prefix: "tenants/prod/"   # Namespace for this service

    ttlDays: 7                 # COS lifecycle rule (day-level granularity)

```

This configuration excerpt from [`config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.example.yaml) (lines 19-28) shows the recommended production settings that enable cross-pod coherence.

### Manually Evicting a Service’s COS Cache

When destroying a proxy instance, explicitly clear its cached objects using the `evictCosSpace` utility:

```typescript
import { evictCosSpace } from "./storage/factory";

/**
 * Remove all cached objects for a given `spaceId`.
 * This is typically called when the instance is being destroyed.
 */
async function clearServiceCache(spaceId: string) {
  const result = await evictCosSpace(spaceId);
  console.log(`Cache eviction for ${spaceId}: ${result}`);
}

```

This pattern appears in [`factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/factory.ts) (lines 222-227) and ensures complete removal of a tenant’s data from the shared COS bucket.

### Writing TTL-Bound Entries to COS

Create atomic, expiring cache entries using the `CosStorage` class:

```typescript
import { CosStorage } from "./cos-storage";

const cos = new CosStorage(/* injected COS client */);
await cos.putIfAbsent("proxy_cache/ttl/space123/my-key", Buffer.from("value"));

```

The `putIfAbsent` method in [`cos-storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/cos-storage.ts) (lines 12-16) uses the `If-None-Match: "*"` header to guarantee atomic creation, preventing duplicate entries when multiple pods attempt simultaneous writes.

## Summary

- **COS is required** for any production deployment with multiple MemoryProxy instances to ensure shared state visibility.
- **Kernel-STS authentication** mandates COS because it is the only backend supporting dynamic credential refresh.
- **Cache eviction** operations like `proxy-destroy` require COS to guarantee cluster-wide deletion of stale data.
- **TTL enforcement** relies on COS lifecycle rules to ensure consistent expiration across all pods.
- The `ProxyStorage` factory in [`factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/factory.ts) automatically selects COS when `storage.enabled: true` and production configuration flags are present.

## Frequently Asked Questions

### What happens if I use SQLite instead of COS in a multi-pod deployment?

If you configure SQLite or file-system storage while running multiple MemoryProxy pods, each pod maintains an isolated local database. This causes severe cache coherence issues where writes on one pod remain invisible to others, leading to inconsistent injection data and potential split-brain scenarios. The source code explicitly recommends COS for any multi-instance setup.

### Can I use COS with static AK/SK credentials instead of Kernel-STS?

No. According to [`factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/factory.ts) lines 31-33, static Access Key/Secret Key support has been removed from the codebase for security reasons. The COS backend now requires Kernel-STS temporary credentials, which it refreshes automatically. This design choice forces secure credential management practices in production environments.

### How does COS handle cache eviction when I delete a proxy instance?

When you call the `proxy-destroy` API, MemoryProxy invokes `evictCosSpace` (lines 218-227 in [`factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/factory.ts)), which enumerates and deletes all objects under the service’s `path_prefix` in your COS bucket. This ensures that subsequent proxy instances or other pods do not encounter stale hook-cache or binding data from the deleted instance.

### Is COS required for single-instance development environments?

No. For local development or single-pod scenarios, you can configure `provider: "sqlite"` or `provider: "memory"` in your configuration. The COS backend is only required when you need cross-instance durability, TTL enforcement across restarts, or the specific security features provided by Kernel-STS authentication.