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

> Learn how TCVDB storage backend configuration activates your TencentDB Agent Memory. Discover how to set storeBackend to tcvdb and initialize a remote Vector Database client.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/config.ts), the system reads the global configuration and normalizes the backend identifier:

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

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

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

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/tcvdb.ts#L44-L46)).

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](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/MemoryCore/src/core/store/store-pool.ts#L104-L112)), 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:

```json
{
  "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:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.