agent-working-memory 0.7.16 → 0.8.5

package/src/storage/sqlite.ts

@@ -9,6 +9,7 @@
 
 import Database from 'better-sqlite3';
 import { randomUUID } from 'node:crypto';
+import { cosineSimilarity } from '../core/embeddings.js';
 import type {
   Engram, EngramCreate, EngramStage, Association, AssociationType,
   SearchQuery, SalienceFeatures, ActivationEvent, StagingEvent,
@@ -369,6 +370,26 @@ export class EngramStore {
     } catch {
       this.db.exec(`ALTER TABLE engrams ADD COLUMN memory_type TEXT NOT NULL DEFAULT 'unclassified'`);
     }
+
+    // Migration (0.8 Cluster A): sequence column for story-time / chronology.
+    // Nullable — existing engrams stay NULL. Partial index keeps the cost low.
+    try {
+      this.db.prepare('SELECT sequence FROM engrams LIMIT 0').get();
+    } catch {
+      this.db.exec(`ALTER TABLE engrams ADD COLUMN sequence INTEGER`);
+      this.db.exec(
+        `CREATE INDEX IF NOT EXISTS idx_engrams_agent_sequence
+         ON engrams(agent_id, sequence) WHERE sequence IS NOT NULL`
+      );
+    }
+
+    // Migration (0.8 Cluster A): references_json column for typed cross-record
+    // links. Wired through HTTP in Cluster D — schema slot only here.
+    try {
+      this.db.prepare('SELECT references_json FROM engrams LIMIT 0').get();
+    } catch {
+      this.db.exec(`ALTER TABLE engrams ADD COLUMN references_json TEXT`);
+    }
   }
 
   // --- Engram CRUD ---
@@ -383,8 +404,9 @@ export class EngramStore {
     this.db.prepare(`
       INSERT INTO engrams (id, agent_id, concept, content, embedding, confidence, salience,
         access_count, last_accessed, created_at, salience_features, reason_codes, stage, tags, episode_id,
-        ttl, memory_class, supersedes, task_status, task_priority, blocked_by, memory_type)
-      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ttl, memory_class, supersedes, task_status, task_priority, blocked_by, memory_type,
+        sequence, references_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       id, input.agentId, input.concept, input.content, embeddingBlob,
       input.confidence ?? 0.5,
@@ -401,6 +423,9 @@ export class EngramStore {
       input.taskPriority ?? null,
       input.blockedBy ?? null,
       input.memoryType ?? 'unclassified',
+      input.sequence ?? null,
+      input.references && input.references.length > 0
+        ? JSON.stringify(input.references) : null,
     );
 
     // Add to slim cache (skip if not yet populated — first slim fetch will load it)
@@ -575,7 +600,7 @@ export class EngramStore {
     if (agentIds.length === 1) return this.searchBM25WithRank(agentIds[0], query, limit);
 
     const sanitized = query
-      .replace(/[^\w\s]/g, '')
+      .replace(/[^\w\s]/g, ' ')   // Split on punctuation so hyphenated IDs (PROJ-1000) match FTS5's separator-split tokens.
       .split(/\s+/)
       .filter(w => w.length > 1)
       .map(w => `"${w}"`)
@@ -650,6 +675,16 @@ export class EngramStore {
     this.cacheUpdateStage(id, stage);
   }
 
+  /**
+   * Replace an engram's content. Used by the fade phase of consolidation
+   * (Paper 1: storage degradation) to coarsen un-recalled memories without
+   * deleting them — concept + tags stay intact for tag-based retrieval, but
+   * BM25 content surface area shrinks.
+   */
+  updateContent(id: string, content: string): void {
+    this.db.prepare('UPDATE engrams SET content = ? WHERE id = ?').run(content, id);
+  }
+
   updateConfidence(id: string, confidence: number): void {
     this.db.prepare('UPDATE engrams SET confidence = ? WHERE id = ?').run(
       Math.max(0, Math.min(1, confidence)), id
@@ -712,6 +747,46 @@ export class EngramStore {
     return this.searchBM25WithRank(agentId, query, limit).map(r => r.engram);
   }
 
+  /**
+   * Vector similarity top-K search. SQLite has no native vector index, so we
+   * iterate over the slim cache, compute cosine similarity in-process, and
+   * return the top-K nearest neighbors. PGlite uses pgvector + ivfflat for
+   * the same operation in O(log N).
+   *
+   * Returns engrams with their cosine distance (0 = identical, 2 = opposite)
+   * to match the PGlite contract. Activation engine consumes `1 - distance`
+   * as the cosine similarity score.
+   */
+  searchByVector(
+    agentId: string,
+    vec: number[],
+    limit: number = 10,
+  ): Array<{ engram: Engram; distance: number }> {
+    if (!vec || vec.length === 0) return [];
+    // Include both 'active' and 'fading' — faded engrams retain their embedding
+    // (Paper 1: storage degradation; only content is trimmed) so they should still
+    // participate in vector recall. Concept + tags + truncated content remain in BM25.
+    const activeSlim = this.getEngramsByAgentSlim(agentId, 'active', false);
+    const fadingSlim = this.getEngramsByAgentSlim(agentId, 'fading', false);
+    const slim = activeSlim.concat(fadingSlim);
+    const scored: Array<{ id: string; sim: number }> = [];
+    for (const e of slim) {
+      if (!e.embedding) continue;
+      const sim = cosineSimilarity(vec, e.embedding);
+      scored.push({ id: e.id, sim });
+    }
+    scored.sort((a, b) => b.sim - a.sim);
+    const topIds = scored.slice(0, limit).map(s => s.id);
+    if (topIds.length === 0) return [];
+    const engrams = this.getEngramsByIds(topIds);
+    const engramMap = new Map(engrams.map(e => [e.id, e]));
+    return scored
+      .slice(0, limit)
+      .map(s => ({ engram: engramMap.get(s.id), sim: s.sim }))
+      .filter((x): x is { engram: Engram; sim: number } => x.engram !== undefined)
+      .map(x => ({ engram: x.engram, distance: 1 - x.sim }));
+  }
+
   /**
    * BM25 search returning rank scores alongside engrams.
    * FTS5 rank is negative (lower = better match).
@@ -720,7 +795,7 @@ export class EngramStore {
   searchBM25WithRank(agentId: string, query: string, limit: number = 10): { engram: Engram; bm25Score: number }[] {
     // Sanitize query for FTS5: quote each word to prevent column name interpretation
     const sanitized = query
-      .replace(/[^\w\s]/g, '')
+      .replace(/[^\w\s]/g, ' ')   // Split on punctuation so hyphenated IDs (PROJ-1000) match FTS5's separator-split tokens.
       .split(/\s+/)
       .filter(w => w.length > 1)
       .map(w => `"${w}"`)
@@ -789,14 +864,48 @@ export class EngramStore {
       sql += ' AND retracted = ?';
       params.push(query.retracted ? 1 : 0);
     }
-    if (query.tags && query.tags.length > 0) {
-      for (const tag of query.tags) {
+
+    // ── Tag filters (0.8 Cluster B) ──
+    // AND-set: merge legacy `tags` + new `tagsAll`. Both apply (intersection).
+    const allTags = [...(query.tags ?? []), ...(query.tagsAll ?? [])];
+    if (allTags.length > 0) {
+      for (const tag of allTags) {
         sql += ' AND tags LIKE ?';
         params.push(`%"${tag}"%`);
       }
     }
+    // OR-set: at least one must match.
+    if (query.tagsAny && query.tagsAny.length > 0) {
+      const ors = query.tagsAny.map(() => 'tags LIKE ?').join(' OR ');
+      sql += ` AND (${ors})`;
+      for (const tag of query.tagsAny) params.push(`%"${tag}"%`);
+    }
+    // NOT-set: none may match.
+    if (query.tagsNone && query.tagsNone.length > 0) {
+      const ors = query.tagsNone.map(() => 'tags LIKE ?').join(' OR ');
+      sql += ` AND NOT (${ors})`;
+      for (const tag of query.tagsNone) params.push(`%"${tag}"%`);
+    }
+
+    // ── Sort (0.8 Cluster B) ──
+    // Default preserves legacy behavior (last_accessed DESC). Map TS camelCase
+    // to SQL snake_case. `sequence` puts NULLs last via (col IS NULL) trick.
+    const sortCol = ({
+      createdAt: 'created_at',
+      sequence: 'sequence',
+      salience: 'salience',
+      confidence: 'confidence',
+      lastAccessed: 'last_accessed',
+    } as const)[query.sortBy ?? 'lastAccessed'];
+    const dir = query.sortOrder === 'asc' ? 'ASC' : 'DESC';
+    if (query.sortBy === 'sequence') {
+      // NULLs last regardless of direction so engrams without a story-time
+      // value don't shuffle into the middle of sequenced results.
+      sql += ` ORDER BY (sequence IS NULL), sequence ${dir}`;
+    } else {
+      sql += ` ORDER BY ${sortCol} ${dir}`;
+    }
 
-    sql += ' ORDER BY last_accessed DESC';
     sql += ` LIMIT ? OFFSET ?`;
     params.push(query.limit ?? 50, query.offset ?? 0);
 
@@ -889,6 +998,37 @@ export class EngramStore {
     this.db.prepare('UPDATE engrams SET supersedes = ? WHERE id = ?').run(oldId, newId);
   }
 
+  /**
+   * Find the most recent active engram matching `concept` (case-insensitive,
+   * trimmed) and all of `requiredTags`. Excludes superseded and retracted
+   * engrams. Used by /memory/supersede Form B (0.8 Cluster D) and by
+   * /memory/write's references[] resolution.
+   *
+   * Returns null if no match.
+   */
+  findActiveMatchByConcept(
+    agentId: string,
+    concept: string,
+    requiredTags?: string[],
+  ): Engram | null {
+    let sql = `SELECT * FROM engrams
+               WHERE agent_id = ?
+               AND LOWER(TRIM(concept)) = LOWER(TRIM(?))
+               AND stage = 'active'
+               AND retracted = 0
+               AND superseded_by IS NULL`;
+    const params: any[] = [agentId, concept];
+    if (requiredTags && requiredTags.length > 0) {
+      for (const tag of requiredTags) {
+        sql += ' AND tags LIKE ?';
+        params.push(`%"${tag}"%`);
+      }
+    }
+    sql += ' ORDER BY created_at DESC LIMIT 1';
+    const row = this.db.prepare(sql).get(...params) as any;
+    return row ? this.rowToEngram(row) : null;
+  }
+
   /**
    * Check if an engram has been superseded.
    */
@@ -1223,6 +1363,8 @@ export class EngramStore {
       taskStatus: row.task_status ?? null,
       taskPriority: row.task_priority ?? null,
       blockedBy: row.blocked_by ?? null,
+      sequence: row.sequence == null ? null : Number(row.sequence),
+      references: row.references_json ? JSON.parse(row.references_json) : null,
     };
   }
 
@@ -1463,4 +1605,257 @@ export class EngramStore {
     this.walCheckpoint();
     this.db.close();
   }
+
+  /**
+   * Run `fn` in a SQL transaction. All writes succeed atomically or roll back
+   * on throw. Synchronous (matches better-sqlite3 semantics).
+   *
+   * Used by 0.8 Cluster D's `/memory/supersede` Form B to wrap find-match +
+   * performWrite + supersede + causal-edge + confidence-decay so callers
+   * never observe an intermediate state where new engram exists but old
+   * isn't yet superseded.
+   */
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  /**
+   * Async-aware transaction wrapper. `fn` may await — we hold the SQLite
+   * lock across awaits by issuing raw BEGIN/COMMIT/ROLLBACK statements rather
+   * than using better-sqlite3's sync `db.transaction()`.
+   *
+   * Used by Form B (atomic write + supersede) where the body calls
+   * async store methods through the IEngramStore contract.
+   */
+  async withTransaction<T>(fn: () => Promise<T>): Promise<T> {
+    this.db.exec('BEGIN');
+    try {
+      const result = await fn();
+      this.db.exec('COMMIT');
+      return result;
+    } catch (err) {
+      try { this.db.exec('ROLLBACK'); } catch { /* best-effort */ }
+      throw err;
+    }
+  }
+
+  // ============================================================
+  // 0.8 Cluster C — materialized-view + atomic-counter primitives
+  // ============================================================
+
+  /**
+   * For each distinct value of the tag whose key prefix is `tagKeyPrefix`
+   * (e.g. `"character="`), return the most-recent active engram. Used by
+   * NovelForge's "latest emotional state per character", "latest motif
+   * phase per motif", "recent chapter summaries".
+   *
+   * `sortBy` defaults to `createdAt`. With `"sequence"`, engrams without a
+   * sequence are excluded (they have no story-time anchor).
+   */
+  getLatestByTag(opts: {
+    agentId: string;
+    tagKeyPrefix: string;          // e.g. "character=", "motif=", "chapter="
+    scopeTagsAll?: string[];       // optional narrowing (e.g. ["topic=motif-use"])
+    retracted?: boolean;
+    sortBy?: 'createdAt' | 'sequence';
+    limit?: number;
+  }): Engram[] {
+    let sql = `SELECT * FROM engrams
+               WHERE agent_id = ?
+               AND retracted = ?
+               AND stage = 'active'
+               AND tags LIKE ?`;
+    const params: any[] = [
+      opts.agentId,
+      opts.retracted ? 1 : 0,
+      `%"${opts.tagKeyPrefix}%`,
+    ];
+    if (opts.scopeTagsAll && opts.scopeTagsAll.length > 0) {
+      for (const t of opts.scopeTagsAll) {
+        sql += ' AND tags LIKE ?';
+        params.push(`%"${t}"%`);
+      }
+    }
+    if (opts.sortBy === 'sequence') {
+      sql += ' AND sequence IS NOT NULL';
+    }
+    sql += ' ORDER BY ' + (opts.sortBy === 'sequence' ? 'sequence DESC, created_at DESC' : 'created_at DESC');
+
+    const rows = this.db.prepare(sql).all(...params) as any[];
+    const engrams = rows.map(r => this.rowToEngram(r));
+
+    // Group by extracted tag value, take first (already sorted newest first).
+    const seen = new Map<string, Engram>();
+    for (const e of engrams) {
+      const value = this.extractTagValue(e.tags, opts.tagKeyPrefix);
+      if (value == null) continue;
+      if (!seen.has(value)) seen.set(value, e);
+    }
+    const out = Array.from(seen.values());
+    return opts.limit ? out.slice(0, opts.limit) : out;
+  }
+
+  /**
+   * Filter engrams by tag-set operators and sort by numeric value extracted
+   * from a tag prefix (e.g. `"weight="` → numeric value of `weight=8`).
+   * Used by NovelForge's "top 40 active promises by weight".
+   *
+   * Missing or unparseable numeric values sort last.
+   */
+  getTopBy(opts: {
+    agentId: string;
+    sortField: string;             // tag prefix, e.g. "weight="
+    order: 'asc' | 'desc';
+    filterTagsAll?: string[];
+    filterTagsAny?: string[];
+    filterTagsNone?: string[];
+    limit?: number;
+    retracted?: boolean;
+  }): Engram[] {
+    // Build the base query inline (mirrors search() but adds the topBy sort).
+    let sql = `SELECT * FROM engrams
+               WHERE agent_id = ?
+               AND retracted = ?
+               AND stage = 'active'
+               AND tags LIKE ?`;
+    const params: any[] = [
+      opts.agentId,
+      opts.retracted ? 1 : 0,
+      `%"${opts.sortField}%`,        // must have a tag with this prefix
+    ];
+
+    if (opts.filterTagsAll && opts.filterTagsAll.length > 0) {
+      for (const tag of opts.filterTagsAll) {
+        sql += ' AND tags LIKE ?';
+        params.push(`%"${tag}"%`);
+      }
+    }
+    if (opts.filterTagsAny && opts.filterTagsAny.length > 0) {
+      const ors = opts.filterTagsAny.map(() => 'tags LIKE ?').join(' OR ');
+      sql += ` AND (${ors})`;
+      for (const tag of opts.filterTagsAny) params.push(`%"${tag}"%`);
+    }
+    if (opts.filterTagsNone && opts.filterTagsNone.length > 0) {
+      const ors = opts.filterTagsNone.map(() => 'tags LIKE ?').join(' OR ');
+      sql += ` AND NOT (${ors})`;
+      for (const tag of opts.filterTagsNone) params.push(`%"${tag}"%`);
+    }
+
+    const rows = this.db.prepare(sql).all(...params) as any[];
+    const engrams = rows.map(r => this.rowToEngram(r));
+
+    // Extract numeric value from the sortField tag; missing or NaN sorts last.
+    const valued = engrams.map(e => {
+      const raw = this.extractTagValue(e.tags, opts.sortField);
+      const n = raw == null ? NaN : Number(raw);
+      return { e, n };
+    });
+    valued.sort((a, b) => {
+      const aNaN = Number.isNaN(a.n);
+      const bNaN = Number.isNaN(b.n);
+      if (aNaN && bNaN) return 0;
+      if (aNaN) return 1;   // NaN last
+      if (bNaN) return -1;
+      return opts.order === 'asc' ? a.n - b.n : b.n - a.n;
+    });
+    const sorted = valued.map(v => v.e);
+    return opts.limit ? sorted.slice(0, opts.limit) : sorted;
+  }
+
+  /**
+   * Compute the effective state of an engram from referenced events.
+   *
+   *   - 'superseded' if engram.supersededBy is set
+   *   - else: scan engrams whose references_json names this engram with a
+   *     terminal relation type (resolves / subverts / abandons). Take the
+   *     latest by createdAt. effectiveState = that type.
+   *   - else: 'active'
+   *
+   * Returns `null` if target engram not found.
+   */
+  resolveEffectiveState(targetEngramId: string): {
+    engram: Engram;
+    effectiveState: 'active' | 'resolved' | 'subverted' | 'abandoned' | 'superseded';
+    resolvingEvents: Array<{ id: string; type: string; createdAt: string }>;
+  } | null {
+    const target = this.getEngram(targetEngramId);
+    if (!target) return null;
+
+    if (target.supersededBy) {
+      return { engram: target, effectiveState: 'superseded', resolvingEvents: [] };
+    }
+
+    // Find candidate referencing engrams. LIKE-filter first to narrow,
+    // then JSON.parse each candidate's references_json to verify the
+    // matchEngramId and type. Cheap enough at NovelForge's scale.
+    const candidates = this.db.prepare(
+      `SELECT id, references_json, created_at FROM engrams
+       WHERE agent_id = ?
+       AND retracted = 0
+       AND stage = 'active'
+       AND references_json IS NOT NULL
+       AND references_json LIKE ?`
+    ).all(target.agentId, `%"${targetEngramId}"%`) as Array<{
+      id: string;
+      references_json: string;
+      created_at: string;
+    }>;
+
+    const terminalTypes = new Set(['resolves', 'subverts', 'abandons']);
+    const resolvingEvents: Array<{ id: string; type: string; createdAt: string }> = [];
+    for (const c of candidates) {
+      try {
+        const refs = JSON.parse(c.references_json) as Array<{ type: string; matchEngramId?: string }>;
+        for (const ref of refs) {
+          if (ref.matchEngramId === targetEngramId && terminalTypes.has(ref.type)) {
+            resolvingEvents.push({ id: c.id, type: ref.type, createdAt: c.created_at });
+          }
+        }
+      } catch { /* malformed references_json — skip */ }
+    }
+
+    if (resolvingEvents.length === 0) {
+      return { engram: target, effectiveState: 'active', resolvingEvents: [] };
+    }
+
+    // Latest event wins.
+    resolvingEvents.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const latestType = resolvingEvents[0]!.type as 'resolves' | 'subverts' | 'abandons';
+    const effectiveState = (
+      latestType === 'resolves' ? 'resolved'
+        : latestType === 'subverts' ? 'subverted'
+          : 'abandoned'
+    );
+    return { engram: target, effectiveState, resolvingEvents };
+  }
+
+  /**
+   * Atomically allocate the next sequence number for an agent.
+   *
+   * Uses BEGIN IMMEDIATE to serialize concurrent callers — better-sqlite3's
+   * transaction() acquires a RESERVED lock which prevents other writers
+   * from racing. Returns MAX(sequence)+1 for the agent, or 1 if no engrams
+   * have a sequence yet.
+   */
+  allocateNextSequence(agentId: string): number {
+    return this.transaction(() => {
+      const row = this.db.prepare(
+        'SELECT MAX(sequence) AS max_seq FROM engrams WHERE agent_id = ?'
+      ).get(agentId) as { max_seq: number | null };
+      return (row?.max_seq ?? 0) + 1;
+    });
+  }
+
+  /**
+   * Extract the value following a tag prefix, e.g. `["weight=8"]` + `"weight="`
+   * → `"8"`. Returns null if no tag with that prefix is present.
+   */
+  private extractTagValue(tags: string[], tagKeyPrefix: string): string | null {
+    for (const t of tags) {
+      if (t.startsWith(tagKeyPrefix)) {
+        return t.slice(tagKeyPrefix.length);
+      }
+    }
+    return null;
+  }
 }

package/src/storage/store.ts

@@ -0,0 +1,80 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Backend-agnostic storage contract for AWM.
+ *
+ * AWM 0.8.x introduces a pluggable storage layer:
+ *   - SQLiteEngramStore: better-sqlite3 + FTS5 + BLOB embeddings (current default)
+ *   - PGliteEngramStore: @electric-sql/pglite + pgvector + tsvector (opt-in via
+ *     `AWM_STORE_BACKEND=pglite`, planned default in 0.9.x)
+ *   - PostgresEngramStore: real Postgres backend for scale (planned, post-1.0)
+ *
+ * All backends provide the same public surface — defined here as `IEngramStore`.
+ * The cognitive engines (activation, consolidation, Hebbian, eviction, etc.)
+ * accept `IEngramStore` and work against any conforming backend.
+ *
+ * The interface is derived from the SQLite implementation via TypeScript's
+ * `Omit<>` so it stays in sync automatically. SQLite-specific methods
+ * (DB handle access, WAL checkpointing, slim-cache management, integrity
+ * checks) are excluded — these are implementation-internal and don't belong
+ * in a backend-agnostic contract.
+ *
+ * Future backends MUST implement every method on `IEngramStore`. They MAY
+ * additionally expose backend-specific methods (e.g., PGlite-specific tooling,
+ * Postgres pool management) — those are not part of the contract.
+ */
+
+import type { EngramStore as SqliteEngramStore } from './sqlite.js';
+
+/**
+ * Backend-specific methods on SqliteEngramStore that are NOT part of the
+ * shared contract. Other backends may provide functionally-similar methods
+ * under different names or not at all.
+ */
+type SqliteSpecificMethods =
+  | 'getDb'              // Returns better-sqlite3 Database — SQLite-only API
+  | 'integrityCheck'     // SQLite PRAGMA integrity_check
+  | 'walCheckpoint'      // SQLite WAL checkpoint
+  | 'stopWalCheckpointTimer'
+  | 'backup'             // SQLite backup API; PGlite/Postgres use pg_dump
+  | 'warmSlimCache'      // In-memory cache pre-population (SQLite-specific perf opt)
+  | 'resetSlimCache'
+  | 'getSlimCacheStats'
+  | 'transaction';       // SQLite sync transaction helper — PGlite uses withTransaction
+
+/**
+ * MaybePromise — covariant union that lets sync and async backends share one contract.
+ *
+ * Engines `await` every store call. `await T` resolves to T immediately when
+ * the backend is sync (SQLite, returning bare values) and resolves the Promise
+ * when the backend is async (PGlite). Both shapes satisfy the same interface.
+ */
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Turn every method return type R into `MaybePromise<Awaited<R>>` so the
+ * contract accepts both sync and async backends.
+ */
+type AsyncifyMethods<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => MaybePromise<Awaited<R>>
+    : T[K];
+};
+
+/**
+ * The backend-agnostic storage contract.
+ *
+ * Any class with this shape can be used as the EngramStore for the AWM
+ * cognitive engines. New backends should `implements IEngramStore` to get
+ * compile-time enforcement of the full surface.
+ */
+export type IEngramStore = AsyncifyMethods<Omit<SqliteEngramStore, SqliteSpecificMethods>>;
+
+/**
+ * Convenience type-only re-export so consumers can `import type { EngramStore }`
+ * from this module and get the backend-agnostic contract instead of the
+ * SQLite-specific class. Existing imports from `'../storage/sqlite.js'`
+ * continue to work and resolve to the SQLite class (which is a structural
+ * supertype of IEngramStore).
+ */
+export type EngramStore = IEngramStore;