@zensation/adapter-sqlite

Zero-config SQLite storage adapter for ZenBrain. No database server needed.

Quick Start

npm install @zensation/core @zensation/adapter-sqlite

This package is ESM. require() loads it on Node 22.12 and later; on Node 22.0–22.11, use import.

import { SemanticMemory } from '@zensation/core';
import { SqliteAdapter } from '@zensation/adapter-sqlite';

// File-based (persistent)
const storage = new SqliteAdapter({ filename: './my-memory.db' });

// Or in-memory (testing)
import { createMemoryAdapter } from '@zensation/adapter-sqlite';
const testStorage = createMemoryAdapter();

const memory = new SemanticMemory({ storage });
await memory.storeFact('The user prefers answers in German.', 'conversation');

When to Use

| Use Case | Adapter | |----------|---------| | Development / prototyping | SQLite | | Single-user desktop app | SQLite | | Unit tests | SQLite (:memory:) | | Multi-user production | PostgreSQL | | Vector similarity search | PostgreSQL (pgvector) |

Limitations

• Similarity search is a full scan per query: embeddings are stored as JSON arrays and compared by a cosine-distance function, with no ANN index. Fine for development and single-user data volumes; use PostgreSQL with pgvector for large stores.
• Without an embedding provider, recall ranks by wording, not meaning: synonyms need one.
• Single-writer concurrency (WAL mode helps with reads)

Schema

The adapter creates these tables on first open (CREATE TABLE IF NOT EXISTS) and records the schema version in PRAGMA user_version (exported as SCHEMA_VERSION, currently 1).

| Layer | Table | Columns | |---|---|---| | Episodic | episodic_memories | id, content, context, embedding (JSON array), emotional_weight, metadata (JSON), created_at | | Semantic | learned_facts | id, content, confidence, source, embedding, access_count, fsrs_difficulty, fsrs_stability, fsrs_next_review, created_at, last_accessed | | Procedural | procedural_memories | id, trigger, steps (JSON), tools (JSON), outcome, embedding, success_rate, execution_count, created_at | | Core | core_memory_blocks | id, label (one block per label), content, pinned (1 or 0), updated_at | | Cross-context | cross_context_links | id, entity_a, entity_b (one link per pair), created_at | | — | knowledge_entities | id, name, type, embedding, created_at |

Working and short-term memory live in the process and have no table. Episodes carry emotional_weight; confidence is a column of facts only.

Timestamps are text in one format: ISO 8601, UTC, milliseconds, Z (2026-09-28T21:25:17.000Z), so text order is time order and every value parses as UTC. Code that writes these tables directly should use the same format — in SQL, strftime('%Y-%m-%dT%H:%M:%fZ','now').

| Schema version | Change | |---|---| | 1 | One timestamp format. A file written by an earlier version is rewritten once when it is opened; text SQLite cannot read as a time is left as it was. |

Configuration

const storage = new SqliteAdapter({
  filename: './data/memory.db', // default: './zenbrain.db'
  walMode: true,                // default: true (better read concurrency)
  logger: console,              // optional
});

License

Apache 2.0

About ZenBrain

ZenBrain is a seven-layer, neuroscience-derived memory architecture for LLM agents, built in TypeScript and published under Apache-2.0; @zensation/algorithms and @zensation/core have no third-party dependencies. The benchmark results, and the configuration they were measured in, are reported in the paper; the reproduction packages are on Zenodo.

Works out of the box without an embedding provider — lexical ranking, nothing extra to install. In the paper, ZenBrain's benchmark runs against other systems used nomic-embed-text as the embedding provider; the retrieval ablations used OpenAI text-embedding-3-small.

• Source and issues: github.com/zensation-ai/zenbrain
• Paper: arXiv:2604.23878 · Open-access archive: 10.5281/zenodo.19353663
• Try it in the browser: zensation.ai/en/playground
• Model card: huggingface.co/zensation-ai/zenbrain
• Packages: @zensation/algorithms · @zensation/core · @zensation/adapter-postgres · @zensation/adapter-sqlite · @zensation/mcp · @zensation/ai-sdk

License: Apache-2.0