# MemoryCore Storage Backends: SQLite vs TCVDB Configuration Guide

> Explore MemoryCore storage backends: SQLite vs TCVDB. Learn configuration details and choose the best option for your vector storage needs. Automatic fallback included.

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

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/tcvdb-client.ts) contains the HTTP client wrapper for Tencent Cloud API communication, while [`MemoryCore/src/core/store/tcvdb.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:

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

```typescript
// 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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/factory.ts) handles backend instantiation:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/sqlite-storage.ts), which handles connection pooling, BM25 indexing, and TTL management for automatic memory expiration.