nexusmem 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,8 @@
 # NexusMem
 
+[![CI](https://github.com/yaminbkk/NexusMem/actions/workflows/ci.yml/badge.svg)](https://github.com/yaminbkk/NexusMem/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/nexusmem)](https://www.npmjs.com/package/nexusmem)
+[![npm downloads](https://img.shields.io/npm/dm/nexusmem)](https://www.npmjs.com/package/nexusmem)
 [![License: MIT](https://img.shields.io/badge/license-MIT-informational)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)
 
@@ -70,6 +72,55 @@ Requirements: Node 22 or newer, and git. Node 20 will not work, because `better-
 prebuilt binary for it and Node 20 went end-of-life in April 2026. Ollama is optional and only
 affects semantic search (see below).
 
+## Optional: exact shell capture
+
+Scraped history files (PSReadLine, `.bash_history`, `.zsh_history`) give you command text and not
+much else. The hook gives you working directory, exit code and a real timestamp:
+
+```bash
+nexusmem hook install
+```
+
+It wraps your existing PowerShell prompt rather than replacing it, is idempotent, and
+`nexusmem hook remove` undoes it cleanly.
+
+Exit codes are what make this worth installing. A failed command is a stronger signal than a
+successful one, and without the hook there is no way to tell them apart.
+
+## Failure → fix chains (opt-in)
+
+```bash
+nexusmem sync --link-failures
+```
+
+After a normal sync, this walks every failed `shell_command` (non-zero exit code) and looks for
+whatever later resolved it, using two independent heuristics: a later command in the same project
+and working directory, exact same normalized text, that exited `0` within 24h (**same-command
+retry**); and, separately, the best full-text match among nearby conversation turns or session
+summaries, requiring every significant word of the failing command to appear, not just one
+(**conversation bridge**). A failure can be linked by either, both, or neither.
+
+Both links are surfaced in query results. The conversation-bridge heuristic originally matched on
+any shared word, and dogfooding against this repo's own real history found it wrong on roughly half
+its links — a shared word as generic as "npm" was enough to link an unrelated discussion. Requiring
+every significant word fixed that: re-dogfooded against the same corpus, every resulting link (the
+full set produced, not a sample) checked out correct on manual review of the full text, not just the
+summary.
+
+When a linked failure appears in a result set, its fix rides along immediately after it, inheriting
+the failure's own relevance score rather than needing to match the query on its own merits. That is
+the point: a query about why something failed shouldn't need to separately guess the words used in
+whatever fixed it. This works across projects too — `query --all-projects` chains a failure to its
+fix using whichever project's own database recorded the link, since links are always local to the
+project they were found in.
+
+```
+$ nexusmem query "why did npm whoami fail"
+
+- 2026-08-12 shell: npm whoami  (exit 1)
+- 2026-08-12 shell: npm login   (exit 0)  -- linked as the fix
+```
+
 ## How retrieval works
 
 Every source normalizes to the same `MemoryNode` shape, so a commit, a shell command and a docs
@@ -155,21 +206,6 @@ Three tools over stdio: `search_memory` returns the packed context block, `sync_
 MCP tool call carries no shell working directory. `sync_project` runs `init` for you if the
 repository has not been set up.
 
-## Optional: exact shell capture
-
-Scraped history files (PSReadLine, `.bash_history`, `.zsh_history`) give you command text and not
-much else. The hook gives you working directory, exit code and a real timestamp:
-
-```bash
-nexusmem hook install
-```
-
-It wraps your existing PowerShell prompt rather than replacing it, is idempotent, and
-`nexusmem hook remove` undoes it cleanly.
-
-Exit codes are what make this worth installing. A failed command is a stronger signal than a
-successful one, and without the hook there is no way to tell them apart.
-
 ## What it costs you
 
 Two numbers get conflated in tools like this, so they are kept apart here.
@@ -179,14 +215,40 @@ corpus it runs 81–84%. It is useful for tuning the ranker and useless as a cla
 because the baseline is hypothetical: without NexusMem those candidates were never going into your
 context window in the first place.
 
-**End-to-end saving** compares packed context against reading the equivalent files in full. Measured
-at **~40%** on design queries against this codebase, hand-tallied from one real session rather than
-instrumented. Treat it as an order of magnitude.
-
-The long-term target is >70%, and this repository cannot demonstrate it. That figure describes repos
-with thousands of commits, where the win comes from omitting hundreds of unrelated items rather than
-shaving a handful. A benchmark at that size is still outstanding, and until it exists the honest
-number is 40%.
+**End-to-end saving** compares the packed context NexusMem actually sends against reading, in full,
+the same files its own ranking identified as relevant to the query. Measured with
+[`scripts/benchmark.ts`](scripts/benchmark.ts) (`npm run bench`), which anyone who clones this repo
+and points it at a synced corpus can re-run from scratch:
+
+| Corpus | Commits | Query set | vs. full file content | vs. `git log -p` on those files |
+| --- | --- | --- | --- | --- |
+| This repo | 62 | 16 real prompts, verbatim from this project's own history | 95% (median 94%) | 98% (median 97%) |
+| [`vitejs/vite`](https://github.com/vitejs/vite) | 9,567 | 16, mechanically sampled — see below | 99% (median 98%) | ~100% (median ~100%) — see caveat |
+
+Both clear the original >70% target ("cut API token spend versus sending full context"), and the vite
+run is the first measurement at the scale that target was always described as applying to.
+
+**Read the methodology before quoting either number, because it is a narrower claim than it looks:**
+
+- The file set each query is graded against comes from NexusMem's *own* ranking — whichever files the
+  packed nodes for that query touch, not an outside judge's idea of the right answer. This isolates
+  what the pack step (rank → budget → excerpt) saves once retrieval has already picked a candidate
+  set; it does not independently verify that the candidate set was the right one to pick.
+- The vite query set is not hand-picked: an even sample, across the full commit history, of
+  well-explained `fix`/`feat`/`perf`/`refactor` commits turned into "why does vite `<description>`"
+  from the commit's own conventional-commit text, plus rationale-bearing doc section headings. This
+  repo's own query set instead reuses real historical prompts verbatim from `conversation_turn`
+  nodes — several are broad task instructions rather than narrow questions, which pulls a wider file
+  set into scope and is part of why its number, while still high, sits below vite's. Both derivations
+  are mechanical and disclosed in `scripts/benchmark.ts`, neither is cherry-picked per-query.
+- `git log -p` on a file touched by thousands of commits is enormous — one vite query's baseline hit
+  7.5M tokens because a file in its resolved set has that much history. That is itself a finding, not
+  noise: at this scale, "just read the file's history instead" stops being a viable alternative at
+  all, which is a big part of why that column rounds to ~100%.
+- **This supersedes the previous ~40% figure**, which was hand-tallied from two hand-picked queries
+  against this repo alone, never instrumented, and used an unstated baseline. It was not wrong so much
+  as underspecified — this number replaces it with a stated method and a script that reproduces it,
+  rather than being a claim that the product got better.
 
 One thing that is not a percentage: shell commands and conversation turns have no cheap `grep`
 equivalent. Without something recording them, they are gone, not merely more expensive to find.
@@ -241,6 +303,11 @@ optimizing, and it is somebody else's process.
   unmounted drive is not a deleted project.
 - **Conversation chunking is unevaluated.** Splitting long replies at heading boundaries measurably
   helped, but it has never been tested systematically.
+- **A chunked node's sibling count in one result is capped, not tuned.** `conversation_turn` and
+  `doc_section` both split one reply or file into several nodes; at most 2 of them may appear
+  together in a packed result. Found live: a query for "token" returned 9 of its top 12 hits as
+  different pieces of one heavily-sectioned reply, crowding out the node that actually answered it.
+  The cap of 2 is a judgement call, not a measured optimum, same as the ranking priors' budget above.
 - **The size of the prior budget is a judgement call, not a measured optimum.** Priors are now
   bounded jointly rather than one at a time, which closed a real 4× hole (see the ranking section),
   but the 2× budget itself has never been tuned against a labelled relevance set — there isn't one.
@@ -260,8 +327,9 @@ is the intended way to tune scoring against a real repository before committing
 `--json` to pipe them somewhere.
 
 Every command takes `-C <path>` to target another repository. On `sync`, `--conversation` opts the
-transcript source in for one run without persisting it, `--no-embed` skips the vector pass, and
-`--rebuild` drops the project's nodes and re-ingests from scratch.
+transcript source in for one run without persisting it, `--no-embed` skips the vector pass,
+`--link-failures` builds the failure → fix chains described above, and `--rebuild` drops the
+project's nodes and re-ingests from scratch.
 
 ## Recall across projects
 
@@ -315,8 +383,8 @@ Deleting `.nexusmem/` loses nothing that `sync` cannot rebuild.
 
 ## Status
 
-Ingestion, hybrid retrieval, budgeted packing and the MCP server all work and are covered by 315
-tests running on Linux and Windows across Node 22 and 24. Phase 3 is complete.
+Ingestion, hybrid retrieval, budgeted packing and the MCP server all work and are covered by 342
+tests running on Linux and Windows across Node 22 and 24.
 
 ## Development