@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-hermes-memory/src/index.ts

@@ -30,7 +30,7 @@ import { SkillStore } from "./store/skill-store.js";
 import { DatabaseManager } from "./store/db.js";
 import { indexSession, upsertSessionFileMetadata, pruneEphemeralReviewSessions, pruneOldSessions, retentionCutoffMs } from "./store/session-indexer.js";
 import { runRecoveryMaintenance } from "./store/recovery-maintenance.js";
-import { scheduleSessionBackfill, waitForSessionBackfill, SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS } from "./handlers/session-backfill.js";
+import { scheduleSessionBackfill, joinSessionBackfill, waitForSessionBackfill, SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS, type SessionBackfillState } from "./handlers/session-backfill.js";
 import { scheduleLiveSessionIndex, waitForLiveSessionIndex, SESSION_LIVE_INDEX_SHUTDOWN_TIMEOUT_MS } from "./handlers/session-live-index.js";
 import { parseSessionFile } from "./store/session-parser.js";
 import { registerMemoryTool } from "./tools/memory-tool.js";
@@ -60,6 +60,7 @@ import { migrateLegacyProjectMemoryDirs } from "./project-memory-migration.js";
 import { AGENT_ROOT } from "./paths.js";
 import { isDatabaseMigrationPending } from "./extension-root-migration.js";
 import { measureLifecycle, measureLifecycleSync } from "./lifecycle-timing.js";
+import { createMemoryInitializer, withMemoryInitialization, type EnsureMemoryReady } from "./memory-initialization.js";
 
 export function resolveProjectSkillDiscovery(
   skillStore: SkillStore,
@@ -90,6 +91,8 @@ export function registerProjectSkillDiscoveryHandler(
 
 export default function (pi: ExtensionAPI) {
   const config = loadConfig();
+  const lazy = config.lazyInitialization === true && config.memoryMode === "policy-only";
+  let sessionContext: ExtensionContext | undefined;
 
   const agentRoot = AGENT_ROOT;
   const legacyGlobalDir = path.join(agentRoot, "memory");
@@ -109,7 +112,7 @@ export default function (pi: ExtensionAPI) {
   // Captured at session_start: the extension factory runs with no session, but
   // the auto-consolidator needs model access to use the fast in-process direct
   // transport instead of always spawning a slow `pi -p` subprocess agent.
-  let sessionModelCtx: Pick<ExtensionContext, "model" | "modelRegistry"> | null = null;
+  let sessionModelCtx: Pick<ExtensionContext, "model" | "modelRegistry" | "sessionManager"> | null = null;
 
   const store = new MemoryStore({ ...config, memoryDir: globalDir });
   // Factory may run with no session (Pi public contract). Do not snapshot
@@ -125,16 +128,16 @@ export default function (pi: ExtensionAPI) {
     migrationSentinelPath: path.join(globalDir, ".skills-migrated-to-extension-storage"),
   });
   const dbManager = new DatabaseManager(globalDir);
+  let databaseClosed = false;
+  const backfillState: SessionBackfillState = { inProgress: false, promise: null };
   dbManager.setQuickCheckOnOpen(config.quickCheckOnOpen ?? true);
-  let databaseMigrationPending = shouldMigrateExtensionRoot
-    && isDatabaseMigrationPending(legacyGlobalDir, globalDir);
-  if (databaseMigrationPending) {
-    dbManager.setOpenGuard(() => {
-      if (databaseMigrationPending) {
-        throw new Error("Legacy sessions.db migration is pending");
-      }
-    });
-  }
+  // No database may open before first-use migration has completed.
+  let databaseMigrationPending = (lazy && shouldMigrateExtensionRoot) || (shouldMigrateExtensionRoot
+    && isDatabaseMigrationPending(legacyGlobalDir, globalDir));
+  dbManager.setOpenGuard(() => {
+    if (databaseClosed) throw new Error("Memory session has shut down");
+    if (databaseMigrationPending) throw new Error("Legacy sessions.db migration is pending");
+  });
   const sessionsDir = path.join(agentRoot, "sessions");
 
   const refreshSkillProjectContext = (cwd?: string) => {
@@ -149,7 +152,7 @@ export default function (pi: ExtensionAPI) {
   // Keep project memory available for users upgrading from the old
   // ~/.selesai/agent/<project>/ layout. This is non-destructive: legacy folders
   // remain in place while entries are copied/merged into projects-memory/.
-  migrateLegacyProjectMemoryDirs(agentRoot, config.projectsMemoryDir);
+  if (!lazy) migrateLegacyProjectMemoryDirs(agentRoot, config.projectsMemoryDir);
   // Project-scoped store: ~/.selesai/agent/<projectsMemoryDir>/<project_name>/
   // Bound from session/tool ctx.cwd, never from factory process.cwd().
   const createProjectStore = (projectInfo: ReturnType<typeof detectProject>): MemoryStore | null => {
@@ -162,6 +165,7 @@ export default function (pi: ExtensionAPI) {
   };
   let projectMemoryDir: string | null = null;
   let projectStore: MemoryStore | null = null;
+  let projectLoad: Promise<void> | undefined;
   const projectStoreRef = () => projectStore;
   const projectNameRef = () => projectName;
   let configureProjectStore: (candidate: MemoryStore | null) => void = () => {};
@@ -175,22 +179,37 @@ export default function (pi: ExtensionAPI) {
       projectStore = createProjectStore(nextProject);
       configureProjectStore(projectStore);
       configureMemoryToolProjectStore(projectStore);
-      if (projectStore) await projectStore.loadFromDisk();
+      projectLoad = projectStore?.loadFromDisk().catch((error) => {
+        projectMemoryDir = null;
+        projectStore = null;
+        projectName = "";
+        projectLoad = undefined;
+        throw error;
+      });
     }
+    await projectLoad;
     projectName = nextProject.name ?? "";
   };
   // Never written by review, consolidation or the correction detector — see
   // store/standing-instructions.ts for why provenance has to be structural.
   const standingStore = config.standingInstructionsEnabled !== false
-    ? new StandingInstructions(path.join(globalDir, STANDING_FILE))
+    ? new StandingInstructions(path.join(globalDir, STANDING_FILE), undefined, undefined,
+        shouldMigrateExtensionRoot ? path.join(legacyGlobalDir, STANDING_FILE) : undefined)
     : null;
 
-  // ── 1. Load memory from disk on session start ──
-  pi.on("session_start", async (_event, ctx) => {
-    sessionModelCtx = { model: ctx.model, modelRegistry: ctx.modelRegistry };
+  const initialization = createMemoryInitializer(async (ctx) => {
+    const timingPrefix = lazy ? "memory-init" : "session-start";
+    if (lazy) migrateLegacyProjectMemoryDirs(agentRoot, config.projectsMemoryDir);
     if (!persistenceInitialized) {
       try {
-        await measureLifecycle("session-start.persistence-sync", async () => {
+        await measureLifecycle(`${timingPrefix}.persistence-sync`, async () => {
+          // Startup reconciles the global files plus the current project only:
+          // a full sweep over every projects-memory folder serialized
+          // concurrent startups on the shared mutation-lock database.
+          // /memory-sync-markdown remains the repair path for other scopes.
+          const startupProject = ctx?.cwd
+            ? detectProject(config.projectsMemoryDir, ctx.cwd).name
+            : null;
           await migrateThenSyncMarkdownMemories(
             dbManager,
             shouldMigrateExtensionRoot ? legacyGlobalDir : null,
@@ -198,27 +217,22 @@ export default function (pi: ExtensionAPI) {
             config.projectsMemoryDir,
             agentRoot,
             {
+              onlyProjects: startupProject ? [startupProject] : [],
               onMigrationSucceeded: () => {
                 databaseMigrationPending = false;
-                dbManager.setOpenGuard(null);
               },
             },
           );
         });
         persistenceInitialized = true;
-      } catch {
+      } catch (error) {
+        if (lazy) throw error;
         // Best-effort only: migration or SQLite backfill must not block startup.
       }
     }
 
-    await measureLifecycle("session-start.load", async () => {
-      await bindProjectFromCwd(ctx.cwd);
-      refreshSkillProjectContext(ctx.cwd);
-      await skillStore.migrateLegacySkills();
-      await skillStore.ensureDiscoveredRoots();
+    await measureLifecycle(`${timingPrefix}.load`, async () => {
       await store.loadFromDisk();
-      if (projectStore) await projectStore.loadFromDisk();
-      if (standingStore) await standingStore.load();
     });
 
     if (persistenceInitialized) {
@@ -249,8 +263,9 @@ export default function (pi: ExtensionAPI) {
         console.warn(`⚠️ Snapshot retention sweep failed: ${err instanceof Error ? err.message : String(err)}`);
       }
       scheduleSessionBackfill(dbManager, sessionsDir, {
+        state: backfillState,
         notify: (message, level) => {
-          const ui = (ctx as { ui?: { notify?: (message: string, level?: string) => void } }).ui;
+          const ui = sessionContext?.ui;
           if (ui?.notify) {
             ui.notify(message, level);
           } else if (level === "error" || level === "warning") {
@@ -264,6 +279,28 @@ export default function (pi: ExtensionAPI) {
         retentionCutoffMs: retentionCutoffMs(config.sessionRetentionDays),
       });
     }
+  }, async (ctx) => {
+    try {
+      await bindProjectFromCwd(ctx.cwd);
+    } finally {
+      // Even a failed project bind must not leave backfill running past close.
+      if (lazy) await joinSessionBackfill(backfillState);
+    }
+  });
+
+  const ensureMemoryReady: EnsureMemoryReady = (ctx, signal) => initialization.ensure(ctx, signal);
+  const memoryPi = withMemoryInitialization(pi, initialization);
+
+  // Skills and pinned instructions must be available even without a lookup.
+  pi.on("session_start", async (_event, ctx) => {
+    sessionContext = ctx;
+    sessionModelCtx = { model: ctx.model, modelRegistry: ctx.modelRegistry, sessionManager: ctx.sessionManager };
+    // Pinned directives must not depend on migration/SQLite being healthy.
+    if (standingStore) await standingStore.load();
+    if (!lazy) await ensureMemoryReady(ctx);
+    refreshSkillProjectContext(ctx.cwd);
+    await skillStore.migrateLegacySkills();
+    await skillStore.ensureDiscoveredRoots();
   });
 
   registerProjectSkillDiscoveryHandler(pi, skillStore, config.projectsMemoryDir);
@@ -271,16 +308,35 @@ export default function (pi: ExtensionAPI) {
   // ── 2. Inject memory policy by default; legacy mode keeps full frozen memory blocks ──
   pi.on("before_agent_start", async (event, _ctx) => {
     const promptContext = await buildPromptContext(config, store, projectStoreRef(), projectNameRef(), standingStore);
+    if (!promptContext) return;
 
-    if (promptContext) {
-      return {
-        systemPrompt: event.systemPrompt + "\n\n" + promptContext,
-      };
+    // pi 0.86+ hands handlers a normalized clone of these options and re-renders
+    // the prompt from it, so appending through `appendSystemPrompt` keeps the
+    // prompt a set of named sections; returning `systemPrompt` instead forces the
+    // rendered text and flattens the sections for every later handler and for
+    // section-aware providers (#251).
+    //
+    // Branch on that mechanism, not on the field: `systemPromptOptions` is on the
+    // event at the 0.80.6 floor too, but 0.80.x-0.85.x pass the raw long-lived
+    // base options and only apply a returned `systemPrompt`, so an append there
+    // reaches no prompt and does not stay private either — it accumulates in the
+    // object `ctx.getSystemPromptOptions()` hands to other extensions. Every
+    // 0.86+ runner normalizes `sections` onto the clone it passes.
+    const promptOptions = event.systemPromptOptions;
+    if (promptOptions && "sections" in promptOptions) {
+      promptOptions.appendSystemPrompt = [promptOptions.appendSystemPrompt, promptContext]
+        .filter(Boolean)
+        .join("\n\n");
+      return;
     }
+
+    return {
+      systemPrompt: event.systemPrompt + "\n\n" + promptContext,
+    };
   });
 
   // ── 3. Register action-specific memory write tools with SQLite sync ──
-  configureMemoryToolProjectStore = registerMemoryTool(pi, store, projectStoreRef, dbManager, projectNameRef, bindProjectFromCwd);
+  configureMemoryToolProjectStore = registerMemoryTool(memoryPi, store, projectStoreRef, dbManager, projectNameRef, bindProjectFromCwd);
 
   // ── 4. Register the skill tool ──
   registerSkillTool(pi, skillStore);
@@ -289,10 +345,11 @@ export default function (pi: ExtensionAPI) {
   setupBackgroundReview(pi, store, projectStoreRef, config, {
     dbManager,
     projectName: projectNameRef,
+    ensureMemoryReady,
   });
 
   // ── 6. Setup session-end flush ──
-  setupSessionFlush(pi, store, projectStoreRef, config, dbManager, projectNameRef);
+  setupSessionFlush(pi, store, projectStoreRef, config, dbManager, projectNameRef, { ensureMemoryReady });
 
   // ── 7. Setup auto-consolidation (inject consolidator into stores) ──
   // Keep the failure in the tool result regardless; session-console logging is
@@ -312,11 +369,13 @@ export default function (pi: ExtensionAPI) {
       toolTarget,
       config,
       sessionModelCtx,
+      dbManager,
+      toolTarget === "project" ? projectNameRef() : null,
     );
     if (result.deferred) {
       console.info(`⏳ Auto-consolidation for '${toolTarget}' deferred: ${result.error ?? "another session holds the consolidation lock"}`);
-    } else if (shouldWarnAutoConsolidationFailure(config.autoConsolidationWarnOnFailure, result.consolidated)) {
-      console.warn(`⚠️ Auto-consolidation failed for '${toolTarget}': ${result.error ?? "no reason reported"}`);
+    } else if (shouldWarnAutoConsolidationFailure(config.autoConsolidationWarnOnFailure, result.consolidated, result.partial === true)) {
+      console.warn(`⚠️ Auto-consolidation ${result.partial ? "partially " : ""}failed for '${toolTarget}': ${result.error ?? "no reason reported"}`);
     }
     return result;
   };
@@ -329,32 +388,35 @@ export default function (pi: ExtensionAPI) {
     );
   };
   configureProjectStore(projectStore);
-  registerConsolidateCommand(pi, store, config.consolidationTimeoutMs, projectStoreRef, projectNameRef, config, dbManager);
+  registerConsolidateCommand(memoryPi, store, config.consolidationTimeoutMs, projectStoreRef, projectNameRef, config, dbManager);
 
   // ── 8. Setup correction detection ──
-  setupCorrectionDetector(pi, store, projectStoreRef, config, dbManager, projectNameRef);
+  setupCorrectionDetector(pi, store, projectStoreRef, config, dbManager, projectNameRef, { ensureMemoryReady });
 
   // ── 9. Register commands ──
-  registerInsightsCommand(pi, store, projectStoreRef, projectNameRef);
+  registerInsightsCommand(memoryPi, store, projectStoreRef, projectNameRef, dbManager);
   registerSkillsCommand(pi, skillStore);
-  registerInterviewCommand(pi, store);
+  registerInterviewCommand(memoryPi, store);
   registerSwitchProjectCommand(pi, config);
   registerLearnMemoryCommand(pi);
-  registerSyncMarkdownMemoriesCommand(pi, dbManager, globalDir, config.projectsMemoryDir, agentRoot);
-  registerPreviewContextCommand(pi, store, projectStoreRef, projectNameRef, config, standingStore);
+  registerSyncMarkdownMemoriesCommand(memoryPi, dbManager, globalDir, config.projectsMemoryDir, agentRoot);
+  registerPreviewContextCommand(lazy ? pi : memoryPi, store, projectStoreRef, projectNameRef, config, standingStore);
   if (standingStore) registerStandingPinCommand(pi, standingStore);
 
   // ── 10. Live session indexing ──
   pi.on("message_end", async (_event, ctx) => {
+    // Cold lazy sessions remain in Pi's JSONL files and are backfilled on use.
+    if (lazy && !initialization.isReady()) return;
     scheduleLiveSessionIndex(dbManager, ctx.sessionManager, {
       onError: (err) => console.warn(`⚠️ Live session indexing failed: ${err instanceof Error ? err.message : String(err)}`),
     });
   });
 
   // ── 11. SQLite session search + extended memory ──
-  registerSessionSearchTool(pi, dbManager, config.sessionSearch ?? { variant: "legacy" });
-  registerMemorySearchTool(pi, dbManager);
-  registerIndexSessionsCommand(pi, config);
+  registerSessionSearchTool(config.sessionSearch?.variant === "anchors" ? pi : memoryPi,
+    dbManager, config.sessionSearch ?? { variant: "legacy" });
+  registerMemorySearchTool(memoryPi, dbManager, { usageTrackingEnabled: config.usageHitTrackingEnabled });
+  registerIndexSessionsCommand(memoryPi, config);
 
   // ── 12. Auto-index session on shutdown ──
   // Registered last, so this runs after the session-flush shutdown handler and
@@ -368,10 +430,16 @@ export default function (pi: ExtensionAPI) {
   // DB-writing session_shutdown handler after this block — it would run after
   // close() and silently no-op.
   pi.on("session_shutdown", async (_event, ctx) => {
+    await initialization.close();
+    if (lazy && !initialization.isReady()) {
+      databaseClosed = true;
+      dbManager.close();
+      return;
+    }
     try {
       measureLifecycleSync("shutdown.active-index", () => {
         const sessionFile = ctx.sessionManager.getSessionFile();
-        if (sessionFile && require("node:fs").existsSync(sessionFile)) {
+        if (sessionFile && fs.existsSync(sessionFile)) {
           const sessionData = parseSessionFile(sessionFile);
           if (sessionData) {
             dbManager.withCorruptionRecovery(() => {
@@ -390,13 +458,14 @@ export default function (pi: ExtensionAPI) {
     } finally {
       try {
         await measureLifecycle("shutdown.index-waits", () => Promise.all([
-          waitForSessionBackfill(SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS),
+          waitForSessionBackfill(SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS, backfillState),
           waitForLiveSessionIndex(SESSION_LIVE_INDEX_SHUTDOWN_TIMEOUT_MS),
         ]));
       } catch {
         // Best effort only — shutdown should not be held up by indexing errors.
       }
       try {
+        databaseClosed = true;
         measureLifecycleSync("shutdown.database-close", () => dbManager.close());
       } catch { /* best effort — never block shutdown */ }
     }

package/dist/extensions/pi-hermes-memory/src/memory-initialization.ts

@@ -0,0 +1,101 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type MemoryContext = Pick<ExtensionContext, "cwd">;
+export type EnsureMemoryReady = (ctx: MemoryContext, signal?: AbortSignal) => Promise<void>;
+
+/** Cancel one waiter without cancelling initialization shared with other users. */
+function waitForReady(promise: Promise<void>, signal?: AbortSignal): Promise<void> {
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason ?? new Error("Memory operation aborted"));
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+
+/** Own initialization, per-use preparation and operations through shutdown. */
+export function createMemoryInitializer(
+  initialize: (ctx?: MemoryContext) => Promise<void>,
+  prepare?: (ctx: MemoryContext) => Promise<void>,
+) {
+  let pending: Promise<void> | undefined;
+  let initialized = false;
+  let ready = false;
+  let closed = false;
+  const active = new Set<Promise<unknown>>();
+
+  function assertOpen(): void {
+    if (closed) throw new Error("Memory session has shut down");
+  }
+
+  function track<T>(work: Promise<T>): Promise<T> {
+    active.add(work);
+    void work.then(() => active.delete(work), () => active.delete(work));
+    return work;
+  }
+
+  async function ensure(ctx?: MemoryContext, signal?: AbortSignal): Promise<void> {
+    assertOpen();
+    signal?.throwIfAborted();
+    if (!initialized) {
+      pending ??= Promise.resolve().then(() => initialize(ctx)).then(() => {
+        initialized = true;
+      }).finally(() => {
+        pending = undefined;
+      });
+    }
+    // Track the underlying preparation even when an individual waiter cancels.
+    const preparation = track((pending ?? Promise.resolve()).then(async () => {
+      if (ctx) await prepare?.(ctx);
+      ready = true;
+    }));
+    await waitForReady(preparation, signal);
+    signal?.throwIfAborted();
+    assertOpen();
+  }
+
+  return {
+    isReady: () => ready,
+    ensure,
+    run<T>(ctx: MemoryContext, work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+      return track(ensure(ctx, signal).then(() => {
+        assertOpen();
+        signal?.throwIfAborted();
+        return work();
+      }));
+    },
+    async close(): Promise<void> {
+      closed = true;
+      // No new work is accepted. Join loads, project binds, backfill and callers
+      // already executing before the owner checkpoints/closes its database.
+      await Promise.allSettled([...active]);
+    },
+  };
+}
+
+/** Guard memory entry points without changing schemas, rendering or events. */
+export function withMemoryInitialization(
+  pi: ExtensionAPI,
+  initialization: Pick<ReturnType<typeof createMemoryInitializer>, "run">,
+): ExtensionAPI {
+  return {
+    ...pi,
+    registerTool(tool) {
+      pi.registerTool({
+        ...tool,
+        async execute(id, params, signal, onUpdate, ctx) {
+          return initialization.run(ctx, () => tool.execute(id, params, signal, onUpdate, ctx), signal);
+        },
+      });
+    },
+    registerCommand(name, options) {
+      pi.registerCommand(name, {
+        ...options,
+        async handler(args, ctx) {
+          return initialization.run(ctx, () => options.handler(args, ctx));
+        },
+      });
+    },
+  };
+}

package/dist/extensions/pi-hermes-memory/src/store/atomic-lock-coordinator.ts

@@ -97,7 +97,15 @@ function probeProcessIncarnation(pid: number): string | null {
   return result.status === 0 ? result.stdout.trim() || null : null;
 }
 
-const currentProcessIncarnation = probeProcessIncarnation(process.pid);
+// Deferred: probing our own incarnation spawns a helper process (powershell.exe
+// costs ~1.4s on Windows) and is only needed once a lock is actually taken.
+let currentProcessIncarnation: string | null | undefined;
+function selfIncarnation(): string | null {
+  if (currentProcessIncarnation === undefined) {
+    currentProcessIncarnation = probeProcessIncarnation(process.pid);
+  }
+  return currentProcessIncarnation;
+}
 const RELEASE_ATTEMPTS = 3;
 // Opportunistic dead-row GC: a row must be older than the grace period before
 // a dead pid makes it collectable (guards against a pid we cannot observe, and
@@ -118,7 +126,7 @@ export class AtomicLockCoordinator {
   constructor(private readonly dbPath: string, options: AtomicLockCoordinatorOptions = {}) {
     this.pid = options.pid ?? process.pid;
     this.probeIncarnation = options.probeIncarnation
-      ?? ((pid) => pid === process.pid ? currentProcessIncarnation : probeProcessIncarnation(pid));
+      ?? ((pid) => pid === process.pid ? selfIncarnation() : probeProcessIncarnation(pid));
     this.incarnation = options.incarnation
       ?? this.probeIncarnation(this.pid)
       ?? null;

package/dist/extensions/pi-hermes-memory/src/store/db.ts

@@ -6,6 +6,7 @@ import { AtomicLockCoordinator } from './atomic-lock-coordinator.js';
 import { canonicalStoragePathSync } from './canonical-storage-path.js';
 import { isBunRuntime, loadBetterSqlite3 } from './sqlite-native.js';
 import { measureLifecycleSync } from '../lifecycle-timing.js';
+import { MDSYNC_METADATA_KEY_PREFIX } from '../constants.js';
 
 type StatementLike = {
   run: (...args: any[]) => any;
@@ -651,13 +652,21 @@ export class DatabaseManager {
   }
 
   private copyRecoverableRows(source: DatabaseLike, target: DatabaseLike): Record<string, number> {
-    return {
+    const counts = {
       extension_metadata: this.copyExtensionMetadata(source, target),
       sessions: this.copySessions(source, target),
       messages: this.copyMessages(source, target),
       session_files: this.copySessionFiles(source, target),
       memories: this.copyMemories(source, target),
     };
+    // Markdown-scope fingerprints describe the rows in their source db; the
+    // copies above coerce invalid values instead of dropping rows, so a copied
+    // fingerprint can agree with coerced rows while content drifted. A rebuilt
+    // database re-mirrors markdown exactly once, at zero cost when healthy.
+    // The pattern follows the shared prefix constant, so bumping its version
+    // keeps this strip in step instead of silently missing the new keys.
+    target.prepare("DELETE FROM extension_metadata WHERE key LIKE ?").run(`${MDSYNC_METADATA_KEY_PREFIX}%`);
+    return counts;
   }
 
   private copyExtensionMetadata(source: DatabaseLike, target: DatabaseLike): number {
@@ -746,8 +755,8 @@ export class DatabaseManager {
 
   private copyMemories(source: DatabaseLike, target: DatabaseLike): number {
     const insert = target.prepare(`
-      INSERT OR IGNORE INTO memories (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT OR IGNORE INTO memories (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced, hit_count, last_hit_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     let copied = 0;
 
@@ -762,6 +771,8 @@ export class DatabaseManager {
       'corrected_to',
       'created',
       'last_referenced',
+      'hit_count',
+      'last_hit_at',
     ])) {
       const id = this.integerOr(row.id, NaN);
       if (!Number.isFinite(id) || typeof row.content !== 'string') continue;
@@ -770,6 +781,8 @@ export class DatabaseManager {
       const category = typeof row.category === 'string' && MEMORY_CATEGORIES.has(row.category) ? row.category : null;
       const created = typeof row.created === 'string' ? row.created : new Date(0).toISOString();
       const lastReferenced = typeof row.last_referenced === 'string' ? row.last_referenced : created;
+      const hitCount = this.integerOr(row.hit_count, 0);
+      const lastHitAt = this.nullableString(row.last_hit_at);
 
       insert.run(
         id,
@@ -782,6 +795,8 @@ export class DatabaseManager {
         this.nullableString(row.corrected_to),
         created,
         lastReferenced,
+        hitCount,
+        lastHitAt,
       );
       copied++;
     }
@@ -938,6 +953,12 @@ export class DatabaseManager {
     if (!names.has('corrected_to')) {
       db.exec('ALTER TABLE memories ADD COLUMN corrected_to TEXT');
     }
+    if (!names.has('hit_count')) {
+      db.exec('ALTER TABLE memories ADD COLUMN hit_count INTEGER NOT NULL DEFAULT 0');
+    }
+    if (!names.has('last_hit_at')) {
+      db.exec('ALTER TABLE memories ADD COLUMN last_hit_at DATE');
+    }
   }
 
   private ensureSessionsColumns(db: DatabaseLike): void {
@@ -1006,13 +1027,15 @@ export class DatabaseManager {
             tool_state TEXT,
             corrected_to TEXT,
             created DATE NOT NULL,
-            last_referenced DATE NOT NULL
+            last_referenced DATE NOT NULL,
+            hit_count INTEGER NOT NULL DEFAULT 0,
+            last_hit_at DATE
           );
         `);
 
         db.exec(`
-          INSERT INTO memories_new (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
-          SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
+          INSERT INTO memories_new (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced, hit_count, last_hit_at)
+          SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced, hit_count, last_hit_at
           FROM memories;
         `);
 
@@ -1040,13 +1063,15 @@ export class DatabaseManager {
           tool_state TEXT,
           corrected_to TEXT,
           created DATE NOT NULL,
-          last_referenced DATE NOT NULL
+          last_referenced DATE NOT NULL,
+          hit_count INTEGER NOT NULL DEFAULT 0,
+          last_hit_at DATE
         );
       `);
 
       db.exec(`
-          INSERT INTO memories_new (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
-          SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
+          INSERT INTO memories_new (id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced, hit_count, last_hit_at)
+          SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced, hit_count, last_hit_at
           FROM memories;
         `);