hippo-memory 1.44.0 → 1.46.0

package/README.md

@@ -1,6 +1,6 @@
 # 🦛 Hippo
 
-**The secret to good memory isn't remembering more. It's knowing what to forget.**
+**Hippo learns what is wrong and stops repeating it.** Good memory is knowing what to forget: what turned out wrong, what got replaced, what nobody used.
 
 [![npm](https://img.shields.io/npm/v/hippo-memory)](https://npmjs.com/package/hippo-memory)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
@@ -10,7 +10,7 @@
   <img src="./assets/hippo-init.svg" alt="hippo init --scan ~ — initializing memory across all repos" width="720">
 </p>
 
-A memory layer for AI agents. Modeled on the hippocampus. Decay by default, strength through use, provenance on every memory. SQLite under the hood, zero runtime deps, works with every CLI agent you have.
+A memory layer for AI agents. Mark a memory wrong and it stops coming back. A newer fact replaces the old one. Memories you use get stronger. Provenance on every memory. SQLite under the hood, zero runtime deps, works with every CLI agent you have.
 
 ```bash
 npm install -g hippo-memory && hippo init --scan ~
@@ -18,6 +18,8 @@ npm install -g hippo-memory && hippo init --scan ~
 
 One command. Every git repo on your machine gets memory.
 
+Having an AI agent install it? Point it at [llms-install.md](llms-install.md): it installs, wires hippo into the agents it finds, and verifies with `hippo doctor`.
+
 ```
 Works with:    Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, any MCP client
 Imports from:  ChatGPT, Claude (CLAUDE.md), Cursor (.cursorrules), Slack, markdown
@@ -31,7 +33,7 @@ Dependencies:  Zero runtime deps. Node.js 22.16+. Optional embeddings: bring-you
 
 Most "AI memory" systems save everything and search later. That's storage with semantic search bolted on. It's why your agent kept hitting the same deploy bug last week. And the week before. The system saw the failure four times. It had no way to know it should remember.
 
-Hippo applies the thing brains have been getting right for 500 million years. Memories decay over time. Retrieval makes them stronger. Three biological layers (buffer, episodic, semantic) consolidate during sleep. Hard lessons stick because you used them. Trivia fades because you didn't.
+Hippo learns from outcomes. When a recalled memory turns out wrong, mark it bad and it drops out of the top results. When a fact changes, the new version supersedes the old one. Memories you keep using get stronger. Those are the parts we measured helping ([mechanism audit, round 2](https://github.com/kitfunso/hippo-memory/pull/232)). The design borrows from the hippocampus (decay, three layers, sleep consolidation), but that is inspiration. We have not measured decay or sleep making recall better.
 
 It also fixes the portability problem. Your ChatGPT memories don't travel to Claude. Your `.cursorrules` don't travel to Codex. Hippo is one process behind every agent. CLAUDE.md, Cursor rules, ChatGPT exports, Slack history, all in one SQLite store, all queryable from any tool that speaks MCP or HTTP.
 
@@ -49,7 +51,7 @@ claim we retracted.
 - **R@1 0.41 to 0.62 with `hippo recall "<query>" --reranker jev`** on a private 300-query developer store ([full eval](docs/evals/2026-09-19-jev-reranker.md)). The opt-in [TypeSafe Jev](https://typesafe.ai) reranker, off by default, about 0.0004 USD a recall. 2000-draw paired bootstrap; the margin held in 20 of 20 seeds and a permutation null reached it in 0 of 200 runs. Ranking only: three graded tests did **not** show a better answer rate than the free local cross-encoder, and that negative result is in the same doc. What it buys today is a shorter context, 2 memories ranked by Jev answering as well as 5 ranked by the cross-encoder.
 - **10 of 10 incident scenarios beat transcript replay** on a staged Slack corpus ([benchmarks/e1.3/](benchmarks/e1.3/)). Recall surfaces the cause faster than scrolling the last N messages.
 - **0 outbound HTTP** on the 1000-event ingestion smoke. Proven by a `globalThis.fetch` spy that throws on call, not a hardcoded zero. The default recall path makes no network call either; opt-in features such as the Jev reranker above, the LLM reranker and the API embedders do.
-- **926 tests, real DB, zero mocks.** Project rule. The one mocks-vs-prod divergence that bit us early is now the constraint that kept the next ten releases honest.
+- **3,500+ tests on a real database.** No module mocks and no mocked store; only paid network calls are stubbed. Project rule. The one mocks-vs-prod divergence that bit us early is now the constraint that kept the next ten releases honest.
 - **dlPFC goal-conditioned cluster discrimination, 3/3 queries pass** — full goal stack with policy weighting and lifespan-windowed outcome propagation. Per-goal lift on a 3-cluster fixture where BM25 alone cannot discriminate; deterministic test in [`benchmarks/micro/results/b3-depth.json`](benchmarks/micro/results/b3-depth.json).
 
 ---
@@ -254,6 +256,8 @@ hippo recall "data pipeline" --why --limit 5
 
 Input enters the buffer. Important things get encoded into episodic memory. During "sleep," repeated episodes compress into semantic patterns. Weak memories decay and disappear.
 
+The store is SQLite (`.hippo/hippo.db`). The markdown files and `index.json` are mirrors written after each change. From 1.46.0, `index.json` is no longer refreshed on every write; it comes only from an explicit export, so read the store through the CLI, the MCP server or the HTTP API.
+
 ```mermaid
 flowchart TD
     I[New information] --> B[Buffer<br/>session-only, no decay]
@@ -295,16 +299,15 @@ sequenceDiagram
 
 ### Decay by default
 
-Every memory has a half-life. 7 days by default. Persistence is earned.
+Every memory has a half-life: 365 days by default. Until 1.46.0 the default was 7 days. A pre-registered evaluation found 7 days lost the current version of a fact far more often: it was in the top five 29% of the time at 7 days and 75% at 365 ([result](docs/evals/2026-09-24-decay-default-result.md)). 730 days and decay off both tied with 365. So 365 was not tuned: it is the tested value that tied with the others, and on that test decay made no measurable difference to recall. `hippo sleep` moves memories still on the old 7-day base to the new one, once, and records each move in the audit log. Set `defaultHalfLifeDays` in `.hippo/config.json` to choose your own.
 
 ```bash
 hippo remember "always check cache contents after refresh"
-# stored with half_life: 7d, strength: 1.0
+# stored with half_life: 365d, strength: 1.0
 
-# 14 days later with no retrieval:
+# two years later with no retrieval:
 hippo inspect mem_a1b2c3
 # strength: 0.25  (decayed by 2 half-lives)
-# at risk of removal on next sleep
 ```
 
 ---
@@ -316,12 +319,12 @@ Use it or lose it. Each recall boosts the half-life by 2 days.
 ```bash
 hippo recall "cache issues"
 # finds mem_a1b2c3, retrieval_count: 1 -> 2
-# half_life extended: 7d -> 9d
+# half_life extended: 365d -> 367d
 # strength recalculated from retrieval timestamp
 
 hippo recall "cache issues"   # again next week
 # retrieval_count: 2 -> 3
-# half_life: 9d -> 11d
+# half_life: 367d -> 369d
 # this memory is learning to survive
 ```
 
@@ -452,6 +455,8 @@ hippo sleep
 
 Three or more related episodes get merged into a single semantic memory. The originals decay. The pattern survives.
 
+Sleep keeps the store tidy. It has not been shown to improve recall. In round 2 of the mechanism audit, a slept LongMemEval store scored 3.6 points lower at hit@5 than the same store never slept, and no scorer showed sleep helping ([PR #232](https://github.com/kitfunso/hippo-memory/pull/232)).
+
 **Experimental: learned memory-value rescue (opt-in, default off).** With
 `{"memoryValue":{"enabled":true}}` in `.hippo/config.json`, sleep consults a learned
 linear memory-value scorer before deleting a decayed memory: a memory that scores in the
@@ -465,6 +470,34 @@ usage, NOT real usage value — treat the flag as an experiment, not a recommend
 Tenants with fewer than 10 non-pinned memories never rescue (rank statistics are noise at
 tiny scale).
 
+**Faded memories go dormant, not gone (on by default).** Sleep moves a memory that faded
+below the decay threshold into a dormant store instead of deleting it. A dormant memory
+leaves recall and context exactly like a deleted one and sits out every later sleep, so
+your agent's context stays as lean as before, but nothing is lost:
+
+```bash
+hippo dormant                     # list, newest first (--json, --limit <n>)
+hippo dormant "staging hostname"  # search: every term must match
+hippo dormant restore mem_a1b2c3  # back to active memory, as if just recalled
+hippo dormant forget mem_a1b2c3   # delete for good
+```
+
+A restored memory comes back with a fresh recall clock, so it gets a full half-life before
+it can fade again, and every restore is logged (`hippo audit list --op dormant_restore`) as
+a "forgot it, then needed it" signal. Two guardrails: a faded memory that the secret
+detector flags is deleted, never kept dormant, and a dormant memory nobody restores within
+`dormant.retentionDays` (default 180, `0` keeps them forever) is deleted for good. Rejecting
+a value (`hippo reject`) removes its dormant copies too. To delete faded memories straight
+away as before, set `{"dormant":{"enabled":false}}` in `.hippo/config.json`. Sleep never
+removes pinned memories or raw receipts (Slack, GitHub, vault imports) either way, and
+duplicate removal and junk cleanup still delete.
+
+**See what memory costs in tokens.** Every block of memory text hippo hands an agent (the
+per-prompt hook, `hippo context`, `hippo recall`, the MCP tools, the HTTP API) is recorded
+in a token ledger: counts, surface and session, never the text. `hippo tokens` shows the
+totals for the last 30 days (`--days`, `--json`). Counts are estimates (characters / 4), the
+same estimate every budget uses. Rows older than 90 days are pruned.
+
 ---
 
 ### Outcome feedback
@@ -486,6 +519,8 @@ hippo outcome --bad
 
 Outcomes are cumulative. A memory with 5 positive outcomes and 0 negative has a reward factor of ~1.42, making its effective half-life 42% longer. A memory with 0 positive and 3 negative has a factor of ~0.63, decaying nearly twice as fast. Mixed outcomes converge toward neutral (1.0).
 
+This is the mechanism with the clearest measured win. On the synthetic E1 test, plain BM25 plus the outcome nudge cut how often a marked-bad memory stayed in the top five from 71.9% to 0.0% ([mechanism audit, round 2](https://github.com/kitfunso/hippo-memory/pull/232)). Every mark in E1 is correct; real marks are noisier, since `--bad` marks the whole recall batch.
+
 ---
 
 ### Token budgets
@@ -590,6 +625,11 @@ hippo watch "npm run build"
 | `hippo outcome --id <id> --good` | Target a specific memory |
 | `hippo inspect <id>` | Full detail on one memory |
 | `hippo forget <id>` | Force remove a memory |
+| `hippo dormant [<query>]` | List faded memories sleep kept instead of deleting |
+| `hippo dormant restore <id>` | Bring a dormant memory back to active memory |
+| `hippo dormant forget <id>` | Delete a dormant memory permanently |
+| `hippo doctor [--json]` | Check the install: Node, store, schema, sleep, agent hooks; each problem names its fix |
+| `hippo tokens [--days n]` | Estimated tokens of memory text handed to agents, per surface, and what skipping unchanged hook blocks saved |
 | `hippo embed` | Embed all memories for semantic search |
 | `hippo embed --status` | Show embedding coverage |
 | `hippo watch "<command>"` | Run command, auto-learn from failures |
@@ -681,9 +721,11 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
 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 runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the last 5 writes, so fresh same-session lessons appear on the next prompt before you pin them. Opt out with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
+- a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the last 5 writes, so fresh same-session lessons appear on the next prompt before you pin them. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. `{"pinnedInject":{"skipUnchanged":false}}` sends it every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
 - a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It saves a working-state snapshot (task/summary/next step) and extracts durable memories from the tail, so mid-session compaction can't drop them.
 - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot plus the recent session trail back into context right after compaction.
+- a `PostCompact` hook that runs `hippo post-compact`, which tells you what was saved ("Hippo saved your task snapshot and 2 new memories before compacting"). It prints nothing when nothing was saved.
+- a `PostToolUseFailure` hook that runs `hippo capture-error`, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once.
 
 To remove: `hippo hook uninstall claude-code`
 
@@ -723,7 +765,9 @@ Add to your MCP config (e.g. `.cursor/mcp.json` or `claude_desktop_config.json`)
 }
 ```
 
-Exposes tools: `hippo_recall`, `hippo_remember`, `hippo_outcome`, `hippo_context`, `hippo_status`, `hippo_learn`, `hippo_wm_push`.
+No global install needed: `"command": "npx", "args": ["-y", "hippo-memory", "mcp"]` works too. With no store anywhere, the first tool call creates the global store (`~/.hippo`); `hippo init` in a project adds a project store. Check any install with `hippo doctor`.
+
+Exposes 13 tools: `hippo_recall`, `hippo_assemble`, `hippo_drill`, `hippo_remember`, `hippo_outcome`, `hippo_context`, `hippo_status`, `hippo_learn`, `hippo_conflicts`, `hippo_resolve`, `hippo_share`, `hippo_peers`, `hippo_predict_baserate`.
 
 ### OpenClaw Plugin
 
@@ -745,7 +789,7 @@ Plugin docs: [extensions/openclaw-plugin/](extensions/openclaw-plugin/). Integra
 
 ### Claude Code Plugin
 
-Plugin with SessionStart/Stop hooks and error auto-capture. See [extensions/claude-code-plugin/](extensions/claude-code-plugin/).
+Plugin with session, prompt and compaction hooks plus error auto-capture. See [extensions/claude-code-plugin/](extensions/claude-code-plugin/).
 
 Full integration details: [integrations/](integrations/)
 
@@ -753,11 +797,11 @@ Full integration details: [integrations/](integrations/)
 
 ## The Neuroscience
 
-Hippo is modeled on seven properties of the human hippocampus. Not metaphorically. Literally.
+Hippo's design borrows seven properties of the human hippocampus. This section is design inspiration, not measured benefit. For what we measured, see the Receipts and [PR #232](https://github.com/kitfunso/hippo-memory/pull/232).
 
 **Why two stores?** The brain uses a fast hippocampal buffer + a slow neocortical store (Complementary Learning Systems theory, McClelland et al. 1995). If the neocortex learned fast, new information would overwrite old knowledge. The buffer absorbs new episodes; the neocortex extracts patterns over time.
 
-**Why does decay help?** New neurons born in the dentate gyrus actively disrupt old memory traces (Frankland et al. 2013). This is adaptive: it reduces interference from outdated information. Forgetting isn't failure. It's maintenance.
+**Why decay at all?** In the brain, new neurons born in the dentate gyrus disrupt old memory traces (Frankland et al. 2013), which may reduce interference from outdated information. That is why hippo has decay. In hippo's own tests, age-based decay made no measurable difference to recall: at the 365-day default it tied with decay switched off. The forgetting that measured helpful is by evidence: a bad outcome mark, or a newer fact superseding an old one.
 
 **Why do errors stick?** The amygdala modulates hippocampal consolidation based on emotional significance. Fear and error signals boost encoding. Your first production incident is burned into memory. Your 200th uneventful deploy isn't.
 
@@ -799,16 +843,16 @@ The AI-memory category matured fast in 2026. Hippo's specific take — bio-decay
 | Auto-hook install | Yes | No | No | No | No | No | No | No | No | No |
 | MCP server | Yes | Yes | No | No | Yes (stdio + HTTP/OAuth) | Partial (managed) | Yes (via Letta Code) | Yes (first-party Claude/LangGraph) | Yes | ? |
 | Zero runtime deps | Yes | No (ChromaDB) | No | No | No (PGLite or PG+pgvector) | No (managed service) | No (Python deps) | No (Python deps) | Yes (single Rust binary) | No (managed + OSS) |
-| LongMemEval (best published) | 98.6% default / 99.8% voyage R@5 (s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | ~49-85% R@5 | N/A | 97.6-97.9% R@5 (s_cleaned\*) | N/A (LoCoMo 80.3%) | N/A | N/A | 88.78% overall accuracy w/ reader\*\* | 83.00% overall\*\* (LoCoMo 93.05%, HaluMem 93.04%) |
+| LongMemEval (best published) | 98.0% local / 99.8% voyage R@5 (s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | ~49-85% R@5 | N/A | 97.6-97.9% R@5 (s_cleaned\*) | N/A (LoCoMo 80.3%) | N/A | N/A | 88.78% overall accuracy w/ reader\*\* | 83.00% overall\*\* (LoCoMo 93.05%, HaluMem 93.04%) |
 | Git-friendly | Yes | No | No | Yes | Yes | No | No | No | Yes (Git is the model) | ? |
 | Framework agnostic | Yes | Yes | Partial | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
 | License | MIT | (open) | Apache-2.0 | (open) | MIT | Apache-2.0 (community) | Apache-2.0 | MIT (core) | Apache-2.0 | Apache-2.0 (OSS) + cloud |
 
-\* Hippo's 98.6% (zero-dep default) and 99.8% (voyage-3-large) are on `longmemeval_s_cleaned`, per-question haystack, directly comparable to gbrain's 97.6% on the same split and metric (measured 2026-06-09, see [`docs/evals/2026-06-09-longmemeval-per-haystack-dual.md`](docs/evals/2026-06-09-longmemeval-per-haystack-dual.md)). gbrain's figure is their published claim. An older hippo number, 86.8% R@5 on `longmemeval_oracle` under pooled (non-per-haystack) retrieval, is not comparable to per-haystack figures.
+\* Hippo's 98.0% uses the free local MiniLM embedder (an optional install) and 99.8% uses voyage-3-large (measured 2026-06-09, not re-run). Both are on `longmemeval_s_cleaned` with a per-question haystack, the split and metric of gbrain's published 97.6%. Each is the best of five retrieval settings in the benchmark scripts, not `hippo recall`. At 500 questions the 95% interval is about ±1.2 points, so 98.0 and 97.6 are a tie. The June 2026 build scored 98.6; [`docs/evals/2026-09-23-longmemeval-reproduction.md`](docs/evals/2026-09-23-longmemeval-reproduction.md) has both runs. An older hippo number, 86.8% R@5 on `longmemeval_oracle` under pooled (non-per-haystack) retrieval, is not comparable to per-haystack figures.
 
 \*\* Different metric: Memoria's 88.78% and EverMind's 83% are reported as overall accuracy with a reader LLM, not retrieval R@5. Higher denominator + LLM helps. Not directly comparable to retrieval-only R@5 numbers above.
 
-Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." gbrain, Zep, and Cognee implement "extract typed entities and relationships into a knowledge graph." Letta implements "the agent edits its own memory blocks." Memoria implements "Git-style version control over the memory state itself." EverMind implements "self-evolving Skill Memory + multi-modal retrieval over hierarchical scopes." Hippo implements "forget by default, earn persistence through use." These are complementary takes, not a single-axis ranking: bio-lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
+Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." gbrain, Zep, and Cognee implement "extract typed entities and relationships into a knowledge graph." Letta implements "the agent edits its own memory blocks." Memoria implements "Git-style version control over the memory state itself." EverMind implements "self-evolving Skill Memory + multi-modal retrieval over hierarchical scopes." Hippo implements "learn what is wrong and stop repeating it." These are complementary takes, not a single-axis ranking: bio-lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
 
 ---
 
@@ -820,16 +864,16 @@ Three benchmarks testing three different things. Full details in [`benchmarks/`]
 
 [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.
 
-**Standard per-haystack result (`_s` split, measured 2026-06-09).** Each question is scored against its own ~48-session haystack, the same way gbrain and other published systems report. The v1.23.0 pluggable embedding provider lets you choose the embedder:
+**Standard per-haystack result (`_s` split; MiniLM re-measured 2026-09-23, voyage measured 2026-06-09).** Each question is scored against its own ~48-session haystack, the same way gbrain and other published systems report. The v1.23.0 pluggable embedding provider lets you choose the embedder:
 
 | Embedder | Dense-only R@5 | Best hybrid R@5 | R@1 |
 |----------|----------------|-----------------|-----|
-| MiniLM-L6 (zero-dependency default) | 96.6 | 98.6 | 89.6 |
-| voyage-3-large (opt-in) | 99.8 | 99.8 | 94.6 |
+| MiniLM-L6 (local, optional install) | 96.8 | 98.0 | 88.4 |
+| voyage-3-large (opt-in, paid) | 99.8 | 99.8 | 94.6 |
 
-gbrain reports 97.6 R@5 on this split with a paid frontier embedder. Hippo's free, local, zero-dependency default reaches 98.6. Retrieval recall on the standard task is effectively saturated, so the embedder is a swappable commodity, not the differentiator. Method and the global-pool comparison: [`docs/evals/2026-06-09-longmemeval-per-haystack-dual.md`](docs/evals/2026-06-09-longmemeval-per-haystack-dual.md).
+gbrain reports 97.6 R@5 on this split with a paid frontier embedder. Hippo reaches 98.0 with a free local embedder, a tie at 500 questions. These numbers come from the scripts in `benchmarks/longmemeval/`, which index every turn and fuse BM25 with dense ranks; they are not `hippo recall`, and a default install has no embedder. Re-measure: [`docs/evals/2026-09-23-longmemeval-reproduction.md`](docs/evals/2026-09-23-longmemeval-reproduction.md). Retrieval recall on the standard task is effectively saturated, so the embedder is a swappable commodity, not the differentiator. Method and the global-pool comparison: [`docs/evals/2026-06-09-longmemeval-per-haystack-dual.md`](docs/evals/2026-06-09-longmemeval-per-haystack-dual.md).
 
-The differentiator is what happens as one store grows. Point retrieval at a single unified memory of tens of thousands of sessions, with no pre-scoped haystack, and recall stops being free (default 47, voyage 56 on the 19,195-session `_s` store). That is where memory lifecycle (decay, consolidation, supersession) earns its keep, and it is what hippo measures next (see ROADMAP Part III).
+The differentiator is what happens as one store grows. Point retrieval at a single unified memory of tens of thousands of sessions, with no pre-scoped haystack, and recall stops being free (MiniLM 47, voyage 56 on the 19,195-session `_s` store, June 2026). That is where we expect the memory lifecycle to matter, and it is what hippo measures next (see ROADMAP Part III). It is not shown yet: in our tests so far, decay made no measurable difference and sleep cost recall. Outcome marks and supersession are what measured helpful.
 
 **Hippo v0.28.0 oracle-split results (hybrid BM25 + cosine, full 500 questions, pooled retrieval):**
 
@@ -909,7 +953,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:
-- **LongMemEval retrieval (standard task: done).** Per-question-haystack R@5 is 98.6% with the zero-dependency default and 99.8% with voyage-3-large (measured 2026-06-09), at or above the published frontier. Retrieval is no longer the gap; the lifecycle stress eval (ROADMAP Part III) is the next measurement.
+- **LongMemEval retrieval (standard task: done).** Per-question-haystack R@5 is 98.0% with the free local embedder (re-measured 2026-09-23; the June build gave 98.6) and 99.8% with voyage-3-large (measured 2026-06-09), level with the published frontier. Retrieval is no longer the gap; the lifecycle stress eval (ROADMAP Part III) is the next measurement.
 - 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/bin/hippo.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-import '../dist/cli.js';
+import { runCli } from '../dist/cli.js';
+
+runCli();

package/dist/ablation.d.ts

@@ -50,7 +50,13 @@
  *                              arms must not pass it.
  *   HIPPO_ABLATE_OUTCOME_SLOW  rewardFactor := 1 (no half-life modulation).
  *   HIPPO_ABLATE_OUTCOME_FAST  hybridSearch outcomeBoost := 1.
- *   HIPPO_FAKE_NOW             timestamp injected as the default `now` for
+ *   HIPPO_ABLATE_RECENCY       search recency factor := 1 (the creation-age
+ *                              multiplier 0.8 + 0.2*exp(-age/30d)); decay,
+ *                              strengthening and outcomes stay live.
+ *   HIPPO_EVAL_RECENCY_DAYS    a positive number replaces the 30-day scale of
+ *                              that recency factor (tuning grids only). Unset,
+ *                              zero, negative or junk values keep 30.
+ *   HIPPO_FAKE_NOW            timestamp injected as the default `now` for
  *                              strength computation and retrieval stamping
  *                              (simulated-time protocols). MUST be the exact
  *                              Date.toISOString() form
@@ -82,6 +88,9 @@ export declare function isDecayAblated(): boolean;
 export declare function isRecallBoostAblated(): boolean;
 export declare function isOutcomeSlowAblated(): boolean;
 export declare function isOutcomeFastAblated(): boolean;
+export declare function isRecencyAblated(): boolean;
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
+export declare function evalRecencyScaleDays(): number | null;
 /**
  * The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and
  * parseable, else the real clock. Callers that already take an explicit `now`

package/dist/ablation.js

@@ -50,7 +50,13 @@
  *                              arms must not pass it.
  *   HIPPO_ABLATE_OUTCOME_SLOW  rewardFactor := 1 (no half-life modulation).
  *   HIPPO_ABLATE_OUTCOME_FAST  hybridSearch outcomeBoost := 1.
- *   HIPPO_FAKE_NOW             timestamp injected as the default `now` for
+ *   HIPPO_ABLATE_RECENCY       search recency factor := 1 (the creation-age
+ *                              multiplier 0.8 + 0.2*exp(-age/30d)); decay,
+ *                              strengthening and outcomes stay live.
+ *   HIPPO_EVAL_RECENCY_DAYS    a positive number replaces the 30-day scale of
+ *                              that recency factor (tuning grids only). Unset,
+ *                              zero, negative or junk values keep 30.
+ *   HIPPO_FAKE_NOW            timestamp injected as the default `now` for
  *                              strength computation and retrieval stamping
  *                              (simulated-time protocols). MUST be the exact
  *                              Date.toISOString() form
@@ -101,11 +107,14 @@ function readFlags() {
             fakeNowMs = parsed;
         }
     }
+    const recencyDays = Number(process.env.HIPPO_EVAL_RECENCY_DAYS);
     _cache = {
         decay: isTruthy(process.env.HIPPO_ABLATE_DECAY),
         recallBoost: isTruthy(process.env.HIPPO_ABLATE_RECALL_BOOST),
         outcomeSlow: outcomeBoth || isTruthy(process.env.HIPPO_ABLATE_OUTCOME_SLOW),
         outcomeFast: outcomeBoth || isTruthy(process.env.HIPPO_ABLATE_OUTCOME_FAST),
+        recency: isTruthy(process.env.HIPPO_ABLATE_RECENCY),
+        recencyDays: Number.isFinite(recencyDays) && recencyDays > 0 ? recencyDays : null,
         fakeNowMs,
     };
     return _cache;
@@ -122,6 +131,13 @@ export function isOutcomeSlowAblated() {
 export function isOutcomeFastAblated() {
     return readFlags().outcomeFast;
 }
+export function isRecencyAblated() {
+    return readFlags().recency;
+}
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
+export function evalRecencyScaleDays() {
+    return readFlags().recencyDays;
+}
 /**
  * The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and
  * parseable, else the real clock. Callers that already take an explicit `now`

package/dist/api.d.ts

@@ -9,6 +9,8 @@
 import { type DatabaseSyncLike } from './db.js';
 import { deleteEntry, loadAllEntries, type TaskSnapshot, type SessionEvent } from './store.js';
 import { type RejectedValueRow } from './rejection.js';
+import { type DormantMemory, type ListDormantOpts } from './dormant.js';
+import { type TokenSummary, type TokenSurface } from './token-ledger.js';
 import { type SessionHandoff } from './handoff.js';
 import { type MemoryKind, type MemoryEntry } from './memory.js';
 import { auditMemories, type AuditEvent, type AuditOp } from './audit.js';
@@ -31,7 +33,7 @@ import { type AvailabilityHint } from './availability.js';
  * object carrying both the audit-log subject (formerly the string itself) and
  * a role for /v1/sleep admin gating. Audit helpers continue accepting `string`
  * — callers pass `ctx.actor.subject`. Role checks happen at the request
- * boundary (e.g. /v1/sleep), not inside api functions.
+ * boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError).
  */
 export interface Actor {
     /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
@@ -72,9 +74,14 @@ export declare class RecallContractError extends Error {
     readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
     constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);
 }
+/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
+export declare class ForbiddenError extends Error {
+    constructor(message: string);
+}
 import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
-export { passesCliRecallScopeFilter } from './recall-scope.js';
+export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
+export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from './token-ledger.js';
 export { classifyOriginProject } from './project-identity.js';
 /**
  * v39 S4: the secret half of the ambient policy on its own, for surfaces
@@ -141,6 +148,7 @@ export interface RecallOpts {
      * (e.g. mean-of-children summary re-rank).
      */
     scorerWindow?: number;
+    /** Candidate order. `recall` always keeps the BM25 order; `retrieve` honours this. */
     mode?: 'bm25' | 'hybrid' | 'physics';
     /**
      * Restrict results to memories whose `scope` equals this value exactly.
@@ -495,9 +503,8 @@ export declare function buildSuppressionSummary(counts: {
 }): RecallSuppressionSummary;
 /**
  * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
- * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
- * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
- * loader; later tasks can extend this to call the physics/hybrid scorer.
+ * `ctx.tenantId` and keeps that order whatever `mode` says; `retrieve` is the
+ * mode-aware, strengthening variant the HTTP route uses.
  *
  * **api.recall does NOT mutate `index.last_retrieval_ids`** (v1.11.5 contract
  * lock). The CLI `cmdRecall` (cli.ts) writes `last_retrieval_ids` because the
@@ -510,6 +517,8 @@ export declare function buildSuppressionSummary(counts: {
  * `tests/api-recall-no-side-effects.test.ts`.
  */
 export declare function recall(ctx: Context, opts: RecallOpts): RecallResult;
+/** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
+export declare function retrieve(ctx: Context, opts: RecallOpts): Promise<RecallResult>;
 export interface AssembleOpts {
     /** Token budget. Default 4000. */
     budget?: number;
@@ -833,9 +842,8 @@ export interface AuthCreateResult {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently unaudited —
- * we intentionally match that behavior here for consistency. When A5 v2
- * lands and adds the audit op, this function should mirror the cli handler.
+ * Only an admin actor can mint (ForbiddenError otherwise), so a member key
+ * can never create a key, least of all an admin one.
  */
 export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
 /**
@@ -853,8 +861,8 @@ export declare function authList(ctx: Context, opts: {
  * Revoke an API key.
  *
  * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
- * rejected with the same "not found" message used for missing keys, so that a
- * caller cannot probe which key_ids exist on other tenants.
+ * rejected with the "not found" message used for missing keys, and a member may
+ * revoke only its own key (checked first), so no caller can probe other key_ids.
  *
  * Audit: emits 'auth_revoke' with `tenantId` set to the KEY ROW's tenant_id
  * (M1 fix from A5 review, mirrors src/cli.ts:cmdAuthRevoke). Skipped on no-op
@@ -993,9 +1001,65 @@ export interface SleepOpts {
      */
     __phases?: Partial<SleepPhases>;
 }
+/**
+ * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
+ * Best-effort: never throws, because a ledger failure must not fail the
+ * recall or context call that produced the text.
+ */
+export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
+    items: number;
+    tokens: number;
+    sessionId?: string | null;
+}): void;
+/**
+ * Token ledger totals for the tenant over the last `days` days (default 30):
+ * tokens sent per surface, blocks skipped as unchanged and the tokens that
+ * saved, and mean tokens per session.
+ */
+export declare function tokenSummary(ctx: Context, opts?: {
+    days?: number;
+}): TokenSummary;
+/**
+ * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
+ * active memory instead of deleting, when `dormant.enabled` is on. Newest
+ * first; `opts.query` keeps rows containing every term (case-insensitive).
+ */
+export declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
+/**
+ * Bring a dormant memory back into active memory. It returns as if just
+ * recalled: `last_retrieved` is now, so it gets a full half-life before it
+ * can fade again. Every other field is the snapshot taken when it went
+ * dormant.
+ *
+ * Throws when the tenant has no dormant memory with that id (another
+ * tenant's id reads the same way), when a live memory already holds the id,
+ * and RejectedValueError when the value has been rejected since. On any
+ * throw the dormant copy stays where it is.
+ */
+export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
+/**
+ * Permanently delete a dormant memory: the explicit "forget it for good"
+ * that dormant storage leaves to the user. Throws when the tenant has no
+ * dormant memory with that id.
+ */
+export declare function forgetDormant(ctx: Context, id: string): void;
+/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
+export declare function isDormant(ctx: Context, id: string): boolean;
 export interface SleepResult {
     active: number;
     removed: number;
+    /**
+     * Faded memories the decay pass moved to the dormant store instead of
+     * deleting (config `dormant.enabled`). Absent when 0. Per-invocation
+     * activity counter, same class as `removed`.
+     */
+    dormant?: number;
+    /**
+     * Dormant memories deleted for good this sleep because they outlived
+     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
+     * `removed`.
+     */
+    dormantExpired?: number;
     mergedEpisodic: number;
     newSemantic: number;
     dryRun: boolean;
@@ -1014,26 +1078,22 @@ export interface SleepResult {
      * v1.25.0: count of memories the auto-share secret veto withheld this sleep
      * — rows that passed every other admission gate (transfer score,
      * not-already-global) and were blocked solely by `detectSecret`. Absent
-     * when 0 or when auto-share did not run. Same redaction class as `shared`
-     * (per-invocation activity counter, NOT redacted on egress — see the
-     * "NOT redacted" list in src/sleep-redact.ts).
+     * when 0 or when auto-share did not run.
      */
     secretSkipped?: number;
     /**
      * AT1: count of auto-share candidates the GLOBAL store's rejection
      * tombstone refused this sleep (docs/plans/2026-08-15-at1-rejected-value-tombstone.md
      * plan §3 — copy paths must not let one rejected candidate abort the
-     * batch). Absent when 0 or when auto-share did not run. Same
-     * per-invocation-activity class as `secretSkipped` (sibling counter,
-     * same autoShare call) — NOT redacted on egress, see sleep-redact.ts.
+     * batch). Absent when 0 or when auto-share did not run.
      */
     rejectedSkipped?: number;
     ambient?: AmbientState | null;
     /**
      * E3 sleep enqueue-hook: graph re-extraction totals across the tenants rebuilt
      * this sleep. Absent when no tenant was dirty, and under dryRun (the graph
-     * phase runs only on a real sleep). Cross-tenant aggregate — zeroed on
-     * non-loopback non-self egress by sleep-redact.ts.
+     * phase runs only on a real sleep). Cross-tenant aggregate, one reason
+     * /v1/sleep stays loopback-only.
      */
     graph?: {
         tenants: number;
@@ -1054,10 +1114,9 @@ export interface SleepResult {
  * serving lands — at that point the route will need an admin-role gate OR
  * api.sleep itself will need to scope dedup / audit / delete by ctx.tenantId.
  *
- * Audit emission gap: the consolidation phases (dedup, audit-delete) do
- * NOT emit audit_log rows today, matching pre-refactor cmdSleepCore. Same
- * CLI/MCP parity gap that T6 fixed for cmdOutcome, now visible at the api
- * surface. Tracked in TODOS.md "Episode A follow-ups" for a future minor.
+ * Dedup and audit deletes each log a `forget` row with the ctx actor and a
+ * `metadata.reason`. Pinned and raw rows are never auto-deleted (canAutoDelete).
+ * dryRun previews consolidate, dedup and audit, then returns before share/ambient.
  */
 /**
  * v1.12.2: Test-only DI seam shape for `sleep`'s phase dependencies.