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

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, 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 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 (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 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 (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 with the following structure:

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

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

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 (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 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 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), 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.

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