# What Is the Default Storage Backend for TencentDB Agent Memory?

> Discover the default storage backend for TencentDB Agent Memory. Learn how SQLite is automatically used when not explicitly configured for optimal performance.

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

---

**The default storage backend for TencentDB Agent Memory is SQLite**, automatically selected when the `storage.backend` configuration is omitted or explicitly set to `"sqlite"` in [`MemoryProxy/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/config.ts).

TencentDB Agent Memory uses a pluggable storage architecture that abstracts session and memory persistence behind a uniform interface. According to the TencentCloud/TencentDB-Agent-Memory source code, the system defaults to a file-based SQLite implementation unless you configure an alternative backend such as Tencent COS or in-memory storage.

## How the Default Storage Backend Is Configured

The default backend is hardcoded in the application's configuration constants. In [`MemoryProxy/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/config.ts), the `DEFAULT_CONFIG` object explicitly sets the storage backend to `"sqlite"` on lines 48‑51:

```typescript
// MemoryProxy/src/config.ts (lines 48-51)
storage: {
  enabled: false,
  backend: 'sqlite',  // Default storage backend
  ttlDays: 7,
}

```

When the application initializes without a custom configuration file, this default value propagates through the system. The `ProxyStorage` factory reads this configuration string and instantiates the appropriate storage implementation.

## Storage Backend Architecture and Fallback Chain

The storage subsystem implements a factory pattern in [`MemoryProxy/src/storage/factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/factory.ts). On lines 47‑50, the `initProxyStorage` function examines the `backend` property and returns a concrete implementation:

- **`"sqlite"`** → `SqliteStorage` (default)
- **`"cos"`** → `CosStorage` (Tencent Cloud Object Storage)
- **`"fs"`** → `FsStorage` (file system)
- **`"memory"`** → `MemoryStorage` (volatile, in-process)

If instantiation fails, the factory degrades through a fallback chain (`sqlite → fs → memory`) and logs a warning. However, the initial default remains SQLite unless explicitly overridden.

## Implementing the Default SQLite Backend

You do not need to provide a configuration file to use SQLite. The system automatically creates a `SqliteStorage` instance using the defaults:

```typescript
import { initProxyStorage } from "./MemoryProxy/src/storage/factory.js";
import type { StorageConfig } from "./MemoryProxy/src/storage/factory.js";

async function start() {
  // Minimal config relying on SQLite defaults
  const cfg: StorageConfig = {
    backend: "sqlite",
    ttlDays: 7,
    cos: { rootPrefix: "proxy_cache/", shark: { baseUrl: "" } },
    sqlite: { dbPath: "" },  // Empty string uses default path
    fs: { fsRoot: "" },
  };

  const storage = await initProxyStorage(cfg);  // Returns SqliteStorage instance
  
  // Write session data
  await storage.put("session/user_123", JSON.stringify({ context: "active" }));
}

```

Behind the scenes, [`MemoryProxy/src/storage/sqlite-storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/sqlite-storage.ts) implements the `ProxyStorage` interface using a persistent SQLite database file, providing ACID guarantees for agent memory operations.

## Switching to Alternative Backends

While SQLite is the default, you can switch to Tencent COS for multi-node deployments where shared storage is required:

```typescript
const cfg: StorageConfig = {
  backend: "cos",  // Override default SQLite
  ttlDays: 30,
  cos: {
    rootPrefix: "agent_memory/",
    shark: { baseUrl: "https://cos.tencentcloud.com" },
  },
  sqlite: { dbPath: "" },
  fs: { fsRoot: "" },
};

const storage = await initProxyStorage(cfg);  // Returns CosStorage instance

```

This configuration directs the factory to instantiate `CosStorage` from [`MemoryProxy/src/storage/cos-storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/cos-storage.ts) instead of the default `SqliteStorage`.

## Summary

- **SQLite is the default**: Defined in [`MemoryProxy/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/config.ts) with `storage.backend: 'sqlite'`.
- **Factory instantiation**: The `initProxyStorage` function in [`MemoryProxy/src/storage/factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/factory.ts) creates `SqliteStorage` when no backend is specified.
- **Pluggable design**: Four backends supported—`sqlite` (default), `cos`, `fs`, and `memory`.
- **Graceful degradation**: If the configured backend fails, the system falls back through `sqlite → fs → memory`.
- **Zero-config operation**: SQLite works out-of-the-box without YAML configuration or environment variables.

## Frequently Asked Questions

### What is the default storage backend for TencentDB Agent Memory?

The default storage backend is **SQLite**, as defined by the `DEFAULT_CONFIG` constant in [`MemoryProxy/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/config.ts). When you initialize the storage layer without specifying a backend, the `ProxyStorage` factory automatically instantiates `SqliteStorage` from [`MemoryProxy/src/storage/sqlite-storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/sqlite-storage.ts).

### How do I change the default storage backend to Tencent COS?

Set the `storage.backend` property to `"cos"` in your configuration object or YAML file. The factory will then instantiate `CosStorage` from [`MemoryProxy/src/storage/cos-storage.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/storage/cos-storage.ts). You must also provide valid COS credentials and a `rootPrefix` in the `cos` configuration section.

### What happens if the SQLite backend fails to initialize?

The storage factory implements a degradation chain that falls back from `sqlite` to `fs` (file system) and finally to `memory` (non-persistent). The system logs a warning when fallback occurs, but your application continues operating using the next available storage mechanism.

### Is the SQLite backend suitable for production deployments?

SQLite provides ACID-compliant persistence suitable for single-node deployments or development environments. For production scenarios requiring high availability or multi-node access, Tencent recommends configuring the **COS backend** to enable shared storage across distributed agent instances.