hippo-memory 0.26.0 → 0.27.0

package/dist/config.js

@@ -28,6 +28,10 @@ const DEFAULT_CONFIG = {
         'refactor', 'perf', 'chore', 'breaking', 'deprecate',
     ],
     physics: { ...DEFAULT_PHYSICS_CONFIG },
+    mmr: {
+        enabled: true,
+        lambda: 0.7,
+    },
 };
 export function loadConfig(hippoRoot) {
     const configPath = path.join(hippoRoot, 'config.json');
@@ -49,6 +53,7 @@ export function loadConfig(hippoRoot) {
             global: { ...DEFAULT_CONFIG.global, ...(raw.global ?? {}) },
             gitLearnPatterns: raw.gitLearnPatterns ?? DEFAULT_CONFIG.gitLearnPatterns,
             physics: mergePhysicsConfig(raw.physics),
+            mmr: { ...DEFAULT_CONFIG.mmr, ...(raw.mmr ?? {}) },
         };
     }
     catch (err) {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/eval.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Recall eval harness.
+ *
+ * Given a corpus of (query, expected_memory_ids) cases, run recall against
+ * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
+ *
+ * The goal is to make recall quality measurable so MMR lambda, embedding
+ * weights, and future scoring tweaks can be tuned against evidence instead
+ * of intuition.
+ */
+import type { MemoryEntry } from './memory.js';
+export interface EvalCase {
+    /** Free-form ID for humans to reference the case. */
+    id: string;
+    /** The query text to run through recall. */
+    query: string;
+    /** Memory IDs considered relevant. At least one required. */
+    expectedIds: string[];
+    /** Optional short description so a failure report is self-explaining. */
+    description?: string;
+}
+export interface EvalCaseResult {
+    case: EvalCase;
+    returnedIds: string[];
+    /** 1 / rank of the first expected id, else 0. */
+    mrr: number;
+    /** |expected ∩ returned[0..K]| / |expected|, 0 when expected is empty. */
+    recallAt5: number;
+    recallAt10: number;
+    /** Normalized DCG at 10 using binary relevance (expected = 1, else 0). */
+    ndcgAt10: number;
+}
+export interface EvalSummary {
+    cases: EvalCaseResult[];
+    /** Simple arithmetic means across cases. */
+    meanMrr: number;
+    meanRecallAt5: number;
+    meanRecallAt10: number;
+    meanNdcgAt10: number;
+    /** Wall-clock runtime in ms for the whole eval. */
+    durationMs: number;
+}
+export interface RunEvalOptions {
+    mmr?: boolean;
+    mmrLambda?: number;
+    embeddingWeight?: number;
+    /** Max returned results per case. Larger than K-at-10 so metrics stay honest. */
+    budget?: number;
+    hippoRoot?: string;
+    now?: Date;
+}
+/** Mean Reciprocal Rank for a single ranking given expected ids. */
+export declare function mrr(returned: string[], expected: string[]): number;
+/** Recall@K — fraction of expected items found in the top-K. */
+export declare function recallAtK(returned: string[], expected: string[], k: number): number;
+/**
+ * Normalized Discounted Cumulative Gain at K with binary relevance.
+ * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
+ */
+export declare function ndcgAtK(returned: string[], expected: string[], k: number): number;
+export declare function runEval(cases: EvalCase[], entries: MemoryEntry[], options?: RunEvalOptions): Promise<EvalSummary>;
+/**
+ * For each memory, take its first 8 content words as a trivial query and
+ * expect that memory back. Useful as a smoke test: if recall can't find a
+ * memory by its own opening words, something is broken.
+ */
+export declare function bootstrapCorpus(entries: MemoryEntry[], maxCases?: number): EvalCase[];
+//# sourceMappingURL=eval.d.ts.map

package/dist/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../src/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAMD,oEAAoE;AACpE,wBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAOlE;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASnF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBjF;AAMD,wBAAsB,OAAO,CAC3B,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAuCtB;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,SAAK,GAAG,QAAQ,EAAE,CAejF"}

package/dist/eval.js

@@ -0,0 +1,127 @@
+/**
+ * Recall eval harness.
+ *
+ * Given a corpus of (query, expected_memory_ids) cases, run recall against
+ * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
+ *
+ * The goal is to make recall quality measurable so MMR lambda, embedding
+ * weights, and future scoring tweaks can be tuned against evidence instead
+ * of intuition.
+ */
+import { hybridSearch } from './search.js';
+// ---------------------------------------------------------------------------
+// Metrics — pure functions. K is inclusive of position K.
+// ---------------------------------------------------------------------------
+/** Mean Reciprocal Rank for a single ranking given expected ids. */
+export function mrr(returned, expected) {
+    if (expected.length === 0)
+        return 0;
+    const expectedSet = new Set(expected);
+    for (let i = 0; i < returned.length; i++) {
+        if (expectedSet.has(returned[i]))
+            return 1 / (i + 1);
+    }
+    return 0;
+}
+/** Recall@K — fraction of expected items found in the top-K. */
+export function recallAtK(returned, expected, k) {
+    if (expected.length === 0)
+        return 0;
+    const expectedSet = new Set(expected);
+    const topK = returned.slice(0, k);
+    let hits = 0;
+    for (const id of topK) {
+        if (expectedSet.has(id))
+            hits++;
+    }
+    return hits / expected.length;
+}
+/**
+ * Normalized Discounted Cumulative Gain at K with binary relevance.
+ * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
+ */
+export function ndcgAtK(returned, expected, k) {
+    if (expected.length === 0)
+        return 0;
+    const expectedSet = new Set(expected);
+    let dcg = 0;
+    for (let i = 0; i < Math.min(k, returned.length); i++) {
+        if (expectedSet.has(returned[i])) {
+            dcg += 1 / Math.log2(i + 2);
+        }
+    }
+    // Ideal DCG: all relevant items at top positions.
+    const idealHits = Math.min(k, expected.length);
+    let idcg = 0;
+    for (let i = 0; i < idealHits; i++) {
+        idcg += 1 / Math.log2(i + 2);
+    }
+    return idcg === 0 ? 0 : dcg / idcg;
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+export async function runEval(cases, entries, options = {}) {
+    const budget = options.budget ?? 100_000; // generous so metrics aren't truncated
+    const start = Date.now();
+    const results = [];
+    for (const c of cases) {
+        const ranked = await hybridSearch(c.query, entries, {
+            budget,
+            now: options.now,
+            hippoRoot: options.hippoRoot,
+            embeddingWeight: options.embeddingWeight,
+            mmr: options.mmr,
+            mmrLambda: options.mmrLambda,
+        });
+        const returnedIds = ranked.map((r) => r.entry.id);
+        results.push({
+            case: c,
+            returnedIds,
+            mrr: mrr(returnedIds, c.expectedIds),
+            recallAt5: recallAtK(returnedIds, c.expectedIds, 5),
+            recallAt10: recallAtK(returnedIds, c.expectedIds, 10),
+            ndcgAt10: ndcgAtK(returnedIds, c.expectedIds, 10),
+        });
+    }
+    const n = Math.max(1, results.length);
+    const meanMrr = results.reduce((s, r) => s + r.mrr, 0) / n;
+    const meanRecallAt5 = results.reduce((s, r) => s + r.recallAt5, 0) / n;
+    const meanRecallAt10 = results.reduce((s, r) => s + r.recallAt10, 0) / n;
+    const meanNdcgAt10 = results.reduce((s, r) => s + r.ndcgAt10, 0) / n;
+    return {
+        cases: results,
+        meanMrr,
+        meanRecallAt5,
+        meanRecallAt10,
+        meanNdcgAt10,
+        durationMs: Date.now() - start,
+    };
+}
+// ---------------------------------------------------------------------------
+// Bootstrap — generate a synthetic corpus from current memories
+// ---------------------------------------------------------------------------
+/**
+ * For each memory, take its first 8 content words as a trivial query and
+ * expect that memory back. Useful as a smoke test: if recall can't find a
+ * memory by its own opening words, something is broken.
+ */
+export function bootstrapCorpus(entries, maxCases = 50) {
+    const cases = [];
+    for (const e of entries) {
+        if (cases.length >= maxCases)
+            break;
+        const words = e.content.trim().split(/\s+/).filter((w) => w.length > 2);
+        if (words.length < 3)
+            continue;
+        const query = words.slice(0, 8).join(' ');
+        cases.push({
+            id: `bootstrap_${e.id}`,
+            query,
+            expectedIds: [e.id],
+            description: `trivial self-query on memory ${e.id}`,
+        });
+    }
+    return cases;
+}
+//# sourceMappingURL=eval.js.map

package/dist/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../src/eval.ts"],"names":[],"mappings":"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"}

package/dist/search.d.ts

@@ -15,6 +15,54 @@ export interface SearchResult {
     bm25: number;
     cosine: number;
     tokens: number;
+    /** Populated when search is called with options.explain === true. */
+    breakdown?: ScoreBreakdown;
+}
+export interface ScoreBreakdown {
+    /**
+     * - `hybrid`: BM25 blended with a non-zero cosine from a cached doc vector.
+     * - `hybrid-no-vec`: Query was embedded but this doc had no cached vector,
+     *   so the effective score came from BM25 alone even though weights say
+     *   otherwise. Usually means `hippo embed` hasn't run on this memory.
+     * - `bm25-only`: Embedding pipeline unavailable or the model requires re-index.
+     * - `physics`: Scored by the physics engine (gravity + momentum + cluster).
+     */
+    mode: 'hybrid' | 'hybrid-no-vec' | 'bm25-only' | 'physics';
+    /** BM25 score after normalization by max-in-corpus (0..1). */
+    normBm25: number;
+    /** Weight applied to BM25 in the hybrid blend. */
+    bm25Weight: number;
+    /** Weight applied to cosine in the hybrid blend. */
+    embeddingWeight: number;
+    /** Cosine similarity (0 when embeddings not used). */
+    cosine: number;
+    /** Blended base score before multipliers. */
+    base: number;
+    /** Multiplier from memory strength: 0.5 + 0.5*strength. */
+    strengthMultiplier: number;
+    /** Multiplier from age: 0.8 + 0.2*recencyBoost. */
+    recencyMultiplier: number;
+    /** 1.2 if tagged 'decision', else 1.0. */
+    decisionBoost: number;
+    /** 1.0..1.3 based on cwd path tag overlap. */
+    pathBoost: number;
+    /** Extra multiplier applied post-hybrid (e.g. 1.2x for local hits in a
+     *  local+global merged search). 1.0 when not applicable. */
+    sourceBump: number;
+    /** Retrieval-time outcome personalization: 1 + 0.15*tanh(pos - neg), clipped
+     *  to [0.85, 1.15]. Immediate nudge from `hippo outcome --good/--bad`.
+     *  Separate from the slow strength-via-reward-factor path. */
+    outcomeBoost: number;
+    /** Pre-MMR rank (1-indexed). Only set when MMR re-ranking ran. */
+    preMmrRank?: number;
+    /** Post-MMR rank (1-indexed). Only set when MMR re-ranking ran. */
+    postMmrRank?: number;
+    /** Query terms that appeared verbatim in the doc. */
+    matchedTerms: string[];
+    /** Final composite score (= base * multipliers). */
+    final: number;
+    /** Age of the memory in whole days, at scoring time. */
+    ageDays: number;
 }
 /**
  * Hybrid search: BM25 + cosine similarity (when embeddings are available).
@@ -28,7 +76,23 @@ export declare function hybridSearch(query: string, entries: MemoryEntry[], opti
     now?: Date;
     hippoRoot?: string;
     embeddingWeight?: number;
+    explain?: boolean;
+    /** Disable MMR re-ranking even when embeddings are available. */
+    mmr?: boolean;
+    /** MMR balance: 1.0 = pure relevance, 0.0 = pure diversity. Default 0.7. */
+    mmrLambda?: number;
 }): Promise<SearchResult[]>;
+/**
+ * MMR (Maximal Marginal Relevance) re-ranking.
+ *
+ * Iteratively picks the candidate that maximises
+ *   lambda * relevance - (1 - lambda) * max(cos(cand, picked))
+ *
+ * Inputs must already be sorted by relevance descending. When `explain` is
+ * true, attaches `preMmrRank` / `postMmrRank` to each result's breakdown.
+ * Exported for unit tests; production callers go through hybridSearch.
+ */
+export declare function mmrRerank(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
 /**
  * Physics-based search: scores memories using gravitational force, momentum,
  * and cluster amplification. Falls back to classic hybrid for memories
@@ -40,6 +104,7 @@ export declare function physicsSearch(query: string, entries: MemoryEntry[], opt
     hippoRoot?: string;
     physicsConfig?: PhysicsConfig;
     queryEmbedding?: number[];
+    explain?: boolean;
 }): Promise<SearchResult[]>;
 /**
  * Search entries using BM25 + strength + recency composite score.

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAY7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/C;AAgED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CACrB,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CAsGzB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CAiGzB;AAiBD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,YAAY,EAAE,CA2DhB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,WAAW,EAAE,CAc3F;AAMD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAgClF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAaxD"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAY7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/C;AAgED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,WAAW,GAAG,SAAS,CAAC;IAC3D,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB;gEAC4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB;;kEAE8D;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CAwKzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,YAAY,EAAE,EACtB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,YAAY,EAAE,CAgDhB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CA0HzB;AAiBD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,YAAY,EAAE,CA2DhB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,WAAW,EAAE,CAc3F;AAMD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAgClF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAaxD"}

package/dist/search.js

@@ -89,6 +89,9 @@ export async function hybridSearch(query, entries, options = {}) {
     const budget = options.budget ?? 4000;
     const embeddingWeight = options.embeddingWeight ?? 0.6;
     const bm25Weight = 1 - embeddingWeight;
+    const explain = options.explain ?? false;
+    const mmrEnabled = options.mmr ?? true;
+    const mmrLambda = options.mmrLambda ?? 0.7;
     if (entries.length === 0)
         return [];
     const queryTerms = tokenize(query);
@@ -122,6 +125,7 @@ export async function hybridSearch(query, entries, options = {}) {
     // Score each entry
     const scored = [];
     const currentPathTags = extractPathTags(process.cwd());
+    const queryTermSet = new Set(queryTerms);
     for (let i = 0; i < entries.length; i++) {
         const rawBm25 = bm25Scores[i];
         if (!useEmbeddings && rawBm25 <= 0)
@@ -129,21 +133,31 @@ export async function hybridSearch(query, entries, options = {}) {
         const normBm25 = rawBm25 / maxBm25;
         const strength = calculateStrength(entries[i], now);
         const recency = recencyBoost(entries[i], now);
+        const strengthMultiplier = 0.5 + 0.5 * strength;
+        const recencyMultiplier = 0.8 + 0.2 * recency;
         let compositeScore;
         let cosineScore = 0;
+        let base;
+        let modeLabel;
+        let hadCachedVec = false;
         if (useEmbeddings) {
             const cached = embeddingIndex[entries[i].id];
-            cosineScore = cached && queryVector.length > 0
+            hadCachedVec = Boolean(cached && queryVector.length > 0);
+            cosineScore = hadCachedVec
                 ? Math.max(0, cosineSimilarity(queryVector, cached))
                 : 0;
-            // Hybrid: weighted blend, then modulated by strength and recency
-            const hybrid = bm25Weight * normBm25 + embeddingWeight * cosineScore;
-            compositeScore = hybrid * (0.5 + 0.5 * strength) * (0.8 + 0.2 * recency);
+            base = bm25Weight * normBm25 + embeddingWeight * cosineScore;
+            compositeScore = base * strengthMultiplier * recencyMultiplier;
+            // Distinguish "real hybrid" from "query embedded but doc has no cached
+            // vector" so explain can tell users their index is stale without lying
+            // that the search actually used embeddings.
+            modeLabel = hadCachedVec ? 'hybrid' : 'hybrid-no-vec';
         }
         else {
             // Pure BM25 path: identical to original behavior
-            const normQ = queryTerms.length > 0 ? rawBm25 / queryTerms.length : rawBm25;
-            compositeScore = normQ * (0.5 + 0.5 * strength) * (0.8 + 0.2 * recency);
+            base = queryTerms.length > 0 ? rawBm25 / queryTerms.length : rawBm25;
+            compositeScore = base * strengthMultiplier * recencyMultiplier;
+            modeLabel = 'bm25-only';
         }
         // Decision-tagged memories get a 1.2x recall boost
         const decisionBoost = entries[i].tags.includes('decision') ? 1.2 : 1.0;
@@ -153,25 +167,131 @@ export async function hybridSearch(query, entries, options = {}) {
         const pathScore = pathOverlapScore(memPathTags, currentPathTags);
         const pathBoost = 1.0 + (pathScore * 0.3);
         compositeScore *= pathBoost;
+        // Retrieval-time outcome personalization: nudge up/down from user feedback.
+        // Distinct from reward-factor-via-strength (slow); this is immediate.
+        const pos = entries[i].outcome_positive ?? 0;
+        const neg = entries[i].outcome_negative ?? 0;
+        const outcomeBoost = pos === 0 && neg === 0
+            ? 1.0
+            : Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
+        compositeScore *= outcomeBoost;
         if (compositeScore <= 0)
             continue;
         const tokens = estimateTokens(entries[i].content);
-        scored.push({ entry: entries[i], score: compositeScore, bm25: rawBm25, cosine: cosineScore, tokens });
+        const result = {
+            entry: entries[i],
+            score: compositeScore,
+            bm25: rawBm25,
+            cosine: cosineScore,
+            tokens,
+        };
+        if (explain) {
+            const docTerms = new Set(tokenize(`${entries[i].content} ${entries[i].tags.join(' ')}`));
+            const matchedTerms = [];
+            for (const t of queryTermSet)
+                if (docTerms.has(t))
+                    matchedTerms.push(t);
+            const ageDays = Math.max(0, Math.floor((now.getTime() - new Date(entries[i].created).getTime()) / 86_400_000));
+            result.breakdown = {
+                mode: modeLabel,
+                normBm25,
+                bm25Weight: useEmbeddings ? bm25Weight : 1,
+                embeddingWeight: useEmbeddings ? embeddingWeight : 0,
+                cosine: cosineScore,
+                base,
+                strengthMultiplier,
+                recencyMultiplier,
+                decisionBoost,
+                pathBoost,
+                sourceBump: 1,
+                outcomeBoost,
+                matchedTerms,
+                final: compositeScore,
+                ageDays,
+            };
+        }
+        scored.push(result);
     }
     // Sort by composite score descending
     scored.sort((a, b) => b.score - a.score);
+    // MMR re-ranking: de-cluster near-duplicates by trading relevance for
+    // diversity. Only applies when embeddings are loaded (doc-to-doc similarity
+    // is via cosine of cached vectors); otherwise we return the pure-relevance
+    // ordering unchanged.
+    const applyMmr = mmrEnabled && useEmbeddings && scored.length > 1 && mmrLambda < 1;
+    const ordered = applyMmr
+        ? mmrRerank(scored, embeddingIndex, mmrLambda, explain)
+        : scored;
     // Apply token budget
     const results = [];
     let usedTokens = 0;
-    for (let i = 0; i < scored.length; i++) {
-        const tokens = scored[i].tokens;
+    for (let i = 0; i < ordered.length; i++) {
+        const tokens = ordered[i].tokens;
         if (i > 0 && usedTokens + tokens > budget)
             continue; // always include first result
         usedTokens += tokens;
-        results.push(scored[i]);
+        results.push(ordered[i]);
     }
     return results;
 }
+/**
+ * MMR (Maximal Marginal Relevance) re-ranking.
+ *
+ * Iteratively picks the candidate that maximises
+ *   lambda * relevance - (1 - lambda) * max(cos(cand, picked))
+ *
+ * Inputs must already be sorted by relevance descending. When `explain` is
+ * true, attaches `preMmrRank` / `postMmrRank` to each result's breakdown.
+ * Exported for unit tests; production callers go through hybridSearch.
+ */
+export function mmrRerank(scored, embeddingIndex, lambda, explain) {
+    if (scored.length === 0)
+        return scored;
+    const maxScore = scored[0].score || 1;
+    const normScore = scored.map((r) => r.score / maxScore);
+    const vectors = scored.map((r) => embeddingIndex[r.entry.id] ?? null);
+    const picked = [];
+    const remaining = new Set(scored.map((_, i) => i));
+    while (remaining.size > 0) {
+        let bestIdx = -1;
+        let bestMmr = -Infinity;
+        for (const i of remaining) {
+            const rel = normScore[i];
+            let maxSim = 0;
+            const vi = vectors[i];
+            if (vi) {
+                for (const p of picked) {
+                    const vp = embeddingIndex[p.entry.id];
+                    if (!vp || vp.length !== vi.length)
+                        continue;
+                    const sim = Math.max(0, cosineSimilarity(vi, vp));
+                    if (sim > maxSim)
+                        maxSim = sim;
+                }
+            }
+            const mmr = lambda * rel - (1 - lambda) * maxSim;
+            if (mmr > bestMmr) {
+                bestMmr = mmr;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx === -1)
+            break;
+        remaining.delete(bestIdx);
+        picked.push(scored[bestIdx]);
+    }
+    if (explain) {
+        const preRank = new Map();
+        scored.forEach((r, i) => preRank.set(r.entry.id, i + 1));
+        picked.forEach((r, i) => {
+            if (r.breakdown) {
+                r.breakdown.preMmrRank = preRank.get(r.entry.id);
+                r.breakdown.postMmrRank = i + 1;
+            }
+        });
+    }
+    return picked;
+}
 /**
  * Physics-based search: scores memories using gravitational force, momentum,
  * and cluster amplification. Falls back to classic hybrid for memories
@@ -181,6 +301,7 @@ export async function physicsSearch(query, entries, options = {}) {
     const now = options.now ?? new Date();
     const budget = options.budget ?? 4000;
     const config = options.physicsConfig ?? DEFAULT_PHYSICS_CONFIG;
+    const explain = options.explain ?? false;
     if (entries.length === 0 || !options.hippoRoot)
         return [];
     // Get query embedding (use pre-computed if provided)
@@ -240,18 +361,39 @@ export async function physicsSearch(query, entries, options = {}) {
             const entry = entryMap.get(s.memoryId);
             if (!entry)
                 continue;
-            physicsResults.push({
+            const result = {
                 entry,
                 score: s.finalScore,
                 bm25: 0,
                 cosine: s.baseScore,
                 tokens: estimateTokens(entry.content),
-            });
+            };
+            if (explain) {
+                const ageDays = Math.max(0, Math.floor((now.getTime() - new Date(entry.created).getTime()) / 86_400_000));
+                result.breakdown = {
+                    mode: 'physics',
+                    normBm25: 0,
+                    bm25Weight: 0,
+                    embeddingWeight: 1,
+                    cosine: s.baseScore,
+                    base: s.baseScore,
+                    strengthMultiplier: 1,
+                    recencyMultiplier: 1,
+                    decisionBoost: 1,
+                    pathBoost: 1,
+                    sourceBump: 1,
+                    outcomeBoost: 1,
+                    matchedTerms: [],
+                    final: s.finalScore,
+                    ageDays,
+                };
+            }
+            physicsResults.push(result);
         }
     }
     // Score classic memories (no physics state)
     const classicResults = classicEntries.length > 0
-        ? await hybridSearch(query, classicEntries, { ...options, budget: Infinity })
+        ? await hybridSearch(query, classicEntries, { ...options, budget: Infinity, explain })
         : [];
     // Normalize both pools to [0, 1] and merge
     const merged = mergeScorePools(physicsResults, classicResults);