akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/indexer/search/fts-query.js

@@ -1,50 +1,39 @@
 // 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/.
-const UNICODE_TOKEN = /[\p{L}\p{N}]+/gu;
-function quoteToken(token) {
-    return `"${token}"`;
-}
-function prefixToken(token) {
-    return [...token].length >= 3 ? `${quoteToken(token)}*` : quoteToken(token);
-}
 /**
- * Build the sole lexical retrieval plan from raw user input.
+ * Pure FTS5 query building and ref-query helpers.
  *
- * Tokenization follows the useful portion of SQLite FTS5's `unicode61`
- * tokenizer (Unicode letters and numbers). Quoting every term makes FTS
- * operators ordinary searchable words. Tokens are normalized and deduplicated
- * case-insensitively.
- *
- * There is deliberately NO cap on token count. `MAX_LEXICAL_QUERY_TOKENS = 16`
- * used to truncate here, silently: a query past 16 unique tokens searched only
- * its first 16, dropping the tail — which for natural-language input is
- * usually where the discriminating words are. It was unexplained in both the
- * code and the commit that introduced it, unreachable from any flag, config
- * key, or env var, and the user was never told their query had been altered.
- * A wrong answer delivered silently is worse than a slow one.
+ * The lexical channel matches ANY query word: BM25 over an OR of the query's
+ * non-stopword tokens. Requiring every word first and relaxing only when that
+ * found nothing cost 0.108 nDCG@10 on the retrieval suite
+ * (`akm/eval/retrieval/reports/baseline-2026-09-27.md`): one conjunctive match
+ * in a long document suppressed every better OR candidate.
+ * `parseRefPrefixQuery` is the one non-FTS helper: it decides whether a raw
+ * query should bypass FTS entirely (SPEC-4 ref-prefix enumeration).
  */
-export function buildLexicalQueryPlan(query) {
-    const tokens = [];
-    const seen = new Set();
-    const normalized = query.normalize("NFKC");
-    for (const match of normalized.matchAll(UNICODE_TOKEN)) {
-        const token = match[0];
-        const key = token.toLowerCase();
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        tokens.push(token);
-    }
-    const exact = tokens.map(quoteToken).join(" ");
-    const prefixTokens = tokens.map(prefixToken);
-    const exactPrefix = prefixTokens.some((token) => token.endsWith("*")) ? prefixTokens.join(" ") : undefined;
-    // A slash-bearing, whitespace-free input is an identifier/ref lookup, not
-    // sentence prose. Keep it conjunctive so a mistyped/bare ref never fans out
-    // across every path token through OR recovery.
-    const isRefLikeIdentifier = !/\s/u.test(query.trim()) && query.includes("/");
-    const relaxed = tokens.length > 1 && !isRefLikeIdentifier ? prefixTokens.join(" OR ") : undefined;
-    return { tokens, exact, exactPrefix, relaxed };
+/** English function words dropped from the lexical query (the retrieval lab's list). */
+const STOPWORDS = new Set(`a about above after again against all am an and any are as at be because been before being below between both but
+  by can could did do does doing down during each few for from further had has have having he her here hers herself
+  him himself his how i if in into is it its itself just me more most my myself no nor not now of off on once only or
+  other our ours out over own same she should so some such than that the their theirs them then there these they this
+  those through to too under until up very was we were what when where which while who whom why will with would you
+  your yours yourself`.split(/\s+/));
+const UNICODE_TOKEN = /[\p{L}\p{N}]+/gu;
+/**
+ * The query's lexical tokens: Unicode letters and numbers (the useful part of
+ * FTS5's `unicode61` tokenizer), NFKC-normalized, lowercased and deduplicated,
+ * with stopwords removed. A query made only of stopwords keeps all of them, so
+ * "how to" still searches for something.
+ */
+export function ftsQueryTokens(query) {
+    const tokens = [...new Set(query.normalize("NFKC").toLowerCase().match(UNICODE_TOKEN) ?? [])];
+    const content = tokens.filter((token) => !STOPWORDS.has(token));
+    return content.length > 0 ? content : tokens;
+}
+/** FTS5 MATCH expression matching any token. Quoting makes FTS operators ordinary words. */
+export function ftsOrMatch(tokens) {
+    return tokens.map((token) => `"${token}"`).join(" OR ");
 }
 /**
  * D4 — parse a conceptId-prefix browse query.

package/dist/indexer/search/ranking.js

@@ -1,163 +1,37 @@
 // 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/.
-import { stableFtsScore } from "../../core/lexical-score.js";
-import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
-import { buildLexicalQueryPlan } from "./fts-query.js";
-import { lexicalNameTokens, structuralNameTokenMatch } from "./name-match.js";
-import { applyBeliefStateScoreCeiling, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
 /**
- * Lower bounds keep a lexical hit competitive with a vector-only neighbour;
- * the upper bound deliberately leaves room for the ranking contributors that
- * run after retrieval (notably the bounded graph boost).  This is a
- * calibration for the one search pipeline, not a claim that BM25 is
- * comparable across different queries or FTS tables.
- */
-/**
- * Convert FTS5's negative BM25 value into the lexical contribution used by
- * this pipeline.  The transform is fixed and monotone: it depends only on a
- * row's own BM25 value, so appending weaker candidates cannot rewrite an
- * existing row's score. FTS5 commonly emits relevance near 1e-6 for broad
- * queries, so first put relevance on a log scale around that observed value.
- * The shape constant intentionally makes the curve approach its ceiling
- * slowly: rare-term scores retain separation instead of all reading as 0.8.
+ * Reciprocal rank fusion (Cormack, Clarke and Büttcher, SIGIR 2009) of the
+ * lexical and vector candidate lists — the whole of search ranking.
  *
- * FTS5 produces finite non-positive values in normal operation.  Keeping the
- * defensive cases here finite makes this boundary safe if a driver or fixture
- * hands us an invalid value: `-Infinity` is the strongest possible match,
- * while NaN, +Infinity, and positive scores contribute no lexical evidence.
- */
-export function normalizeFtsScores(results) {
-    const ftsScoreMap = new Map();
-    for (const result of results) {
-        ftsScoreMap.set(result.id, { score: result.lexicalScore ?? stableFtsScore(result.bm25Score), result });
-    }
-    return ftsScoreMap;
-}
-export function combineSearchScores(options) {
-    const FTS_WEIGHT = 0.7;
-    const VEC_WEIGHT = 0.3;
-    const excludeTypeSet = options.excludeTypes && options.excludeTypes.length > 0 ? new Set(options.excludeTypes) : null;
-    const scored = [];
-    const seenIds = new Set();
-    for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
-        seenIds.add(id);
-        const embedScore = options.embedScoreMap.get(id);
-        const combinedScore = embedScore !== undefined ? ftsScore * FTS_WEIGHT + embedScore * VEC_WEIGHT : ftsScore;
-        scored.push({
-            id,
-            entry: result.entry,
-            filePath: result.filePath,
-            score: combinedScore,
-            rankingMode: embedScore !== undefined ? "hybrid" : "fts",
-            lexicalMatch: result.lexicalMatch,
-            itemRef: result.itemRef,
-            bundleId: result.bundleId,
-            conceptId: result.conceptId,
-            fragmentId: result.fragmentId,
-        });
-    }
-    for (const [id, cosine] of options.embedScoreMap) {
-        if (seenIds.has(id))
-            continue;
-        const found = options.getEntryById(id);
-        if (!found)
-            continue;
-        if (options.typeFilter && found.entry.type !== options.typeFilter)
-            continue;
-        // #627 — drop vector-only neighbors whose type is excluded on the default path.
-        if (excludeTypeSet?.has(found.entry.type))
-            continue;
-        scored.push({
-            id,
-            entry: found.entry,
-            filePath: found.filePath,
-            score: cosine * VEC_WEIGHT,
-            rankingMode: "semantic",
-            itemRef: found.itemRef,
-            bundleId: found.bundleId,
-            conceptId: found.conceptId,
-        });
-    }
-    return scored;
-}
-export function applyRankingRules(options) {
-    const queryTokens = buildLexicalQueryPlan(options.query).tokens.map((token) => token.toLowerCase());
-    const queryLower = options.query.toLowerCase().trim();
-    const rankingContext = {
-        db: options.db,
-        query: options.query,
-        queryLower,
-        queryTokens,
-        graphContext: options.graphContext,
-        projectContext: options.projectContext,
-    };
-    for (const item of options.items) {
-        applyScoreContributors(item, rankingContext, defaultRankingContributors);
-    }
-    const { global: utilScoresMap, scoped: scopedUtilScoresMap } = getUtilityScoresByIds(options.db, options.items.map((item) => item.id), options.scopeKey);
-    // R2 / #692 — salience-ranking is not in defaultUtilityRankingContributors
-    // (see ranking-contributors.ts), so this is never consumed by the default
-    // ranking path below; it exists only for a caller that explicitly builds a
-    // contributor list including salienceRankingContributor. undefined/null
-    // both normalize to "no data" — there is no state.db fallback load.
-    const salienceRankScores = options.salienceRankScores ?? new Map();
-    const utilityContext = {
-        ...rankingContext,
-        utilityScores: utilScoresMap,
-        scopedUtilityScores: scopedUtilScoresMap,
-        utilityDecayConfig: options.utilityDecayConfig,
-        positiveFeedbackCounts: options.positiveFeedbackCounts,
-        salienceRankScores,
-    };
-    for (const item of options.items) {
-        applyUtilityContributors(item, utilityContext, defaultUtilityRankingContributors);
-        applyRelaxedLexicalScoreCeiling(item, queryTokens);
-        // SPEC-5: demoting belief states (superseded/contradicted/archived/
-        // deprecated) cap the FINAL score. The additive belief penalty inside the
-        // multiplicative boost sum can still overwhelm an additive belief penalty,
-        // so without the ceiling a superseded incumbent can outrank its correction.
-        applyBeliefStateScoreCeiling(item);
-    }
-    return options.items;
-}
-const RELAXED_NON_NAME_SCORE_CEILING = 0.65;
-/**
- * Rank name evidence without relying on punctuation or ASCII-only splitting.
- * The tiers are intentionally structural: an exact normalized name, all query
- * tokens in a longer name, any query token in the name, or no name evidence.
+ * Fusing ranks rather than scores needs no calibration between BM25 and cosine
+ * similarity, so it holds for every embedding model. On the retrieval suite,
+ * BM25 fused with document vectors this way scored nDCG@10 0.568 against 0.349
+ * for the additive boost stack it replaced
+ * (`akm/eval/retrieval/reports/baseline-2026-09-27.md`).
  */
-export function lexicalNameMatchTier(entry, queryTokens) {
-    if (queryTokens.length === 0)
-        return 0;
-    const nameBase = entry.name.toLowerCase().split("/").pop() ?? entry.name.toLowerCase();
-    const nameTokens = lexicalNameTokens(nameBase);
-    if (nameTokens.length === queryTokens.length &&
-        nameTokens.every((token, index) => structuralNameTokenMatch(token, queryTokens[index]))) {
-        return 3;
-    }
-    const matched = queryTokens.filter((token) => nameTokens.some((nameToken) => structuralNameTokenMatch(nameToken, token))).length;
-    if (matched === queryTokens.length)
-        return 2;
-    return matched > 0 ? 1 : 0;
-}
+import { compareCodePoints } from "../../core/common.js";
+/** The RRF constant: a candidate at rank r in a channel adds 1 / (RRF_K + r). */
+export const RRF_K = 60;
 /**
- * A relaxed OR query admits intentionally weak candidates. Candidates with no
- * query token in their name remain visible for body-only recall, but cannot
- * share the same bounded displayed score as stronger name-bearing recoveries.
- * The raw ceiling is 0.65; the public score projection is applied later, so
- * callers never literally receive `0.65` just because this ceiling bound.
- *
- * Preserve the pre-ceiling relevance separately from `preCeilingScore`, which
- * belongs to belief-state demotion and may be written afterwards. A relaxed,
- * belief-demoted candidate otherwise loses both its body relevance and its
- * ordering signal when the second ceiling overwrites the first.
+ * Fuse ranked channels with equal weights. Candidates are ordered by fused
+ * score, then by `itemRef`, so equal scores always come back in the same order.
  */
-function applyRelaxedLexicalScoreCeiling(item, queryTokens) {
-    if (item.lexicalMatch !== "relaxed" || lexicalNameMatchTier(item.entry, queryTokens) > 0)
-        return;
-    if (item.score > RELAXED_NON_NAME_SCORE_CEILING) {
-        item.preRelaxedCeilingScore = item.score;
-        item.score = RELAXED_NON_NAME_SCORE_CEILING;
-    }
+export function reciprocalRankFusion(channels) {
+    const fused = new Map();
+    channels.forEach((channel, channelIndex) => {
+        channel.forEach((candidate, position) => {
+            let entry = fused.get(candidate.id);
+            if (entry === undefined) {
+                entry = { id: candidate.id, itemRef: candidate.itemRef, score: 0, ranks: channels.map(() => undefined) };
+                fused.set(candidate.id, entry);
+            }
+            if (entry.ranks[channelIndex] !== undefined)
+                return;
+            entry.ranks[channelIndex] = position + 1;
+            entry.score += 1 / (RRF_K + position + 1);
+        });
+    });
+    return [...fused.values()].sort((a, b) => b.score - a.score || compareCodePoints(a.itemRef, b.itemRef));
 }

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

@@ -10,52 +10,32 @@ export function attachSearchHitAttribution(target, attribution) {
     };
 }
 export function copySearchHitAttribution(from, to, outputDescription) {
-    const attribution = from[ATTRIBUTION];
-    if (!attribution)
+    const memoryInference = from[ATTRIBUTION]?.memoryInference;
+    if (!memoryInference)
         return;
-    const memoryInference = attribution.memoryInference;
-    const memorySurvives = memoryInference?.exposure !== "surface" ||
+    const memorySurvives = memoryInference.exposure !== "surface" ||
         (memoryInference.surfaceDescription !== undefined && memoryInference.surfaceDescription === outputDescription);
-    const applicable = {
-        ...(attribution.lexical ? { lexical: attribution.lexical } : {}),
-        ...(memorySurvives && memoryInference ? { memoryInference } : {}),
-        ...(attribution.graphExtraction ? { graphExtraction: attribution.graphExtraction } : {}),
-    };
-    if (applicable.lexical || applicable.memoryInference || applicable.graphExtraction) {
-        attachSearchHitAttribution(to, applicable);
-    }
+    if (memorySurvives)
+        attachSearchHitAttribution(to, { memoryInference });
 }
 export function getSearchHitAttribution(target) {
     return target[ATTRIBUTION];
 }
 export function buildUsageEventAttribution(attribution, entryRef, projection = "full") {
-    if (!attribution)
+    const memoryInference = attribution?.memoryInference;
+    if (!memoryInference)
         return undefined;
-    const memoryInference = attribution.memoryInference;
-    const childRef = memoryInference?.exposure === "direct" ? entryRef : memoryInference?.childRef;
-    const graphExtraction = attribution.graphExtraction;
-    const graphApplies = graphExtraction !== undefined && Number.isFinite(graphExtraction.boost) && graphExtraction.boost > 0;
-    const surfaceFields = memoryInference?.surfaceFields ?? [];
-    const surfaceVisible = memoryInference?.exposure !== "surface" ||
+    const childRef = memoryInference.exposure === "direct" ? entryRef : memoryInference.childRef;
+    const surfaceFields = memoryInference.surfaceFields ?? [];
+    const surfaceVisible = memoryInference.exposure !== "surface" ||
         (projection === "full"
             ? surfaceFields.length > 0
             : projection === "normal" || projection === "agent"
                 ? surfaceFields.includes("description")
                 : false);
-    const memoryApplies = memoryInference !== undefined && childRef?.includes("//") === true && surfaceVisible;
-    if (!memoryApplies && !graphApplies)
+    if (childRef?.includes("//") !== true || !surfaceVisible)
         return undefined;
-    return {
-        ...(memoryApplies
-            ? {
-                memoryInference: {
-                    exposure: memoryInference.exposure,
-                    childRef,
-                },
-            }
-            : {}),
-        ...(graphApplies ? { graphExtraction } : {}),
-    };
+    return { memoryInference: { exposure: memoryInference.exposure, childRef } };
 }
 export function usageEventAttributionMetadata(attribution, entryRef, projection = "full") {
     const applicable = buildUsageEventAttribution(attribution, entryRef, projection);

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

@@ -4,6 +4,9 @@
 /**
  * Return per-field search text for multi-column FTS5 indexing.
  *
+ * Text keeps its case: FTS5's `unicode61` tokenizer folds case itself, and
+ * `buildSearchText` feeds the embedder, where case carries meaning.
+ *
  * Fields:
  *  - name: entry name with hyphens/underscores replaced by spaces
  *  - description: entry description
@@ -12,22 +15,15 @@
  *  - content: bounded native/adapter body projection + TOC headings + parameters
  *    (lowest-weight catch-all)
  */
-// NOTE (R5): the collapse detector's frozen canary queries are built from the
-// same surface this function indexes (name tokens / tags / description) and
-// scored via FTS against it. Changing what buildSearchFields includes shifts
-// the detector's recall baseline for ALL existing canary sets — coordinate
-// with src/commands/improve/collapse-detector.ts (buildCanaryQuery) and expect
-// operators to re-mint via `bun scripts/refresh-canary-set.ts --refresh` after
-// such a change.
 export function buildSearchFields(entry) {
-    const name = entry.name.replace(/[-_]/g, " ").toLowerCase();
-    const description = (entry.description ?? "").toLowerCase();
+    const name = entry.name.replace(/[-_]/g, " ");
+    const description = entry.description ?? "";
     const tagParts = [];
     if (entry.tags)
         tagParts.push(entry.tags.join(" "));
     if (entry.aliases)
         tagParts.push(entry.aliases.join(" "));
-    const tags = tagParts.join(" ").toLowerCase();
+    const tags = tagParts.join(" ");
     const hintParts = [];
     if (entry.hints)
         hintParts.push(entry.hints.join(" "));
@@ -51,7 +47,7 @@ export function buildSearchFields(entry) {
         hintParts.push(entry.pageKind);
     if (entry.whenToUse)
         hintParts.push(entry.whenToUse);
-    const hints = hintParts.join(" ").toLowerCase();
+    const hints = hintParts.join(" ");
     const contentParts = [];
     if (entry.toc) {
         contentParts.push(entry.toc.map((h) => h.text).join(" "));
@@ -65,13 +61,13 @@ export function buildSearchFields(entry) {
     }
     if (entry.content)
         contentParts.push(entry.content);
-    const content = contentParts.join(" ").toLowerCase();
+    const content = contentParts.join(" ");
     return { name, description, tags, hints, content };
 }
 /**
- * Build a single concatenated search text string for an entry.
- * Used for the `search_text` column in the entries table.
- * and for generating embedding text.
+ * Build a single concatenated search text string for an entry: the text its
+ * vector is embedded from, derived from the stored document when the entry is
+ * embedded (`entries.embed_hash` holds its hash).
  */
 export function buildSearchText(entry) {
     const fields = buildSearchFields(entry);

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

@@ -2,100 +2,69 @@
 // 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/.
 import { displayRef } from "../../core/asset/resolve-ref.js";
+import { presentationFor } from "../../core/type-presentation.js";
 import { getDerivedForParent, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
 import { getRenderer } from "../walk/file-context.js";
 import { attachSearchHitAttribution } from "./search-attribution.js";
-const rendererSearchHitEnricher = {
-    name: "renderer-search-hit-enricher",
-    appliesTo(ctx) {
-        return ctx.rendererRegistry.rendererNameFor(ctx.type) !== undefined;
-    },
-    async enrich(hit, ctx) {
-        const rendererName = ctx.rendererRegistry.rendererNameFor(ctx.type);
-        if (!rendererName)
-            return;
+/**
+ * Let the hit's type renderer enrich it, then — for a memory, when a DB is
+ * open — surface its derived child ({@link surfaceDerivedMemory}).
+ */
+export async function enrichSearchHit(hit, ctx) {
+    const rendererName = presentationFor(ctx.type).renderer;
+    if (rendererName) {
         const renderer = await getRenderer(rendererName);
         renderer?.enrichSearchHit?.(hit, ctx.stashDir);
-    },
-};
+    }
+    if (ctx.type === "memory" && ctx.db)
+        surfaceDerivedMemory(hit, ctx.db, ctx.bundleId);
+}
 /**
- * Phase 5A / Advantage D5 — derived-memory enricher.
- *
- * When a parent memory has a `.derived` child indexed (the LLM-distilled
- * lesson surface), this enricher rewrites the parent hit to surface the
- * derived child's description / searchHints / tags AND sets `expandTo` to
- * the derived child's ref so callers can fetch it via `akm show <ref>`.
+ * Phase 5A / Advantage D5 — when a parent memory has a `.derived` child
+ * indexed (the LLM-distilled lesson surface), rewrite the parent hit to
+ * surface the derived child's description / tags AND set `expandTo` to the
+ * derived child's ref so callers can fetch it via `akm show <ref>`.
  *
  * The parent ref is preserved on the hit — only the surface text is
  * swapped, so links and provenance still point at the canonical parent.
- *
- * Skipped for:
- *  - non-memory hits
- *  - memory hits that are themselves derived children (name ends with
- *    `.derived`) — we never recurse parent→child→grandchild
- *  - contexts without an open DB connection
  */
-export const derivedMemoryEnricher = {
-    name: "derived-memory-enricher",
-    appliesTo(ctx) {
-        return ctx.type === "memory" && ctx.db !== undefined;
-    },
-    enrich(hit, ctx) {
-        if (!ctx.db)
-            return;
-        // 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"))
-            return;
-        // Parent ref shape: the 0.9.0 `memories/<name>` conceptId. Re-build from the
-        // entry's name so we don't depend on whatever wiki/registry prefix `hit.ref`
-        // carries. INTERNAL lookup key into `getDerivedForParent`: the `derived_from`
-        // column now stores this same conceptId grammar (Group-C item 2 flip — the
-        // metadata producer + this consumer move together).
-        const parentRef = `memories/${hit.name}`;
-        const derived = getDerivedForParent(ctx.db, parentRef, ctx.bundleId);
-        if (!derived)
-            return;
-        // Swap description / searchHints / tags from the derived child.
-        // The parent ref itself is preserved — only the surface text is swapped.
-        const surfaceFields = [];
-        let surfaceDescription;
-        if (typeof derived.entry.description === "string" && derived.entry.description.length > 0) {
-            hit.description = derived.entry.description;
-            surfaceDescription = derived.entry.description;
-            surfaceFields.push("description");
-        }
-        if (Array.isArray(derived.entry.searchHints) && derived.entry.searchHints.length > 0) {
-            // We don't have a `searchHints` field on SourceSearchHit today — it's
-            // only used inside ranking. The plan says to swap when present; we
-            // record it onto the hit only if a future renderer surfaces it. For
-            // now, treat as advisory (no-op when SearchHit lacks the field).
-        }
-        if (Array.isArray(derived.entry.tags) && derived.entry.tags.length > 0) {
-            hit.tags = derived.entry.tags;
-            surfaceFields.push("tags");
-        }
-        // F4b output-spelling flip: `expandTo` is a user-facing `akm show <ref>`
-        // target, so emit the 0.9.0 short conceptId grammar (`memories/<name>`).
-        hit.expandTo = displayRef({ type: "memory", name: derived.entry.name });
-        const childRef = getItemRefById(ctx.db, derived.id);
-        if (childRef && surfaceFields.length > 0) {
-            attachSearchHitAttribution(hit, {
-                memoryInference: {
-                    exposure: "surface",
-                    childRef,
-                    surfaceFields,
-                    ...(surfaceDescription ? { surfaceDescription } : {}),
-                },
-            });
-        }
-    },
-};
-export const defaultSearchHitEnrichers = [rendererSearchHitEnricher, derivedMemoryEnricher];
-export async function enrichSearchHit(hit, ctx, enrichers = defaultSearchHitEnrichers) {
-    for (const enricher of enrichers) {
-        if (!enricher.appliesTo(ctx))
-            continue;
-        await enricher.enrich(hit, ctx);
+function surfaceDerivedMemory(hit, db, bundleId) {
+    // 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"))
+        return;
+    // Parent ref shape: the 0.9.0 `memories/<name>` conceptId. Re-build from the
+    // entry's name so we don't depend on whatever wiki/registry prefix `hit.ref`
+    // 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)
+        return;
+    // Swap description / tags from the derived child (SourceSearchHit carries no
+    // `searchHints`).
+    const surfaceFields = [];
+    let surfaceDescription;
+    if (typeof derived.entry.description === "string" && derived.entry.description.length > 0) {
+        hit.description = derived.entry.description;
+        surfaceDescription = derived.entry.description;
+        surfaceFields.push("description");
+    }
+    if (Array.isArray(derived.entry.tags) && derived.entry.tags.length > 0) {
+        hit.tags = derived.entry.tags;
+        surfaceFields.push("tags");
+    }
+    // `expandTo` is a user-facing `akm show <ref>` target, so emit the 0.9.0
+    // short conceptId grammar (`memories/<name>`).
+    hit.expandTo = displayRef({ type: "memory", name: derived.entry.name });
+    const childRef = getItemRefById(db, derived.id);
+    if (childRef && surfaceFields.length > 0) {
+        attachSearchHitAttribution(hit, {
+            memoryInference: {
+                exposure: "surface",
+                childRef,
+                surfaceFields,
+                ...(surfaceDescription ? { surfaceDescription } : {}),
+            },
+        });
     }
 }

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

@@ -7,14 +7,11 @@ import { isWithin, resolveStashDir } from "../../core/common.js";
 import { bundleComponentConfig, bundleKeyForContentRoot, bundlesToSourceEntries, getSources, isBundleEnabled, loadConfig, } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
 import { getUnresolvedSourcesDir } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
 import { resolveGitContentRoot, resolveWritable } from "../../core/write-source.js";
 import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
 import { ensureWebsiteMirror } from "../../sources/snapshot-fetchers/website-ingest.js";
-// Eager side-effect imports so all built-in source providers self-register
-// before resolveEntryContentDir() runs.
-import "../../sources/providers/index.js";
-import { warn } from "../../core/warn.js";
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
  * Build the ordered list of stash sources, walking every configured stash

package/dist/indexer/usage/usage-events.js

@@ -91,20 +91,49 @@ export function countUsageEventsByType(db, eventType) {
     return db.prepare("SELECT COUNT(*) AS cnt FROM usage_events WHERE event_type = ?").get(eventType)
         .cnt;
 }
+/**
+ * Durable refs a user-attributed `search`, `curate` or `show` returned, or a
+ * user `feedback` named, at or after `sinceIso`. Machine traffic (`improve`,
+ * `task`, `audit`, `unknown`) is not demand, as in {@link countFeedbackSignals}.
+ */
+export function listUsedEntryRefs(db, sinceIso) {
+    const rows = db
+        .prepare(`SELECT DISTINCT entry_ref FROM usage_events
+       WHERE event_type IN ('search', 'curate', 'show', 'feedback')
+         AND source = 'user'
+         AND entry_ref IS NOT NULL
+         AND julianday(created_at) >= julianday(?)`)
+        .all(sinceIso);
+    return rows.map((row) => row.entry_ref);
+}
+/**
+ * The distinct query texts of user `search` and `curate` events that returned
+ * `conceptId` (any bundle prefix), most recent first.
+ */
+export function listRetrievalQueries(db, conceptId) {
+    const rows = db
+        .prepare(`SELECT query, MAX(created_at) AS last_at FROM usage_events
+       WHERE event_type IN ('search', 'curate')
+         AND source = 'user'
+         AND query IS NOT NULL AND trim(query) != ''
+         AND instr(entry_ref, '//') > 0
+         AND substr(entry_ref, instr(entry_ref, '//') + 2) = ?
+       GROUP BY query
+       ORDER BY last_at DESC`)
+        .all(conceptId);
+    return rows.map((row) => row.query);
+}
+/** Usage events older than this many days are purged on every `akm index`. */
+export const USAGE_EVENT_RETENTION_DAYS = 90;
 /**
  * Delete usage events older than the given number of days.
  */
-export function purgeOldUsageEvents(db, retentionDays, options) {
+export function purgeOldUsageEvents(db, retentionDays) {
     if (!Number.isFinite(retentionDays) || retentionDays <= 0)
         return;
     try {
-        const stateSchema = options?.stateSchema;
-        if (stateSchema !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(stateSchema)) {
-            throw new Error("Invalid attached state schema name.");
-        }
-        const usageEvents = stateSchema === undefined ? "usage_events" : `"${stateSchema}".usage_events`;
         const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-        db.prepare(`DELETE FROM ${usageEvents} WHERE created_at < ?`).run(cutoff);
+        db.prepare("DELETE FROM usage_events WHERE created_at < ?").run(cutoff);
     }
     catch {
         /* Table may not exist yet */