Class SqliteBrain

Unified cross-platform connection manager for a single agent's persistent brain.

Uses the StorageAdapter interface from @framers/sql-storage-adapter to support multiple backends (better-sqlite3, sql.js, IndexedDB, Postgres, etc.) transparently. All methods are async.

Usage:

const brain = await SqliteBrain.open('/path/to/agent/brain.sqlite');

// Async query API for subsystems
const row = await brain.get<{ value: string }>('SELECT value FROM brain_meta WHERE key = ?', ['schema_version']);

// Meta helpers
await brain.setMeta('last_sync', Date.now().toString());
const ver = await brain.getMeta('schema_version'); // '1'

await brain.close();

Subsystems (KnowledgeGraph, MemoryGraph, ConsolidationLoop, etc.) receive the SqliteBrain instance and call its async proxy methods (run, get, all, exec, transaction) for all database operations.

Accessors

adapter features

Methods

open run get all exec transaction getMeta setMeta checkEmbeddingCompat close

Accessors

adapter

  • get adapter(): StorageAdapter

  • Expose the raw storage adapter for advanced usage.

    Primarily used by SqliteExporter (VACUUM INTO) and SqliteImporter (which needs direct adapter access for the target brain).

    Returns StorageAdapter

features

  • get features(): StorageFeatures

  • Platform-aware feature bundle (dialect, FTS, BLOB codec, exporter). Consumers use this to generate cross-platform SQL instead of hardcoding SQLite-specific syntax.

    Returns StorageFeatures

Methods

Static open

  • open(dbPath): Promise<SqliteBrain>

  • Create or open the agent's brain database at dbPath.

    Async factory that replaces the previous synchronous constructor.

    Initialization sequence:

    1. Resolve the best available storage adapter for the current runtime.
    2. Enable WAL journal mode for concurrent read access (when supported).
    3. Enable foreign key enforcement (OFF by default in SQLite).
    4. Execute the full DDL schema (all CREATE TABLE IF NOT EXISTS).
    5. Create the FTS5 virtual table for full-text memory search.
    6. Seed brain_meta with schema_version and created_at if absent.

    Parameters

    • dbPath: string

      Absolute path to the .sqlite file. The file is created if it does not exist; parent directories must already exist.

    Returns Promise<SqliteBrain>

    A fully initialised SqliteBrain instance.

run

  • run(sql, params?): Promise<StorageRunResult>

  • Execute a mutation statement (INSERT, UPDATE, DELETE).

    Parameters

    • sql: string

      SQL statement with ? positional placeholders.

    • Optional params: StorageParameters

      Parameter array matching the placeholders.

    Returns Promise<StorageRunResult>

    Metadata about affected rows.

get

  • get<T>(sql, params?): Promise<null | T>

  • Retrieve a single row (or null if none found).

    Type Parameters

    • T = unknown

    Parameters

    • sql: string

      SQL SELECT statement.

    • Optional params: StorageParameters

      Parameter array.

    Returns Promise<null | T>

    First matching row or null.

all

  • all<T>(sql, params?): Promise<T[]>

  • Retrieve all rows matching the statement.

    Type Parameters

    • T = unknown

    Parameters

    • sql: string

      SQL SELECT statement.

    • Optional params: StorageParameters

      Parameter array.

    Returns Promise<T[]>

    Array of matching rows (empty array if none).

exec

transaction

  • transaction<T>(fn): Promise<T>

  • Execute a callback within a database transaction.

    The transaction is automatically committed on success or rolled back on error.

    Type Parameters

    • T

    Parameters

    • fn: ((trx) => Promise<T>)

      Async callback receiving a transactional adapter.

        • (trx): Promise<T>

        • Parameters

          • trx: StorageAdapter

          Returns Promise<T>

    Returns Promise<T>

    Result of the callback.

getMeta

  • getMeta(key): Promise<undefined | string>

  • Read a value from the brain_meta key-value store.

    Parameters

    • key: string

      The metadata key to look up.

    Returns Promise<undefined | string>

    The stored string value, or undefined if the key does not exist.

setMeta

  • setMeta(key, value): Promise<void>

  • Upsert a value into the brain_meta key-value store.

    Uses INSERT OR REPLACE semantics — creates the row if absent, or overwrites if present.

    Parameters

    • key: string

      The metadata key.

    • value: string

      The string value to store.

    Returns Promise<void>

checkEmbeddingCompat

  • checkEmbeddingCompat(dimensions): Promise<boolean>

  • Check whether a given embedding dimension is compatible with this brain.

    On first call (no stored embedding_dimensions), returns true and stores the provided dimension for future compatibility checks.

    Subsequent calls compare dimensions against the stored value. Mismatches indicate that a different embedding model was used to encode memories — mixing dimensions would corrupt vector similarity searches.

    Parameters

    • dimensions: number

      The embedding vector length to check (e.g. 1536 for OpenAI ada-002).

    Returns Promise<boolean>

    true if compatible (or no prior value), false on mismatch.

close

  • close(): Promise<void>

  • Close the database connection.

    Must be called when the agent shuts down to flush the WAL and release the file lock. Failing to close may leave the database in WAL mode with an unconsumed WAL file.

    Returns Promise<void>

Settings

Member Visibility

Theme

On This Page

adapterfeaturesopenrungetallexectransactiongetMetasetMetacheckEmbeddingCompatclose