hippo-memory 1.17.0 → 1.19.0

package/dist/cli.js

@@ -916,7 +916,17 @@ async function cmdRecall(hippoRoot, query, flags) {
         results = results.map((r) => {
             const peers = r.entry.conflicts_with || [];
             const hasPeerInResults = peers.some((peerId) => presentIds.has(peerId));
-            return hasPeerInResults ? { ...r, score: r.score * 0.3 } : r;
+            if (!hasPeerInResults)
+                return r;
+            const next = { ...r, score: r.score * 0.3 };
+            // A7 recall-trace: interference (vlPFC) down-rank. Only when --why.
+            if (showWhy) {
+                next.rerankTrace = [
+                    ...(r.rerankTrace ?? []),
+                    { stage: 'interference', multiplier: 0.3, scoreBefore: r.score, scoreAfter: next.score },
+                ];
+            }
+            return next;
         });
         results.sort((a, b) => b.score - a.score);
     }
@@ -936,7 +946,15 @@ async function cmdRecall(hippoRoot, query, flags) {
                 return r;
             const raw = 1 + 0.3 * Math.tanh(pos - neg);
             const valueMult = Math.max(0.7, Math.min(1.3, raw));
-            return { ...r, score: r.score * valueMult };
+            const next = { ...r, score: r.score * valueMult };
+            // A7 recall-trace: vmPFC continuous value attribution. Only when --why.
+            if (showWhy) {
+                next.rerankTrace = [
+                    ...(r.rerankTrace ?? []),
+                    { stage: 'value', multiplier: valueMult, scoreBefore: r.score, scoreAfter: next.score },
+                ];
+            }
+            return next;
         });
         results.sort((a, b) => b.score - a.score);
     }
@@ -960,8 +978,17 @@ async function cmdRecall(hippoRoot, query, flags) {
             .map((r) => {
             const strength = typeof r.entry.strength === 'number' ? r.entry.strength : 1.0;
             const costFactor = Math.min(0.3, (r.tokens || 0) / 10000);
-            const utility = r.score * (0.5 + 0.5 * strength) * (1 - costFactor);
-            return { ...r, score: utility };
+            const utilityMult = (0.5 + 0.5 * strength) * (1 - costFactor);
+            const utility = r.score * utilityMult;
+            const next = { ...r, score: utility };
+            // A7 recall-trace: OFC option-value re-rank. Only when --why.
+            if (showWhy) {
+                next.rerankTrace = [
+                    ...(r.rerankTrace ?? []),
+                    { stage: 'utility', multiplier: utilityMult, scoreBefore: r.score, scoreAfter: utility },
+                ];
+            }
+            return next;
         })
             .sort((a, b) => b.score - a.score);
     }
@@ -990,11 +1017,22 @@ async function cmdRecall(hippoRoot, query, flags) {
             // salience) that sort by `r.score` honor the reranker's order rather
             // than unwinding it. Original score is preserved on rerankScore's
             // input, but downstream sorters key on `score`.
-            const withPostRank = reranked.map((r, i) => ({
-                ...r,
-                score: r.rerankScore,
-                postRerankRank: i + 1,
-            }));
+            const withPostRank = reranked.map((r, i) => {
+                const next = {
+                    ...r,
+                    score: r.rerankScore,
+                    postRerankRank: i + 1,
+                };
+                // A7 recall-trace: F6 reranker pass (reorder + rescale; not a scalar
+                // multiply, so no multiplier field). Only when --why.
+                if (showWhy) {
+                    next.rerankTrace = [
+                        ...(r.rerankTrace ?? []),
+                        { stage: 'reranker', scoreBefore: r.score, scoreAfter: r.rerankScore },
+                    ];
+                }
+                return next;
+            });
             results = [...withPostRank, ...tail];
         }
     }
@@ -1008,7 +1046,23 @@ async function cmdRecall(hippoRoot, query, flags) {
     const goalTag = flags['goal'] !== undefined ? String(flags['goal']).trim() : '';
     if (goalTag) {
         results = results
-            .map((r) => (r.entry.tags?.includes(goalTag) ? { ...r, score: r.score * 1.5 } : r))
+            .map((r) => {
+            if (!r.entry.tags?.includes(goalTag))
+                return r;
+            const boosted = { ...r, score: r.score * 1.5 };
+            // A7 recall-trace: the explicit `--goal <tag>` boost is a public CLI
+            // re-ranker (score *= 1.5) and is mutually exclusive with the session
+            // goal-stack boost below, so it must record its OWN step or `--why
+            // --goal` produces no ranking line (codex review). Stage `goal`
+            // (explicit flag) is distinct from `goal-boost` (session stack).
+            if (showWhy) {
+                boosted.rerankTrace = [
+                    ...(r.rerankTrace ?? []),
+                    { stage: 'goal', multiplier: 1.5, scoreBefore: r.score, scoreAfter: r.score * 1.5, note: `--goal ${goalTag}` },
+                ];
+            }
+            return boosted;
+        })
             .sort((a, b) => b.score - a.score);
     }
     // dlPFC depth (B3, v0.38; lifted v1.7.4 into applyGoalStackBoost). When
@@ -1022,16 +1076,31 @@ async function cmdRecall(hippoRoot, query, flags) {
         : process.env.HIPPO_SESSION_ID ?? '').trim();
     if (sessionId && goalTag === '') {
         const dbForGoals = openHippoDb(hippoRoot);
+        // A7 recall-trace: goal-boost is the shared helper, not an inline map. It
+        // writes its steps into this SEPARATE accumulator (keyed by entry id), NOT
+        // onto the row (the helper strips internal markers on re-spread). Only
+        // allocated under --why.
+        const goalBoostTrace = showWhy ? new Map() : undefined;
         try {
             results = applyGoalStackBoost(dbForGoals, results, {
                 sessionId,
                 tenantId,
                 limit,
+                ...(goalBoostTrace ? { trace: goalBoostTrace } : {}),
             });
         }
         finally {
             closeHippoDb(dbForGoals);
         }
+        // Merge the accumulated goal-boost steps onto the matching SearchResult.
+        if (goalBoostTrace && goalBoostTrace.size > 0) {
+            results = results.map((r) => {
+                const step = goalBoostTrace.get(r.entry.id);
+                if (!step)
+                    return r;
+                return { ...r, rerankTrace: [...(r.rerankTrace ?? []), step] };
+            });
+        }
     }
     // Pineal salience MVP (RESEARCH.md §"AI Pineal Gland — Intuition and Awareness
     // Module"). When --salience-threshold T is set (T > 0), memories whose
@@ -1061,7 +1130,17 @@ async function cmdRecall(hippoRoot, query, flags) {
             if (count >= T)
                 return r;
             const mult = Math.max(0.5, count / T);
-            return { ...r, score: r.score * mult };
+            const next = { ...r, score: r.score * mult };
+            // A7 recall-trace: pineal salience (retrieval_count) down-weight. The
+            // stage names the ACTUAL transform (retrieval_count, not goal-stack).
+            // Only when --why.
+            if (showWhy) {
+                next.rerankTrace = [
+                    ...(r.rerankTrace ?? []),
+                    { stage: 'retrieval-count-downweight', multiplier: mult, scoreBefore: r.score, scoreAfter: next.score },
+                ];
+            }
+            return next;
         })
             .sort((a, b) => b.score - a.score);
     }
@@ -1389,6 +1468,10 @@ async function cmdRecall(hippoRoot, query, flags) {
                 if (explanation.envelope) {
                     base.envelope = explanation.envelope;
                 }
+                // A7 recall-trace: emit the ordered lifecycle re-ranking steps.
+                if (r.rerankTrace && r.rerankTrace.length > 0) {
+                    base.rerankTrace = r.rerankTrace;
+                }
             }
             return base;
         });
@@ -1513,6 +1596,17 @@ async function cmdRecall(hippoRoot, query, flags) {
                     console.log(`    session_id: ${env.session_id}`);
                 console.log(`    confidence: ${env.confidence}`);
             }
+            // A7 recall-trace: render the ordered lifecycle re-ranking chain, e.g.
+            // "ranking: base 0.420 -> interference x0.3 -> 0.126 -> goal-boost x1.5 -> 0.189".
+            if (r.rerankTrace && r.rerankTrace.length > 0) {
+                const parts = [`base ${fmt(r.rerankTrace[0].scoreBefore, 3)}`];
+                for (const step of r.rerankTrace) {
+                    const mult = step.multiplier !== undefined ? ` x${fmt(step.multiplier, 2)}` : '';
+                    parts.push(`${step.stage}${mult}`);
+                    parts.push(fmt(step.scoreAfter, 3));
+                }
+                console.log(`    ranking: ${parts.join(' -> ')}`);
+            }
         }
         console.log();
         console.log(e.content);
@@ -2262,6 +2356,10 @@ export function renderSleepResult(result) {
     if (result.ambient) {
         console.log(`\n${renderAmbientSummary(result.ambient)}`);
     }
+    if (result.graph && result.graph.tenants > 0) {
+        const { tenants, entities, relations } = result.graph;
+        console.log(`\nGraph: rebuilt ${tenants} tenant${tenants === 1 ? '' : 's'} (${entities} entities, ${relations} relations).`);
+    }
 }
 async function cmdSleepCore(hippoRoot, flags) {
     requireInit(hippoRoot);