akm-cli 0.10.261008-beta → 0.10.261010-beta

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

@@ -64,6 +64,12 @@ const FM_INFERRED = "inferred";
 const FM_INFERENCE_PROCESSED = "inferenceProcessed";
 const FM_SOURCE = "source";
 const FM_CAPTURE_MODE = "captureMode";
+/**
+ * Cache namespace for this pass. Bump it when the cached response semantics
+ * change (v3: a cached row may be an explicit no-change decision); rows under an
+ * older namespace are never read again, which is a disposable cache miss.
+ */
+const MEMORY_INFERENCE_CACHE_VARIANT = "memory-inference-v3";
 function validateDerivedMemoryDraft(raw) {
     if (!raw || typeof raw !== "object")
         return undefined;
@@ -79,6 +85,10 @@ function validateDerivedMemoryDraft(raw) {
         ? { title, description, tags, searchHints, content }
         : undefined;
 }
+/** Cache validator: a recognised no-change decision, a complete draft, or `undefined` (unusable → recompute). */
+function validateMemoryInferDecision(raw) {
+    return memoryInfer.isMemoryInferNoChange(raw) ? memoryInfer.MEMORY_INFER_NO_CHANGE : validateDerivedMemoryDraft(raw);
+}
 function planPendingMemoryRecord(record, ctx) {
     if (ctx.signal?.aborted)
         return { kind: "aborted", record };
@@ -86,11 +96,11 @@ function planPendingMemoryRecord(record, ctx) {
         return { kind: "existing-child", record };
     if (ctx.db && !ctx.reEnrich) {
         const cached = bestEffort(() => {
-            const entry = getLlmCacheEntry(ctx.db, record.filePath, computeBodyHash(record.body), "memory-inference-v2");
-            return entry ? validateDerivedMemoryDraft(JSON.parse(entry.resultJson)) : undefined;
+            const entry = getLlmCacheEntry(ctx.db, record.filePath, computeBodyHash(record.body), MEMORY_INFERENCE_CACHE_VARIANT);
+            return entry ? validateMemoryInferDecision(JSON.parse(entry.resultJson)) : undefined;
         }, "memory inference cache read corrupt — fall through to recompute");
         if (cached)
-            return { kind: "cache-hit", record, derived: cached };
+            return { kind: "cache-hit", record, decision: cached };
     }
     return { kind: "model", record };
 }
@@ -132,11 +142,11 @@ async function inferPendingMemoryRecord(plan, ctx) {
         retryAttempts += 1;
     };
     const infer = () => compressMemoryToDerivedMemory(llmRunner, record.body, signal, featureConfig, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices);
-    let derived = plan.kind === "cache-hit" ? plan.derived : undefined;
+    let derived = plan.kind === "cache-hit" ? plan.decision : undefined;
     try {
         if (plan.kind === "model") {
             derived = db
-                ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, infer, validateDerivedMemoryDraft, undefined, "memory-inference-v2", {
+                ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, infer, validateMemoryInferDecision, undefined, MEMORY_INFERENCE_CACHE_VARIANT, {
                     onCacheHit: () => {
                         fromCache = true;
                     },
@@ -153,6 +163,12 @@ async function inferPendingMemoryRecord(plan, ctx) {
     }
     if (!derived)
         return { skipped: true, fromCache, retryAttempts };
+    // An explicit decision, not a failure. The parent is left exactly as it is: stamping it
+    // `inferenceProcessed` would hide every later edit, and the cached decision already
+    // stops the retry for as long as the effective input is unchanged.
+    if (memoryInfer.isMemoryInferNoChange(derived)) {
+        return { skipped: false, splitParent: false, written: 0, noChange: true, fromCache, retryAttempts };
+    }
     const writeOutcome = await writeDerivedMemory(record, derived);
     if (writeOutcome.written > 0) {
         markParentProcessed(record);
@@ -209,6 +225,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
         retryAttempts: 0,
         splitParents: 0,
         writtenFacts: 0,
+        noChange: 0,
         skippedNoFacts: 0,
         skippedChildExists: 0,
         skippedAborted: 0,
@@ -273,7 +290,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
         assertRunnerCredentials(llmRunner);
     let processed = 0;
     const total = pending.length;
-    onProgress?.({ processed, total, writtenFacts: 0, skippedNoFacts: 0 });
+    onProgress?.({ processed, total, writtenFacts: 0, noChange: 0, skippedNoFacts: 0 });
     let configFailure;
     const perRecordResults = await concurrentMap(plans, (plan) => inferPendingMemoryRecord(plan, {
         config,
@@ -305,6 +322,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
                 processed,
                 total,
                 writtenFacts: result.writtenFacts,
+                noChange: result.noChange,
                 skippedNoFacts: result.skippedNoFacts,
                 currentRef: pending[i]?.ref,
             });
@@ -321,6 +339,9 @@ async function runMemoryInferencePassBody(ctx, provenance) {
             // Intentionally NOT marked processed — a transient LLM failure should
             // be retried on the next index run.
         }
+        else if ("noChange" in res && res.noChange) {
+            result.noChange += 1;
+        }
         else if (res.splitParent) {
             result.splitParents += 1;
             result.writtenFacts += res.written;
@@ -349,6 +370,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
             processed,
             total,
             writtenFacts: result.writtenFacts,
+            noChange: result.noChange,
             skippedNoFacts: result.skippedNoFacts,
             currentRef: pending[i]?.ref,
         });

package/dist/indexer/passes/metadata.js

@@ -165,6 +165,8 @@ export function validateStashEntry(entry) {
     const evidenceSources = normalizeNonEmptyStringList(e.evidenceSources);
     if (evidenceSources)
         result.evidenceSources = evidenceSources;
+    if (typeof e.evidence === "string" && e.evidence.trim().length > 0)
+        result.evidence = e.evidence;
     if (typeof e.derivedFrom === "string" && e.derivedFrom.trim().length > 0) {
         result.derivedFrom = e.derivedFrom.trim();
     }
@@ -242,6 +244,19 @@ export function applyScopeFrontmatter(entry, fmData) {
     if (scope)
         entry.scope = scope;
 }
+/** The same normalized tuple the index projects, including legacy nested scope. */
+export function scopeFromFrontmatter(fm) {
+    const entry = { type: "memory", name: "scope" };
+    if (typeof fm.scope === "object" && fm.scope !== null && !Array.isArray(fm.scope)) {
+        entry.scope = normalizeScopeObject(fm.scope);
+    }
+    applyScopeFrontmatter(entry, fm);
+    return entry.scope ?? {};
+}
+/** Exact maintenance equality: absence is a value, never a wildcard. */
+export function sameScope(a, b) {
+    return SCOPE_KEYS.every((key) => a[key] === b[key]);
+}
 function normalizeIntent(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -367,6 +382,8 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const evidenceSources = normalizeNonEmptyStringList(fmData.evidenceSources);
     if (evidenceSources)
         entry.evidenceSources = evidenceSources;
+    if (typeof fmData.evidence === "string" && fmData.evidence.trim().length > 0)
+        entry.evidence = fmData.evidence;
     // Phase 5A / Advantage D5: capture parent ref for derived memories.
     // Memory-inference writes `source: "memories/<parent>"` and `inferred: true`
     // (and a derived child name suffix `.derived`). We mirror that source ref into

package/dist/indexer/scan/doc-to-entry.js

@@ -138,6 +138,7 @@ export function indexDocumentToStashEntry(doc) {
         entry.wikiRole = dj.wikiRole;
     assignStringList(entry, "sources", dj.sources);
     assignStringList(entry, "evidenceSources", dj.evidenceSources);
+    assignString(entry, "evidence", dj.evidence);
     assignStringList(entry, "uses", dj.uses);
     // D2 (#730): OKF v0.2 provenance promoteProposal stamps onto AKM-native
     // writes, carried via DOCUMENT_JSON_CARRIED_FIELDS (akm-adapter.ts) —

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

@@ -22,7 +22,7 @@ import { embed } from "../../llm/embedder.js";
 import { applyEmbeddingTemplate, resolveEmbeddingProfile } from "../../llm/embedders/profile.js";
 import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
-import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getEntryRefsAndTypes, } from "../../storage/repositories/index-entries-repository.js";
+import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntriesByIds, getEntryById, getEntryCount, getEntryRefsAndTypes, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { getEmbeddingCount, searchVec } from "../../storage/repositories/index-vec-repository.js";
@@ -221,8 +221,14 @@ async function searchDatabase(db, input) {
     const typeFilter = searchType === "any" ? undefined : searchType;
     const startedAt = Date.now();
     // The query embedding request goes out first, so FTS runs while it is in flight.
-    const vectorChannel = startVectorChannel(db, query, config);
-    const lexical = searchFts(db, query, CHANNEL_DEPTH, typeFilter, defaultExcludes);
+    const filterCandidates = (ids) => {
+        const entries = getEntriesByIds(db, ids)
+            .filter(hasIndexedProvenance)
+            .filter((row) => (typeFilter ? row.entry.type === typeFilter : !defaultExcludes.includes(row.entry.type)));
+        return new Set(applyEntryFilters(entries, filterOptions).map((row) => row.id));
+    };
+    const vectorChannel = startVectorChannel(db, query, config, filterCandidates);
+    const lexical = searchFts(db, query, CHANNEL_DEPTH, typeFilter, defaultExcludes, filterCandidates);
     const vector = await vectorChannel;
     const embedMs = Date.now() - startedAt;
     const tRank0 = Date.now();
@@ -244,6 +250,7 @@ async function searchDatabase(db, input) {
         sources,
         config,
         db,
+        eligible: (row) => applyEntryFilters([row], filterOptions).length > 0,
     })));
     const mode = vector.warning ? "fts-fallback" : vector.neighbors ? "semantic" : "keyword";
     return { embedMs, rankMs, hits, mode, semanticWarning: vector.warning, feedbackWarning: feedback.warning };
@@ -371,6 +378,7 @@ async function enumerateEntries(opts) {
         sources,
         config,
         db,
+        eligible: (row) => applyEntryFilters([row], opts).length > 0,
     })));
 }
 /**
@@ -378,7 +386,7 @@ async function enumerateEntries(opts) {
  * source-narrowing → scope → proposed-quality → derived-twin belief
  * inheritance → belief filter.
  */
-function applyEntryFilters(items, opts) {
+export function applyEntryFilters(items, opts) {
     const { filters } = opts;
     // Source filter: when the caller narrowed `sources` via `--from <name>`,
     // drop entries whose filePath does not live under any requested source. The
@@ -428,7 +436,7 @@ function inheritDerivedTwinBeliefStates(db, items) {
         }
     }
 }
-function matchBeliefFilter(beliefState, filter) {
+export function matchBeliefFilter(beliefState, filter) {
     if (filter === "all")
         return true;
     // 03: the belief filter applies to ANY flagged entry, not just memories, so
@@ -452,7 +460,7 @@ function matchBeliefFilter(beliefState, filter) {
  * query overlaps it. A slow or failing embedder degrades the search to keyword
  * ranking with a warning after `embedding.queryTimeoutMs`.
  */
-function startVectorChannel(db, query, config) {
+function startVectorChannel(db, query, config, filterCandidates) {
     if (config.semanticSearchMode === "off")
         return Promise.resolve({ neighbors: null });
     // A real-time completeness fact, not a cached verdict: skip the round trip
@@ -472,7 +480,7 @@ function startVectorChannel(db, query, config) {
     });
     const queryText = applyEmbeddingTemplate(resolveEmbeddingProfile(config.embedding).queryTemplate, query);
     return Promise.race([embed(queryText, config.embedding, controller.signal), timeout])
-        .then((vector) => ({ neighbors: searchVec(db, vector, CHANNEL_DEPTH) }))
+        .then((vector) => ({ neighbors: searchVec(db, vector, CHANNEL_DEPTH, undefined, filterCandidates) }))
         .catch((error) => ({ neighbors: null, warning: buildVectorFallbackWarning(config, error) }))
         .finally(() => clearTimeout(timer));
 }
@@ -574,6 +582,7 @@ export async function buildDbHit(input) {
         stashDir: entryStashDir,
         bundleId: input.bundleId,
         db: input.db,
+        eligible: input.eligible,
     });
     return hit;
 }

package/dist/indexer/search/search-hit-enrichers.js

@@ -17,7 +17,7 @@ export async function enrichSearchHit(hit, ctx) {
         renderer?.enrichSearchHit?.(hit, ctx.stashDir);
     }
     if (ctx.type === "memory" && ctx.db)
-        surfaceDerivedMemory(hit, ctx.db, ctx.bundleId);
+        surfaceDerivedMemory(hit, ctx.db, ctx.bundleId, ctx.eligible);
 }
 /**
  * Phase 5A / Advantage D5 — when a parent memory has a `.derived` child
@@ -28,7 +28,7 @@ export async function enrichSearchHit(hit, ctx) {
  * The parent ref is preserved on the hit — only the surface text is
  * swapped, so links and provenance still point at the canonical parent.
  */
-function surfaceDerivedMemory(hit, db, bundleId) {
+function surfaceDerivedMemory(hit, db, bundleId, eligible) {
     // Never recurse: a `.derived` hit is itself the child surface; leaving
     // it untouched also avoids `<parent>.derived.derived` chains.
     if (hit.name.toLowerCase().endsWith(".derived"))
@@ -38,7 +38,7 @@ function surfaceDerivedMemory(hit, db, bundleId) {
     // carries. INTERNAL lookup key into `getDerivedForParent`: the `derived_from`
     // column stores this same conceptId grammar.
     const derived = getDerivedForParent(db, `memories/${hit.name}`, bundleId);
-    if (!derived)
+    if (!derived || (eligible && !eligible(derived)))
         return;
     // Swap description / tags from the derived child (SourceSearchHit carries no
     // `searchHints`).

package/dist/llm/memory-infer.js

@@ -34,35 +34,40 @@ const PROMPT_PLACEHOLDERS = new Set([
     "search phrase 2",
     "2-3 sentence compressed body preserving key facts verbatim",
 ]);
+export const MEMORY_INFER_NO_CHANGE = Object.freeze({ noChange: true });
+export function isMemoryInferNoChange(value) {
+    return typeof value === "object" && value !== null && value.noChange === true;
+}
 /**
  * Strict JSON Schema for the derived-memory payload. Sent as `response_format`
  * unless the engine sets `supportsJsonSchema: false`; the client drops it once
  * for a provider that rejects it.
  *
- * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
- * the memory-inference path. Mirrors the validation gate below
- * (title/description/content + non-empty tags/searchHints) so a
- * schema-compliant response is guaranteed to pass the downstream check
- * — no more "incomplete derived memory payload from LLM; skipping memory"
- * for shape-only failures.
+ * Every property is required (a strict provider refuses otherwise), so the
+ * explicit no-change decision is `noChange: true` with the other fields empty.
+ * That also means the schema cannot demand non-empty fields: the parser below
+ * is the gate that requires a complete payload whenever `noChange` is false.
  */
 export const DERIVED_MEMORY_JSON_SCHEMA = {
     type: "object",
     properties: {
-        title: { type: "string", minLength: 1 },
-        description: { type: "string", minLength: 1 },
-        content: { type: "string", minLength: 1 },
-        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
-        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+        noChange: { type: "boolean" },
+        title: { type: "string" },
+        description: { type: "string" },
+        content: { type: "string" },
+        tags: { type: "array", items: { type: "string" }, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, maxItems: 6 },
     },
-    required: ["title", "description", "content", "tags", "searchHints"],
+    required: ["noChange", "title", "description", "content", "tags", "searchHints"],
     additionalProperties: false,
 };
 /**
  * Compress a single memory body into one derived memory via the configured LLM.
  *
- * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
- * Errors are logged via `warn()` but never thrown — a failed split for one memory
+ * Returns the draft, or {@link MEMORY_INFER_NO_CHANGE} when the model explicitly
+ * decides the memory needs no derived memory. Returns `undefined` on any failure
+ * (timeout, invalid JSON, empty or incomplete response, HTML, abort, disabled
+ * pass), which is never the same thing as no-change. Errors are logged via `warn()` but never thrown — a failed split for one memory
  * must not abort the rest of the index pass.
  *
  * Routes through `callStructured({ feature: "memory_inference", ... })` so the
@@ -105,6 +110,10 @@ export async function compressMemoryToDerivedMemory(llmRunner, body, signal, akm
                 warn("memory inference: invalid JSON response from LLM; skipping memory.");
                 return undefined;
             }
+            // Only a literal boolean `true` is a decision; anything else falls through
+            // to the complete-payload checks, so a malformed reply is never restraint.
+            if (parsed.noChange === true)
+                return MEMORY_INFER_NO_CHANGE;
             const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
             const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
             const content = typeof parsed.content === "string" ? parsed.content.trim() : "";

package/dist/output/shapes/curate.js

@@ -5,7 +5,7 @@ import { capDescription, NORMAL_DESCRIPTION_LIMIT, pickFields } from "./helpers.
 // Curation is a small, high-signal top-N. Even at `brief` we keep `followUp`
 // (the actionable `akm show <ref>` command) and `reason` (why this asset was
 // selected) — these are the point of curate, unlike a bulk search listing.
-const BRIEF_FIELDS = ["source", "type", "name", "ref", "id", "supportRefs", "followUp", "reason"];
+const BRIEF_FIELDS = ["source", "type", "name", "ref", "id", "supportRefs", "beliefState", "followUp", "reason"];
 const NORMAL_FIELDS = [
     "source",
     "type",
@@ -21,6 +21,7 @@ const NORMAL_FIELDS = [
     "parameters",
     "run",
     "supportRefs",
+    "beliefState",
     "followUp",
     "reason",
     "score",
@@ -37,6 +38,7 @@ const AGENT_FIELDS = [
     "id",
     "description",
     "supportRefs",
+    "beliefState",
     "followUp",
     "reason",
     "score",

package/dist/output/shapes/helpers.js

@@ -386,6 +386,9 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "steps",
             "keys",
             "links",
+            "evidence",
+            "evidenceSources",
+            "provenance",
             ...FRAGMENT_PROVENANCE_FIELDS,
             ...FRAGMENT_CONTEXT_FIELDS,
         ]);
@@ -418,6 +421,9 @@ export function shapeShowOutput(result, detail, shape = "human") {
         "activeRun",
         "keys",
         "links",
+        "evidence",
+        "evidenceSources",
+        "provenance",
         ...FRAGMENT_PROVENANCE_FIELDS,
         ...FRAGMENT_CONTEXT_FIELDS,
         // ref, path, and editable are always projected — at every --detail level,

package/dist/output/text/show-format.js

@@ -20,6 +20,13 @@ export function formatShowPlain(r, detail) {
     }
     if (r.description)
         lines.push(`description: ${String(r.description)}`);
+    // Evidence is captured text: keep it on one line so it cannot forge other fields.
+    if (r.evidence)
+        lines.push(`evidence: ${String(r.evidence).replace(/\s+/g, " ")}`);
+    if (Array.isArray(r.evidenceSources))
+        lines.push(`evidenceSources: ${r.evidenceSources.join(", ")}`);
+    if (r.evidence && r.provenance)
+        lines.push(`provenance: ${JSON.stringify(r.provenance)}`);
     if (r.workflowTitle)
         lines.push(`workflowTitle: ${String(r.workflowTitle)}`);
     if (r.agent)