Skip to main content

Class: SqliteBrain

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:293

Unified SQLite connection manager for a single agent's persistent brain.

Usage:

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

// Direct DB access for subsystems
const row = brain.db.prepare('SELECT * FROM memory_traces WHERE id = ?').get(id);

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

brain.close();

Subsystems (MemoryTraceRepository, KnowledgeGraphStore, DocumentChunkStore, etc.) receive the SqliteBrain instance and call brain.db directly to prepare statements — this avoids redundant connection overhead across subsystems.

Constructors​

Constructor​

new SqliteBrain(dbPath): SqliteBrain

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:321

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

Initialization sequence:

  1. Open (or create) the SQLite file.
  2. Enable WAL journal mode for concurrent read access.
  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​

SqliteBrain

Properties​

db​

readonly db: Database

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:301

The raw better-sqlite3 database handle.

Exposed as readonly so subsystems can prepare their own statements without going through an intermediary layer. better-sqlite3 is synchronous and thread-safe for single-writer, multi-reader scenarios.

Methods​

checkEmbeddingCompat()​

checkEmbeddingCompat(dimensions): boolean

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:432

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​

boolean

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

close()​

close(): void

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:451

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​

void

getMeta()​

getMeta(key): string | undefined

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:396

Read a value from the brain_meta key-value store.

Parameters​

key​

string

The metadata key to look up.

Returns​

string | undefined

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

setMeta()​

setMeta(key, value): void

Defined in: packages/agentos/src/memory/store/SqliteBrain.ts:413

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​

void