MemoryCore Storage Backends: SQLite vs TCVDB Configuration Guide

MemoryCore supports two storage backends—SQLite for local file-based persistence and Tencent Cloud VectorDB (TCVDB) for remote cloud-based vector storage—with automatic fallback to SQLite when TCVDB credentials are unavailable or the connection fails.

TencentDB-Agent-Memory's MemoryCore abstracts persistent storage behind the StoreBackend type defined in MemoryCore/src/config.ts, allowing seamless switching between lightweight local databases and scalable cloud services. This architecture ensures high availability through graceful degradation, enabling applications to continue operating even when cloud connectivity is disrupted.

Supported Storage Backends

The StoreBackend type is defined as a union of "sqlite" and "tcvdb" in the configuration schema. This type-safe abstraction enables the factory pattern implemented in MemoryCore/src/core/store/factory.ts to instantiate the appropriate storage implementation at runtime.

SQLite Backend (Local File Storage)

SQLite provides a local, file-based database solution leveraging the better-sqlite3 driver for synchronous database operations. This backend requires no cloud credentials and serves as the default when MemoryCore runs in standalone mode.

The implementation resides in MemoryProxy/src/storage/sqlite-storage.ts, which handles connection management, BM25 indexing, and automatic TTL (time-to-live) sweeping for memory expiration. By default, SQLite stores data at ~/.tdai-memory-proxy/proxy.db on the local filesystem.

Key characteristics include:

• Simple key-value storage with built-in BM25 text indexing
• Synchronous API via the better-sqlite3 driver
• Zero external network dependencies

TCVDB Backend (Tencent Cloud VectorDB)

TCVDB (Tencent Cloud VectorDB) provides a remote vector-database service offering server-side dense embeddings and hybrid search capabilities. This backend is optimized for service-mode deployments requiring distributed, scalable memory storage with advanced semantic search.

The implementation spans two critical files: MemoryCore/src/core/store/tcvdb-client.ts contains the HTTP client wrapper for Tencent Cloud API communication, while MemoryCore/src/core/store/tcvdb.ts implements the concrete TcvdbMemoryStore class. TCVDB requires explicit configuration including url, apiKey, and database credentials.

Key capabilities include:

• Server-side dense embedding generation (e.g., bge-large-zh model)
• Hybrid search combining vector similarity and keyword matching
• Remote persistence with configurable timeouts

Configuration Examples

Configuring MemoryCore involves setting the storeBackend field in your MemoryTdaiConfig object and providing appropriate credentials for cloud-based options.

SQLite Configuration

To use SQLite, specify "sqlite" for the storeBackend field:

// memory-config.ts
export const memoryConfig = {
  // ...
  storeBackend: "sqlite",          // ← use local SQLite
  // tcvdb block may be omitted
};

TCVDB Configuration

To connect to Tencent Cloud VectorDB, specify "tcvdb" and include the required credential object:

// memory-config.ts
export const memoryConfig = {
  // ...
  storeBackend: "tcvdb",           // ← request remote TCVDB backend
  tcvdb: {
    url: "https://tdb.tencentcloudapi.com", // instance endpoint
    username: "root",
    apiKey: "YOUR_TCVDB_API_KEY",           // ← secure credential
    database: "my_memory_db",
    // optional settings
    embeddingEnabled: true,
    embeddingModel: "bge-large-zh",
    timeout: 10000,
  },
};

Programmatic Store Creation

The StoreFactory class in MemoryCore/src/core/store/factory.ts handles backend instantiation:

import { StoreFactory } from "./core/store/factory";
import { MemoryTdaiConfig } from "./config";

async function initStore(cfg: MemoryTdaiConfig) {
  const store = await StoreFactory.create(cfg.storeBackend, cfg);
  // `store` will be an instance of either TcvdbMemoryStore or
  // a SQLite-backed store (via ProxyStorage → SqliteStorage)
  return store;
}

Automatic Fallback Behavior

When storeBackend is configured as "tcvdb" but required credentials are missing or the TCVDB initialization fails, MemoryCore automatically degrades to SQLite. This fallback mechanism is implemented in the initialization logic referenced in MemoryCore/src/core/skill/skill-config.ts.

If StoreFactory.create() throws an error due to missing url, apiKey, or database fields, the higher-level initialization catches the failure and instantiates a SQLite-backed store instead. This ensures service continuity in offline environments or during credential rotation.

Summary

• MemoryCore defines storage options via the StoreBackend type ("sqlite" | "tcvdb") in MemoryCore/src/config.ts
• SQLite stores data locally at ~/.tdai-memory-proxy/proxy.db using the better-sqlite3 driver with no configuration required
• TCVDB requires valid url, apiKey, and database credentials and provides server-side embeddings via MemoryCore/src/core/store/tcvdb.ts
• The system automatically falls back to SQLite when TCVDB initialization fails, ensuring high availability
• Use StoreFactory.create() in MemoryCore/src/core/store/factory.ts to instantiate backends programmatically

Frequently Asked Questions

What happens if TCVDB credentials are invalid or missing?

If the tcvdb configuration block lacks required fields (url, apiKey, database) or the TCVDB service is unreachable, MemoryCore throws an initialization error that triggers automatic fallback to SQLite. This degradation ensures the service remains operational using local file storage until valid credentials are provided.

Can I migrate data from SQLite to TCVDB?

The source code does not expose built-in migration utilities between storage backends. Since SQLite persists data locally in ~/.tdai-memory-proxy/proxy.db while TCVDB manages data remotely through TcvdbMemoryStore, migrating existing memories would require custom logic that exports from SqliteStorage and imports via the ProxyStorage interface defined in MemoryProxy/src/storage/proxy-storage.ts.

Which backend should I use for production deployments?

TCVDB is recommended for production service-mode deployments requiring horizontal scalability, server-side embeddings, and hybrid search capabilities. SQLite is suitable for standalone development environments, edge deployments, or air-gapped scenarios where cloud connectivity is unavailable, as it requires no external infrastructure.

Where is the SQLite database file located?

By default, SQLite stores the database at ~/.tdai-memory-proxy/proxy.db on the local filesystem. This path is managed by the SqliteStorage implementation in MemoryProxy/src/storage/sqlite-storage.ts, which handles connection pooling, BM25 indexing, and TTL management for automatic memory expiration.

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