akm-cli 0.9.0-beta.5 → 0.9.0-beta.50

package/dist/indexer/indexer.js

@@ -10,8 +10,10 @@ import { getDbPath } from "../core/paths.js";
 import { isVerbose, warn, warnVerbose } from "../core/warn.js";
 import { resolveIndexPassLLM } from "../llm/index-passes.js";
 import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
-import { clearStaleCacheEntries, closeDatabase, deleteEntriesByDir, deleteEntriesByIds, deleteEntriesByStashDir, deleteIndexDirStatesByStashDir, getAllEntriesForEmbedding, getEmbeddableEntryCount, getEmbeddingCount, getEntriesByDir, getEntryCount, getIndexDirState, getMeta, isVecAvailable, openDatabase, openExistingDatabase, rebuildFts, relinkUsageEvents, setMeta, upsertEmbedding, upsertEntry, upsertIndexDirState, upsertUtilityScore, upsertWorkflowDocument, warnIfVecMissing, } from "./db/db.js";
+import { clearStaleCacheEntries, closeDatabase, deleteEntriesByDir, deleteEntriesByIds, deleteEntriesByStashDir, deleteIndexDirStatesByStashDir, getAllEntriesForEmbedding, getEmbeddableEntryCount, getEmbeddingCount, getEntryCount, getMeta, isVecAvailable, openExistingDatabase, openIndexDatabase, purgeEmbeddings, rebuildFts, relinkUsageEvents, setMeta, upsertEmbedding, upsertEntry, upsertIndexDirState, upsertUtilityScore, upsertWorkflowDocument, warnIfVecMissing, } from "./db/db.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
+import { withIndexWriterLease } from "./index-writer-lock.js";
+import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
 import { applyCuratedFrontmatter, applyWikiFrontmatter, generateMetadataFlat, isEnrichmentComplete, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./passes/metadata.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./search/semantic-status.js";
@@ -195,8 +197,8 @@ async function runFinalizePhase(ctx) {
     }
     onProgress({ phase: "verify", message: verification.message });
     // Store verification result and totalEntries on ctx for the caller to use
-    ctx._verification = verification;
-    ctx._totalEntries = totalEntries;
+    ctx.verification = verification;
+    ctx.totalEntries = totalEntries;
     // suppress unused warning — sources was previously used inline
     void sources;
 }
@@ -225,119 +227,123 @@ function runCleanPass(db, dryRun) {
 }
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function akmIndex(options) {
-    const stashDir = options?.stashDir || resolveStashDir();
-    const onProgress = options?.onProgress ?? (() => { });
-    const signal = options?.signal;
-    const reEnrich = options?.reEnrich === true;
-    const full = options?.full === true;
-    const clean = options?.clean === true;
-    const dryRun = options?.dryRun === true;
-    // Load config and resolve all stash sources
-    const { loadConfig } = await import("../core/config/config.js");
-    const config = loadConfig();
-    // One-time, read-only guard: warn if the writable stash still holds an
-    // un-migrated `vaults/` directory. In 0.9.0 the indexer skips `vaults/`
-    // entirely, so an unmigrated vault's `.env` data would silently never be
-    // indexed. Non-destructive — only stats, never reads/writes/deletes.
-    const { warnOnUnmigratedVaults } = await import("./usage/unmigrated-vaults-guard.js");
-    warnOnUnmigratedVaults(stashDir);
-    // Ensure git stash caches are extracted before resolving stash dirs,
-    // so their content directories exist on disk for the walker to discover.
-    const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
-    await ensureSourceCaches(config, { force: full });
-    const allSourceEntries = resolveSourceEntries(stashDir, config);
-    const allSourceDirs = allSourceEntries.map((s) => s.path);
-    const t0 = Date.now();
-    // Open database — pass embedding dimension from config if available
-    const dbPath = getDbPath();
-    const embeddingDim = config.embedding?.dimension;
-    const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
-    try {
-        // Determine incremental vs full mode
-        const prevStashDir = getMeta(db, "stashDir");
-        const prevBuiltAt = getMeta(db, "builtAt");
-        const isIncremental = !full && prevStashDir === stashDir && !!prevBuiltAt;
-        const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
-        // Assemble the run context
-        const ctx = {
-            db,
-            config,
-            sources: allSourceEntries,
-            sourceDirs: allSourceDirs,
-            full,
-            reEnrich,
-            stashDir,
-            onProgress,
-            signal,
-            timing: {
-                t0,
-                tWalkStart: t0,
-                tWalkEnd: t0,
-                tLlmEnd: t0,
-                tFtsEnd: t0,
-                tEmbedEnd: t0,
-            },
-            isIncremental,
-            builtAtMs,
-            hadRemovedSources: false,
-            scannedDirs: 0,
-            skippedDirs: 0,
-            generatedCount: 0,
-            walkWarnings: [],
-            dirsNeedingLlm: [],
-            embeddingResult: null,
-            graphExtractionResult: null,
-        };
-        onProgress({
-            phase: "summary",
-            message: buildIndexSummaryMessage({
+    return withIndexWriterLease({ purpose: "akm-index", signal: options?.signal }, async () => {
+        const stashDir = options?.stashDir || resolveStashDir();
+        const onProgress = options?.onProgress ?? (() => { });
+        const signal = options?.signal;
+        const reEnrich = options?.reEnrich === true;
+        const full = options?.full === true;
+        const clean = options?.clean === true;
+        const dryRun = options?.dryRun === true;
+        // Load config and resolve all stash sources
+        const { loadConfig } = await import("../core/config/config.js");
+        const config = loadConfig();
+        // One-time, read-only guard: warn if the writable stash still holds an
+        // un-migrated `vaults/` directory. In 0.9.0 the indexer skips `vaults/`
+        // entirely, so an unmigrated vault's `.env` data would silently never be
+        // indexed. Non-destructive — only stats, never reads/writes/deletes.
+        const { warnOnUnmigratedVaults } = await import("./usage/unmigrated-vaults-guard.js");
+        warnOnUnmigratedVaults(stashDir);
+        // Ensure git stash caches are extracted before resolving stash dirs,
+        // so their content directories exist on disk for the walker to discover.
+        const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
+        await ensureSourceCaches(config, { force: full });
+        const allSourceEntries = resolveSourceEntries(stashDir, config);
+        const allSourceDirs = allSourceEntries.map((s) => s.path);
+        const t0 = Date.now();
+        // Open database — pass embedding dimension from config if available
+        const dbPath = getDbPath();
+        const embeddingDim = config.embedding?.dimension;
+        const db = openIndexDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+        try {
+            // Determine incremental vs full mode
+            const prevStashDir = getMeta(db, "stashDir");
+            const prevBuiltAt = getMeta(db, "builtAt");
+            const isIncremental = !full && prevStashDir === stashDir && !!prevBuiltAt;
+            const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
+            // Assemble the run context
+            const ctx = {
+                db,
+                config,
+                sources: allSourceEntries,
+                sourceDirs: allSourceDirs,
+                full,
+                reEnrich,
+                stashDir,
+                onProgress,
+                signal,
+                timing: {
+                    t0,
+                    tWalkStart: t0,
+                    tWalkEnd: t0,
+                    tLlmEnd: t0,
+                    tFtsEnd: t0,
+                    tEmbedEnd: t0,
+                },
+                isIncremental,
+                builtAtMs,
+                hadRemovedSources: false,
+                scannedDirs: 0,
+                skippedDirs: 0,
+                generatedCount: 0,
+                walkWarnings: [],
+                dirsNeedingLlm: [],
+                embeddingResult: null,
+                graphExtractionResult: null,
+            };
+            onProgress({
+                phase: "summary",
+                message: buildIndexSummaryMessage({
+                    mode: isIncremental ? "incremental" : "full",
+                    sourcesCount: allSourceDirs.length,
+                    semanticSearchMode: config.semanticSearchMode,
+                    embeddingProvider: getEmbeddingProvider(config.embedding),
+                    llmEnabled: !!resolveIndexPassLLM("enrichment", config),
+                    vecAvailable: isVecAvailable(db),
+                }),
+            });
+            // ── Phase sequence ───────────────────────────────────────────────────────
+            await runSourceCachePhase(ctx);
+            await runWalkPhase(ctx);
+            await runEmbeddingPhase(ctx);
+            await runFinalizePhase(ctx);
+            // ────────────────────────────────────────────────────────────────────────
+            // runFinalizePhase always populates these before returning.
+            const verification = ctx.verification;
+            const totalEntries = ctx.totalEntries;
+            const { timing } = ctx;
+            // ── Clean pass ───────────────────────────────────────────────────────────
+            // After the normal index completes, remove entries whose source files no
+            // longer exist on disk. Remote entries (empty file_path) are skipped.
+            let cleanResult;
+            if (clean) {
+                cleanResult = runCleanPass(db, dryRun);
+            }
+            // ────────────────────────────────────────────────────────────────────────
+            return {
+                stashDir,
+                totalEntries,
+                generatedMetadata: ctx.generatedCount,
+                indexPath: dbPath,
                 mode: isIncremental ? "incremental" : "full",
-                sourcesCount: allSourceDirs.length,
-                semanticSearchMode: config.semanticSearchMode,
-                embeddingProvider: getEmbeddingProvider(config.embedding),
-                llmEnabled: !!resolveIndexPassLLM("enrichment", config),
-                vecAvailable: isVecAvailable(db),
-            }),
-        });
-        // ── Phase sequence ───────────────────────────────────────────────────────
-        await runSourceCachePhase(ctx);
-        await runWalkPhase(ctx);
-        await runEmbeddingPhase(ctx);
-        await runFinalizePhase(ctx);
-        // ────────────────────────────────────────────────────────────────────────
-        const { _verification: verification, _totalEntries: totalEntries } = ctx;
-        const { timing } = ctx;
-        // ── Clean pass ───────────────────────────────────────────────────────────
-        // After the normal index completes, remove entries whose source files no
-        // longer exist on disk. Remote entries (empty file_path) are skipped.
-        let cleanResult;
-        if (clean) {
-            cleanResult = runCleanPass(db, dryRun);
+                directoriesScanned: ctx.scannedDirs,
+                directoriesSkipped: ctx.skippedDirs,
+                ...(ctx.walkWarnings.length > 0 ? { warnings: ctx.walkWarnings } : {}),
+                verification,
+                timing: {
+                    totalMs: Date.now() - timing.t0,
+                    walkMs: timing.tWalkEnd - timing.tWalkStart,
+                    llmMs: timing.tLlmEnd - timing.tWalkEnd,
+                    embedMs: timing.tEmbedEnd - timing.tLlmEnd,
+                    ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
+                },
+                ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
+            };
         }
-        // ────────────────────────────────────────────────────────────────────────
-        return {
-            stashDir,
-            totalEntries,
-            generatedMetadata: ctx.generatedCount,
-            indexPath: dbPath,
-            mode: isIncremental ? "incremental" : "full",
-            directoriesScanned: ctx.scannedDirs,
-            directoriesSkipped: ctx.skippedDirs,
-            ...(ctx.walkWarnings.length > 0 ? { warnings: ctx.walkWarnings } : {}),
-            verification,
-            timing: {
-                totalMs: Date.now() - timing.t0,
-                walkMs: timing.tWalkEnd - timing.tWalkStart,
-                llmMs: timing.tLlmEnd - timing.tWalkEnd,
-                embedMs: timing.tEmbedEnd - timing.tLlmEnd,
-                ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
-            },
-            ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
-        };
-    }
-    finally {
-        closeDatabase(db);
-    }
+        finally {
+            closeDatabase(db);
+        }
+    });
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
 async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress) {
@@ -634,98 +640,6 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadR
     insertTransaction();
     return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
-function getDirIndexState(db, dirPath, files, builtAtMs) {
-    const prevEntries = getEntriesByDir(db, dirPath);
-    const fingerprint = computeDirFingerprint(dirPath, files);
-    if (prevEntries.length > 0) {
-        const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
-        if (!staleReason) {
-            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
-        }
-        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
-    }
-    const cachedState = getIndexDirState(db, dirPath);
-    if (cachedState &&
-        cachedState.fileSetHash === fingerprint.fileSetHash &&
-        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
-        return {
-            stale: false,
-            reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
-            persistedRowCount: 0,
-        };
-    }
-    return {
-        stale: true,
-        reason: { kind: "no-previous-rows", detail: cachedState ? `cached=${cachedState.reason}` : undefined },
-        persistedRowCount: 0,
-    };
-}
-function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
-    const state = getDirIndexState(db, dirPath, files, builtAtMs);
-    if (state.stale || state.reason.kind !== "cached-zero-row-state")
-        return undefined;
-    if (!canUseIncrementalSkip(state, priorDirsChanged))
-        return undefined;
-    return state;
-}
-function canUseIncrementalSkip(state, priorDirsChanged) {
-    return !(priorDirsChanged &&
-        state.reason.kind === "cached-zero-row-state" &&
-        state.reason.detail === "deduped-zero-row");
-}
-function computeDirFingerprint(_dirPath, files) {
-    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
-    let fileMtimeMaxMs = 0;
-    for (const file of files) {
-        try {
-            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
-        }
-        catch {
-            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
-            break;
-        }
-    }
-    return {
-        fileSetHash: normalizedFiles.join("\0"),
-        fileMtimeMaxMs,
-    };
-}
-function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
-    const prevFileNames = new Set(previousEntries
-        .map((ie) => {
-        const fromPath = path.basename(ie.filePath);
-        return fromPath || ie.entry.filename;
-    })
-        .filter((e) => !!e));
-    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
-    if (prevFileNames.size !== currFileNames.size) {
-        return { kind: "file-set-changed", detail: `${prevFileNames.size} -> ${currFileNames.size} files` };
-    }
-    for (const name of currFileNames) {
-        if (!prevFileNames.has(name))
-            return { kind: "file-set-changed", detail: name };
-    }
-    for (const file of currentFiles) {
-        try {
-            if (fs.statSync(file).mtimeMs > builtAtMs)
-                return { kind: "mtime-changed", detail: path.basename(file) };
-        }
-        catch {
-            return { kind: "missing-file", detail: path.basename(file) };
-        }
-    }
-    return undefined;
-}
-function inferZeroRowReason(stash, priorReason, warnings, dirPath, dedupedRows) {
-    if (dedupedRows > 0)
-        return "deduped-zero-row";
-    const workflowNoise = warnings.some((warning) => warning.startsWith("Skipped workflow ") && warning.includes(dirPath));
-    if (workflowNoise)
-        return "workflow-noise";
-    if (!stash || stash.entries.length === 0)
-        return "empty-generated-set";
-    return `zero-row:${priorReason?.kind ?? "unknown"}`;
-}
 async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, _enrich = false, reEnrich = false) {
     // Resolve per-pass LLM config via the unified shim. Returns undefined when
     // either no `akm.llm` is configured or the user opted this pass out via
@@ -896,21 +810,9 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
     const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
     const storedFingerprint = getMeta(db, "embeddingFingerprint");
     if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        try {
-            db.exec("DELETE FROM embeddings");
-        }
-        catch {
-            /* ignore */
-        }
-        if (isVecAvailable(db)) {
-            try {
-                db.exec("DELETE FROM entries_vec");
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        setMeta(db, "hasEmbeddings", "0");
+        // Model/provider changed → stored vectors are incompatible. Clear them
+        // (same dimension, so keep the vec table); re-embedded by this index run.
+        purgeEmbeddings(db);
     }
     try {
         const { embedBatch } = await import("../llm/embedder.js");

package/dist/indexer/passes/dir-staleness.js

@@ -0,0 +1,114 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Incremental dir-staleness engine.
+ *
+ * Decides, per stash directory, whether the directory's indexed rows are still
+ * fresh relative to what is on disk — so an incremental `akm index` run can
+ * skip unchanged directories instead of regenerating their metadata.
+ *
+ * Two persisted signals back the decision:
+ *   1. The `entries` rows already indexed for the directory (`getEntriesByDir`).
+ *   2. The `index_dir_state` fingerprint row (`getIndexDirState`), which caches
+ *      the file-set hash + max mtime for directories that legitimately produced
+ *      zero rows, so they are not rescanned every run.
+ *
+ * `computeDirFingerprint` derives the fingerprint (basename set + max mtime)
+ * that both the freshness check and the persisted `index_dir_state` row use.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getEntriesByDir, getIndexDirState } from "../db/db.js";
+export function getDirIndexState(db, dirPath, files, builtAtMs) {
+    const prevEntries = getEntriesByDir(db, dirPath);
+    const fingerprint = computeDirFingerprint(dirPath, files);
+    if (prevEntries.length > 0) {
+        const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
+        if (!staleReason) {
+            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
+        }
+        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+    }
+    const cachedState = getIndexDirState(db, dirPath);
+    if (cachedState &&
+        cachedState.fileSetHash === fingerprint.fileSetHash &&
+        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
+        return {
+            stale: false,
+            reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
+            persistedRowCount: 0,
+        };
+    }
+    return {
+        stale: true,
+        reason: { kind: "no-previous-rows", detail: cachedState ? `cached=${cachedState.reason}` : undefined },
+        persistedRowCount: 0,
+    };
+}
+export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
+    const state = getDirIndexState(db, dirPath, files, builtAtMs);
+    if (state.stale || state.reason.kind !== "cached-zero-row-state")
+        return undefined;
+    if (!canUseIncrementalSkip(state, priorDirsChanged))
+        return undefined;
+    return state;
+}
+export function canUseIncrementalSkip(state, priorDirsChanged) {
+    return !(priorDirsChanged &&
+        state.reason.kind === "cached-zero-row-state" &&
+        state.reason.detail === "deduped-zero-row");
+}
+export function computeDirFingerprint(_dirPath, files) {
+    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
+    let fileMtimeMaxMs = 0;
+    for (const file of files) {
+        try {
+            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
+            break;
+        }
+    }
+    return {
+        fileSetHash: normalizedFiles.join("\0"),
+        fileMtimeMaxMs,
+    };
+}
+function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
+    const prevFileNames = new Set(previousEntries
+        .map((ie) => {
+        const fromPath = path.basename(ie.filePath);
+        return fromPath || ie.entry.filename;
+    })
+        .filter((e) => !!e));
+    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
+    if (prevFileNames.size !== currFileNames.size) {
+        return { kind: "file-set-changed", detail: `${prevFileNames.size} -> ${currFileNames.size} files` };
+    }
+    for (const name of currFileNames) {
+        if (!prevFileNames.has(name))
+            return { kind: "file-set-changed", detail: name };
+    }
+    for (const file of currentFiles) {
+        try {
+            if (fs.statSync(file).mtimeMs > builtAtMs)
+                return { kind: "mtime-changed", detail: path.basename(file) };
+        }
+        catch {
+            return { kind: "missing-file", detail: path.basename(file) };
+        }
+    }
+    return undefined;
+}
+export function inferZeroRowReason(stash, priorReason, warnings, dirPath, dedupedRows) {
+    if (dedupedRows > 0)
+        return "deduped-zero-row";
+    const workflowNoise = warnings.some((warning) => warning.startsWith("Skipped workflow ") && warning.includes(dirPath));
+    if (workflowNoise)
+        return "workflow-noise";
+    if (!stash || stash.entries.length === 0)
+        return "empty-generated-set";
+    return `zero-row:${priorReason?.kind ?? "unknown"}`;
+}

package/dist/indexer/passes/memory-inference.js

@@ -425,10 +425,17 @@ function markParentProcessed(parent) {
         warn(`memory inference: failed to re-read parent ${parent.filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return;
     }
-    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
     const block = parseFrontmatterBlock(raw);
-    const body = block?.content ?? raw;
-    const next = assembleAsset(updatedFm, body);
+    if (!block) {
+        // Cannot safely rewrite malformed frontmatter — skip marking so the memory
+        // is retried on the next run once the frontmatter is repaired. Writing with
+        // `body = raw` would wrap the entire file (including the bad frontmatter)
+        // in a new block, producing a duplicate-frontmatter corruption.
+        warn(`memory inference: skipping markParentProcessed for ${parent.filePath} — could not parse frontmatter block`);
+        return;
+    }
+    const updatedFm = { ...parent.data, [FM_INFERENCE_PROCESSED]: true };
+    const next = assembleAsset(updatedFm, block.content);
     try {
         fs.writeFileSync(parent.filePath, next, "utf8");
     }

package/dist/indexer/passes/staleness-detect.js

@@ -44,6 +44,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import stalenessDetectSystemPrompt from "../../assets/prompts/staleness-detect-system.md" with { type: "text" };
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
 import { concurrentMap } from "../../core/concurrent.js";
@@ -319,11 +320,7 @@ function pickSimilar(candidate, all) {
     return scored.slice(0, TOP_K_SIMILAR).map((s) => s.snap);
 }
 // ── LLM dispatch ────────────────────────────────────────────────────────────
-const SYSTEM_PROMPT = "You are a belief-state classifier for a memory store. Given a candidate memory and a list of more-recent similar memories from the same store, decide whether the candidate is still current or has been superseded.\n\n" +
-    "Respond on the first line with exactly YES or NO.\n" +
-    "If YES, the second line MUST be of the form `SUPERSEDED_BY: <ref>` where <ref> is the exact ref of the superseding memory from the list provided. Do NOT invent refs.\n" +
-    "If NO, do not include any additional lines.\n" +
-    "No prose, no preamble, no markdown.";
+const SYSTEM_PROMPT = stalenessDetectSystemPrompt;
 async function askValidator(connection, candidate, allMemories, signal, timeoutMs) {
     const similar = pickSimilar(candidate, allMemories);
     if (similar.length === 0) {

package/dist/indexer/search/db-search.js

@@ -65,6 +65,7 @@ export async function searchLocal(input) {
     const includeProposed = input.includeProposed === true;
     const beliefFilter = input.beliefFilter ?? "all";
     const restrictToSources = input.restrictToSources === true;
+    const includeExcludedTypes = input.includeExcludedTypes === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
@@ -114,7 +115,7 @@ export async function searchLocal(input) {
                 mode: "keyword",
             };
         }
-        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources);
+        const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes);
         return {
             hits,
             tip: hits.length === 0
@@ -131,14 +132,19 @@ export async function searchLocal(input) {
     }
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false) {
     const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
+    // #627 — resolve the default type-exclusion policy. It applies ONLY on the
+    // untyped ('any') path and only when the caller did not opt back in via
+    // `includeExcludedTypes`. When the config key is ABSENT a built-in default of
+    // ['session'] is applied; an explicit empty list disables exclusion.
+    const defaultExcludes = searchType === "any" && !includeExcludedTypes ? (config.search?.defaultExcludeTypes ?? ["session"]) : [];
     // Empty queries — including ones that sanitize down to no searchable FTS
     // tokens such as "." — should enumerate matching entries instead of
     // returning an empty result set from FTS.
     if (!hasSearchableTokens) {
         const typeFilter = searchType === "any" ? undefined : searchType;
-        const allEntries = getAllEntries(db, typeFilter);
+        const allEntries = getAllEntries(db, typeFilter, defaultExcludes);
         // Deduplicate by file path — multiple entries can share the same file
         const seenFilePaths = new Set();
         const uniqueEntries = allEntries.filter((ie) => {
@@ -187,7 +193,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const typeFilter = searchType === "any" ? undefined : searchType;
     const tEmbed0 = Date.now();
     const embeddingPromise = tryVecScores(db, query, limit * 3, config);
-    const ftsResults = searchFts(db, query, limit * 3, typeFilter);
+    const ftsResults = searchFts(db, query, limit * 3, typeFilter, defaultExcludes);
     const embeddingScores = await embeddingPromise;
     const embedMs = Date.now() - tEmbed0;
     const tRank0 = Date.now();
@@ -208,6 +214,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         embedScoreMap,
         getEntryById: (id) => getEntryById(db, id) ?? undefined,
         typeFilter,
+        // #627 — also exclude default-hidden types from the vector-only branch so a
+        // session asset that is a top-k vector neighbor (but not an FTS match) does
+        // not leak into default ('any') results. defaultExcludes is already []
+        // unless this is the untyped path without includeExcludedTypes.
+        excludeTypes: defaultExcludes,
     });
     // ── Scoring Phase ──────────────────────────────────────────────────────
     // Apply boosts as multiplicative factors (all boosts in a single phase

package/dist/indexer/search/ranking-contributors.js

@@ -9,6 +9,9 @@ const TYPE_BOOST = {
     agent: 0.3,
     script: 0.2,
     knowledge: 0.22,
+    // Facts are authoritative, durable declarations about the stash — rank them
+    // alongside knowledge so they surface reliably when relevant.
+    fact: 0.22,
     memory: -0.02,
 };
 const MAX_BOOST_SUM = 3.0;
@@ -206,6 +209,24 @@ const lessonStrengthContributor = {
         return Math.min(0.3, 0.06 * strength);
     },
 };
+/**
+ * Pinned-fact boost.
+ *
+ * Facts marked `pinned: true` form the small always-injected "core context"
+ * (see docs/design/fact-asset-type.md). The fact metadata contributor records
+ * a `pinned` search hint; here we give those facts a modest additive boost so
+ * the core outranks ordinary facts on otherwise-equal queries. Capped small so
+ * it cannot overpower an exact-name match.
+ */
+const pinnedFactRankingContributor = {
+    name: "pinned-fact-ranking",
+    appliesTo(item) {
+        return item.entry.type === "fact" && (item.entry.searchHints?.includes("pinned") ?? false);
+    },
+    adjust() {
+        return 0.15;
+    },
+};
 /**
  * Blend ratio for scoped vs. global utility signals.
  *
@@ -310,6 +331,7 @@ export const defaultRankingContributors = [
     graphRankingContributor,
     captureModeRankingContributor,
     lessonStrengthContributor,
+    pinnedFactRankingContributor,
     projectContextRankingContributor,
 ];
 export const defaultUtilityRankingContributors = [utilityRankingContributor];