memorix 1.2.3 → 1.2.4

package/src/memory/session.ts

@@ -22,6 +22,17 @@ import { redactCredentials, sanitizeCredentials } from './secret-filter.js';
 import { canReadObservation } from './visibility.js';
 
 const PRIORITY_TYPES = new Set(['gotcha', 'decision', 'problem-solution', 'trade-off', 'discovery']);
+const RESUME_TYPES = new Set([
+  'gotcha',
+  'decision',
+  'problem-solution',
+  'trade-off',
+  'discovery',
+  'how-it-works',
+  'what-changed',
+  'reasoning',
+  'session-request',
+]);
 const TYPE_EMOJI: Record<string, string> = {
   'gotcha': '[DISCOVERY]',
   'decision': '[WHY]',
@@ -178,6 +189,138 @@ function isSystemSelfObservation(obs: Observation): boolean {
   return SYSTEM_SELF_PATTERNS.some((pattern) => pattern.test(text));
 }
 
+export interface SessionResumeMemory {
+  id: number;
+  title: string;
+  type: string;
+  detail?: string;
+}
+
+/** A compact, source-aware view of prior work for a task continuation. */
+export interface SessionResumeBrief {
+  previousSession?: {
+    id: string;
+    agent?: string;
+    endedAt?: string;
+    summary: string;
+  };
+  memories: SessionResumeMemory[];
+}
+
+function readerForAlias(
+  reader: ObservationReader | undefined,
+  aliases: Set<string>,
+  observation: Observation,
+): ObservationReader | undefined {
+  if (!reader) return undefined;
+  return reader.projectId && aliases.has(observation.projectId)
+    ? { ...reader, projectId: observation.projectId }
+    : reader;
+}
+
+function readableAliasObservations(
+  observations: Observation[],
+  aliases: Set<string>,
+  reader?: ObservationReader,
+): Observation[] {
+  return reader
+    ? observations.filter((observation) => canReadObservation(
+      observation,
+      readerForAlias(reader, aliases, observation),
+    ))
+    : observations;
+}
+
+function isUsefulSessionSummary(summary: string | undefined): summary is string {
+  return Boolean(summary)
+    && !NOISE_PATTERNS.some((pattern) => pattern.test(summary!))
+    && !SYSTEM_SELF_PATTERNS.some((pattern) => pattern.test(summary!));
+}
+
+function continuationTaskTokens(task?: string): string[] {
+  return [...new Set(
+    (task?.toLowerCase().match(/[a-z0-9_./-]+|[\u4e00-\u9fff]+/g) ?? [])
+      .map((token) => token.trim())
+      .filter((token) => token.length > 1 && !['continue', 'resume', '继续', '接手', '恢复'].includes(token)),
+  )].slice(0, 8);
+}
+
+function continuationScore(observation: Observation, projectTokens: string[], task?: string): number {
+  let score = scoreObservationForSessionContext(observation, projectTokens);
+  if (observation.type === 'session-request' || observation.type === 'what-changed') score += 1;
+  const text = stringifyObservation(observation);
+  const matches = continuationTaskTokens(task).filter((token) => text.includes(token)).length;
+  score += Math.min(matches, 2) * 2;
+  return score;
+}
+
+/**
+ * Return only the latest meaningful session summary and a few durable memory
+ * anchors. It is deliberately separate from the verbose session-context view:
+ * this is a delivery projection for one bounded Task Workset, not another
+ * storage model or an automatic transcript dump.
+ */
+export async function getSessionResumeBrief(
+  projectId: string,
+  task?: string,
+  reader?: ObservationReader,
+): Promise<SessionResumeBrief> {
+  const aliasSet = await resolveProjectIds(projectId);
+  const [sessions, allObs] = await Promise.all([
+    loadAliasSessions(aliasSet),
+    loadAliasActiveObservations(aliasSet),
+  ]);
+  const readableObs = readableAliasObservations(allObs, aliasSet, reader);
+  const previous = sessions
+    .filter((session) => session.status === 'completed')
+    .sort((a, b) => new Date(b.endedAt || b.startedAt).getTime() - new Date(a.endedAt || a.startedAt).getTime())
+    .find((session) => (
+      session.summary
+      && session.summary !== '(session ended implicitly by new session start)'
+      && isUsefulSessionSummary(session.summary)
+    ));
+
+  const projectTokens = tokenizeProjectId(projectId);
+  const memories = readableObs
+    .filter((observation) => RESUME_TYPES.has(observation.type))
+    .filter((observation) => classifyLayer(observation) === 'L2')
+    .filter((observation) => !isNoiseObservation(observation) && !isSystemSelfObservation(observation))
+    .map((observation) => ({
+      observation,
+      score: continuationScore(observation, projectTokens, task),
+    }))
+    .sort((a, b) => (
+      b.score - a.score
+      || new Date(b.observation.createdAt).getTime() - new Date(a.observation.createdAt).getTime()
+      || a.observation.id - b.observation.id
+    ))
+    .slice(0, 3)
+    .map(({ observation }) => ({
+      id: observation.id,
+      title: sanitizeCredentials(observation.title),
+      type: observation.type,
+      ...(observation.facts?.[0]
+        ? { detail: sanitizeCredentials(observation.facts[0]) }
+        : observation.narrative
+          ? { detail: sanitizeCredentials(observation.narrative) }
+          : {}),
+    }));
+
+  return {
+    ...(previous?.summary
+      ? {
+        previousSession: {
+          id: previous.id,
+          ...(previous.agent ? { agent: previous.agent } : {}),
+          ...(previous.endedAt ? { endedAt: previous.endedAt } : {}),
+          summary: sanitizeCredentials(previous.summary),
+        },
+      }
+      : {}),
+    memories,
+  };
+}
+
 export function scoreObservationForSessionContext(obs: Observation, projectTokens: string[], now = Date.now()): number {
   let score = TYPE_WEIGHTS[obs.type] ?? 1;
   const text = stringifyObservation(obs);
@@ -322,16 +465,7 @@ export async function getSessionContext(
     loadAliasSessions(aliasSet),
     loadAliasActiveObservations(aliasSet),
   ]);
-  const readableObs = reader
-    ? allObs.filter((observation) => {
-        // Aliases represent one project across moved/renamed worktrees. Preserve
-        // that project equivalence while still enforcing the caller's identity.
-        const observationReader = reader.projectId && aliasSet.has(observation.projectId)
-          ? { ...reader, projectId: observation.projectId }
-          : reader;
-        return canReadObservation(observation, observationReader);
-      })
-    : allObs;
+  const readableObs = readableAliasObservations(allObs, aliasSet, reader);
   /** Check if a session summary contains noise/system-self content */
   const isNoisySummary = (summary: string | undefined): boolean => {
     if (!summary) return false;

package/src/server.ts

@@ -228,6 +228,9 @@ export const BOOTSTRAP_SAFE_TOOL_NAMES = new Set([
   'memorix_context_pack',
 ]);
 
+const AUTOPILOT_RETRIEVAL_BOUNDARY_TTL_MS = 2 * 60 * 1000;
+const READ_ONLY_TASK_PATTERN = /\b(?:do not|don't|never)\s+(?:modify|edit|change|write)\b|\bread[- ]only\b|(?:不要|不准|勿|禁止).{0,6}(?:修改|编辑|写入)|只读/i;
+
 export function shouldAwaitProjectRuntime(toolName: string): boolean {
   return !BOOTSTRAP_SAFE_TOOL_NAMES.has(toolName);
 }
@@ -602,6 +605,63 @@ export async function createMemorixServer(
     };
   };
 
+  // A complete Autopilot brief is the normal retrieval boundary for one coding
+  // turn. Keep accidental search/detail loops cheap, while preserving an
+  // explicit escape hatch when a caller really needs deeper history.
+  let autopilotRetrievalBoundary: {
+    projectId: string;
+    issuedAt: number;
+    coveredObservationIds: Set<number>;
+    readOnly: boolean;
+  } | null = null;
+  const getActiveAutopilotRetrievalBoundary = () => {
+    const boundary = autopilotRetrievalBoundary;
+    if (!boundary) return null;
+    if (boundary.projectId === project.id && Date.now() - boundary.issuedAt <= AUTOPILOT_RETRIEVAL_BOUNDARY_TTL_MS) {
+      return boundary;
+    }
+    autopilotRetrievalBoundary = null;
+    return null;
+  };
+  const requireExplicitAutopilotExpansion = (toolName: string, purpose?: string) => {
+    if (!getActiveAutopilotRetrievalBoundary() || purpose?.trim()) return null;
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text:
+          'Memorix Autopilot retrieval boundary: the latest `memorix_project_context` already supplied the default bounded brief for this coding turn, so no additional memory was retrieved. ' +
+          'Verify the current project first. To intentionally expand beyond that brief, call `' + toolName + '` again with `purpose` naming the specific missing fact or the user\'s explicit request.',
+      }],
+    };
+  };
+  const blockCoveredAutopilotEvidence = (toolName: string, observationIds: number[], force?: boolean) => {
+    const boundary = getActiveAutopilotRetrievalBoundary();
+    if (!boundary || force || observationIds.length === 0 || !observationIds.every(id => boundary.coveredObservationIds.has(id))) {
+      return null;
+    }
+    return {
+      content: [{
+        type: 'text' as const,
+        text:
+          'Memorix Autopilot retrieval boundary: every requested memory is already represented in the latest project brief, so no duplicate detail was retrieved. ' +
+          'Inspect the current project or seek a new source. Retry with `force: true` only when the user explicitly asks to read the underlying record in full.',
+      }],
+    };
+  };
+  const blockReadOnlyAutopilotWrite = (overrideReadOnly?: boolean) => {
+    const boundary = getActiveAutopilotRetrievalBoundary();
+    if (!boundary?.readOnly || overrideReadOnly) return null;
+    return {
+      content: [{
+        type: 'text' as const,
+        text:
+          'Memorix write boundary: the latest task is read-only or asks not to modify files, so no memory was stored. ' +
+          'Persist a record only when the user explicitly asks to save it, then retry with `overrideReadOnly: true`.',
+      }],
+    };
+  };
+
   // ================================================================
   // Memorix Extended Tools (3-layer Progressive Disclosure)
   // ================================================================
@@ -622,7 +682,8 @@ export async function createMemorixServer(
         'problem-solution ([FIX] bug fix), how-it-works ([INFO] explanation), what-changed ([CHANGE] change), ' +
         'discovery ([DISCOVERY] insight), why-it-exists ([WHY] rationale), trade-off ([TRADEOFF] compromise), ' +
         'session-request ([SESSION] original goal). ' +
-        'Project visibility is the default. Personal or team visibility requires an explicitly joined coordination identity.',
+        'Project visibility is the default. Personal or team visibility requires an explicitly joined coordination identity. ' +
+        'For a read-only task, do not store unless the user explicitly asks to save a record.',
       inputSchema: {
         entityName: z.string().describe('The entity this observation belongs to (e.g., "auth-module", "port-config")'),
         type: z.enum(OBSERVATION_TYPES).describe('Observation type for classification'),
@@ -646,11 +707,16 @@ export async function createMemorixServer(
         visibility: z.enum(['personal', 'project', 'team']).optional().describe(
           'Retrieval scope. Project is the normal shared default; personal/team require memorix_session_start with joinTeam=true.',
         ),
+        overrideReadOnly: z.boolean().optional().describe(
+          'Use only when the user explicitly asks to save memory during a read-only or no-modification task.',
+        ),
       },
     },
-    async ({ entityName: rawEntityName, type: rawType, title: rawTitle, narrative, facts, filesModified, concepts, topicKey, progress, relatedCommits, relatedEntities, visibility }) => {
+    async ({ entityName: rawEntityName, type: rawType, title: rawTitle, narrative, facts, filesModified, concepts, topicKey, progress, relatedCommits, relatedEntities, visibility, overrideReadOnly }) => {
       const unresolved = requireResolvedProject('store memory in the current project');
       if (unresolved) return unresolved;
+      const readOnlyBoundary = blockReadOnlyAutopilotWrite(overrideReadOnly);
+      if (readOnlyBoundary) return readOnlyBoundary;
       const requestedVisibility = (visibility ?? 'project') as 'personal' | 'project' | 'team';
       const reader = getObservationReader();
       if (requestedVisibility !== 'project' && !currentAgentId) {
@@ -1224,6 +1290,7 @@ export async function createMemorixServer(
       title: 'Search Memory',
       description:
         'Search project memory. Returns a compact index (~50-100 tokens/result). ' +
+        'Do not use as a follow-up to a complete memorix_project_context brief unless a specific fact is still missing or the user asks for deeper history; provide purpose when intentionally expanding. ' +
         'Use memorix_detail to fetch full content for specific IDs. ' +
         'Use memorix_timeline to see chronological context. ' +
         'Searches across all observations stored from any IDE session — enabling cross-session and cross-agent context retrieval.',
@@ -1243,13 +1310,23 @@ export async function createMemorixServer(
         source: z.enum(['agent', 'git', 'manual']).optional().describe(
           'Filter by memory source. "git" returns only commit-derived ground truth memories. Omit for all sources.',
         ),
+        purpose: z.string().optional().describe(
+          'Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user\'s explicit request.',
+        ),
+        force: z.boolean().optional().describe(
+          'Use only when the user explicitly asks to read a record already represented in the latest Autopilot brief.',
+        ),
       },
     },
-    async ({ query, limit, type, maxTokens, scope, since, until, status, source }) => {
+    async ({ query, limit, type, maxTokens, scope, since, until, status, source, purpose, force }) => {
       if (scope !== 'global') {
         const unresolved = requireResolvedProject('search the current project');
         if (unresolved) return unresolved;
       }
+      if (scope !== 'global') {
+        const boundary = requireExplicitAutopilotExpansion('memorix_search', purpose);
+        if (boundary) return boundary;
+      }
       return withFreshIndex(async () => {
 
       const safeLimit = limit != null ? coerceNumber(limit, 20) : undefined;
@@ -1295,6 +1372,18 @@ export async function createMemorixServer(
         throw error;
       }
 
+      const activeBoundary = getActiveAutopilotRetrievalBoundary();
+      if (
+        scope !== 'global'
+        && activeBoundary
+        && !force
+        && result.entries.length > 0
+        && result.entries.every(entry => activeBoundary.coveredObservationIds.has(entry.id))
+      ) {
+        const duplicate = blockCoveredAutopilotEvidence('memorix_search', result.entries.map(entry => entry.id), force);
+        if (duplicate) return duplicate;
+      }
+
       // Append retrieval diagnostics only; do not mix workspace-sync guidance into memory results.
       let text = result.formatted;
       try {
@@ -1414,6 +1503,7 @@ export async function createMemorixServer(
         observations,
         task,
         refresh: refresh ?? 'auto',
+        reader: getObservationReader(),
         enqueueRefresh: () => {
           enqueueCodegraphRefresh({
             dataDir: projectDir,
@@ -1430,6 +1520,17 @@ export async function createMemorixServer(
           ? formatAutoProjectContextSummary(context)
           : formatAutoProjectContextPrompt(context);
 
+      autopilotRetrievalBoundary = {
+        projectId: project.id,
+        issuedAt: Date.now(),
+        coveredObservationIds: new Set([
+          ...(context.workset.continuation?.memories.map(memory => memory.id) ?? []),
+          ...context.workset.reliableMemory.map(memory => memory.id),
+          ...context.workset.cautionMemory.map(memory => memory.id),
+        ]),
+        readOnly: READ_ONLY_TASK_PATTERN.test(task ?? ''),
+      };
+
       return {
         content: [{ type: 'text' as const, text }],
       };
@@ -1475,18 +1576,24 @@ export async function createMemorixServer(
       title: 'Context Pack',
       description:
         'Build a prompt-ready working context pack for a coding task. ' +
-        'Combines relevant memories, CodeGraph Memory facts, freshness warnings, suggested reads, and verification hints.',
+        'Combines relevant memories, CodeGraph Memory facts, freshness warnings, suggested reads, and verification hints. ' +
+        'After a complete memorix_project_context brief, provide purpose only when deliberately expanding beyond it.',
       inputSchema: {
         task: z.string().describe('Current coding task or question'),
         limit: z.preprocess(
           value => (typeof value === 'string' && value.trim() !== '' ? Number(value) : value),
           z.number().int().positive().max(100),
         ).optional().describe('Max active memories to inspect before code-ref filtering (default: 20)'),
+        purpose: z.string().optional().describe(
+          'Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user\'s explicit request.',
+        ),
       },
     },
-    async ({ task, limit }) => {
+    async ({ task, limit, purpose }) => {
       const unresolved = requireResolvedProject('build a context pack for the current project');
       if (unresolved) return unresolved;
+      const boundary = requireExplicitAutopilotExpansion('memorix_context_pack', purpose);
+      if (boundary) return boundary;
 
       const [
         { CodeGraphStore },
@@ -2380,6 +2487,7 @@ export async function createMemorixServer(
       description:
         'Fetch full observation or mini-skill details — includes source kind (explicit memory / hook trace / git evidence), ' +
         'value category, and cross-references (~500-1000 tokens each). ' +
+        'Do not re-fetch content already covered by a complete memorix_project_context brief unless a specific fact is still missing or the user asks for deeper history; provide purpose when intentionally expanding. ' +
         'Always use memorix_search first to find relevant IDs, then fetch only what you need. ' +
         'Accepts typed refs from search results (e.g. "obs:42", "skill:3") via the typedRefs field, ' +
         'or legacy numeric ids / object refs for backward compatibility.',
@@ -2392,19 +2500,39 @@ export async function createMemorixServer(
           }),
         ).optional().describe('Explicit observation refs. Prefer this for global search results.'),
         typedRefs: z.array(z.string()).optional().describe('Typed memory refs from search results, e.g. "obs:42", "skill:3", "obs:42@org/proj"'),
+        purpose: z.string().optional().describe(
+          'Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user\'s explicit request.',
+        ),
+        force: z.boolean().optional().describe(
+          'Use only when the user explicitly asks to read a record already represented in the latest Autopilot brief.',
+        ),
       },
     },
-    async ({ ids, refs, typedRefs }) => {
+    async ({ ids, refs, typedRefs, purpose, force }) => {
       // Defensive coercion: Claude Code CLI + GLM may send "[16]" instead of [16]
       const safeIds = coerceNumberArray(ids);
       const safeRefs = coerceObservationRefs(refs);
       const safeTypedRefs = coerceStringArray(typedRefs);
+      const hasCrossProjectRef = safeRefs.some((ref) => ref.projectId && ref.projectId !== project.id)
+        || safeTypedRefs.some((ref) => ref.includes('@') && !ref.endsWith(`@${project.id}`));
+      if (!hasCrossProjectRef) {
+        const boundary = requireExplicitAutopilotExpansion('memorix_detail', purpose);
+        if (boundary) return boundary;
+        const requestedObservationIds = [
+          ...safeIds,
+          ...safeRefs.map(ref => ref.id),
+          ...safeTypedRefs.flatMap((ref) => {
+            const match = /^obs:(\d+)(?:@.+)?$/i.exec(ref.trim());
+            return match ? [Number(match[1])] : [];
+          }),
+        ];
+        const duplicate = blockCoveredAutopilotEvidence('memorix_detail', requestedObservationIds, force);
+        if (duplicate) return duplicate;
+      }
 
       // Priority: typedRefs > refs > ids (each is a complete, homogeneous input path)
       let result;
       try {
-        const hasCrossProjectRef = safeRefs.some((ref) => ref.projectId && ref.projectId !== project.id)
-          || safeTypedRefs.some((ref) => ref.includes('@') && !ref.endsWith(`@${project.id}`));
         const reader = getObservationReader(hasCrossProjectRef ? 'global' : 'project');
         if (safeTypedRefs.length > 0) {
           // Pass typed ref strings directly — compactDetail handles parsing
@@ -4825,6 +4953,7 @@ export async function createMemorixServer(
 
     // Phase 4a: clear agent identity — old project's agent is not valid in new project
     currentAgentId = undefined;
+    autopilotRetrievalBoundary = null;
 
     // Re-resolve data dir with canonical ID (may differ from raw detected ID)
     const canonicalProjectDir = newCanonicalId !== newDetected.id

package/src/store/bun-sqlite-compat.ts

@@ -1,21 +1,120 @@
 /**
  * Bun SQLite Compatibility Layer
  *
- * Provides a better-sqlite3 compatible API using bun:sqlite when running under Bun.
- * Falls back to better-sqlite3 when running under Node.js.
+ * Provides a small better-sqlite3 compatibility layer for the available local
+ * SQLite implementation. Node 22 ships node:sqlite, which keeps Memorix
+ * usable when an optional better-sqlite3 native binary is unavailable.
  */
 
 import { createRequire } from 'node:module';
 
 let Database: any;
+let driver: 'better-sqlite3' | 'node:sqlite' | 'bun:sqlite' | undefined;
 const requireFromHere = createRequire(import.meta.url);
 
+function loadNodeSqlite(): any {
+  const nodeSqlite = requireFromHere('node:sqlite');
+  return nodeSqlite.DatabaseSync;
+}
+
+function isNativeBindingFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /could not locate the bindings file|better_sqlite3\.node|module did not self-register/i.test(message);
+}
+
+function addCompatibility(db: any): any {
+  // Bun and node:sqlite do not expose better-sqlite3's pragma helper.
+  if (!db.pragma) {
+    db.pragma = function (pragma: string, options?: { simple?: boolean }) {
+      const statement = db.prepare(`PRAGMA ${pragma}`);
+      if (options?.simple) {
+        const result = statement.get();
+        return result ? Object.values(result)[0] : undefined;
+      }
+      return statement.all();
+    };
+  }
+
+  // Stores use better-sqlite3's synchronous transaction factory. Keep nested
+  // calls correct with savepoints instead of silently committing inner work.
+  if (!db.transaction) {
+    let depth = 0;
+    let sequence = 0;
+    db.transaction = function <T>(fn: (...args: any[]) => T) {
+      return (...args: any[]): T => {
+        const outermost = depth === 0;
+        const savepoint = `memorix_tx_${++sequence}`;
+        if (outermost) {
+          db.exec('BEGIN IMMEDIATE');
+        } else {
+          db.exec(`SAVEPOINT ${savepoint}`);
+        }
+        depth += 1;
+        try {
+          const result = fn(...args);
+          if (result && typeof (result as any).then === 'function') {
+            throw new Error('[memorix] SQLite transactions must be synchronous');
+          }
+          depth -= 1;
+          if (outermost) {
+            db.exec('COMMIT');
+          } else {
+            db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+          }
+          return result;
+        } catch (error) {
+          depth -= 1;
+          try {
+            if (outermost) {
+              db.exec('ROLLBACK');
+            } else {
+              db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+              db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+            }
+          } catch {
+            // Preserve the original application failure when rollback itself fails.
+          }
+          throw error;
+        }
+      };
+    };
+  }
+
+  return db;
+}
+
+function instantiateDatabase(Sqlite: any, filePath: string, options?: any): any {
+  // DatabaseSync validates that an explicitly supplied second argument is an
+  // object, unlike better-sqlite3 which accepts undefined.
+  return driver === 'node:sqlite' && options === undefined
+    ? new Sqlite(filePath)
+    : new Sqlite(filePath, options);
+}
+
 export function loadSqlite(): any {
   if (Database) return Database;
 
+  // Kept as an operational escape hatch and a regression-test seam. Node 22
+  // is the supported minimum runtime, so this does not expand the platform
+  // contract beyond package.json's existing engine requirement.
+  if (process.env.MEMORIX_SQLITE_DRIVER === 'node') {
+    Database = loadNodeSqlite();
+    driver = 'node:sqlite';
+    return Database;
+  }
+
   // Try better-sqlite3 first (Node.js)
   try {
     Database = requireFromHere('better-sqlite3');
+    driver = 'better-sqlite3';
+    return Database;
+  } catch {
+    // Fall through to node:sqlite, then Bun's runtime implementation.
+  }
+
+  try {
+    Database = loadNodeSqlite();
+    driver = 'node:sqlite';
     return Database;
   } catch {
     // Fall through to bun:sqlite
@@ -26,9 +125,10 @@ export function loadSqlite(): any {
     // bun:sqlite is a Bun built-in
     const bunSqlite = requireFromHere('bun:sqlite');
     Database = bunSqlite.Database;
+    driver = 'bun:sqlite';
     return Database;
   } catch {
-    throw new Error('[memorix] Neither better-sqlite3 nor bun:sqlite is available');
+    throw new Error('[memorix] SQLite is unavailable (better-sqlite3, node:sqlite, and bun:sqlite failed)');
   }
 }
 
@@ -38,18 +138,21 @@ export function loadSqlite(): any {
  */
 export function createDatabase(path: string, options?: any): any {
   const Sqlite = loadSqlite();
-  const db = new Sqlite(path, options);
-
-  // Bun's sqlite doesn't have .pragma() method, add compatibility
-  if (!db.pragma) {
-    db.pragma = function (pragma: string, options?: any) {
-      if (options && options.simple) {
-        const result = db.prepare(`PRAGMA ${pragma}`).get();
-        return result ? Object.values(result)[0] : undefined;
-      }
-      return db.prepare(`PRAGMA ${pragma}`).all();
-    };
+  try {
+    return addCompatibility(instantiateDatabase(Sqlite, path, options));
+  } catch (error) {
+    // require('better-sqlite3') can succeed even when npm had no prebuild and
+    // no local compiler. Fall back to Node's built-in SQLite for that one
+    // recoverable case; real open/corruption errors still surface unchanged.
+    if (driver !== 'better-sqlite3' || !isNativeBindingFailure(error)) throw error;
+    Database = loadNodeSqlite();
+    driver = 'node:sqlite';
+    return addCompatibility(instantiateDatabase(Database, path, options));
   }
+}
 
-  return db;
+/** Test-only reset for the driver cache used by the forced node:sqlite path. */
+export function resetSqliteDriverForTests(): void {
+  Database = undefined;
+  driver = undefined;
 }

package/src/store/sqlite-db.ts

@@ -17,7 +17,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { createDatabase, loadSqlite } from './bun-sqlite-compat.js';
 
-// Dynamic require for SQLite (better-sqlite3 or bun:sqlite)
+// Dynamic require for SQLite (better-sqlite3, node:sqlite, or bun:sqlite)
 let BetterSqlite3: any;
 
 export function loadBetterSqlite3(): any {
@@ -26,7 +26,7 @@ export function loadBetterSqlite3(): any {
     BetterSqlite3 = loadSqlite();
     return BetterSqlite3;
   } catch {
-    throw new Error('[memorix] SQLite is not available (neither better-sqlite3 nor bun:sqlite)');
+    throw new Error('[memorix] SQLite is not available (better-sqlite3, node:sqlite, and bun:sqlite all failed)');
   }
 }
 
@@ -688,7 +688,7 @@ function applySchemaMigrations(db: any): void {
 const _dbCache = new Map<string, any>();
 
 /**
- * Get or create a shared better-sqlite3 database handle for the given data directory.
+ * Get or create a shared SQLite database handle for the given data directory.
  *
  * The handle is cached per normalized dataDir path. All stores (observations,
  * mini-skills, sessions) share the same connection and the same DB file.