How TCVDB Storage Backend Configuration Works in TencentDB-Agent-Memory

The TCVDB storage backend is activated by setting storeBackend: "tcvdb" in the agent configuration, which triggers the system to parse connection credentials from a tcvdb object and initialize a remote Vector Database client rather than the default SQLite store.

The TencentDB-Agent-Memory repository supports Tencent Cloud Vector Database (TCVDB) as a production-grade alternative to local SQLite storage for multi-agent deployments. Understanding how the configuration schema drives backend selection, connection pooling, and tenant isolation is essential for deploying scalable memory services.

Configuration Schema and Backend Selection

The memory service determines which storage engine to use by evaluating the storeBackend field at initialization time within the configuration loader.

Selecting the Store Backend

In MemoryCore/src/config.ts, the system reads the global configuration and normalizes the backend identifier:

// MemoryCore/src/config.ts – lines 78-81
const storeBackendRaw = str(c, "storeBackend") ?? "sqlite";
const storeBackend: StoreBackend = storeBackendRaw === "tcvdb" ? "tcvdb" : "sqlite";

When the value equals "tcvdb", the downstream StorePool instantiates TcvdbMemoryStore instances; any other value (or omission) defaults to the SQLite backend.

Required TCVDB Connection Parameters

Upon selecting the TCVDB backend, the configuration parser extracts a mandatory tcvdb object containing connection credentials and operational settings:

// MemoryCore/src/config.ts – lines 99-107
const tcvdbGroup = obj(c, "tcvdb");

const tcvdb: {
  url: string;
  username: string;
  apiKey: string;
  database: string;
  alias?: string;
  embeddingEnabled?: boolean;
  embeddingModel?: string;
  timeout?: number;
  caPemPath?: string;
} = {
  url: str(tcvdbGroup, "url") ?? "",
  username: str(tcvdbGroup, "username") ?? "root",
  apiKey: str(tcvdbGroup, "apiKey") ?? "",
  database: str(tcvdbGroup, "database") ?? "",
  alias: str(tcvdbGroup, "alias") ?? "",
  embeddingEnabled: bool(tcvdbGroup, "embeddingEnabled") ?? false,
  embeddingModel: str(tcvdbGroup, "embeddingModel") ?? "bge-large-zh",
  timeout: num(tcvdbGroup, "timeout") ?? 10000,
  caPemPath: str(tcvdbGroup, "caPemPath") || undefined,
};

Critical fields (url, apiKey, database) must be populated; otherwise, the service throws a validation error at startup. Optional parameters control TLS certificate authority paths, server-side embedding generation, and connection timeouts.

Store Pool Architecture and Initialization

The StorePool class in MemoryCore/src/core/store/store-pool.ts manages the lifecycle of both SQLite and TCVDB stores, implementing a fingerprint-based caching mechanism to avoid redundant connection initialization.

Fingerprint-Based Caching

When an agent instance requests a store, the pool computes a deterministic fingerprint to identify reusable connections:

// MemoryCore/src/core/store/store-pool.ts – lines 71-78
const fingerprint = this.mode === "tcvdb" && vdbConfig
  ? this.computeFingerprint(vdbConfig)
  : `sqlite:${instanceId}`;

This fingerprint incorporates the TCVDB connection parameters, ensuring that configuration changes trigger the creation of fresh stores while identical configs reuse existing connections.

Store Instantiation Logic

If the pool lacks a cached store for the computed fingerprint, it branches based on the configured mode:

// MemoryCore/src/core/store/store-pool.ts – lines 95-99
const pooledStore = this.mode === "tcvdb" && vdbConfig
  ? this.createTcvdbStore(vdbConfig)
  : this.createSqliteStore(instanceId);

The createTcvdbStore() method constructs a TcvdbMemoryStore instance, passing the validated configuration object to the constructor.

TCVDB Store Implementation Details

The TcvdbMemoryStore class defined in MemoryCore/src/core/store/tcvdb.ts encapsulates remote Vector Database operations, handling client authentication, collection management, and hybrid search capabilities.

Client Initialization and TLS Configuration

During construction, the store initializes a TcvdbClient with the provided credentials:

1. HTTPS CA Handling: If the URL uses the https:// protocol, the optional caPemPath or VDB_CA_PEM_PATH environment variable loads the certificate authority bundle (tcvdb.ts lines 44-46).

2. Connection Parameters: The client receives the endpoint URL, username, API key, database name, timeout, and TLS configuration to establish persistent HTTP connections to Tencent Cloud's Vector Database service.

Collection Management and Hybrid Search

Upon first access, the store automatically provisions collections named ${database}_memories for conversation history and ${database}_skills for capability storage. When embeddingEnabled is true, the store configures the server-side embedding model specified in embeddingModel (defaulting to bge-large-zh) to generate vector representations remotely rather than computing them client-side.

The store advertises nativeHybridSearch = true when the TCVDB cluster supports hybrid vector and full-text search endpoints, allowing the memory service to delegate complex queries directly to the remote engine rather than performing client-side filtering.

Skill Store and Multi-Tenant Isolation

Beyond conversation memory, the system maintains a separate skill store for persistent agent capabilities. The pool provides getSkillStore() (store-pool.ts lines 104-112), which returns a specialized TcvdbSkillStore pointing to the ${database}_skills collection.

Tenant isolation is enforced through the database configuration field. Each agent instance must specify a unique database name, ensuring that vectors and metadata remain segregated at the collection level even when multiple agents share the same TCVDB endpoint and credentials.

Configuration Examples

Minimal TCVDB Configuration

The following JSON enables TCVDB storage for an agent instance:

{
  "storeBackend": "tcvdb",
  "tcvdb": {
    "url": "https://tcvdb.tencentcloudapi.com",
    "username": "root",
    "apiKey": "YOUR_TCVDB_API_KEY",
    "database": "agent_instance_prod_001",
    "embeddingEnabled": true,
    "embeddingModel": "bge-large-zh",
    "timeout": 12000
  }
}

Programmatic Store Access

Applications can interact with the configured backend through the StorePool abstraction:

import { StorePool } from "./core/store/store-pool";

// Initialize pool with TCVDB configuration
const pool = new StorePool({
  mode: "tcvdb",
  maxStores: 100,
  logger,
  memoryCfg: config,
});

// Retrieve or create instance-specific store
const store = await pool.getStore("instance-42", {
  url: "https://tcvdb.tencentcloudapi.com",
  user: "root",
  apiKey: "secret-key",
  database: "agent_instance_prod_001",
});

// Insert memory document
await store.store.upsert({ 
  id: "mem-1", 
  content: "User prefers formal communication" 
});

Summary

• Backend Selection: Set storeBackend: "tcvdb" in MemoryCore/src/config.ts to switch from SQLite to Tencent Cloud Vector Database.
• Required Fields: The tcvdb object must include url, apiKey, and database; optional fields control TLS, timeouts, and server-side embedding.
• Pooling Mechanism: StorePool uses configuration fingerprints to cache and reuse TCVDB connections across agent instances.
• Implementation Classes: TcvdbMemoryStore handles memory persistence while TcvdbSkillStore manages capability storage, both utilizing TcvdbClient for HTTP transport.
• Isolation Strategy: Unique database names per instance ensure multi-tenancy at the collection level without separate TCVDB clusters.

Frequently Asked Questions

What happens if the TCVDB configuration is incomplete?

The configuration validator in MemoryCore/src/config.ts checks for the presence of url, apiKey, and database. If any are missing or empty, the service throws a startup error requiring correction before the agent can initialize.

Can multiple agent instances share the same TCVDB database name?

No. Each instance requires a unique database identifier. Sharing names would result in collision of memory vectors and skill documents between different agents, breaking isolation guarantees and potentially leaking context across sessions.

How does the system handle TCVDB connection failures?

The TcvdbClient implements retry logic with exponential backoff for transient HTTP errors. Persistent connection failures surface as errors in the StorePool, which logs the incident but allows the agent to continue operating with degraded memory capabilities depending on the application's error handling strategy.

Is server-side embedding mandatory when using TCVDB?

No. While embeddingEnabled: true delegates vector generation to the TCVDB service using the model specified in embeddingModel, you can disable this feature to compute embeddings client-side before transmission, reducing server load at the cost of increased network bandwidth.

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