hippo-memory 0.28.0 → 0.29.1

package/README.md

@@ -60,6 +60,17 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
+### What's new in v0.29.1
+
+- **Raise default `pinnedInject.budget` to 1500.** Smoke-testing on a real 10-pinned-memory store showed 500 tokens truncated new invariants off the bottom. 1500 matches `defaultContextBudget` and fits typical mature installs. Explicit `.hippo/config.json` overrides are untouched; only the default changes.
+
+### What's new in v0.29.0
+
+- **Mid-session pinned re-injection (Claude Code).** Pinned memories now re-enter context every turn via a new `UserPromptSubmit` hook — not just at SessionStart — so invariants survive long sessions where Opus 4.7 might otherwise forget them. `hippo context --pinned-only --format additional-context` is the command the hook runs; it's read-only so retrieval_count doesn't inflate. Existing users must re-run `hippo hook install claude-code` to pick it up. Opt out with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
+- **Replay consolidation pass.** `hippo sleep` now rehearses 5 high-value memories per cycle (weighted by outcome feedback, emotional valence, under-rehearsal, idle time, strength). Closes the "replay" gap in the 7 hippocampal mechanisms. Non-destructive; opt out with `{"replay":{"count":0}}`.
+- **Model profile benchmark (null result).** New reusable eval harness at `evals/model-profile-bench.json` + `scripts/run-model-profile-bench.mjs` measures invariant honor, hallucination guard, noise rejection, and contradiction rejection. 4.6 and 4.7 both score 100% with hippo context injection — no per-model profile tuning needed. See `docs/plans/2026-04-21-phase-a-decision.md`.
+- **Physics soak test harness.** `scripts/soak-test.mjs` + 10 synthetic workload profiles. All 10 bounded at 100-tick smoke scale; grant-scale 100hr runs are separate follow-up work.
+
 ### What's new in v0.28.0
 
 - **Budget saturation fix.** Large memories (14k+ chars) no longer starve retrieval. New `minResults` option guarantees at least N results regardless of token budget. `hippo recall <q> --min-results 5`.
@@ -748,7 +759,7 @@ No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 If you prefer explicit control:
 
 ```bash
-hippo hook install claude-code   # patches CLAUDE.md + adds SessionStart/SessionEnd hooks
+hippo hook install claude-code   # patches CLAUDE.md + adds SessionStart/SessionEnd + UserPromptSubmit hooks
 hippo hook install codex         # optional repair/manual run: patches AGENTS.md + wraps the detected Codex launcher
 hippo hook install cursor        # patches .cursorrules
 hippo hook install openclaw      # patches AGENTS.md
@@ -760,7 +771,10 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
 2. Run `hippo remember "<lesson>" --error` on errors
 3. Run `hippo outcome --good` on completion
 
-For Claude Code, it also adds a Stop hook to `~/.claude/settings.json` so `hippo sleep` runs automatically when the session exits.
+For Claude Code, it also adds:
+- a `SessionEnd` hook so `hippo sleep` runs automatically when the session exits
+- a `SessionStart` hook that prints the previous session's consolidation output
+- a `UserPromptSubmit` hook that re-injects pinned memories (`hippo remember <text> --pin`) into every turn's context — so invariants survive long sessions where Opus 4.7 might otherwise "forget" them. Budget: 500 tokens per turn, skipped entirely when no pinned memories exist. Opt out with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
 
 To remove: `hippo hook uninstall claude-code`
 
@@ -874,7 +888,7 @@ For how these mechanisms connect to LLM training, continual learning, and open r
 | Auto-hook install | Yes | No | No | No |
 | MCP server | Yes | Yes | No | No |
 | Zero dependencies | Yes | No (ChromaDB) | No | No |
-| LongMemEval R@5 (retrieval) | 74.0% (BM25 only) | 96.6% (raw) / 100% (reranked) | ~49-85% | N/A |
+| LongMemEval R@5 (retrieval) | 73.8% (hybrid, v0.28) | 96.6% (raw) / 100% (reranked) | ~49-85% | N/A |
 | Git-friendly | Yes | No | No | Yes |
 | Framework agnostic | Yes | Yes | Partial | Yes |
 
@@ -890,28 +904,30 @@ Two benchmarks testing two different things. Full details in [`benchmarks/`](ben
 
 [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) is the industry-standard benchmark: 500 questions across 5 memory abilities, embedded in 115k+ token chat histories.
 
-**Hippo v0.11.0 results (BM25 only, zero dependencies):**
+**Hippo v0.28.0 results (hybrid BM25 + cosine, full 500 questions):**
+
+| Metric | v0.28 | v0.11 (BM25 only) |
+|--------|-------|-------------------|
+| Recall@1 | 46.6% | 50.4% |
+| Recall@3 | **67.0%** | 66.6% |
+| Recall@5 | 73.8% | 74.0% |
+| Recall@10 | 81.0% | 82.6% |
+| Answer in content@5 | **49.6%** | 46.6% |
 
-| Metric | Score |
-|--------|-------|
-| Recall@1 | 50.4% |
-| Recall@3 | 66.6% |
-| Recall@5 | 74.0% |
-| Recall@10 | 82.6% |
-| Answer in content@5 | 46.6% |
+| Question Type | Count | R@5 | R@10 |
+|---------------|-------|-----|------|
+| single-session-assistant | 56 | 100.0% | 100.0% |
+| knowledge-update | 78 | 89.7% | 96.2% |
+| multi-session | 133 | 72.2% | 82.0% |
+| temporal-reasoning | 133 | 72.9% | 78.9% |
+| single-session-user | 70 | 62.9% | 71.4% |
+| single-session-preference | 30 | 20.0% | 33.3% |
 
-| Question Type | Count | R@5 |
-|---------------|-------|-----|
-| single-session-assistant | 56 | 94.6% |
-| knowledge-update | 78 | 88.5% |
-| temporal-reasoning | 133 | 73.7% |
-| multi-session | 133 | 72.2% |
-| single-session-user | 70 | 65.7% |
-| single-session-preference | 30 | 26.7% |
+For context: MemPalace scores 96.6% (raw) using ChromaDB embeddings + spatial indexing. Hippo v0.28 achieves 73.8% R@5 with hybrid BM25 + cosine. Hybrid scoring trades a little R@1 accuracy for better top-5 content relevance (answer_in_content@5 +3pp vs v0.11).
 
-For context: MemPalace scores 96.6% (raw) using ChromaDB embeddings + spatial indexing. Hippo achieves 74.0% using BM25 keyword matching alone with zero runtime dependencies. Adding embeddings via `hippo embed` (optional `@xenova/transformers` peer dep) enables hybrid search and should close the gap.
+Hippo's strongest categories (single-session-assistant 100% R@5, knowledge-update 89.7%) are where keyword overlap between question and stored content is highest. The weakest (preference 20%) involves indirect references that need deeper semantic understanding.
 
-Hippo's strongest categories (knowledge-update 88.5%, single-session-assistant 94.6%) are the ones where keyword overlap between question and stored content is highest. The weakest (preference 26.7%) involves indirect references that need semantic understanding.
+> Note: v0.28 R@10 is 1.6pp below v0.11's BM25-only result. The earlier v0.27 benchmark showed an apparent 35pp regression — that was a methodology bug (budget-limited retrieval vs unlimited), fixed in v0.28 with the `minResults` option. See [`evals/README.md`](evals/README.md) for the full investigation and per-type breakdown.
 
 ```bash
 cd benchmarks/longmemeval
@@ -948,7 +964,7 @@ node run.mjs --adapter all
 Issues and PRs welcome. Before contributing, run `hippo status` in the repo root to see the project's own memory.
 
 The interesting problems:
-- **Improve LongMemEval score.** Current R@5 is 74.0% with BM25 only. Adding embeddings (`hippo embed`) and hybrid search should close the gap toward MemPalace's 96.6%.
+- **Improve LongMemEval score.** Current R@5 is 73.8% with hybrid BM25 + cosine (v0.28). Gap to MemPalace's 96.6% likely needs better chunking, reranking, or semantic compression — not just more of the same retrieval.
 - Better consolidation heuristics (LLM-powered merge vs current text overlap)
 - Web UI / dashboard for visualizing decay curves and memory health
 - Optimal decay parameter tuning from real usage data

package/dist/cli.js

@@ -299,6 +299,9 @@ function autoInstallHooks(quiet) {
             if (result.installedSessionStart) {
                 console.log(`   Auto-installed hippo last-sleep SessionStart hook in ${hook} settings`);
             }
+            if (result.installedUserPromptSubmit) {
+                console.log(`   Auto-installed hippo pinned-inject UserPromptSubmit hook in ${hook} settings`);
+            }
             if (result.migratedFromStop) {
                 console.log(`   Migrated legacy Stop hook → SessionEnd (no longer runs every turn)`);
             }
@@ -2102,7 +2105,41 @@ async function cmdContext(hippoRoot, args, flags) {
     const recentSessionEvents = activeSnapshot?.session_id
         ? listSessionEvents(hippoRoot, { session_id: activeSnapshot.session_id, limit: 5 })
         : [];
-    if (query === '*') {
+    // --pinned-only: restrict to pinned entries only. Used by the Claude Code
+    // UserPromptSubmit hook so invariants stay in context every turn.
+    const pinnedOnly = flags['pinned-only'] === true;
+    if (pinnedOnly) {
+        const pinnedCfg = loadConfig(hippoRoot);
+        if (!pinnedCfg.pinnedInject.enabled)
+            return; // user disabled via config
+        // Effective budget: explicit --budget wins over config.
+        const effBudget = flags['budget'] !== undefined ? budget : pinnedCfg.pinnedInject.budget;
+        const pinnedLocal = localEntries.filter((e) => e.pinned);
+        const pinnedGlobal = globalEntries.filter((e) => e.pinned);
+        if (pinnedLocal.length === 0 && pinnedGlobal.length === 0)
+            return; // zero output
+        const nowP = new Date();
+        const rankedPinned = [
+            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: false })),
+            ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
+        ]
+            .map(({ entry, isGlobal }) => ({
+            entry,
+            score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
+            tokens: estimateTokens(entry.content),
+            isGlobal,
+        }))
+            .sort((a, b) => b.score - a.score);
+        let usedP = 0;
+        for (const r of rankedPinned) {
+            if (usedP + r.tokens > effBudget)
+                continue;
+            selectedItems.push(r);
+            usedP += r.tokens;
+        }
+        totalTokens = usedP;
+    }
+    else if (query === '*') {
         // No query: return strongest memories by strength, up to budget
         const now = new Date();
         const localRanked = localEntries
@@ -2165,17 +2202,26 @@ async function cmdContext(hippoRoot, args, flags) {
     }
     if (selectedItems.length === 0 && !activeSnapshot && recentSessionEvents.length === 0)
         return;
-    // Mark retrieved and persist
-    const toUpdate = selectedItems.map((s) => s.entry);
-    const updatedEntries = markRetrieved(toUpdate);
-    const localIndex = loadIndex(hippoRoot);
-    for (const u of updatedEntries) {
-        const targetRoot = localIndex.entries[u.id] ? hippoRoot : (hasGlobal ? globalRoot : hippoRoot);
-        writeEntry(targetRoot, u);
+    // --pinned-only is called by the UserPromptSubmit hook every turn. Treat it
+    // as read-only so pinned memories don't inflate retrieval_count or extend
+    // their half_life by 2 days * turn-count over a long session.
+    let updatedEntries;
+    if (pinnedOnly) {
+        updatedEntries = selectedItems.map((s) => s.entry);
+    }
+    else {
+        // Mark retrieved and persist
+        const toUpdate = selectedItems.map((s) => s.entry);
+        updatedEntries = markRetrieved(toUpdate);
+        const localIndex = loadIndex(hippoRoot);
+        for (const u of updatedEntries) {
+            const targetRoot = localIndex.entries[u.id] ? hippoRoot : (hasGlobal ? globalRoot : hippoRoot);
+            writeEntry(targetRoot, u);
+        }
+        localIndex.last_retrieval_ids = updatedEntries.map((u) => u.id);
+        saveIndex(hippoRoot, localIndex);
+        updateStats(hippoRoot, { recalled: selectedItems.length });
     }
-    localIndex.last_retrieval_ids = updatedEntries.map((u) => u.id);
-    saveIndex(hippoRoot, localIndex);
-    updateStats(hippoRoot, { recalled: selectedItems.length });
     const format = String(flags['format'] ?? 'markdown');
     const framing = String(flags['framing'] ?? 'observe');
     if (format === 'json') {
@@ -2190,6 +2236,38 @@ async function cmdContext(hippoRoot, args, flags) {
         }));
         console.log(JSON.stringify({ query, activeSnapshot, recentSessionEvents, memories: output, tokens: totalTokens }));
     }
+    else if (format === 'additional-context') {
+        // Claude Code UserPromptSubmit hook JSON shape. Capture the markdown that
+        // printContextMarkdown would write and wrap it as `additionalContext`.
+        const lines = [];
+        const realLog = console.log;
+        console.log = (...parts) => { lines.push(parts.map(String).join(' ')); };
+        try {
+            if (activeSnapshot)
+                printActiveTaskSnapshot(activeSnapshot);
+            if (recentSessionEvents.length > 0)
+                printSessionEvents(recentSessionEvents);
+            printContextMarkdown(selectedItems.map((r) => ({
+                entry: updatedEntries.find((u) => u.id === r.entry.id) ?? r.entry,
+                score: r.score,
+                tokens: r.tokens,
+                isGlobal: r.isGlobal ?? false,
+            })), totalTokens, framing);
+        }
+        finally {
+            console.log = realLog;
+        }
+        const textBlock = lines.join('\n');
+        if (!textBlock.trim())
+            return;
+        const payload = {
+            hookSpecificOutput: {
+                hookEventName: 'UserPromptSubmit',
+                additionalContext: textBlock,
+            },
+        };
+        process.stdout.write(JSON.stringify(payload));
+    }
     else {
         if (activeSnapshot) {
             printActiveTaskSnapshot(activeSnapshot);
@@ -2783,6 +2861,9 @@ function cmdHook(args, flags) {
             if (result.installedSessionStart) {
                 console.log(`Installed hippo last-sleep SessionStart hook in ${result.target} settings`);
             }
+            if (result.installedUserPromptSubmit) {
+                console.log(`Installed hippo pinned-inject UserPromptSubmit hook in ${result.target} settings`);
+            }
             if (result.migratedFromStop) {
                 console.log(`Migrated legacy Stop hook → SessionEnd (was running every turn; now fires once on session exit)`);
             }
@@ -2873,6 +2954,8 @@ function cmdSetup(flags) {
             bits.push('SessionEnd (session-end)');
         if (result.installedSessionStart)
             bits.push('SessionStart');
+        if (result.installedUserPromptSubmit)
+            bits.push('UserPromptSubmit (pinned-inject)');
         if (result.migratedFromStop)
             bits.push('migrated legacy Stop');
         if (result.migratedSplitSessionEnd)
@@ -2968,7 +3051,8 @@ function installClaudeCodeSessionEndHook() {
     const result = installJsonHooks('claude-code');
     return {
         installed: result.installedSessionEnd ||
-            result.installedSessionStart,
+            result.installedSessionStart ||
+            result.installedUserPromptSubmit,
         migratedFromStop: result.migratedFromStop,
     };
 }
@@ -3104,7 +3188,8 @@ Commands:
   context                  Smart context injection for AI agents
     --auto                 Auto-detect task from git state
     --budget <n>           Token budget (default: 1500)
-    --format <fmt>         Output format: markdown (default) or json
+    --pinned-only          Only inject pinned memories (used by UserPromptSubmit hook)
+    --format <fmt>         Output format: markdown (default), json, or additional-context (Claude Code hook JSON)
     --framing <mode>       Framing: observe (default), suggest, assert
   sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)
     --dry-run              Preview without writing