akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/commands/reflect.js

@@ -19,16 +19,22 @@
  * a committed asset, and the `accept` flow is the bridge.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
 import { ConfigError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
 import { lintLessonContent } from "../core/lesson-lint";
+import { stripMarkdownFences } from "../core/markdown";
 import { createProposal } from "../core/proposals";
 import { lookup } from "../indexer/indexer";
-import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { runAgent, } from "../integrations/agent";
+import { resolveProcessAgentProfile } from "../integrations/agent/config";
 import { buildReflectPrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
+import { runAgentSdk } from "../integrations/agent/sdk-runner";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "./agent-support";
+import { deriveLessonRef } from "./distill";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -45,7 +51,7 @@ function readRecentFeedback(ref) {
         for (const event of result.events.slice(-limit)) {
             const md = (event.metadata ?? {});
             const signal = typeof md.signal === "string" ? md.signal : "?";
-            const note = typeof md.note === "string" ? md.note : typeof md.reason === "string" ? md.reason : "";
+            const note = typeof md.reason === "string" ? md.reason : typeof md.note === "string" ? md.note : "";
             const details = note ? `[${signal}] ${note}` : `[${signal}]`;
             lines.push(!ref && event.ref ? `${event.ref} ${details}` : details);
         }
@@ -68,27 +74,83 @@ function buildSchemaHints(type, content) {
     const report = lintLessonContent(content, "reflect");
     return report.findings.map((f) => `[${f.kind}] ${f.message}`);
 }
-function loadAgentConfigFromDisk() {
-    const config = loadConfig();
-    return parseAgentConfig(config.agent);
+function hasRelatedSkillSource(content, skillRef) {
+    const parsed = parseFrontmatter(content);
+    const sources = parsed.data.sources;
+    return Array.isArray(sources) && sources.some((source) => typeof source === "string" && source.trim() === skillRef);
 }
-function resolveProfile(options) {
-    if (options.agentProfile)
-        return options.agentProfile;
-    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-    return requireAgentProfile(agent, options.profile);
+async function readRelatedLessons(stash, ref, parsedRef) {
+    if (parsedRef.type !== "skill")
+        return [];
+    const related = new Map();
+    const derivedLessonRef = deriveLessonRef(ref);
+    const candidateRefs = new Set([derivedLessonRef]);
+    const derivedLessonPath = path.join(stash, "lessons", `${derivedLessonRef.slice("lesson:".length)}.md`);
+    if (fs.existsSync(derivedLessonPath)) {
+        related.set(derivedLessonRef, { ref: derivedLessonRef, content: fs.readFileSync(derivedLessonPath, "utf8") });
+    }
+    try {
+        const feedbackEvents = readEvents({ type: "distill_invoked", ref }).events;
+        for (const event of feedbackEvents) {
+            const lessonRef = typeof event.metadata?.lessonRef === "string" ? event.metadata.lessonRef : undefined;
+            if (lessonRef?.startsWith("lesson:"))
+                candidateRefs.add(lessonRef);
+        }
+    }
+    catch {
+        // Best effort only.
+    }
+    for (const candidateRef of candidateRefs) {
+        try {
+            const entry = await lookup(parseAssetRef(candidateRef));
+            if (!entry?.filePath || !fs.existsSync(entry.filePath))
+                continue;
+            const content = fs.readFileSync(entry.filePath, "utf8");
+            related.set(candidateRef, { ref: candidateRef, content });
+        }
+        catch {
+            // Index miss is non-fatal.
+        }
+    }
+    try {
+        const lessonsDir = path.join(stash, "lessons");
+        if (fs.existsSync(lessonsDir)) {
+            for (const fileName of fs.readdirSync(lessonsDir)) {
+                if (!fileName.endsWith(".md"))
+                    continue;
+                const content = fs.readFileSync(path.join(lessonsDir, fileName), "utf8");
+                if (!hasRelatedSkillSource(content, ref))
+                    continue;
+                const lessonName = fileName.slice(0, -3);
+                const lessonRef = `lesson:${lessonName}`;
+                if (!related.has(lessonRef)) {
+                    related.set(lessonRef, { ref: lessonRef, content });
+                }
+            }
+        }
+    }
+    catch {
+        // Best effort only.
+    }
+    return [...related.values()];
+}
+function fallbackPayloadFromRawContent(stdout, ref) {
+    if (!ref)
+        return undefined;
+    const trimmed = stripMarkdownFences(stdout).trim();
+    if (!trimmed)
+        return undefined;
+    if (!looksLikeAssetContent(trimmed))
+        return undefined;
+    return { ref, content: trimmed };
+}
+function looksLikeAssetContent(value) {
+    return value.startsWith("#") || value.startsWith("---");
 }
 function failureEnvelope(result, ref, fallbackReason = "non_zero_exit") {
-    const reason = result.reason ?? fallbackReason;
     return {
-        schemaVersion: 1,
-        ok: false,
-        reason,
-        error: result.error ?? `agent failure (${reason})`,
+        ...baseFailureFields(result, fallbackReason),
         ...(ref ? { ref } : {}),
-        exitCode: result.exitCode,
-        ...(result.stdout ? { stdout: result.stdout } : {}),
-        ...(result.stderr ? { stderr: result.stderr } : {}),
     };
 }
 export async function akmReflect(options = {}) {
@@ -120,9 +182,32 @@ export async function akmReflect(options = {}) {
     }
     // 3. Resolve agent profile. ConfigError surfaces as a thrown error so the
     // CLI dispatcher renders the standard envelope.
+    //
+    // When an explicit --profile flag is given, honour it directly (existing
+    // behaviour). Otherwise use resolveProcessAgentProfile so that per-process
+    // agent config (agent.processes["reflect"]) is picked up automatically.
     let profile;
+    let resolvedTimeoutMs = options.timeoutMs;
     try {
-        profile = resolveProfile(options);
+        if (options.agentProfile) {
+            // Test seam: injected profile bypasses all config.
+            profile = options.agentProfile;
+        }
+        else if (options.profile) {
+            // Explicit --profile flag wins over process config.
+            profile = resolveAgentProfile(options);
+        }
+        else {
+            // Use per-process config resolution (falls back to agent.default).
+            const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+            const processName = options.agentProcess ?? "reflect";
+            const resolved = resolveProcessAgentProfile(processName, agent);
+            profile = resolved.profile;
+            // Only apply process-resolved timeoutMs when caller didn't supply one.
+            if (resolvedTimeoutMs === undefined) {
+                resolvedTimeoutMs = resolved.timeoutMs;
+            }
+        }
     }
     catch (err) {
         if (err instanceof ConfigError || err instanceof UsageError)
@@ -130,8 +215,12 @@ export async function akmReflect(options = {}) {
         throw err;
     }
     // 4. Build the prompt.
+    // Keep reflect on the same captured JSON path the bench harness already
+    // uses successfully. The draft-file interactive path proved brittle with
+    // local opencode models and caused proposal generation failures.
     const feedback = readRecentFeedback(options.ref);
     const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
+    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(stash, options.ref, parsedRef) : [];
     const prompt = buildReflectPrompt({
         ...(options.ref ? { ref: options.ref } : {}),
         ...(parsedRef?.type ? { type: parsedRef.type } : {}),
@@ -139,36 +228,64 @@ export async function akmReflect(options = {}) {
         ...(assetContent !== undefined ? { assetContent } : {}),
         ...(feedback.length > 0 ? { feedback } : {}),
         ...(schemaHints.length > 0 ? { schemaHints } : {}),
+        ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
         ...(options.task ? { task: options.task } : {}),
+        ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
     });
-    // 5. Spawn the agent. Force captured stdio + JSON parse so we can extract
-    // the structured payload without confusing terminal control codes.
-    const runOptions = {
-        stdio: "captured",
-        parseOutput: "text",
-        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-        ...(options.runAgentOptions ?? {}),
-    };
-    const result = await runAgent(profile, prompt, runOptions);
+    // 5. Spawn the agent.
+    // Fall back to raw runAgent when a custom spawn function is injected (test seam).
+    // Production path dispatches directly to runAgentSdk or runAgent.
+    let result;
+    if (options.runAgentOptions?.spawn) {
+        // Test seam: use raw runAgent with injected spawn so tests remain deterministic.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+            ...(options.runAgentOptions ?? {}),
+        };
+        result = await runAgent(profile, prompt, runOptions);
+    }
+    else {
+        // Production path: dispatch directly to the appropriate runner.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+        };
+        result = profile.sdkMode
+            ? await runAgentSdk(profile, prompt ?? "", runOptions)
+            : await runAgent(profile, prompt, runOptions);
+    }
     if (!result.ok) {
+        // B3: ENOENT / not-found gives an actionable hint.
+        if (isEnoentFailure(result)) {
+            return { ...failureEnvelope(result, options.ref), error: enoentHintMessage(profile.bin) };
+        }
         return failureEnvelope(result, options.ref);
     }
-    // 6. Parse stdout into a proposal payload.
+    // 6. Resolve the proposal content from stdout JSON.
     let payload;
     try {
-        payload = parseAgentProposalPayload(result.stdout);
+        payload = parseAgentProposalPayload(result.stdout ?? "");
     }
     catch (err) {
-        return {
-            schemaVersion: 1,
-            ok: false,
-            reason: "parse_error",
-            error: err instanceof Error ? err.message : String(err),
-            ...(options.ref ? { ref: options.ref } : {}),
-            exitCode: result.exitCode,
-            stdout: result.stdout,
-            ...(result.stderr ? { stderr: result.stderr } : {}),
-        };
+        const fallback = fallbackPayloadFromRawContent(result.stdout ?? "", options.ref);
+        if (fallback) {
+            payload = fallback;
+        }
+        else {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: err instanceof Error ? err.message : String(err),
+                ...(options.ref ? { ref: options.ref } : {}),
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
     }
     // 7. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.
@@ -182,6 +299,15 @@ export async function akmReflect(options = {}) {
         },
     };
     const proposal = createProposal(stash, createInput, options.ctx);
+    appendEvent({
+        eventType: "reflect_completed",
+        ref: proposal.ref,
+        metadata: {
+            proposalId: proposal.id,
+            source: "reflect",
+            agentProfile: profile.name,
+        },
+    });
     return {
         schemaVersion: 1,
         ok: true,

package/dist/commands/registry-search.js

@@ -1,5 +1,5 @@
 import { toErrorMessage } from "../core/common";
-import { DEFAULT_CONFIG, loadConfig } from "../core/config";
+import { DEFAULT_CONFIG } from "../core/config";
 import { warn } from "../core/warn";
 import { resolveProviderFactory } from "../registry/factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
@@ -133,7 +133,7 @@ export function resolveRegistries(configRegistries) {
         }
         return entries;
     }
-    const registries = configRegistries ?? loadConfig().registries ?? DEFAULT_CONFIG.registries ?? [];
+    const registries = configRegistries ?? DEFAULT_CONFIG.registries ?? [];
     return registries.filter((r) => r.enabled !== false);
 }
 // ── Provider resolution ─────────────────────────────────────────────────────

package/dist/commands/remember.js

@@ -11,6 +11,7 @@ import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { SCOPE_KEYS } from "../indexer/metadata";
+import { parseFlagValue } from "../output/context";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
  * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
@@ -138,7 +139,7 @@ export async function runLlmEnrich(body) {
         return { tags: [] };
     }
     const llmConfig = config.llm;
-    const { chatCompletion, parseJsonResponse } = await import("../llm/client");
+    const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:
 - "tags": array of 1-5 short lowercase keyword tags
@@ -188,3 +189,56 @@ Return ONLY the JSON object, no prose, no markdown fences.`;
         return { tags: [] };
     }
 }
+// ── Content-arg disambiguation ───────────────────────────────────────────────
+/**
+ * Guard against citty consuming a global flag value as the `content` positional.
+ *
+ * When the user runs `akm remember --format json` without a content argument,
+ * citty may assign `"json"` to the `content` positional because of how it
+ * handles flag order. This helper detects that case and returns `undefined`
+ * so `readMemoryContent` falls through to stdin.
+ */
+export function resolveRememberContentArg(content) {
+    if (content === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined &&
+        content === parsedFormat &&
+        wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined &&
+        content === parsedDetail &&
+        wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return content;
+}
+function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
+    const argv = process.argv.slice(2);
+    const rememberIndex = argv.indexOf("remember");
+    const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
+    let flagIndex = -1;
+    let flagConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === flagName) {
+            flagIndex = i;
+            flagConsumesNextToken = true;
+            break;
+        }
+        if (token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (tokens.slice(0, flagIndex).includes(content))
+        return false;
+    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? 2 : 1);
+    if (tokens.slice(firstTokenAfterFlag).includes(content))
+        return false;
+    return true;
+}

package/dist/commands/schema-repair.js

@@ -0,0 +1,130 @@
+/**
+ * Schema-repair pass for `akm improve`.
+ *
+ * Attempts to patch missing frontmatter fields (`description`, `when_to_use`)
+ * on assets that failed schema validation, using a single bounded in-tree LLM
+ * call per asset. Results are recorded as `schema_repair_invoked` events.
+ *
+ * This module is extracted from `improve.ts` to make the repair logic
+ * independently testable and to use the `tryLlmFeature` seam rather than raw
+ * `chatCompletion`.
+ */
+import fs from "node:fs";
+import { stringify as yamlStringify } from "yaml";
+import { parseAssetRef } from "../core/asset-ref";
+import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
+import { info } from "../core/warn";
+import { resolveAssetPath } from "../indexer/path-resolver";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Minimum gap between schema-repair attempts on the same asset. */
+const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Run the schema-repair loop for a batch of validation failures.
+ * Returns a list of per-asset outcome records and the set of refs that were
+ * successfully repaired (so the caller can exclude them from skip logic).
+ */
+export async function runSchemaRepairPass(failures, options) {
+    const repairs = [];
+    const repairedRefs = new Set();
+    const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, } = options;
+    for (const failure of failures) {
+        if (Date.now() - startMs >= budgetMs)
+            break;
+        // Cooldown: skip repair if we ran it successfully recently.
+        const recentRepairs = readEvents({ type: "schema_repair_invoked", ref: failure.ref });
+        const lastRepair = recentRepairs.events
+            .filter((e) => e.metadata?.outcome === "written")
+            .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
+        if (lastRepair?.ts && Date.now() - new Date(lastRepair.ts).getTime() < SCHEMA_REPAIR_COOLDOWN_MS) {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        const filePath = await findFilePath(failure.ref, stashDir);
+        if (!filePath) {
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+            continue;
+        }
+        try {
+            const raw = fs.readFileSync(filePath, "utf8");
+            const fm = parseFrontmatter(raw);
+            const missingFields = [];
+            if (!fm.data.description)
+                missingFields.push("description");
+            if (isLessonCandidateFn(failure.ref) && !fm.data.when_to_use)
+                missingFields.push("when_to_use");
+            if (missingFields.length === 0) {
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                continue;
+            }
+            const fieldList = missingFields.join(" and ");
+            info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
+            const bodyPreview = (fm.content ?? raw).slice(0, 2000);
+            const llmResponse = await chatCompletion(llmConfig, [
+                {
+                    role: "system",
+                    content: `You generate concise asset frontmatter fields. Respond with a JSON object containing only the missing fields. No prose, no markdown fences.`,
+                },
+                {
+                    role: "user",
+                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${parseAssetRef(failure.ref).type} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}\n\n${bodyPreview}`,
+                },
+            ]);
+            const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
+            if (!parsed) {
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "error",
+                    error: "LLM returned unparseable JSON for schema repair",
+                });
+                continue;
+            }
+            const newFm = { ...fm.data };
+            if (parsed.description)
+                newFm.description = parsed.description;
+            if (parsed.when_to_use)
+                newFm.when_to_use = parsed.when_to_use;
+            const fmStr = yamlStringify(newFm).trimEnd();
+            const newContent = `---\n${fmStr}\n---\n${fm.content}`;
+            fs.writeFileSync(filePath, newContent, "utf8");
+            info(`[improve] schema-repair written: ${failure.ref}`);
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: { outcome: "written", reason: failure.reason },
+            });
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "written" });
+            repairedRefs.add(failure.ref);
+        }
+        catch (e) {
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: { outcome: "error", reason: failure.reason, error: String(e) },
+            });
+            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "error", error: String(e) });
+        }
+    }
+    return { repairs, repairedRefs };
+}
+// ── Default seam implementations ─────────────────────────────────────────────
+function defaultIsLessonCandidate(ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        return parsed.type === "lesson";
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultFindFilePath(ref, stashDir) {
+    return resolveAssetPath(ref, {
+        stashDir,
+        mode: "index-first",
+        directoryIndexNames: ["SKILL.md", "index.md", "README.md"],
+        preserveDirectNameFallback: true,
+    });
+}

package/dist/commands/search.js

@@ -11,7 +11,7 @@
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
+import { bumpUtilityScoresBatch, closeDatabase, openExistingDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
 // Eagerly import source providers to trigger self-registration before the
@@ -48,6 +48,7 @@ export async function akmSearch(input) {
     const stashDir = sources[0].path;
     const filters = normalizeScopeFilters(input.filters);
     const includeProposed = input.includeProposed === true;
+    const belief = input.belief ?? "all";
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -59,6 +60,7 @@ export async function akmSearch(input) {
             config,
             filters,
             includeProposed,
+            beliefFilter: belief,
         });
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {
@@ -73,7 +75,7 @@ export async function akmSearch(input) {
             warnings: localResult?.warnings?.length ? localResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
-        logSearchEvent(query, response);
+        logSearchEvent(query, response, undefined, localResult?.mode ?? "keyword");
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
@@ -124,7 +126,7 @@ export async function akmSearch(input) {
         warnings: warnings.length ? warnings : undefined,
         timing: { totalMs: Date.now() - t0 },
     };
-    logSearchEvent(query, response);
+    logSearchEvent(query, response, undefined, localResult?.mode ?? "keyword");
     return response;
 }
 /**
@@ -160,13 +162,13 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, existingDb) {
+function logSearchEvent(query, response, existingDb, mode = "keyword") {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
     appendEvent({
         eventType: "search",
-        metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
+        metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref), mode },
     });
     try {
         const db = existingDb ?? openExistingDatabase();
@@ -180,6 +182,12 @@ function logSearchEvent(query, response, existingDb) {
                     entry_ref: ref,
                 });
             }
+            // Bump utility scores for all resolved entries (MemRL retrieval signal).
+            // The indexer overwrites these at next reindex; bumps are temporary hints.
+            const resolvedIds = resolved.map((r) => r.entryId).filter((id) => id !== undefined);
+            if (resolvedIds.length > 0) {
+                bumpUtilityScoresBatch(db, resolvedIds, 1.0);
+            }
             // Count registry hits separately so registry-only searches record a
             // non-zero resultCount. response.hits is always [] when source="registry".
             const stashHitCount = response.hits.length;
@@ -192,6 +200,7 @@ function logSearchEvent(query, response, existingDb) {
                     stashHitCount,
                     registryHitCount,
                     resolvedCount: resolved.length,
+                    mode,
                 }),
             });
         }
@@ -221,6 +230,13 @@ export function parseSearchSource(source) {
         return "stash";
     throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`, "INVALID_SOURCE_VALUE");
 }
+export function parseBeliefFilterMode(value) {
+    if (value === undefined || value === "all")
+        return "all";
+    if (value === "current" || value === "historical")
+        return value;
+    throw new UsageError(`Invalid value for --belief: ${String(value)}. Expected one of: all|current|historical`, "INVALID_FLAG_VALUE");
+}
 /**
  * Strip empty / non-string values from a scope filter object. Returns
  * `undefined` when nothing meaningful remains, so callers don't pay for an