supipowers 1.5.2 → 2.0.0

package/src/context-mode/knowledge/store.ts

@@ -1,11 +1,14 @@
-import { Database } from "bun:sqlite";
+import { constants, Database } from "bun:sqlite";
 import fs from "node:fs";
+import type { KnowledgeOwner, KnowledgeOwnerScope } from "../../types.js";
 import type { Chunk } from "./chunker.js";
 
 export interface SearchOptions {
   source?: string;
   contentType?: "code" | "prose";
   limit?: number;
+  owner?: KnowledgeOwner;
+  includeAllSessions?: boolean;
 }
 
 export interface SearchResult {
@@ -14,6 +17,8 @@ export interface SearchResult {
   source: string;
   contentType: string;
   score: number;
+  ownerScope: KnowledgeOwnerScope;
+  ownerId: string;
 }
 
 export interface QueryGroupedResults {
@@ -27,13 +32,22 @@ export interface StoreStats {
   dbSizeBytes: number;
 }
 
+export interface KnowledgeClearResult {
+  chunksDeleted: number;
+  urlCacheDeleted: number;
+}
+
+const SCHEMA_VERSION = 2;
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS content_chunks (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   source TEXT NOT NULL,
   title TEXT NOT NULL DEFAULT '',
   body TEXT NOT NULL,
-  content_type TEXT NOT NULL DEFAULT 'prose'
+  content_type TEXT NOT NULL DEFAULT 'prose',
+  owner_scope TEXT NOT NULL DEFAULT 'project',
+  owner_id TEXT NOT NULL DEFAULT ''
 );
 
 CREATE VIRTUAL TABLE IF NOT EXISTS content_chunks_fts USING fts5(
@@ -52,42 +66,145 @@ CREATE TRIGGER IF NOT EXISTS content_chunks_ad AFTER DELETE ON content_chunks BE
   INSERT INTO content_chunks_fts(content_chunks_fts, rowid, title, body) VALUES ('delete', old.id, old.title, old.body);
 END;
 
+CREATE INDEX IF NOT EXISTS idx_content_chunks_owner ON content_chunks(owner_scope, owner_id);
+CREATE INDEX IF NOT EXISTS idx_content_chunks_source_owner ON content_chunks(source, owner_scope, owner_id);
+
 CREATE TABLE IF NOT EXISTS url_cache (
   url TEXT NOT NULL,
   source TEXT NOT NULL,
+  owner_scope TEXT NOT NULL DEFAULT 'project',
+  owner_id TEXT NOT NULL DEFAULT '',
   fetched_at INTEGER NOT NULL,
-  PRIMARY KEY (url, source)
+  PRIMARY KEY (url, source, owner_scope, owner_id)
 );
+
+CREATE INDEX IF NOT EXISTS idx_url_cache_owner ON url_cache(owner_scope, owner_id);
 `;
 
+const PROJECT_OWNER: Required<KnowledgeOwner> = { ownerScope: "project", ownerId: "" };
+
 export class KnowledgeStore {
   private _db: Database;
   private dbPath: string;
+  #closed = false;
 
   /** Public accessor for direct SQL on extension tables (e.g. url_cache). */
   get db(): Database {
     return this._db;
   }
 
+  get path(): string {
+    return this.dbPath;
+  }
+
   constructor(dbPath: string) {
     this.dbPath = dbPath;
     this._db = new Database(dbPath);
-    this._db.exec("PRAGMA journal_mode=WAL");
   }
 
   init(): void {
+    this.#ensureDeleteJournalMode();
+    this.#migrate();
     this._db.exec(SCHEMA);
+    this._db.exec("INSERT INTO content_chunks_fts(content_chunks_fts) VALUES('rebuild')");
+  }
+
+  #ensureDeleteJournalMode(): void {
+    const journalMode = this.#getJournalMode();
+    if (journalMode === "delete") return;
+
+    if (journalMode === "wal") {
+      this.#cleanupWalSidecars();
+    }
+
+    try {
+      this._db.exec("PRAGMA journal_mode = DELETE");
+    } catch {
+      // Older WAL-backed databases can stay on WAL for this process.
+      // close() still checkpoints them so teardown and the next reopen succeed.
+    }
+  }
+
+  #getJournalMode(): string {
+    const { journal_mode } = this._db.prepare("PRAGMA journal_mode").get() as {
+      journal_mode: string;
+    };
+    return journal_mode.toLowerCase();
   }
-  index(chunks: Chunk[], source: string): void {
-    const del = this._db.prepare("DELETE FROM content_chunks WHERE source = ?");
+
+  #cleanupWalSidecars(): void {
+    try {
+      this._db.fileControl(constants.SQLITE_FCNTL_PERSIST_WAL, 0);
+      this._db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    } catch {
+      // Best effort only: close() still releases the handle in finally.
+    }
+  }
+
+  #migrate(): void {
+    const { user_version } = this._db.prepare("PRAGMA user_version").get() as {
+      user_version: number;
+    };
+    if (user_version >= SCHEMA_VERSION) return;
+
+    const hasContentChunks = tableExists(this._db, "content_chunks");
+    if (hasContentChunks) {
+      addColumnIfMissing(this._db, "content_chunks", "owner_scope", "TEXT NOT NULL DEFAULT 'legacy'");
+      addColumnIfMissing(this._db, "content_chunks", "owner_id", "TEXT NOT NULL DEFAULT ''");
+      this._db.prepare(
+        `UPDATE content_chunks
+         SET owner_scope = 'legacy'
+         WHERE owner_scope IS NULL OR owner_scope = ''`,
+      ).run();
+    }
+
+    const hasUrlCache = tableExists(this._db, "url_cache");
+    if (hasUrlCache && !columnExists(this._db, "url_cache", "owner_scope")) {
+      this._db.exec(`
+        CREATE TABLE IF NOT EXISTS url_cache_v2 (
+          url TEXT NOT NULL,
+          source TEXT NOT NULL,
+          owner_scope TEXT NOT NULL DEFAULT 'legacy',
+          owner_id TEXT NOT NULL DEFAULT '',
+          fetched_at INTEGER NOT NULL,
+          PRIMARY KEY (url, source, owner_scope, owner_id)
+        );
+        INSERT OR REPLACE INTO url_cache_v2 (url, source, owner_scope, owner_id, fetched_at)
+          SELECT url, source, 'legacy', '', fetched_at FROM url_cache;
+        DROP TABLE url_cache;
+        ALTER TABLE url_cache_v2 RENAME TO url_cache;
+      `);
+    }
+
+    this._db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+  }
+
+  index(chunks: Chunk[], source: string, owner?: KnowledgeOwner): void {
+    const resolvedOwner = normalizeOwner(owner);
+    const del = this._db.prepare(
+      `DELETE FROM content_chunks
+       WHERE source = ?
+         AND (
+           (owner_scope = ? AND owner_id = ?)
+           OR (? = 'project' AND owner_scope = 'legacy')
+         )`,
+    );
     const ins = this._db.prepare(
-      "INSERT INTO content_chunks (source, title, body, content_type) VALUES (?, ?, ?, ?)",
+      `INSERT INTO content_chunks (source, title, body, content_type, owner_scope, owner_id)
+       VALUES (?, ?, ?, ?, ?, ?)`,
     );
 
     this._db.transaction(() => {
-      del.run(source);
+      del.run(source, resolvedOwner.ownerScope, resolvedOwner.ownerId, resolvedOwner.ownerScope);
       for (const chunk of chunks) {
-        ins.run(source, chunk.title, chunk.body, chunk.contentType);
+        ins.run(
+          source,
+          chunk.title,
+          chunk.body,
+          chunk.contentType,
+          resolvedOwner.ownerScope,
+          resolvedOwner.ownerId,
+        );
       }
     })();
   }
@@ -107,6 +224,8 @@ export class KnowledgeStore {
 
       let sql = `
         SELECT c.title, c.body, c.source, c.content_type AS contentType,
+               c.owner_scope AS ownerScope,
+               c.owner_id AS ownerId,
                bm25(content_chunks_fts, 5.0, 1.0) AS score
         FROM content_chunks_fts f
         JOIN content_chunks c ON c.id = f.rowid
@@ -123,6 +242,12 @@ export class KnowledgeStore {
         params.push(options.contentType);
       }
 
+      const visibility = buildVisibilityClause(options);
+      if (visibility) {
+        sql += ` AND ${visibility.sql}`;
+        params.push(...visibility.params);
+      }
+
       sql += " ORDER BY score LIMIT ?";
       params.push(limit);
 
@@ -149,6 +274,73 @@ export class KnowledgeStore {
     return count;
   }
 
+  listSessions(): { session_id: string; chunk_count: number; url_cache_count: number }[] {
+    const merged = new Map<string, { session_id: string; chunk_count: number; url_cache_count: number }>();
+    const chunkRows = this._db.prepare(
+      `SELECT owner_id AS session_id, COUNT(*) AS chunk_count
+         FROM content_chunks
+        WHERE owner_scope = 'session'
+        GROUP BY owner_id`,
+    ).all() as Array<{ session_id: string; chunk_count: number }>;
+    const urlRows = this._db.prepare(
+      `SELECT owner_id AS session_id, COUNT(*) AS url_cache_count
+         FROM url_cache
+        WHERE owner_scope = 'session'
+        GROUP BY owner_id`,
+    ).all() as Array<{ session_id: string; url_cache_count: number }>;
+
+    for (const row of chunkRows) {
+      merged.set(row.session_id, {
+        session_id: row.session_id,
+        chunk_count: row.chunk_count,
+        url_cache_count: 0,
+      });
+    }
+    for (const row of urlRows) {
+      const existing = merged.get(row.session_id);
+      if (existing) {
+        existing.url_cache_count = row.url_cache_count;
+      } else {
+        merged.set(row.session_id, {
+          session_id: row.session_id,
+          chunk_count: 0,
+          url_cache_count: row.url_cache_count,
+        });
+      }
+    }
+    return [...merged.values()].sort((a, b) => a.session_id.localeCompare(b.session_id));
+  }
+
+  clearSession(ownerId: string): KnowledgeClearResult {
+    const chunks = this._db.prepare(
+      "SELECT COUNT(*) AS cnt FROM content_chunks WHERE owner_scope = 'session' AND owner_id = ?",
+    ).get(ownerId) as { cnt: number };
+    const urls = this._db.prepare(
+      "SELECT COUNT(*) AS cnt FROM url_cache WHERE owner_scope = 'session' AND owner_id = ?",
+    ).get(ownerId) as { cnt: number };
+    this._db.prepare(
+      "DELETE FROM content_chunks WHERE owner_scope = 'session' AND owner_id = ?",
+    ).run(ownerId);
+    this._db.prepare(
+      "DELETE FROM url_cache WHERE owner_scope = 'session' AND owner_id = ?",
+    ).run(ownerId);
+    this._db.exec("INSERT INTO content_chunks_fts(content_chunks_fts) VALUES('rebuild')");
+    return { chunksDeleted: chunks.cnt, urlCacheDeleted: urls.cnt };
+  }
+
+  clearProject(): KnowledgeClearResult {
+    const chunks = this._db.prepare("SELECT COUNT(*) AS cnt FROM content_chunks").get() as {
+      cnt: number;
+    };
+    const urls = this._db.prepare("SELECT COUNT(*) AS cnt FROM url_cache").get() as {
+      cnt: number;
+    };
+    this._db.exec("DELETE FROM content_chunks");
+    this._db.exec("DELETE FROM url_cache");
+    this._db.exec("INSERT INTO content_chunks_fts(content_chunks_fts) VALUES('rebuild')");
+    return { chunksDeleted: chunks.cnt, urlCacheDeleted: urls.cnt };
+  }
+
   getStats(): StoreStats {
     const countRow = this._db.prepare("SELECT COUNT(*) AS cnt FROM content_chunks").get() as {
       cnt: number;
@@ -168,14 +360,66 @@ export class KnowledgeStore {
   pruneExpiredUrls(ttlHours = 24): number {
     const cutoff = Math.floor(Date.now() / 1000) - ttlHours * 3600;
     const result = this._db.prepare("DELETE FROM url_cache WHERE fetched_at < ?").run(cutoff);
-    return result.changes;
+    return result.changes as number;
   }
 
   close(): void {
-    this._db.close();
+    if (this.#closed) return;
+
+    try {
+      try {
+        if (this.#getJournalMode() === "wal") {
+          this.#cleanupWalSidecars();
+        }
+      } catch {
+        // The DB path may already be gone during teardown; still close the handle.
+      }
+    } finally {
+      this._db.close();
+      this.#closed = true;
+    }
   }
 }
 
+function normalizeOwner(owner: KnowledgeOwner | undefined): Required<KnowledgeOwner> {
+  if (!owner) return PROJECT_OWNER;
+  return {
+    ownerScope: owner.ownerScope,
+    ownerId: owner.ownerScope === "session" ? owner.ownerId ?? "" : owner.ownerId ?? "",
+  };
+}
+
+function buildVisibilityClause(options: SearchOptions | undefined): { sql: string; params: string[] } | null {
+  if (options?.includeAllSessions) return null;
+
+  const owner = options?.owner;
+  if (owner?.ownerScope === "session") {
+    return {
+      sql: "(c.owner_scope IN ('project', 'legacy') OR (c.owner_scope = 'session' AND c.owner_id = ?))",
+      params: [owner.ownerId ?? ""],
+    };
+  }
+
+  return {
+    sql: "c.owner_scope IN ('project', 'legacy')",
+    params: [],
+  };
+}
+
+function tableExists(db: Database, table: string): boolean {
+  return db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?").get(table) != null;
+}
+
+function columnExists(db: Database, table: string, column: string): boolean {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+  return rows.some((row) => row.name === column);
+}
+
+function addColumnIfMissing(db: Database, table: string, column: string, definition: string): void {
+  if (columnExists(db, table, column)) return;
+  db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+}
+
 /** Strip FTS5 special operators to prevent syntax errors. Keep alphanumeric + spaces. */
 function sanitizeFtsQuery(query: string): string {
   // Remove characters that have special meaning in FTS5: ^, *, ", (, ), {, }, +, -

package/src/context-mode/memory-store.ts

@@ -0,0 +1,325 @@
+// src/context-mode/memory-store.ts
+//
+// L5 cross-session memory store. Keeps durable observations/decisions/tasks
+// per project under <projectStateDir>/sessions/memory.db. Mirrors the
+// event-store/metrics-store conventions: DELETE journal mode, idempotent
+// migration, best-effort failures, content-addressed dedup, and bounded
+// retrieval.
+//
+// Privacy contract:
+// - Every row carries an explicit `owner_scope` (`session` | `project`) and
+//   `owner_id`. Session clear deletes session-owned rows for the active
+//   session and stamps a clear epoch so project-owned rows that pre-date the
+//   epoch are filtered out of subsequent injection for that session.
+// - Project clear deletes every row and every epoch for the project.
+
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const SCHEMA_VERSION = 1;
+
+export type MemoryOwnerScope = "session" | "project";
+export type MemoryType = "observation" | "decision" | "task";
+
+export interface MemoryStoreOptions {
+  dbPath: string;
+  projectSlug: string;
+}
+
+export interface MemoryRow {
+  id: number;
+  ownerScope: MemoryOwnerScope;
+  ownerId: string;
+  type: MemoryType;
+  body: string;
+  bodyHash: string;
+  priority: number;
+  createdAt: number;
+}
+
+export interface MemoryPutInput {
+  ownerScope: MemoryOwnerScope;
+  ownerId?: string;
+  type: MemoryType;
+  body: string;
+  priority?: number;
+  now?: number;
+}
+
+export interface MemoryRetrieveOptions {
+  sessionId: string;
+  byteBudget?: number;
+  limit?: number;
+  now?: number;
+}
+
+const DEFAULT_PRIORITY = 3;
+const DEFAULT_BYTE_BUDGET = 4 * 1024;
+const DEFAULT_LIMIT = 25;
+const RETENTION_DAYS = 30;
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS memory_entries (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  owner_scope TEXT NOT NULL,
+  owner_id TEXT NOT NULL DEFAULT '',
+  type TEXT NOT NULL,
+  body TEXT NOT NULL,
+  body_hash TEXT NOT NULL,
+  priority INTEGER NOT NULL DEFAULT 3,
+  created_at INTEGER NOT NULL,
+  UNIQUE(owner_scope, owner_id, type, body_hash)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_owner ON memory_entries(owner_scope, owner_id);
+CREATE INDEX IF NOT EXISTS idx_memory_priority ON memory_entries(priority, created_at);
+
+CREATE TABLE IF NOT EXISTS memory_clear_epochs (
+  session_id TEXT PRIMARY KEY,
+  cleared_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS memory_meta (
+  project_slug TEXT PRIMARY KEY,
+  last_prune_at INTEGER,
+  last_project_clear_at INTEGER
+);
+`;
+
+export class MemoryStore {
+  readonly #dbPath: string;
+  readonly #projectSlug: string;
+  #db: Database;
+  #closed = false;
+
+  constructor(opts: MemoryStoreOptions) {
+    this.#dbPath = opts.dbPath;
+    this.#projectSlug = opts.projectSlug;
+    fs.mkdirSync(path.dirname(opts.dbPath), { recursive: true });
+    this.#db = new Database(opts.dbPath);
+  }
+
+  get dbPath(): string {
+    return this.#dbPath;
+  }
+
+  get projectSlug(): string {
+    return this.#projectSlug;
+  }
+
+  init(): void {
+    try {
+      this.#db.exec("PRAGMA journal_mode = DELETE;");
+    } catch {
+      // Older WAL-backed databases stay on WAL until close().
+    }
+    this.#db.exec(SCHEMA);
+    this.#migrate();
+  }
+
+  #migrate(): void {
+    const { user_version } = this.#db.prepare("PRAGMA user_version").get() as {
+      user_version: number;
+    };
+    if (user_version === SCHEMA_VERSION) return;
+    if (user_version > SCHEMA_VERSION) {
+      throw new Error(
+        `memory-store: unknown schema version ${user_version} (max supported: ${SCHEMA_VERSION})`,
+      );
+    }
+    this.#db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+  }
+
+  put(input: MemoryPutInput): MemoryRow | null {
+    this.#assertOpen();
+    const body = input.body.trim();
+    if (!body) return null;
+    const ownerId = input.ownerScope === "session" ? input.ownerId ?? "" : "";
+    const bodyHash = sha256(body);
+    const now = input.now ?? Date.now();
+    const priority = clampPriority(input.priority ?? DEFAULT_PRIORITY);
+
+    this.#db.prepare(
+      `INSERT INTO memory_entries (owner_scope, owner_id, type, body, body_hash, priority, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(owner_scope, owner_id, type, body_hash) DO UPDATE SET
+         priority = MIN(memory_entries.priority, excluded.priority),
+         created_at = excluded.created_at`,
+    ).run(input.ownerScope, ownerId, input.type, body, bodyHash, priority, now);
+
+    return this.#readRowByKey(input.ownerScope, ownerId, input.type, bodyHash);
+  }
+
+  retrieve(options: MemoryRetrieveOptions): MemoryRow[] {
+    this.#assertOpen();
+    const byteBudget = Math.max(0, options.byteBudget ?? DEFAULT_BYTE_BUDGET);
+    if (byteBudget === 0) return [];
+    const limit = Math.max(1, options.limit ?? DEFAULT_LIMIT);
+    const epoch = this.#readClearEpoch(options.sessionId) ?? -1;
+
+    const sql = `
+      SELECT id, owner_scope AS ownerScope, owner_id AS ownerId, type, body,
+             body_hash AS bodyHash, priority, created_at AS createdAt
+      FROM memory_entries
+      WHERE (
+        (owner_scope = 'session' AND owner_id = ?)
+        OR (owner_scope = 'project' AND created_at > ?)
+      )
+      ORDER BY priority ASC, created_at DESC
+      LIMIT ?
+    `;
+    const rows = this.#db.prepare(sql).all(options.sessionId, epoch, limit) as MemoryRow[];
+
+    const collected: MemoryRow[] = [];
+    let used = 0;
+    for (const row of rows) {
+      const cost = byteLength(row.body);
+      if (used + cost > byteBudget) continue;
+      used += cost;
+      collected.push(row);
+    }
+    return collected;
+  }
+
+  recordClearEpoch(sessionId: string, now = Date.now()): void {
+    this.#assertOpen();
+    this.#db.prepare(
+      `INSERT INTO memory_clear_epochs (session_id, cleared_at)
+       VALUES (?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET cleared_at = excluded.cleared_at`,
+    ).run(sessionId, now);
+  }
+
+  clearSession(sessionId: string, now = Date.now()): { deleted: number } {
+    this.#assertOpen();
+    const deleted = this.#db.prepare(
+      `DELETE FROM memory_entries WHERE owner_scope = 'session' AND owner_id = ?`,
+    ).run(sessionId).changes as number;
+    this.recordClearEpoch(sessionId, now);
+    return { deleted };
+  }
+
+  clearProject(now = Date.now()): { deleted: number } {
+    this.#assertOpen();
+    const stats = this.#db.prepare("SELECT COUNT(*) AS cnt FROM memory_entries").get() as {
+      cnt: number;
+    };
+    this.#db.exec("DELETE FROM memory_entries");
+    this.#db.exec("DELETE FROM memory_clear_epochs");
+    this.#db.prepare(
+      `INSERT INTO memory_meta (project_slug, last_project_clear_at)
+       VALUES (?, ?)
+       ON CONFLICT(project_slug) DO UPDATE SET last_project_clear_at = excluded.last_project_clear_at`,
+    ).run(this.#projectSlug, now);
+    return { deleted: stats.cnt };
+  }
+
+  pruneOld(retentionDays = RETENTION_DAYS, now = Date.now()): number {
+    this.#assertOpen();
+    const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+    const deleted = this.#db.prepare(
+      `DELETE FROM memory_entries WHERE created_at < ?`,
+    ).run(cutoff).changes as number;
+    this.#db.prepare(
+      `INSERT INTO memory_meta (project_slug, last_prune_at)
+       VALUES (?, ?)
+       ON CONFLICT(project_slug) DO UPDATE SET last_prune_at = excluded.last_prune_at`,
+    ).run(this.#projectSlug, now);
+    return deleted;
+  }
+
+  getStats(): { totalRows: number; sessionRows: number; projectRows: number } {
+    this.#assertOpen();
+    const total = this.#db.prepare(
+      "SELECT COUNT(*) AS cnt FROM memory_entries",
+    ).get() as { cnt: number };
+    const sessionRows = this.#db.prepare(
+      "SELECT COUNT(*) AS cnt FROM memory_entries WHERE owner_scope = 'session'",
+    ).get() as { cnt: number };
+    const projectRows = this.#db.prepare(
+      "SELECT COUNT(*) AS cnt FROM memory_entries WHERE owner_scope = 'project'",
+    ).get() as { cnt: number };
+    return {
+      totalRows: total.cnt,
+      sessionRows: sessionRows.cnt,
+      projectRows: projectRows.cnt,
+    };
+  }
+
+  countSessionRows(sessionId: string): number {
+    this.#assertOpen();
+    const row = this.#db.prepare(
+      "SELECT COUNT(*) AS cnt FROM memory_entries WHERE owner_scope = 'session' AND owner_id = ?",
+    ).get(sessionId) as { cnt: number };
+    return row.cnt;
+  }
+
+  listSessions(): { session_id: string; row_count: number }[] {
+    this.#assertOpen();
+    return this.#db.prepare(
+      `SELECT owner_id AS session_id, COUNT(*) AS row_count
+         FROM memory_entries
+        WHERE owner_scope = 'session'
+        GROUP BY owner_id
+        ORDER BY owner_id`,
+    ).all() as Array<{ session_id: string; row_count: number }>;
+  }
+
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#db.close();
+  }
+
+  #readRowByKey(
+    ownerScope: MemoryOwnerScope,
+    ownerId: string,
+    type: MemoryType,
+    bodyHash: string,
+  ): MemoryRow | null {
+    return (this.#db.prepare(
+      `SELECT id, owner_scope AS ownerScope, owner_id AS ownerId, type, body,
+              body_hash AS bodyHash, priority, created_at AS createdAt
+       FROM memory_entries
+       WHERE owner_scope = ? AND owner_id = ? AND type = ? AND body_hash = ?`,
+    ).get(ownerScope, ownerId, type, bodyHash) as MemoryRow | undefined) ?? null;
+  }
+
+  #readClearEpoch(sessionId: string): number | null {
+    const row = this.#db.prepare(
+      `SELECT cleared_at AS clearedAt FROM memory_clear_epochs WHERE session_id = ?`,
+    ).get(sessionId) as { clearedAt: number } | undefined;
+    return row?.clearedAt ?? null;
+  }
+
+  #assertOpen(): void {
+    if (this.#closed) {
+      throw new Error("memory-store: cannot use a closed store");
+    }
+  }
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function byteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function clampPriority(priority: number): number {
+  if (!Number.isFinite(priority)) return DEFAULT_PRIORITY;
+  return Math.min(5, Math.max(1, Math.floor(priority)));
+}
+
+let _memoryStoreRef: MemoryStore | null = null;
+
+export function getMemoryStore(): MemoryStore | null {
+  return _memoryStoreRef;
+}
+
+export function _setMemoryStoreRef(store: MemoryStore | null): void {
+  _memoryStoreRef = store;
+}