@dzhechkov/memory 0.2.0

package/src/cascade.ts

@@ -0,0 +1,52 @@
+/**
+ * The backend cascade — probe optional backends, fall back gracefully.
+ *
+ * Heavier backends (a vector / embedding store, `agentdb`, `sql.js`) can be
+ * registered as probes. If none initialises, a guaranteed fallback is used.
+ * This keeps such backends *optional* — never a hard dependency.
+ *
+ * @packageDocumentation
+ */
+
+import type { MemoryBackend } from './backend.js';
+
+/** A candidate backend the cascade may select. */
+export interface BackendProbe {
+  /** Probe name, for the `tried` log. */
+  readonly name: string;
+  /** Try to create the backend; resolve `undefined` (or throw) if unavailable. */
+  create(): Promise<MemoryBackend | undefined>;
+}
+
+/** The outcome of {@link selectBackend}. */
+export interface CascadeResult {
+  /** The selected backend. */
+  readonly backend: MemoryBackend;
+  /** Name of the selected backend (probe name, or the fallback's name). */
+  readonly selected: string;
+  /** Probe names attempted, in order. */
+  readonly tried: string[];
+}
+
+/**
+ * Walk `probes` in order; return the first backend that initialises. If every
+ * probe is unavailable (returns `undefined` or throws), return `fallback`.
+ */
+export async function selectBackend(
+  probes: readonly BackendProbe[],
+  fallback: MemoryBackend,
+): Promise<CascadeResult> {
+  const tried: string[] = [];
+  for (const probe of probes) {
+    tried.push(probe.name);
+    try {
+      const backend = await probe.create();
+      if (backend !== undefined) {
+        return { backend, selected: probe.name, tried };
+      }
+    } catch {
+      // probe unavailable — fall through to the next
+    }
+  }
+  return { backend: fallback, selected: fallback.name, tried };
+}

package/src/dreaming.ts

@@ -0,0 +1,127 @@
+/**
+ * Agent SDK Dreaming integration — bridges Opus 4.8 Dreaming with Reflexion.
+ *
+ * Per ADR-005: this is orchestration-layer code. It reads session JSONL files
+ * (produced by Agent SDK), extracts patterns, and feeds them into the Reflexion
+ * system. The MemoryBackend interface is unchanged.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { MemoryRecord } from './backend.js';
+
+/** A pattern extracted from an Agent SDK session. */
+export interface DreamPattern {
+  readonly skillId: string;
+  readonly outcome: 'excellent' | 'good' | 'needs_work' | 'failed';
+  readonly score: number;
+  readonly insight: string;
+  readonly sessionFile: string;
+  readonly timestamp: string;
+}
+
+/** Options for the dream harvester. */
+export interface DreamOptions {
+  /** Directory containing Agent SDK session JSONL files. */
+  readonly sessionsDir: string;
+  /** Only process sessions newer than this ISO timestamp. */
+  readonly since?: string;
+}
+
+/**
+ * Harvest patterns from Agent SDK session files.
+ *
+ * Scans `.jsonl` files in `sessionsDir`, extracts tool-use outcomes
+ * and skill invocations, and returns them as `DreamPattern`s ready
+ * to be fed into Reflexion via `reflexion.record()`.
+ */
+export function harvestDreamPatterns(options: DreamOptions): DreamPattern[] {
+  const { sessionsDir, since } = options;
+  if (!existsSync(sessionsDir)) return [];
+
+  const patterns: DreamPattern[] = [];
+  const files = readdirSync(sessionsDir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .sort();
+
+  for (const file of files) {
+    const filePath = join(sessionsDir, file);
+    const lines = readFileSync(filePath, 'utf-8').split('\n').filter((l) => l.trim().length > 0);
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+
+        // Skip entries older than `since`
+        if (since !== undefined && entry.timestamp && entry.timestamp < since) continue;
+
+        // Extract skill invocations from tool_use messages
+        if (entry.type === 'assistant' && entry.message?.content) {
+          const content = Array.isArray(entry.message.content) ? entry.message.content : [entry.message.content];
+          for (const block of content) {
+            if (block.type === 'tool_use' && block.name?.startsWith?.('mcp__')) {
+              // MCP tool invocation — extract skill context
+              const skillId = block.input?.targetPath ?? block.input?.scope ?? 'unknown';
+              patterns.push({
+                skillId: typeof skillId === 'string' ? skillId : 'unknown',
+                outcome: 'good',
+                score: 0.7,
+                insight: `Tool ${block.name} invoked during session`,
+                sessionFile: file,
+                timestamp: entry.timestamp ?? new Date().toISOString(),
+              });
+            }
+          }
+        }
+
+        // Extract checkpoint responses (reward signals)
+        if (entry.type === 'user' && typeof entry.message?.content === 'string') {
+          const text = entry.message.content.toLowerCase();
+          let outcome: DreamPattern['outcome'] = 'good';
+          let score = 0.7;
+          if (text === 'ок' || text === 'ok' || text === 'next' || text === 'продолжай') {
+            outcome = 'excellent';
+            score = 1.0;
+          } else if (text.includes('переделай') || text.includes('rework') || text.includes('заново')) {
+            outcome = 'needs_work';
+            score = 0.3;
+          } else if (text.includes('стоп') || text.includes('stop') || text.includes('wrong')) {
+            outcome = 'failed';
+            score = 0.0;
+          }
+
+          if (outcome !== 'good') {
+            patterns.push({
+              skillId: 'checkpoint-response',
+              outcome,
+              score,
+              insight: `User responded: "${entry.message.content.slice(0, 100)}"`,
+              sessionFile: file,
+              timestamp: entry.timestamp ?? new Date().toISOString(),
+            });
+          }
+        }
+      } catch {
+        // Skip malformed JSONL lines
+      }
+    }
+  }
+
+  return patterns;
+}
+
+/** Convert a DreamPattern to a MemoryRecord for storage via any MemoryBackend. */
+export function dreamPatternToRecord(pattern: DreamPattern): MemoryRecord {
+  return {
+    id: `dream:${pattern.sessionFile}:${pattern.skillId}:${Date.now()}`,
+    skillId: pattern.skillId,
+    text: pattern.insight,
+    score: pattern.score,
+    outcome: pattern.outcome,
+    timestamp: pattern.timestamp,
+    metadata: { sessionFile: pattern.sessionFile },
+  };
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `@dzhechkov/memory` — the harness memory layer.
+ *
+ * @packageDocumentation
+ */
+
+/** Package version. Kept in sync with `package.json`. */
+export const MEMORY_VERSION = '0.1.0';
+
+export type { MemoryBackend, MemoryQuery, MemoryRecord } from './backend.js';
+export { JsonFileBackend } from './json-backend.js';
+export type { JsonFileBackendOptions } from './json-backend.js';
+export { selectBackend } from './cascade.js';
+export type { BackendProbe, CascadeResult } from './cascade.js';
+export { SqliteBackend } from './sqlite-backend.js';
+export type { SqliteBackendOptions } from './sqlite-backend.js';
+export { SqliteProbe } from './sqlite-probe.js';
+export type { SqliteProbeOptions } from './sqlite-probe.js';
+export { Reflexion } from './reflexion.js';
+export type { ReflexionInput } from './reflexion.js';
+export { importMemoryMarkdown, MemoryBridge } from './bridge.js';
+export type { BridgeOptions } from './bridge.js';
+export { harvestDreamPatterns, dreamPatternToRecord } from './dreaming.js';
+export type { DreamPattern, DreamOptions } from './dreaming.js';

package/src/json-backend.ts

@@ -0,0 +1,109 @@
+/**
+ * `JsonFileBackend` — the default memory backend.
+ *
+ * Pure JavaScript, zero runtime dependencies: records live in an in-memory map
+ * and persist to a JSON file. Retrieval is scored keyword overlap. No native
+ * build, no WASM, no model download — it works everywhere.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import type { MemoryBackend, MemoryQuery, MemoryRecord } from './backend.js';
+
+const DEFAULT_LIMIT = 20;
+
+/** Split text into lowercase word tokens of length > 1. */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length > 1);
+}
+
+/** Count how many query terms appear in a record's text/skillId. */
+function relevanceOf(record: MemoryRecord, terms: readonly string[]): number {
+  if (terms.length === 0) return 0;
+  const haystack = new Set(tokenize(`${record.text} ${record.skillId}`));
+  let hits = 0;
+  for (const term of terms) {
+    if (haystack.has(term)) hits += 1;
+  }
+  return hits;
+}
+
+/** Options for {@link JsonFileBackend}. */
+export interface JsonFileBackendOptions {
+  /** File the records persist to. Omit for an in-memory-only backend. */
+  readonly filePath?: string;
+}
+
+/** The default memory backend — in-memory map with optional JSON-file persistence. */
+export class JsonFileBackend implements MemoryBackend {
+  readonly name = 'json-file';
+
+  private readonly records = new Map<string, MemoryRecord>();
+  private readonly filePath: string | undefined;
+
+  constructor(options: JsonFileBackendOptions = {}) {
+    this.filePath = options.filePath;
+  }
+
+  /** Create a backend and load any records already persisted at `filePath`. */
+  static async open(filePath: string): Promise<JsonFileBackend> {
+    const backend = new JsonFileBackend({ filePath });
+    await backend.load();
+    return backend;
+  }
+
+  put(record: MemoryRecord): Promise<void> {
+    this.records.set(record.id, record);
+    return Promise.resolve();
+  }
+
+  query(query: MemoryQuery): Promise<MemoryRecord[]> {
+    const limit = query.limit ?? DEFAULT_LIMIT;
+    const terms = query.text !== undefined ? tokenize(query.text) : [];
+    let candidates = [...this.records.values()];
+    if (query.skillId !== undefined) {
+      candidates = candidates.filter((record) => record.skillId === query.skillId);
+    }
+    const ranked = candidates
+      .map((record) => ({ record, relevance: relevanceOf(record, terms) }))
+      .sort(
+        (a, b) =>
+          b.relevance - a.relevance ||
+          b.record.score - a.record.score ||
+          b.record.timestamp.localeCompare(a.record.timestamp),
+      );
+    return Promise.resolve(ranked.slice(0, limit).map((entry) => entry.record));
+  }
+
+  all(): Promise<MemoryRecord[]> {
+    return Promise.resolve([...this.records.values()]);
+  }
+
+  count(): Promise<number> {
+    return Promise.resolve(this.records.size);
+  }
+
+  /** Persist every record to `filePath`. No-op when no path is configured. */
+  save(): Promise<void> {
+    if (this.filePath !== undefined) {
+      mkdirSync(dirname(this.filePath), { recursive: true });
+      writeFileSync(this.filePath, JSON.stringify([...this.records.values()], null, 2));
+    }
+    return Promise.resolve();
+  }
+
+  /** Load records from `filePath`. No-op when no path is set or the file is absent. */
+  load(): Promise<void> {
+    if (this.filePath !== undefined && existsSync(this.filePath)) {
+      const data = JSON.parse(readFileSync(this.filePath, 'utf-8')) as MemoryRecord[];
+      for (const record of data) this.records.set(record.id, record);
+    }
+    return Promise.resolve();
+  }
+}

package/src/reflexion.ts

@@ -0,0 +1,79 @@
+/**
+ * `Reflexion` — the skill-outcome feedback loop.
+ *
+ * Records the outcome of using a skill (`record(skillId, outcome, score)`) and
+ * ranks skills by their most recent score. Reads are **monotonic**: the latest
+ * record for a skill supersedes older ones.
+ *
+ * @packageDocumentation
+ */
+
+import type { MemoryBackend, MemoryRecord } from './backend.js';
+
+/** Monotonic counter — keeps record ids unique within a process. */
+let sequence = 0;
+
+/** Optional extras for {@link Reflexion.record}. */
+export interface ReflexionInput {
+  /** Free text to store (defaults to `"<skillId> <outcome>"`). */
+  readonly text?: string;
+  /** String-keyed metadata. */
+  readonly metadata?: Record<string, string>;
+}
+
+/** Records skill outcomes against a {@link MemoryBackend} and ranks skills. */
+export class Reflexion {
+  constructor(private readonly backend: MemoryBackend) {}
+
+  /**
+   * Record the outcome of using a skill.
+   *
+   * @param score reward score, must be within `[0, 1]`.
+   * @throws if `score` is outside `[0, 1]`.
+   */
+  async record(
+    skillId: string,
+    outcome: string,
+    score: number,
+    input: ReflexionInput = {},
+  ): Promise<MemoryRecord> {
+    if (!Number.isFinite(score) || score < 0 || score > 1) {
+      throw new Error(`reflexion: score must be within [0, 1], got ${score}`);
+    }
+    sequence += 1;
+    const record: MemoryRecord = {
+      id: `reflexion:${skillId}:${Date.now()}:${sequence}`,
+      skillId,
+      text: input.text ?? `${skillId} ${outcome}`,
+      score,
+      outcome,
+      timestamp: new Date().toISOString(),
+      ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+    };
+    await this.backend.put(record);
+    return record;
+  }
+
+  /** The most recently recorded score for a skill, or `undefined` if none. */
+  async scoreOf(skillId: string): Promise<number | undefined> {
+    const records = await this.backend.query({ skillId, limit: Number.MAX_SAFE_INTEGER });
+    if (records.length === 0) return undefined;
+    return records.reduce((latest, record) =>
+      record.timestamp >= latest.timestamp ? record : latest,
+    ).score;
+  }
+
+  /** Every skill with a recorded outcome, ranked by most-recent score, descending. */
+  async ranking(): Promise<{ skillId: string; score: number }[]> {
+    const latest = new Map<string, MemoryRecord>();
+    for (const record of await this.backend.all()) {
+      const current = latest.get(record.skillId);
+      if (current === undefined || record.timestamp > current.timestamp) {
+        latest.set(record.skillId, record);
+      }
+    }
+    return [...latest.values()]
+      .map((record) => ({ skillId: record.skillId, score: record.score }))
+      .sort((a, b) => b.score - a.score);
+  }
+}

package/src/sqlite-backend.ts

@@ -0,0 +1,263 @@
+/**
+ * `SqliteBackend` — production-scale memory backend using better-sqlite3.
+ *
+ * Write-through persistence (every `put` is durable), WAL mode for concurrency,
+ * and indexed columns for efficient queries. Handles 100k+ records where
+ * JsonFileBackend degrades.
+ *
+ * @packageDocumentation
+ */
+
+import { createRequire } from 'node:module';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import type { MemoryBackend, MemoryQuery, MemoryRecord } from './backend.js';
+
+const require = createRequire(import.meta.url);
+
+const DEFAULT_LIMIT = 20;
+
+/** Split text into lowercase word tokens of length > 1. */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length > 1);
+}
+
+/** Count how many query terms appear in a record's text/skillId. */
+function relevanceOf(record: MemoryRecord, terms: readonly string[]): number {
+  if (terms.length === 0) return 0;
+  const haystack = new Set(tokenize(`${record.text} ${record.skillId}`));
+  let hits = 0;
+  for (const term of terms) {
+    if (haystack.has(term)) hits += 1;
+  }
+  return hits;
+}
+
+/** Schema version for future migrations. */
+const SCHEMA_VERSION = 2;
+
+const INIT_SQL = `
+  CREATE TABLE IF NOT EXISTS memory_records (
+    id TEXT PRIMARY KEY,
+    skill_id TEXT NOT NULL,
+    text TEXT NOT NULL,
+    score REAL NOT NULL,
+    outcome TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    metadata TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_skill ON memory_records(skill_id);
+  CREATE INDEX IF NOT EXISTS idx_timestamp ON memory_records(timestamp);
+  PRAGMA user_version = ${SCHEMA_VERSION};
+`;
+
+/** FTS5 virtual table + triggers for automatic sync. */
+const FTS5_SQL = `
+  CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+    text, skill_id, content=memory_records, content_rowid=rowid
+  );
+  CREATE TRIGGER IF NOT EXISTS memory_fts_insert AFTER INSERT ON memory_records BEGIN
+    INSERT INTO memory_fts(rowid, text, skill_id) VALUES (new.rowid, new.text, new.skill_id);
+  END;
+  CREATE TRIGGER IF NOT EXISTS memory_fts_delete AFTER DELETE ON memory_records BEGIN
+    INSERT INTO memory_fts(memory_fts, rowid, text, skill_id) VALUES ('delete', old.rowid, old.text, old.skill_id);
+  END;
+  CREATE TRIGGER IF NOT EXISTS memory_fts_update AFTER UPDATE ON memory_records BEGIN
+    INSERT INTO memory_fts(memory_fts, rowid, text, skill_id) VALUES ('delete', old.rowid, old.text, old.skill_id);
+    INSERT INTO memory_fts(rowid, text, skill_id) VALUES (new.rowid, new.text, new.skill_id);
+  END;
+`;
+
+/** FTS5 query — returns matching record ids ranked by relevance. */
+const FTS5_SEARCH_SQL = `
+  SELECT mr.* FROM memory_fts fts
+  JOIN memory_records mr ON mr.rowid = fts.rowid
+  WHERE memory_fts MATCH ?
+  ORDER BY fts.rank
+`;
+
+const FTS5_SEARCH_SKILL_SQL = `
+  SELECT mr.* FROM memory_fts fts
+  JOIN memory_records mr ON mr.rowid = fts.rowid
+  WHERE memory_fts MATCH ? AND mr.skill_id = ?
+  ORDER BY fts.rank
+`;
+
+const UPSERT_SQL = `
+  INSERT OR REPLACE INTO memory_records (id, skill_id, text, score, outcome, timestamp, metadata)
+  VALUES (?, ?, ?, ?, ?, ?, ?)
+`;
+
+const ALL_SQL = 'SELECT * FROM memory_records';
+const COUNT_SQL = 'SELECT COUNT(*) as cnt FROM memory_records';
+const BY_SKILL_SQL = 'SELECT * FROM memory_records WHERE skill_id = ?';
+
+/** Options for SqliteBackend. */
+export interface SqliteBackendOptions {
+  /** Path to the SQLite database file. */
+  readonly filePath: string;
+}
+
+/**
+ * SQLite-backed memory store. Write-through, WAL mode, indexed.
+ *
+ * Requires `better-sqlite3` at runtime — use via {@link SqliteProbe} in the
+ * cascade to gracefully fall back when the native module is unavailable.
+ */
+export class SqliteBackend implements MemoryBackend {
+  readonly name = 'sqlite';
+
+  private readonly db: any; // better-sqlite3 Database instance
+  private readonly upsertStmt: any;
+  private readonly allStmt: any;
+  private readonly countStmt: any;
+  private readonly bySkillStmt: any;
+  private readonly ftsSearchStmt: any | undefined;
+  private readonly ftsSearchSkillStmt: any | undefined;
+  private readonly hasFts5: boolean;
+
+  constructor(db: any) {
+    this.db = db;
+    db.exec(INIT_SQL);
+
+    // Try to enable FTS5 — gracefully degrade if unavailable
+    let ftsOk = false;
+    try {
+      db.exec(FTS5_SQL);
+      // Rebuild FTS index from existing data (idempotent)
+      db.exec(`INSERT INTO memory_fts(memory_fts) VALUES ('rebuild')`);
+      this.ftsSearchStmt = db.prepare(FTS5_SEARCH_SQL);
+      this.ftsSearchSkillStmt = db.prepare(FTS5_SEARCH_SKILL_SQL);
+      ftsOk = true;
+    } catch {
+      // FTS5 not compiled in — fall back to keyword overlap
+    }
+    this.hasFts5 = ftsOk;
+
+    this.upsertStmt = db.prepare(UPSERT_SQL);
+    this.allStmt = db.prepare(ALL_SQL);
+    this.countStmt = db.prepare(COUNT_SQL);
+    this.bySkillStmt = db.prepare(BY_SKILL_SQL);
+  }
+
+  /** Open (or create) a SQLite database at the given path. */
+  static open(filePath: string): SqliteBackend {
+    mkdirSync(dirname(filePath), { recursive: true });
+    // Dynamic require — better-sqlite3 must be available at runtime
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Database = require('better-sqlite3');
+    const db = new Database(filePath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+    return new SqliteBackend(db);
+  }
+
+  put(record: MemoryRecord): Promise<void> {
+    this.upsertStmt.run(
+      record.id,
+      record.skillId,
+      record.text,
+      record.score,
+      record.outcome,
+      record.timestamp,
+      record.metadata ? JSON.stringify(record.metadata) : null,
+    );
+    return Promise.resolve();
+  }
+
+  query(query: MemoryQuery): Promise<MemoryRecord[]> {
+    const limit = query.limit ?? DEFAULT_LIMIT;
+
+    // FTS5 path — use SQLite full-text search when available and text query provided
+    if (this.hasFts5 && query.text !== undefined && query.text.trim().length > 0) {
+      try {
+        // FTS5 query syntax: simple terms joined by spaces (implicit AND → OR with ranking)
+        const ftsQuery = tokenize(query.text).join(' OR ');
+        if (ftsQuery.length > 0) {
+          let rows: any[];
+          if (query.skillId !== undefined) {
+            rows = this.ftsSearchSkillStmt!.all(ftsQuery, query.skillId);
+          } else {
+            rows = this.ftsSearchStmt!.all(ftsQuery);
+          }
+          const records = rows.map(rowToRecord);
+          // FTS5 rank is already applied; tiebreak by score DESC, timestamp DESC
+          records.sort(
+            (a, b) => b.score - a.score || b.timestamp.localeCompare(a.timestamp),
+          );
+          return Promise.resolve(records.slice(0, limit));
+        }
+      } catch {
+        // FTS5 query failed (e.g., special chars) — fall through to keyword approach
+      }
+    }
+
+    // Keyword overlap fallback
+    const terms = query.text !== undefined ? tokenize(query.text) : [];
+    let rows: any[];
+    if (query.skillId !== undefined) {
+      rows = this.bySkillStmt.all(query.skillId);
+    } else {
+      rows = this.allStmt.all();
+    }
+
+    const records = rows.map(rowToRecord);
+    const ranked = records
+      .map((record) => ({ record, relevance: relevanceOf(record, terms) }))
+      .sort(
+        (a, b) =>
+          b.relevance - a.relevance ||
+          b.record.score - a.record.score ||
+          b.record.timestamp.localeCompare(a.record.timestamp),
+      );
+    return Promise.resolve(ranked.slice(0, limit).map((entry) => entry.record));
+  }
+
+  all(): Promise<MemoryRecord[]> {
+    return Promise.resolve(this.allStmt.all().map(rowToRecord));
+  }
+
+  count(): Promise<number> {
+    return Promise.resolve(this.countStmt.get().cnt);
+  }
+
+  /** Batch insert records within a transaction (for bulk loading). */
+  putMany(records: readonly MemoryRecord[]): void {
+    const insertMany = this.db.transaction((items: readonly MemoryRecord[]) => {
+      for (const record of items) {
+        this.upsertStmt.run(
+          record.id,
+          record.skillId,
+          record.text,
+          record.score,
+          record.outcome,
+          record.timestamp,
+          record.metadata ? JSON.stringify(record.metadata) : null,
+        );
+      }
+    });
+    insertMany(records);
+  }
+
+  /** Close the database connection. */
+  close(): void {
+    this.db.close();
+  }
+}
+
+/** Convert a raw SQLite row to a MemoryRecord. */
+function rowToRecord(row: any): MemoryRecord {
+  return {
+    id: row.id,
+    skillId: row.skill_id,
+    text: row.text,
+    score: row.score,
+    outcome: row.outcome,
+    timestamp: row.timestamp,
+    metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+  };
+}

package/src/sqlite-probe.ts

@@ -0,0 +1,44 @@
+/**
+ * `SqliteProbe` — cascade probe for the SQLite backend.
+ *
+ * Attempts to load `better-sqlite3` and open the database. Returns `undefined`
+ * if the native module is unavailable (not installed, build failed, etc.).
+ *
+ * @packageDocumentation
+ */
+
+import type { BackendProbe } from './cascade.js';
+import type { MemoryBackend } from './backend.js';
+
+/** Options for SqliteProbe. */
+export interface SqliteProbeOptions {
+  /** Path to the SQLite database file. Default: `.dz/memory.sqlite` */
+  readonly filePath?: string;
+}
+
+/**
+ * A {@link BackendProbe} that tries to initialise a SQLite backend.
+ * Safe to construct unconditionally — if `better-sqlite3` is not installed,
+ * `create()` returns `undefined` and the cascade moves on.
+ */
+export class SqliteProbe implements BackendProbe {
+  readonly name = 'sqlite';
+  private readonly filePath: string;
+
+  constructor(options: SqliteProbeOptions = {}) {
+    this.filePath = options.filePath ?? '.dz/memory.sqlite';
+  }
+
+  async create(): Promise<MemoryBackend | undefined> {
+    try {
+      // Attempt to load better-sqlite3 via the SqliteBackend.
+      // If the native module is not installed, this throws and we return undefined.
+      const { SqliteBackend } = await import('./sqlite-backend.js');
+      const backend = SqliteBackend.open(this.filePath);
+      return backend;
+    } catch {
+      // Module not available or build failed — fall through
+      return undefined;
+    }
+  }
+}