@skanl/brambo-memory-sqlite 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @skanl/brambo-memory-sqlite
+
+The embedded-SQLite `MemoryProvider`, on `node:sqlite`'s `DatabaseSync`.
+
+**No new dependency.** `node:sqlite` is the platform, measured working on Node 24.14.1 and Node
+26.8.1 — the exact two versions CI runs. Brambo ships exactly one non-`@skanl/brambo-*` runtime dependency
+in total (`jsonc-parser`, in `@skanl/brambo-projection`) and this package does not make it two.
+
+```ts
+import { SqliteMemoryProvider } from '@skanl/brambo-memory-sqlite'
+
+const provider = await SqliteMemoryProvider.open({ databasePath: '/tmp/brambo-memory.db' })
+await provider.save({
+  payload: 'the deploy script needs BRAMBO_HOME set',
+  provenance: { agentId: 'claude-code', workspaceId: 'ws-7', recordedAt: new Date().toISOString() },
+})
+const recent = await provider.search({ workspaceId: 'ws-7' })
+await provider.dispose()
+```
+
+The store is one `entries` table whose `sequence` is `INTEGER PRIMARY KEY AUTOINCREMENT`, and the
+format version lives in `PRAGMA user_version`, which is where SQLite already keeps exactly this
+fact. Append-only is enforced by omission and by SQL: `sqlite-memory-provider.ts` contains no
+UPDATE and no DELETE. `user_version = 0` is a database nobody has stamped — an absent store, so it
+is stamped and served (AD-5); any other value is refused with
+`BRAMBO_CONTRACT_MEMORY_STORE_VERSION_MISMATCH`, and the refused open closes its connection and
+creates no table.
+
+## The experimental warning
+
+Node 24 prints `ExperimentalWarning: SQLite is an experimental feature` when `node:sqlite` LOADS,
+not when a database opens — so a static import would put it on stderr for a consumer that never
+touches a store, and stderr is a contract surface for `brambo run`. `src/load-sqlite.ts` therefore
+does two things: it imports the module lazily on first `open()`, and it confines that one warning
+for the duration of that one import. The filter is narrow (type AND text), so every other warning
+still reaches the user. `test/load-sqlite.test.ts` proves all of it in child processes, with two
+controls: a plain import that MUST show the warning, and an unrelated `ExperimentalWarning` that
+MUST survive the confinement.
+
+## Conformance
+
+`packages/contracts/src/contract-suite/memory-clauses.ts` holds the clauses, and
+`test/contract.test.ts` runs every one of them against this provider. The identical array runs
+against `@skanl/brambo-memory-filesystem`; that swap is FR-16 and scenario S2.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { SqliteMemoryProvider, type SqliteMemoryProviderOptions } from './sqlite-memory-provider.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { SqliteMemoryProvider } from './sqlite-memory-provider.js';

package/dist/load-sqlite.d.ts

@@ -0,0 +1,34 @@
+type SqliteModule = typeof import('node:sqlite');
+/**
+ * Loads `node:sqlite` LAZILY and with its experimental warning confined.
+ *
+ * Two facts, both measured on Node 24.14.1 (the version CI runs):
+ *
+ * 1. The warning fires when the MODULE LOADS, not when a database is opened. A
+ *    static `import { DatabaseSync } from 'node:sqlite'` therefore prints
+ *    `ExperimentalWarning: SQLite is an experimental feature and might change at
+ *    any time` on stderr the moment anything imports this package — including a
+ *    consumer that never touches a store. stderr is a contract surface for
+ *    `brambo run`, so that is brambo's output, not SQLite's.
+ * 2. `process.emitWarning` is where it comes out, and the emission lands during
+ *    the awaited import (Node schedules it on `process.nextTick`, which drains
+ *    before this function's continuation). So a patch installed around the
+ *    import and removed after it catches exactly that warning and nothing else.
+ *
+ * Both halves are applied because they answer different questions: the lazy
+ * import means nothing loads until a consumer actually opens a store, and the
+ * confinement means opening one is silent too. The filter is narrow — the type
+ * AND the text — so any other warning, experimental or not, still reaches the
+ * user. `packages/memory-sqlite/test/load-sqlite.test.ts` drives that with a
+ * control warning that must survive.
+ *
+ * ponytail: the patch is a global mutation, held for the duration of ONE
+ * memoised import. Ceiling: a warning emitted by unrelated code inside that
+ * window is still handed to the original emitter, but a concurrent patcher that
+ * replaces `process.emitWarning` in the same window would have its replacement
+ * restored away — which is why the restore checks that the function it is
+ * replacing is still ours. Upgrade path: delete this file's body down to a plain
+ * `import('node:sqlite')` the release `node:sqlite` stops being experimental in.
+ */
+export declare function loadSqlite(): Promise<SqliteModule>;
+export {};

package/dist/load-sqlite.js

@@ -0,0 +1,55 @@
+let pending;
+/**
+ * Loads `node:sqlite` LAZILY and with its experimental warning confined.
+ *
+ * Two facts, both measured on Node 24.14.1 (the version CI runs):
+ *
+ * 1. The warning fires when the MODULE LOADS, not when a database is opened. A
+ *    static `import { DatabaseSync } from 'node:sqlite'` therefore prints
+ *    `ExperimentalWarning: SQLite is an experimental feature and might change at
+ *    any time` on stderr the moment anything imports this package — including a
+ *    consumer that never touches a store. stderr is a contract surface for
+ *    `brambo run`, so that is brambo's output, not SQLite's.
+ * 2. `process.emitWarning` is where it comes out, and the emission lands during
+ *    the awaited import (Node schedules it on `process.nextTick`, which drains
+ *    before this function's continuation). So a patch installed around the
+ *    import and removed after it catches exactly that warning and nothing else.
+ *
+ * Both halves are applied because they answer different questions: the lazy
+ * import means nothing loads until a consumer actually opens a store, and the
+ * confinement means opening one is silent too. The filter is narrow — the type
+ * AND the text — so any other warning, experimental or not, still reaches the
+ * user. `packages/memory-sqlite/test/load-sqlite.test.ts` drives that with a
+ * control warning that must survive.
+ *
+ * ponytail: the patch is a global mutation, held for the duration of ONE
+ * memoised import. Ceiling: a warning emitted by unrelated code inside that
+ * window is still handed to the original emitter, but a concurrent patcher that
+ * replaces `process.emitWarning` in the same window would have its replacement
+ * restored away — which is why the restore checks that the function it is
+ * replacing is still ours. Upgrade path: delete this file's body down to a plain
+ * `import('node:sqlite')` the release `node:sqlite` stops being experimental in.
+ */
+export function loadSqlite() {
+    pending ??= importWithWarningConfined();
+    return pending;
+}
+async function importWithWarningConfined() {
+    const original = process.emitWarning;
+    const patched = (warning, ...rest) => {
+        const first = rest[0];
+        const type = typeof first === 'string' ? first : first?.type;
+        const text = typeof warning === 'string' ? warning : warning.message;
+        if (type === 'ExperimentalWarning' && text.includes('SQLite'))
+            return;
+        original.call(process, warning, ...rest);
+    };
+    process.emitWarning = patched;
+    try {
+        return await import('node:sqlite');
+    }
+    finally {
+        if (process.emitWarning === patched)
+            process.emitWarning = original;
+    }
+}

package/dist/sqlite-memory-provider.d.ts

@@ -0,0 +1,29 @@
+import type { MemoryEntry, MemoryProvider, MemorySaveRequest, MemorySearchQuery, MemorySearchResult, MemoryStoreInfo, MemoryTimeline } from '@skanl/brambo-contracts';
+export interface SqliteMemoryProviderOptions {
+    /** Path to the SQLite database file. Its directory must already exist. */
+    readonly databasePath: string;
+}
+/**
+ * Embedded-SQLite MemoryProvider on `node:sqlite`'s `DatabaseSync`.
+ *
+ * NO new dependency: `node:sqlite` is the platform, measured working on Node
+ * 24.14.1 and 26.8.1 — the exact two versions CI runs. Its experimental warning
+ * is handled in `load-sqlite.ts`, which is also why this module imports the
+ * class TYPE only and the runtime binding arrives through `loadSqlite()`.
+ *
+ * Append-only is enforced by omission and by SQL: this file contains no UPDATE
+ * and no DELETE, and the format version lives in `PRAGMA user_version`, which is
+ * where SQLite already keeps exactly this fact.
+ */
+export declare class SqliteMemoryProvider implements MemoryProvider {
+    #private;
+    private constructor();
+    static open(options: SqliteMemoryProviderOptions): Promise<SqliteMemoryProvider>;
+    save(request: MemorySaveRequest): Promise<MemoryEntry>;
+    search(query: MemorySearchQuery): Promise<MemorySearchResult>;
+    timeline(): Promise<MemoryTimeline>;
+    describe(): Promise<MemoryStoreInfo>;
+    overwrite(entryId: string): Promise<never>;
+    /** Idempotent, and destroys nothing: the database file outlives every provider. */
+    dispose(): Promise<void>;
+}

package/dist/sqlite-memory-provider.js

@@ -0,0 +1,223 @@
+import { randomUUID } from 'node:crypto';
+import { MEMORY_FORMAT_VERSION, BramboError, BRAMBO_ERROR_CODES, memoryOverwriteUnsupported, memoryStoreVersionMismatch, validateMemorySaveRequest, } from '@skanl/brambo-contracts';
+import { loadSqlite } from './load-sqlite.js';
+/**
+ * The store, as one table. `sequence` is `INTEGER PRIMARY KEY AUTOINCREMENT`
+ * rather than a plain rowid alias: AUTOINCREMENT is what guarantees the counter
+ * never goes backwards, and an append-only log with a reused sequence number is
+ * a log that reorders itself.
+ */
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS entries (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  payload TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  workspace_id TEXT NOT NULL,
+  recorded_at TEXT NOT NULL,
+  supersedes TEXT
+)`;
+const COLUMNS = 'sequence, id, payload, agent_id, workspace_id, recorded_at, supersedes';
+/**
+ * Embedded-SQLite MemoryProvider on `node:sqlite`'s `DatabaseSync`.
+ *
+ * NO new dependency: `node:sqlite` is the platform, measured working on Node
+ * 24.14.1 and 26.8.1 — the exact two versions CI runs. Its experimental warning
+ * is handled in `load-sqlite.ts`, which is also why this module imports the
+ * class TYPE only and the runtime binding arrives through `loadSqlite()`.
+ *
+ * Append-only is enforced by omission and by SQL: this file contains no UPDATE
+ * and no DELETE, and the format version lives in `PRAGMA user_version`, which is
+ * where SQLite already keeps exactly this fact.
+ */
+export class SqliteMemoryProvider {
+    #databasePath;
+    #db;
+    #disposed = false;
+    constructor(databasePath, db) {
+        this.#databasePath = databasePath;
+        this.#db = db;
+    }
+    static async open(options) {
+        const databasePath = options?.databasePath;
+        if (typeof databasePath !== 'string' || databasePath.trim().length === 0) {
+            throw new BramboError(BRAMBO_ERROR_CODES.contractMemoryStoreUnavailable, 'SqliteMemoryProvider requires a non-empty string databasePath');
+        }
+        const { DatabaseSync: Database } = await loadSqlite();
+        let db;
+        try {
+            db = new Database(databasePath);
+        }
+        catch (error) {
+            throw unavailable('open', databasePath, error);
+        }
+        try {
+            const found = readUserVersion(db, databasePath);
+            // 0 is SQLite's default for a database nobody has stamped: an absent store,
+            // not a wrong one (AD-5). Any OTHER value is a store this build refuses —
+            // version by reject, never migrate.
+            if (found !== 0 && found !== MEMORY_FORMAT_VERSION) {
+                throw memoryStoreVersionMismatch(databasePath, found);
+            }
+            db.exec(SCHEMA);
+            if (found === 0)
+                db.exec(`PRAGMA user_version = ${String(MEMORY_FORMAT_VERSION)}`);
+        }
+        catch (error) {
+            // A database opened but not accepted must not be left open, or a caller
+            // that retries after fixing the store meets a lock it cannot explain.
+            try {
+                db.close();
+            }
+            catch {
+                // The refusal below is the verdict; a close failure must not replace it.
+            }
+            throw error instanceof BramboError ? error : unavailable('initialise', databasePath, error);
+        }
+        return new SqliteMemoryProvider(databasePath, db);
+    }
+    async save(request) {
+        this.#assertActive();
+        const valid = validateMemorySaveRequest(request);
+        if (valid.supersedes !== undefined) {
+            const existing = this.#db.prepare('SELECT 1 AS present FROM entries WHERE id = ?').get(valid.supersedes);
+            if (existing === undefined) {
+                throw new BramboError(BRAMBO_ERROR_CODES.contractMemoryUnknownEntry, `memory store '${this.#databasePath}' holds no entry '${valid.supersedes}' to supersede`);
+            }
+        }
+        const id = randomUUID();
+        let inserted;
+        try {
+            inserted = this.#db
+                .prepare('INSERT INTO entries (id, payload, agent_id, workspace_id, recorded_at, supersedes) VALUES (?, ?, ?, ?, ?, ?)')
+                .run(id, valid.payload, valid.provenance.agentId, valid.provenance.workspaceId, valid.provenance.recordedAt, valid.supersedes ?? null);
+        }
+        catch (error) {
+            throw unavailable('append to', this.#databasePath, error);
+        }
+        return Object.freeze({
+            id,
+            sequence: Number(inserted.lastInsertRowid),
+            payload: valid.payload,
+            provenance: Object.freeze({
+                agentId: valid.provenance.agentId,
+                workspaceId: valid.provenance.workspaceId,
+                recordedAt: valid.provenance.recordedAt,
+            }),
+            ...(valid.supersedes === undefined ? {} : { supersedes: valid.supersedes }),
+        });
+    }
+    async search(query) {
+        this.#assertActive();
+        const conditions = [];
+        const parameters = [];
+        if (query?.workspaceId !== undefined) {
+            conditions.push('workspace_id = ?');
+            parameters.push(query.workspaceId);
+        }
+        if (query?.agentId !== undefined) {
+            conditions.push('agent_id = ?');
+            parameters.push(query.agentId);
+        }
+        if (query?.contains !== undefined) {
+            // `instr`, not `LIKE`: LIKE is case-INSENSITIVE for ASCII by default and
+            // would disagree with `String.prototype.includes` in the filesystem
+            // provider on exactly the inputs FR-16 says must behave identically.
+            // Measured on the empty needle too — `instr(x, '') = 1`, matching
+            // `''.includes('') === true`.
+            conditions.push('instr(payload, ?) > 0');
+            parameters.push(query.contains);
+        }
+        const where = conditions.length === 0 ? '' : ` WHERE ${conditions.join(' AND ')}`;
+        const rows = this.#db.prepare(`SELECT ${COLUMNS} FROM entries${where} ORDER BY sequence ASC`).all(...parameters);
+        const entries = rows.map((row) => this.#toEntry(row));
+        return { entries, matched: entries.length };
+    }
+    async timeline() {
+        this.#assertActive();
+        const rows = this.#db.prepare(`SELECT ${COLUMNS} FROM entries ORDER BY sequence ASC`).all();
+        return { entries: rows.map((row) => this.#toEntry(row)) };
+    }
+    async describe() {
+        this.#assertActive();
+        const row = this.#db
+            .prepare('SELECT COUNT(*) AS entry_count, MIN(recorded_at) AS first_write, MAX(recorded_at) AS last_write FROM entries')
+            .get();
+        const entryCount = Number(row?.['entry_count'] ?? 0);
+        const first = row?.['first_write'];
+        const last = row?.['last_write'];
+        return {
+            formatVersion: MEMORY_FORMAT_VERSION,
+            entryCount,
+            // MIN/MAX over an empty table are SQL NULL. Absent, not null and not '' (AD-5).
+            ...(typeof first === 'string' && typeof last === 'string' ? { firstWriteAt: first, lastWriteAt: last } : {}),
+        };
+    }
+    async overwrite(entryId) {
+        this.#assertActive();
+        throw memoryOverwriteUnsupported(entryId);
+    }
+    /** Idempotent, and destroys nothing: the database file outlives every provider. */
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        try {
+            this.#db.close();
+        }
+        catch (error) {
+            throw unavailable('close', this.#databasePath, error);
+        }
+    }
+    #assertActive() {
+        if (this.#disposed) {
+            throw new BramboError(BRAMBO_ERROR_CODES.contractProviderDisposed, 'memory provider has been disposed and no longer serves its store');
+        }
+    }
+    /**
+     * Rows arrive as `SQLOutputValue`, a union that includes `null` and numbers.
+     * Every column is read through a type check rather than a cast, so a database
+     * someone else wrote into surfaces as a coded store failure instead of an
+     * entry with `null` where its workspace id should be — which is precisely the
+     * provenance leak D5 exists to prevent, arriving through the back door.
+     */
+    #toEntry(row) {
+        const sequence = row['sequence'];
+        if (typeof sequence !== 'number' && typeof sequence !== 'bigint') {
+            throw unavailable('read', this.#databasePath, new Error("column 'sequence' is not an integer"));
+        }
+        const supersedes = row['supersedes'];
+        if (supersedes !== null && typeof supersedes !== 'string') {
+            throw unavailable('read', this.#databasePath, new Error("column 'supersedes' is neither NULL nor text"));
+        }
+        return Object.freeze({
+            id: this.#text(row, 'id'),
+            sequence: Number(sequence),
+            payload: this.#text(row, 'payload'),
+            provenance: Object.freeze({
+                agentId: this.#text(row, 'agent_id'),
+                workspaceId: this.#text(row, 'workspace_id'),
+                recordedAt: this.#text(row, 'recorded_at'),
+            }),
+            ...(supersedes === null ? {} : { supersedes }),
+        });
+    }
+    #text(row, column) {
+        const value = row[column];
+        if (typeof value !== 'string') {
+            throw unavailable('read', this.#databasePath, new Error(`column '${column}' is not text`));
+        }
+        return value;
+    }
+}
+function readUserVersion(db, databasePath) {
+    const row = db.prepare('PRAGMA user_version').get();
+    const found = row?.['user_version'];
+    if (typeof found !== 'number' && typeof found !== 'bigint') {
+        throw unavailable('read the format version of', databasePath, new Error('PRAGMA user_version returned no integer'));
+    }
+    return Number(found);
+}
+function unavailable(operation, path, error) {
+    return new BramboError(BRAMBO_ERROR_CODES.contractMemoryStoreUnavailable, `memory store failed to ${operation} '${path}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@skanl/brambo-memory-sqlite",
+  "version": "0.1.1",
+  "description": "The embedded-SQLite MemoryProvider, on node:sqlite's DatabaseSync.",
+  "keywords": [
+    "ai-agent",
+    "brambo",
+    "memory",
+    "sqlite",
+    "persistence"
+  ],
+  "homepage": "https://github.com/SKANL/brambo#readme",
+  "bugs": {
+    "url": "https://github.com/SKANL/brambo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SKANL/brambo.git",
+    "directory": "packages/memory-sqlite"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "brambo-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skanl/brambo-contracts": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json"
+  }
+}