hippo-memory 1.61.0 → 1.62.0

package/README.md

@@ -22,7 +22,7 @@ npm install -g hippo-memory && hippo init
 
 Setting up every git repo under a folder in one go is a second step. The [Quick start](#quick-start) says what it changes, then gives the command.
 
-Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration. See [automatic-save coverage](#does-installation-automatically-save-before-compaction).
+Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration.
 
 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`.
 
@@ -544,7 +544,7 @@ database to `.hippo/backups/` first and logs every id it touched in the audit lo
 ```bash
 hippo projects --global                        # names, counts, live worktrees of this repo
 hippo projects merge hippo-wt-fix hippo --global   # fold an old worktree name into its repo
-hippo projects repair --global                 # re-tag user-global merges by their parents
+hippo projects repair --global                 # set aside note copies, fold old worktree names, re-tag merges
 ```
 
 **See what memory costs in tokens.** Every block of memory text hippo hands an agent (the
@@ -936,53 +936,36 @@ For how these mechanisms connect to LLM training, continual learning, and open r
 
 ## Comparison
 
-Two tables. The first is plain facts: where the data lives, what each tool needs and runs on, and what it has published. Several rows favour the other tools: a managed multi-user service, a native Python library, a full knowledge graph. The second lists design bets, choices a tool made rather than results it measured; what hippo has measured is under [Benchmarks](#benchmarks). Graph-first systems ([gbrain](https://hermesatlas.com/projects/garrytan/gbrain), [Zep](https://www.getzep.com/), [Cognee](https://www.cognee.ai/)), agent-managed systems ([Letta](https://github.com/letta-ai/letta-code)), and version-control or skill-distillation takes ([Memoria](https://github.com/matrixorigin/Memoria), [EverMind](https://evermind.ai/)) solve adjacent problems with different mechanics.
-
-### What each tool is
-
-The rows from where the data lives to the graph were checked against each tool's own pages on 2026-09-28.
+The AI-memory category matured fast in 2026. Hippo's specific take (bio-decay, strengthen-on-use, outcome-weighted half-lives) is one stance among several. The table below is a feature snapshot, not a verdict: graph-first systems ([gbrain](https://hermesatlas.com/projects/garrytan/gbrain), [Zep](https://www.getzep.com/), [Cognee](https://www.cognee.ai/)), agent-managed systems ([Letta](https://github.com/letta-ai/letta-code)), and version-control / skill-distillation takes ([Memoria](https://github.com/matrixorigin/Memoria), [EverMind](https://evermind.ai/)) all solve adjacent problems with different mechanics.
 
 | Feature | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [gbrain](https://hermesatlas.com/projects/garrytan/gbrain) | [Zep](https://www.getzep.com/) | [Letta](https://github.com/letta-ai/letta-code) | [Cognee](https://www.cognee.ai/) | [Memoria](https://github.com/matrixorigin/Memoria) | [EverMind](https://evermind.ai/) |
 |---------|-------|-----------|------|-------------|--------|-----|-------|--------|---------|----------|
-| Where your data lives | Your machine or your server (SQLite) | Your machine (ChromaDB by default) | Where you run it, or Mem0's cloud | Your machine (Markdown files); cloud optional | Your machine (PGLite) or your Postgres | Zep's cloud (your own cloud on Enterprise) | Your machine; cloud backup with /login | Your machine by default; Cognee Cloud optional | Memoria Cloud, or self-hosted (Docker or embedded) | Your machine by default; EverOS Cloud optional |
-| Managed multi-user service | No (self-hosted, with tenants and API keys; hosted SaaS is planned for the commercial edition) | ? | Yes (hosted platform) | Yes (Teams) | ? (self-hosted server with OAuth) | Yes (Zep Cloud) | ? (cloud backup with /login) | Yes (Cognee Cloud) | ? (Memoria Cloud) | Yes (EverOS Cloud) |
-| Needs an account or model key | No | No (core path) | Yes (model key; account for the platform) | No (account for the cloud) | No (keyless mode) | Yes (Zep account; Graphiti needs a model key) | Yes (your own model keys) | No (local) | ? (account for Memoria Cloud) | Yes (an LLM key, OpenRouter) |
-| License | MIT | MIT | Apache-2.0 | AGPL-3.0 | MIT | Proprietary cloud (Graphiti: Apache-2.0) | Apache-2.0 | Apache-2.0 | Apache-2.0 | Apache-2.0 (EverOS) + cloud |
-| Runtime | Node.js 22.16+, no runtime deps | Python 3.9+ (ChromaDB by default) | Python or Node.js (server: Postgres + pgvector) | Python (SQLite by default) | Bun (PGLite or Postgres + pgvector) | Managed service (Graphiti: Python + a graph database) | Node.js (npm) | Python (graph and vector stores, or Postgres) | A CLI binary + a MatrixOne database | Python (SQLite + LanceDB) |
-| SDKs and APIs | CLI, HTTP API, Python SDK over HTTP | Python library, CLI | Python and Node.js libraries, a self-hosted server | CLI, cloud app | CLI, HTTP API | Python, TypeScript and Go SDKs | TypeScript SDK, CLI | Python and TypeScript SDKs, REST API, CLI | Python client, REST API, CLI | Python library, HTTP API, CLI |
-| Native Python library | No (the Python SDK calls hippo serve over HTTP) | Yes (mempalace) | Yes (mem0ai) | Yes (basic-memory) | No (installs with Bun) | Yes (Graphiti: graphiti-core) | ? (Letta Code ships on npm) | Yes (cognee) | ? (memoria-client) | Yes (everos) |
-| Graph or entity relations | Partial (entities from decisions and policies; recall --hops, off by default) | Yes (temporal entity graph) | Partial (entity linking; graph memory on Pro) | Yes (wikilinks and observations) | Yes (typed knowledge graph) | Yes (temporal knowledge graph) | No | Yes (knowledge graph) | No (typed claims) | ? (graph view in progress) |
-| Hybrid search (BM25 + embeddings) | Yes (BM25 by default; embeddings are an optional install) | Embeddings + spatial | Yes (semantic + BM25 + entity) | No | Yes (vec + rerank + graph) | Yes (graph + vec) | ? | Yes (GraphRAG) | Yes (vector + full-text) | Yes (mRAG, multi-modal) |
-| MCP server | Yes | Yes | Yes (hosted, needs an account) | Yes | Yes (stdio + HTTP/OAuth) | Yes (hosted, needs an account) | Yes (hosted, needs an API key) | Yes (first-party Claude/LangGraph) | Yes | ? |
-| Multi-agent shared memory | Yes | No | No | No | Yes (brain repo, team mounts) | Yes | Yes (shared memory blocks) | Yes | Yes (branch/merge across sessions) | Yes (multi-agent coordination) |
-| Auto-hook install | Yes (Claude Code hooks, OpenCode plugin) | No | No | No | No | No | No | No | No | No |
-| Cross-tool import (ChatGPT/Claude/Cursor) | Yes | No | No | No | Partial (data sources) | ? | No | Partial (28 data sources) | No (Git ops) | Partial (mRAG: PDFs/images/URLs) |
-| Git-friendly | Yes | No | No | Yes | Yes | No | Yes (memory tracked in git) | No | Yes (Git is the model) | ? |
-| Framework agnostic | Yes | Yes | Partial | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
-| LongMemEval (published) | 85.6% R@5 from hippo recall, 96.8% with the budget lifted (4,000-token default budget; the benchmark scripts' best of five settings: 98.0% local / 99.8% voyage any-evidence, 88.5% local all-evidence; s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | 94.4 (hosted platform)\*\* | N/A | 95.53% all-evidence R@5 reranked, 93.19% without (s_cleaned\*) | 90.2% accuracy\*\* (LoCoMo 94.7%) | N/A | N/A | 88.78% overall accuracy w/ reader\*\* | 83.00% overall\*\* (LoCoMo 93.05%, HaluMem 93.04%) |
-
-\* Hippo's figures are on `longmemeval_s_cleaned` with a per-question haystack. On a default install, `hippo recall` puts an answer session in its top 5 for 85.6% of the 500 questions inside its default 4,000-token budget. With the budget lifted it scores 96.8%, but then it returns every candidate, so that figure measures the ranking ([result](docs/evals/2026-09-28-recall-cli-longmemeval-result.md)). The 98.0% and 99.8% are the benchmark scripts' retrieval, each the best of five settings, not `hippo recall`. Any-evidence R@5 counts a hit when any answer session is in the top 5, over all 500 questions: 98.0% with the free local MiniLM embedder (an optional install) and 99.8% with voyage-3-large (measured 2026-06-09, not re-run). All-evidence R@5 counts a hit only when every answer session is in the top 5, over the 470 questions that have an answer: 86.8 to 88.5% with MiniLM. gbrain first published 97.6%, an any-evidence score over all 500; its [report](https://github.com/garrytan/gbrain-evals/blob/main/docs/benchmarks/2026-05-07-longmemeval-s.md) now leads with all-evidence, 95.53% (449 of 470) with the paid Voyage rerank-2.5 reranker and 93.19% without it. On all-evidence recall gbrain is ahead. The June 2026 build scored 98.6 any-evidence; [`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: these are end-to-end answer scores, not retrieval R@5. Mem0's 94.4 comes from its hosted platform, which its README says includes optimizations the open-source SDK lacks. Zep's 90.2% and 94.7% are accuracy figures from its homepage. Memoria's 88.78% and EverMind's 83% are overall accuracy with a reader LLM. Higher denominator + LLM helps. Not directly comparable to retrieval-only R@5 numbers above. The Mem0, Zep and Letta columns were last checked against each vendor's own pages on 2026-09-28.
-
-### Design bets
-
-A Yes means the tool made that choice, not that the choice was shown to help. What hippo has measured about its own bets is under [Benchmarks](#benchmarks); decay, for one, tied with decay switched off. Spatial organization and lossless compression are MemPalace's bets.
-
-| Design bet | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [gbrain](https://hermesatlas.com/projects/garrytan/gbrain) | [Zep](https://www.getzep.com/) | [Letta](https://github.com/letta-ai/letta-code) | [Cognee](https://www.cognee.ai/) | [Memoria](https://github.com/matrixorigin/Memoria) | [EverMind](https://evermind.ai/) |
-|---------|-------|-----------|------|-------------|--------|-----|-------|--------|---------|----------|
 | Decay by default | Yes | No | No | No | No | No | No | No | No | No |
 | Retrieval strengthening | Yes | No | No | No | No | No | No | Partial (recall tuning) | No | Partial (Skill Memory distills patterns) |
 | Reward-proportional decay | Yes | No | No | No | No | No | No | No | No | No |
-| Outcome tracking | Yes | No | No | No | No | No | No | No | No | Partial (Cases: agent trajectories) |
+| Hybrid search (BM25 + embeddings) | Yes | Embeddings + spatial | Yes (semantic + BM25 + entity) | No | Yes (vec + rerank + graph) | Yes (graph + vec) | ? | Yes (GraphRAG) | Yes (vector + full-text) | Yes (mRAG, multi-modal) |
+| Schema acceleration / knowledge graph | Yes (schema) | No | Partial (entity linking; graph memory on Pro) | No | Yes (typed KG, self-wiring) | Yes (temporal KG) | No | Yes (auto-ontologies) | No (typed claims) | Yes (hierarchical: user/group/agent) |
 | Conflict detection + resolution | Yes | No | Partial (hosted platform marks superseded facts) | No | Yes (eval-surfaced) | Yes (auto-invalidate stale facts) | No | No | Yes (auto-detect + quarantine) | Partial (temporal tracking) |
+| Multi-agent shared memory | Yes | No | No | No | Yes (brain repo, team mounts) | Yes | Yes (shared memory blocks) | Yes | Yes (branch/merge across sessions) | Yes (multi-agent coordination) |
 | Transfer scoring | Yes | No | No | No | No | No | No | No | No | No |
+| Outcome tracking | Yes | No | No | No | No | No | No | No | No | Partial (Cases: agent trajectories) |
 | Confidence tiers | Yes | No | No | No | No (typed facts) | No | No | No | No | No |
-| Schema acceleration | Yes | No | No | No | No | No | No | No | No | No |
 | Spatial organization | No | Yes (wings/halls/rooms) | No | No | No | No | No | No | No | No |
 | Lossless compression | No | Yes (AAAK, 30x) | No | No | No | No | No | No | No | No |
+| Cross-tool import (ChatGPT/Claude/Cursor) | Yes | No | No | No | Partial (data sources) | ? | No | Partial (28 data sources) | No (Git ops) | Partial (mRAG: PDFs/images/URLs) |
+| Auto-hook install | Yes | No | No | No | No | No | No | No | No | No |
+| MCP server | Yes | Yes | Yes (hosted, needs an account) | Yes | Yes (stdio + HTTP/OAuth) | Yes (hosted, needs an account) | Yes (hosted, needs an API key) | Yes (first-party Claude/LangGraph) | Yes | ? |
+| Zero runtime deps | Yes | No (ChromaDB) | No | No | No (PGLite or PG+pgvector) | No (managed service) | No (npm deps) | No (Python deps) | Yes (single Rust binary) | No (managed + OSS) |
+| LongMemEval (best published) | 98.0% local / 99.8% voyage any-evidence R@5; 88.5% local all-evidence R@5 (s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | 94.4 (hosted platform)\*\* | N/A | 95.53% all-evidence R@5 reranked, 93.19% without (s_cleaned\*) | 90.2% accuracy\*\* (LoCoMo 94.7%) | 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 | Yes (memory tracked in git) | 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 | Proprietary cloud (Graphiti: Apache-2.0) | Apache-2.0 | MIT (core) | Apache-2.0 | Apache-2.0 (OSS) + cloud |
 
-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 rank it down." These are complementary takes, not a single-axis ranking: memory lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
+\* Hippo's figures are on `longmemeval_s_cleaned` with a per-question haystack, each the best of five retrieval settings in the benchmark scripts, not `hippo recall`. Any-evidence R@5 counts a hit when any answer session is in the top 5, over all 500 questions: 98.0% with the free local MiniLM embedder (an optional install) and 99.8% with voyage-3-large (measured 2026-06-09, not re-run). All-evidence R@5 counts a hit only when every answer session is in the top 5, over the 470 questions that have an answer: 86.8 to 88.5% with MiniLM. gbrain first published 97.6%, an any-evidence score over all 500; its [report](https://github.com/garrytan/gbrain-evals/blob/main/docs/benchmarks/2026-05-07-longmemeval-s.md) now leads with all-evidence, 95.53% (449 of 470) with the paid Voyage rerank-2.5 reranker and 93.19% without it. On all-evidence recall gbrain is ahead. The June 2026 build scored 98.6 any-evidence; [`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: these are end-to-end answer scores, not retrieval R@5. Mem0's 94.4 comes from its hosted platform, which its README says includes optimizations the open-source SDK lacks. Zep's 90.2% and 94.7% are accuracy figures from its homepage. Memoria's 88.78% and EverMind's 83% are overall accuracy with a reader LLM. Higher denominator + LLM helps. Not directly comparable to retrieval-only R@5 numbers above. The Mem0, Zep and Letta columns were last checked against each vendor's own pages on 2026-09-28.
+
+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.
 
 ---
 
@@ -1090,7 +1073,7 @@ node run.mjs --adapter all
 
 ### How do I give Claude Code memory between sessions?
 
-Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds 7 hook entries to Claude Code's settings that keep your pinned memories plus up to 5 that match the prompt in context, save a task snapshot and the memories a compaction summary lists, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
+Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds hooks to Claude Code's settings that keep your pinned memories in context, save a task snapshot before compaction, and run `hippo sleep` when the session ends. `hippo init --scan ~` gives every git repo under your home folder a store and installs the same hooks, but adds no block to any `CLAUDE.md`. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both.
 
 ### How do I give Cursor memory between sessions?
 
@@ -1098,19 +1081,11 @@ Run `npm install -g hippo-memory`, then `hippo init` in the project. If the proj
 
 ### How do I give Codex memory across sessions?
 
-`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. When Codex is installed, init also adds two hooks to Codex's `hooks.json`: one puts your pinned memories plus up to 5 that match the prompt into every prompt, the other makes the next prompt send them again after a compaction. Codex asks you to trust each new hook once in `/hooks`, and skips it until you do. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper and the hooks.
+`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper.
 
 ### Which agents does hippo work with?
 
-`hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi. It installs hooks for Claude Code and OpenCode, adds 2 hooks to Codex's `hooks.json` when Codex is installed (Codex runs them once you trust them in `/hooks`), and adds instructions to an existing `AGENTS.md` for Codex, Cursor, OpenClaw and Pi. It only patches instruction files that already exist. Any MCP client can use the [MCP server](#mcp-server), and other tools can call the CLI or the HTTP API that `hippo serve` starts.
-
-### Does installation automatically save before compaction?
-
-Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration.
-
-With the Claude Code hooks or native plugin configured, PreCompact saves a derivable working-state snapshot and a compaction record; PostCompact extracts the lessons listed in the compaction summary. A snapshot, a compaction record and a useful memory are different outputs, and post-compaction extraction is not a guarantee that every earlier lesson was saved before loss. Hippo's Codex hooks currently provide prompt delivery and post-compaction re-injection, with one-time trust in `/hooks`; they install no PreCompact save hook. Codex session-end capture requires the opt-in wrapper. MCP tool access and instruction files alone do not provide automatic lifecycle capture.
-
-Follow the [integration recipes](https://github.com/kitfunso/hippo-memory/tree/master/integrations) for the exact agent and mode. Automatic pre-loss preservation across all supported agents is planned under AZ4-AZ6 in the [roadmap](https://github.com/kitfunso/hippo-memory/blob/master/ROADMAP.md#current-execution-index); it is not a universal install-only capability today.
+`hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi, and wires itself into each one's instruction file, hooks or plugin. It only patches instruction files that already exist. Any MCP client can use the [MCP server](#mcp-server), and other tools can call the CLI or the HTTP API that `hippo serve` starts.
 
 ### Can I use hippo as an MCP memory server?
 
@@ -1118,7 +1093,7 @@ Yes. `hippo mcp` runs the server over stdio, and `npx -y hippo-memory mcp` runs
 
 ### How is hippo different from mem0?
 
-mem0 uses a language model to extract memories, OpenAI by default in its open-source library, and memories stored through its hosted MCP server live in your Mem0 account ([mem0 docs](https://docs.mem0.ai/platform/mem0-mcp), checked 2026-09-28). Hippo stores memories in SQLite on your machine, needs no account and no model, and `hippo init` wires it into the coding agents it finds. mem0's platform marks an older fact superseded when a newer one replaces it; in hippo you run `hippo supersede` yourself. Hippo also lets you mark a recalled memory wrong with `hippo outcome --bad`, and it drops out of the top results.
+mem0 uses a language model to extract memories, OpenAI by default in its open-source library, and memories stored through its hosted MCP server live in your Mem0 account ([mem0 docs](https://docs.mem0.ai/platform/mem0-mcp), checked 2026-09-28). Hippo stores memories in SQLite on your machine, needs no account and no model, and `hippo init` wires it into the coding agents it finds. mem0's platform and hippo both mark an older fact superseded when a newer one replaces it. Hippo also lets you mark a recalled memory wrong with `hippo outcome --bad`, and it drops out of the top results.
 
 ### Is this just RAG?
 
@@ -1126,7 +1101,7 @@ No. RAG searches a fixed corpus. Hippo's store changes as your agent works: a me
 
 ### Does it need embeddings?
 
-No. Recall runs on BM25 out of the box, with no model and no network call, and a default install has no embedder. Embeddings are an optional install for hybrid search. On LongMemEval-S, where each question gets its own haystack, `hippo recall` on a default install puts an answer session in its top five for 85.6% of questions inside its 4,000-token budget, and 87.6% with the free local MiniLM embedder; the budget, not the embedder, is most of the gap to the benchmark scripts. Those scripts, which are not `hippo recall`, fuse BM25 with MiniLM and reach 98.0% recall@5 at their best of five settings, counting a hit when any answer session is in the top five. On LongMemEval's oracle split with one pooled store, BM25 alone scored 74.0% recall@5 in v0.11. These runs use different setups, so they are not a before and after.
+No. Recall runs on BM25 out of the box, with no model and no network call, and a default install has no embedder. Embeddings are an optional install for hybrid search. On LongMemEval-S, where each question gets its own haystack, the benchmark scripts (not `hippo recall`) fuse BM25 with the free local MiniLM embedder and reach 98.0% recall@5, counting a hit when any answer session is in the top five. On LongMemEval's oracle split with one pooled store, BM25 alone scored 74.0% recall@5 in v0.11. The two runs use different setups, so they are not a before and after.
 
 ### Do I still need CLAUDE.md?
 
@@ -1138,11 +1113,11 @@ Mark it, and it drops out of the top results. `hippo outcome --bad` weakens the
 
 ### Where does hippo keep my data?
 
-On your machine, in SQLite: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/` for lessons shared across projects, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev, CLEF or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API whenever `ANTHROPIC_API_KEY` is set in its environment. To turn that last one off, set `{"extraction":{"enabled":false}}` in `.hippo/config.json`.
+On your machine, in SQLite: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/` for lessons shared across projects, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API whenever `ANTHROPIC_API_KEY` is set in its environment. To turn that last one off, set `{"extraction":{"enabled":false}}` in `.hippo/config.json`.
 
 ### What does hippo cost?
 
-Nothing. Hippo is MIT-licensed and needs no account or API key. Optional features that call an outside provider bill through it: the Jev reranker costs about 0.0004 USD a recall, and API embedders and sleep's fact extraction bill your own keys. Memory text handed to your agent uses context tokens when it is sent, and again, usually at the cheaper cached-input rate, on each later model call until the host compacts. `hippo tokens` shows both for the hook and compact-resume blocks, and the sent tokens for the rest.
+Nothing. Hippo is MIT-licensed and needs no account or API key. Optional features that call an outside provider bill through it: the Jev reranker costs about 0.0004 USD a recall, and API embedders and sleep's fact extraction bill your own keys. Memory text handed to your agent uses context tokens, and `hippo tokens` shows how many.
 
 ### Is it production-ready?
 
@@ -1150,7 +1125,7 @@ Judge it by what is tested. 3,500+ tests run against a real database, with no mo
 
 ### Has hippo been shown to make agents better at their work?
 
-No. The published numbers measure retrieval: whether the right memory comes back, and whether a memory marked wrong stays out of the results. Decay and sleep are design choices, not measured wins. In the [mechanism audit](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/2026-09-23-mechanism-audit-round2-result.md), decay had no measurable effect against decay switched off (-0.7 points [-1.4, 0.1] on a 20-session synthetic test, too short for a 365-day half-life to act), and sleep lowered LongMemEval hit@5 by 3.6 points [-5.8, -1.4] under the audit's declared scorer; no scorer there showed sleep helping recall. Every measurement, including failed runs and one retracted claim, is indexed in [docs/evals](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/README.md).
+Not yet. The published numbers measure retrieval: whether the right memory comes back, and whether a memory marked wrong stays out of the results. A paired test that runs real agent sessions with and without hippo is under way. Every measurement, including failed runs and one retracted claim, is indexed in [docs/evals](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/README.md).
 
 ---
 

package/dist/agent-memories/apply.d.ts

@@ -34,7 +34,7 @@ export interface ContainerOutcome {
 }
 /** Throws SQLITE_BUSY when another writer holds the store past its busy timeout; nothing is written then. */
 export declare function syncContainer(s: StoreSession, work: ContainerWork): ContainerOutcome;
-export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover' | 'project-merge';
+export type SetAsideWhy = 'note-gone' | 'note-changed' | 'handover' | 'project-merge' | 'project-repair';
 export type SetAsideResult = {
     readonly kind: 'untagged';
     readonly entry: MemoryEntry;

package/dist/agent-memories/claude-code.d.ts

@@ -6,6 +6,8 @@ export declare function claudeCheckoutRoot(top: string, gitDir: string, common:
 /** Claude Code's folder name for a path: non-alphanumerics made '-', and a name over 200 characters cut to 200 plus a base-36 hash of the whole path. */
 export declare function claudeFolderName(root: string): string;
 export declare const claudeCodeAdapter: Adapter;
-/** Post-compact's read: the session's own notes folder and nothing else, so no git call runs inside the hook's time limit. */
+/** A session's own notes folder and nothing else, with no git call, so post-compact can read it inside the hook's time limit. */
 export declare function claudeTranscriptListing(ctx: AdapterContext, transcriptPath: string): Listing;
+/** The project a session folder's notes belong to: the one Claude named the folder for, the session's start folder, else cwd or a parent; null when none matches. */
+export declare function transcriptNotesOrigin(transcriptPath: string, cwd: string | null, machine: Pick<AdapterContext, 'platform' | 'env'>): string | null;
 //# sourceMappingURL=claude-code.d.ts.map

package/dist/agent-memories/claude-code.js

@@ -1,7 +1,7 @@
 // Claude Code's auto memory: frontmatter `.md` notes in a per-project folder, plus the `autoMemoryDirectory` user folder.
 import fs from 'node:fs';
 import path from 'node:path';
-import { realpathOrResolve } from '../project-identity.js';
+import { deriveOriginProject, realpathOrResolve } from '../project-identity.js';
 import { isStringValue } from '../capture-contract.js';
 import { isJsonObject } from '../hooks/shared.js';
 import { expandHome, frontmatterField, itemTime, readTextFile, splitFrontmatter } from './files.js';
@@ -45,23 +45,67 @@ export const claudeCodeAdapter = {
         return { tool: 'claude-code', home: config, containers: readFolders(folders, scope, ctx.platform), warnings };
     },
 };
-/** Post-compact's read: the session's own notes folder and nothing else, so no git call runs inside the hook's time limit. */
+/** A session's own notes folder and nothing else, with no git call, so post-compact can read it inside the hook's time limit. */
 export function claudeTranscriptListing(ctx, transcriptPath) {
     const config = ctx.env.CLAUDE_CONFIG_DIR || path.join(ctx.home, '.claude');
     const folder = path.join(path.dirname(transcriptPath), 'memory');
     return { tool: 'claude-code', home: config, containers: readFolders([folder], 'project', ctx.platform), warnings: [] };
 }
+/** The project a session folder's notes belong to: the one Claude named the folder for, the session's start folder, else cwd or a parent; null when none matches. */
+export function transcriptNotesOrigin(transcriptPath, cwd, machine) {
+    const fold = (name) => (machine.platform === 'win32' ? name.toLowerCase() : name);
+    const folder = fold(path.basename(path.dirname(transcriptPath)));
+    const start = transcriptStartCwd(transcriptPath);
+    const pinned = pinnedProjectDirName(machine.env);
+    if (pinned !== null && fold(pinned) === folder) {
+        // A pinned name stands for whatever project the session ran in, so its start folder decides.
+        const from = start ?? cwd;
+        return from !== null && fs.existsSync(from) ? deriveOriginProject(from) : null;
+    }
+    for (const from of [start, cwd]) {
+        for (let dir = from === null ? null : path.resolve(from); dir !== null; dir = path.dirname(dir) === dir ? null : path.dirname(dir)) {
+            // A folder gone from disk resolves to its bare name, never the project it was in, so it decides nothing.
+            if ([dir, realpathOrResolve(dir)].some((d) => fold(claudeFolderName(d)) === folder))
+                return fs.existsSync(dir) ? deriveOriginProject(dir) : null;
+        }
+    }
+    return null;
+}
+// Claude writes the cwd on each message line after a few header lines; 64 KB holds the first with room to spare.
+const START_SCAN_BYTES = 64 * 1024;
+/** The cwd on the transcript's first line that has one: the folder Claude named the session folder for, which a folder name alone cannot give back. */
+function transcriptStartCwd(transcriptPath) {
+    if (!fs.existsSync(transcriptPath))
+        return null;
+    const fd = fs.openSync(transcriptPath, 'r');
+    try {
+        const buf = Buffer.alloc(START_SCAN_BYTES);
+        const lines = buf.subarray(0, fs.readSync(fd, buf, 0, buf.length, 0)).toString('utf8').split('\n');
+        for (const line of lines) {
+            const cwd = /"cwd":"((?:[^"\\]|\\.)*)"/.exec(line)?.[1];
+            if (cwd === undefined)
+                continue;
+            // SAFETY: the match is the body of one JSON string, so parsing it in quotes yields a string.
+            return JSON.parse(`"${cwd}"`);
+        }
+        return null;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 function projectFolders(ctx, config) {
     const projects = path.join(config, 'projects');
     const names = ctx.projectRoot === undefined ? [] : [...claudeMemoryFolderNames(ctx.projectRoot, ctx.platform)];
-    const pinned = ctx.env.CLAUDE_CODE_PROJECT_DIR_NAME;
-    // Claude reads the pinned name only alongside a pinned config folder.
-    if (ctx.env.CLAUDE_CONFIG_DIR && pinned !== undefined && PROJECT_DIR_NAME.test(pinned))
+    const pinned = pinnedProjectDirName(ctx.env);
+    if (pinned !== null)
         names.push(pinned);
-    const folders = names.map((name) => path.join(projects, name, 'memory'));
-    if (ctx.transcriptPath)
-        folders.push(path.join(path.dirname(ctx.transcriptPath), 'memory'));
-    return folders;
+    return names.map((name) => path.join(projects, name, 'memory'));
+}
+function pinnedProjectDirName(env) {
+    const pinned = env.CLAUDE_CODE_PROJECT_DIR_NAME;
+    // Claude reads the pinned name only alongside a pinned config folder.
+    return env.CLAUDE_CONFIG_DIR && pinned !== undefined && PROJECT_DIR_NAME.test(pinned) ? pinned : null;
 }
 function userFolders(ctx, config, warnings) {
     const dir = autoMemoryDirectory(path.join(config, 'settings.json'), ctx.home, warnings);

package/dist/agent-memories/sync.d.ts

@@ -24,10 +24,10 @@ export declare function importForStore(hippoRoot: string, opts: SyncOptions): Im
 export declare function importProjectMemories(hippoRoot: string, opts: SyncOptions): ImportReport;
 /** Every tool's user-level memory into the global store, created on demand, with no origin. */
 export declare function importUserMemories(invokingRoot: string, opts: SyncOptions): ImportReport;
-/** Session end in a folder with no store of its own: the session's project into the global store with its origin, then the user pass. */
+/** Session end in a folder with no store of its own: the session's project into the global store with its origin, the session folder's notes, then the user pass. */
 export declare function importAtSessionEnd(cwd: string, transcriptPath: string | undefined, opts: SyncOptions): ImportReport;
-/** Post-compact: the transcript folder's notes only, with no git call, no legacy adoption and no user pass, as the hook has 10 seconds. */
-export declare function importAtCompaction(hippoRoot: string, transcriptPath: string, originProject: string | undefined, opts: SyncOptions): ImportReport;
+/** The session folder's notes under the project Claude filed them for, never cwd's: a session begun at home keeps its home notes user-global wherever it ends. No git call, so post-compact can run it. */
+export declare function importSessionFolder(hippoRoot: string, transcriptPath: string, cwd: string | null, opts: SyncOptions): ImportReport;
 /** The variable when set (empty or `none` is off); else the tools both the invoking and the target store's config allow. */
 export declare function allowedTools(env: Machine['env'], invoking: string, target: string, warnings: string[]): Set<ToolId>;
 //# sourceMappingURL=sync.d.ts.map

package/dist/agent-memories/sync.js

@@ -15,7 +15,7 @@ import { selectLiveEntriesBySourcePrefix } from '../store/entry-reads.js';
 import { updateStats } from '../store/index-and-stats.js';
 import { resolveTenantId } from '../tenant.js';
 import { setAsideRow, syncContainer } from './apply.js';
-import { claudeCodeAdapter, claudeTranscriptListing } from './claude-code.js';
+import { claudeCodeAdapter, claudeTranscriptListing, transcriptNotesOrigin } from './claude-code.js';
 import { codexAdapter } from './codex.js';
 import { copilotAdapter } from './copilot.js';
 import { geminiAdapter } from './gemini.js';
@@ -53,21 +53,29 @@ export function importUserMemories(invokingRoot, opts) {
         scope: 'user', target: resolveGlobalRootDir(), invoking: invokingRoot, list: (a) => a.list(ctx, 'user'), legacy: false, originProject: '', handover: false,
     }, opts);
 }
-/** Session end in a folder with no store of its own: the session's project into the global store with its origin, then the user pass. */
+/** Session end in a folder with no store of its own: the session's project into the global store with its origin, the session folder's notes, then the user pass. */
 export function importAtSessionEnd(cwd, transcriptPath, opts) {
     const globalRoot = resolveGlobalRootDir();
-    const ctx = context(opts.machine, { projectRoot: cwd, transcriptPath });
+    const ctx = context(opts.machine, { projectRoot: cwd });
     const report = runPass({
         scope: 'project', target: globalRoot, invoking: globalRoot, list: (a) => a.list(ctx, 'project'), legacy: false, originProject: deriveOriginProject(cwd), handover: false,
     }, opts);
+    if (transcriptPath !== undefined)
+        mergeReports(report, importSessionFolder(globalRoot, transcriptPath, cwd, opts));
     mergeReports(report, importUserMemories(globalRoot, opts));
     return report;
 }
-/** Post-compact: the transcript folder's notes only, with no git call, no legacy adoption and no user pass, as the hook has 10 seconds. */
-export function importAtCompaction(hippoRoot, transcriptPath, originProject, opts) {
+/** The session folder's notes under the project Claude filed them for, never cwd's: a session begun at home keeps its home notes user-global wherever it ends. No git call, so post-compact can run it. */
+export function importSessionFolder(hippoRoot, transcriptPath, cwd, opts) {
+    const origin = transcriptNotesOrigin(transcriptPath, cwd, opts.machine);
+    if (origin === null)
+        return emptyReport();
+    // A project store takes its own project's notes; another project's, or home's, go to the global store, which parts them by origin.
+    const own = isGlobalStoreRoot(hippoRoot) || origin === deriveOriginProject(path.dirname(hippoRoot));
+    const target = own ? hippoRoot : resolveGlobalRootDir();
     const ctx = context(opts.machine, {});
     return runPass({
-        scope: 'project', target: hippoRoot, invoking: hippoRoot, legacy: false, originProject, handover: false,
+        scope: 'project', target, invoking: hippoRoot, legacy: false, originProject: origin, handover: false,
         list: (a) => (a.tool === 'claude-code' ? claudeTranscriptListing(ctx, transcriptPath) : null),
     }, opts);
 }

package/dist/agent-memories/types.d.ts

@@ -6,8 +6,6 @@ export interface AdapterContext {
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly platform: NodeJS.Platform;
     readonly projectRoot?: string;
-    /** Claude Code's transcript at a hook: its folder's `memory/` holds that session's own notes. */
-    readonly transcriptPath?: string;
 }
 export interface MemoryItem {
     /** A path inside the container with '/' separators, or `<heading slug>/<text hash>` in a single-file store. */

package/dist/api/assemble.js

@@ -59,58 +59,9 @@ export function assemble(ctx, sessionId, opts = {}) {
     const olderRows = scoped.slice(0, tailStartIdx);
     const tailRows = scoped.slice(tailStartIdx);
     // Substitute parent summaries for older rows that share one.
-    const olderItems = [];
-    let summarized = 0;
-    if (summarizeOlder && olderRows.length > 0) {
-        const olderByParent = new Map();
-        for (const r of olderRows) {
-            if (!r.dag_parent_id)
-                continue;
-            const list = olderByParent.get(r.dag_parent_id) ?? [];
-            list.push(r);
-            olderByParent.set(r.dag_parent_id, list);
-        }
-        const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
-        const parents = eligibleParentIds.length > 0
-            ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
-                .filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by)
-                .filter((p) => passesScopeFilterForRecall(p.scope ?? null, opts.scope))
-            : [];
-        const claimedRawIds = new Set();
-        for (const parent of parents) {
-            const claimed = (olderByParent.get(parent.id) ?? []).map((r) => r.id);
-            claimed.forEach((id) => claimedRawIds.add(id));
-            olderItems.push({
-                id: parent.id,
-                content: parent.content,
-                createdAt: parent.earliest_at ?? parent.created,
-                isSummary: true,
-                substitutedFor: claimed,
-                strength: parent.strength,
-            });
-            summarized += claimed.length;
-        }
-        for (const r of olderRows) {
-            if (claimedRawIds.has(r.id))
-                continue;
-            olderItems.push({
-                id: r.id,
-                content: r.content,
-                createdAt: r.created,
-                strength: r.strength,
-            });
-        }
-    }
-    else {
-        for (const r of olderRows) {
-            olderItems.push({
-                id: r.id,
-                content: r.content,
-                createdAt: r.created,
-                strength: r.strength,
-            });
-        }
-    }
+    const { olderItems, summarized } = summarizeOlder && olderRows.length > 0
+        ? substituteSummaries(ctx, olderRows, opts.scope)
+        : { olderItems: olderRows.map(rawItem), summarized: 0 };
     const tailItems = tailRows.map((r) => ({
         id: r.id,
         content: r.content,
@@ -124,9 +75,59 @@ export function assemble(ctx, sessionId, opts = {}) {
     const cmpIso = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
     olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
-    let items = [...olderItems, ...tailItems];
     const itemCost = opts.cost?.item ?? ((it) => estimateTokens(it.content));
     const room = budget - (opts.cost?.fixed(Math.max(budget, totalRaw)) ?? 0);
+    const { items, tokens, evicted } = evictToBudget([...olderItems, ...tailItems], itemCost, room);
+    return { sessionId, items, tokens, totalRaw, summarized, evicted, truncated };
+}
+function rawItem(r) {
+    return {
+        id: r.id,
+        content: r.content,
+        createdAt: r.created,
+        strength: r.strength,
+    };
+}
+function substituteSummaries(ctx, olderRows, scope) {
+    const olderItems = [];
+    let summarized = 0;
+    const olderByParent = new Map();
+    for (const r of olderRows) {
+        if (!r.dag_parent_id)
+            continue;
+        const list = olderByParent.get(r.dag_parent_id) ?? [];
+        list.push(r);
+        olderByParent.set(r.dag_parent_id, list);
+    }
+    const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
+    const parents = eligibleParentIds.length > 0
+        ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
+            .filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by)
+            .filter((p) => passesScopeFilterForRecall(p.scope ?? null, scope))
+        : [];
+    const claimedRawIds = new Set();
+    for (const parent of parents) {
+        const claimed = (olderByParent.get(parent.id) ?? []).map((r) => r.id);
+        claimed.forEach((id) => claimedRawIds.add(id));
+        olderItems.push({
+            id: parent.id,
+            content: parent.content,
+            createdAt: parent.earliest_at ?? parent.created,
+            isSummary: true,
+            substitutedFor: claimed,
+            strength: parent.strength,
+        });
+        summarized += claimed.length;
+    }
+    for (const r of olderRows) {
+        if (claimedRawIds.has(r.id))
+            continue;
+        olderItems.push(rawItem(r));
+    }
+    return { olderItems, summarized };
+}
+function evictToBudget(start, itemCost, room) {
+    let items = start;
     let tokens = items.reduce((acc, it) => acc + itemCost(it), 0);
     let evicted = 0;
     while (tokens > room && items.length > 0) {
@@ -147,6 +148,6 @@ export function assemble(ctx, sessionId, opts = {}) {
         tokens -= cost;
         evicted++;
     }
-    return { sessionId, items, tokens, totalRaw, summarized, evicted, truncated };
+    return { items, tokens, evicted };
 }
 //# sourceMappingURL=assemble.js.map

package/dist/api/context-select.d.ts

@@ -0,0 +1,49 @@
+import type { AmbientLoadResult } from '../store/candidates.js';
+import { type MemoryEntry } from '../memory.js';
+import { type HippoConfig } from '../config.js';
+import type { DeliveryObserver } from '../delivery-recorder.js';
+import type { ContextCost, ContextOpts, ContextResultEntry } from './context-types.js';
+import type { Context } from './types.js';
+/** What getContext resolved from opts and config before it read a row. */
+export interface ContextPlan {
+    pinnedOnly: boolean;
+    limit: number;
+    includeRecent: number;
+    activeScope: string;
+    exactScope: string | undefined;
+    query: string;
+    hasLocal: boolean;
+    hasGlobal: boolean;
+    globalRoot: string;
+    primaryIsGlobal: boolean;
+    hasLocalTaskState: boolean;
+    config: HippoConfig;
+    currentProjectName: string;
+    includeCrossProject: boolean;
+    originProject: string | undefined;
+    promptRecallPending: boolean;
+    cost: ContextCost | undefined;
+    price: (entry: MemoryEntry, isGlobal: boolean, promptRecall?: boolean) => number;
+    obs: DeliveryObserver | undefined;
+}
+/** The ambient admit rules; `digestHidden` is read late because a prompt-recall eligibility check can still set it. */
+export interface ContextAdmission {
+    ambientAdmit: (e: MemoryEntry) => boolean;
+    admit: (e: MemoryEntry) => boolean;
+    /** What the two-store search admits: `admit` without the own-session compaction rule. */
+    bothStoresAdmit: (e: MemoryEntry) => boolean;
+    digestHidden: () => boolean;
+}
+export interface ContextPools {
+    local: AmbientLoadResult;
+    global: AmbientLoadResult;
+}
+export declare function oneCopyPerMemory(local: readonly MemoryEntry[], global: readonly MemoryEntry[], now: Date): [MemoryEntry[], MemoryEntry[]];
+export declare const finiteOr: (v: number, dflt: number, min: number) => number;
+/** Pins plus the prompt-recall or recent-N backfill; null means the block is empty. */
+export declare function selectPinned(ctx: Context, opts: ContextOpts, plan: ContextPlan, left: number, pools: ContextPools, admission: ContextAdmission): ContextResultEntry[] | null;
+/** No query: the strongest memories by strength, up to budget. */
+export declare function selectStrongest(plan: ContextPlan, left: number, pools: ContextPools): ContextResultEntry[];
+/** Real query: hybrid search over both stores, or physics/hybrid over the local rows; emits the 'recall' audit row. */
+export declare function selectBySearch(ctx: Context, plan: ContextPlan, left: number, pools: ContextPools, admission: ContextAdmission): Promise<ContextResultEntry[]>;
+//# sourceMappingURL=context-select.d.ts.map