NexusMem

Your coding agent can read git log. It cannot read the four things you tried last Tuesday that didn't work.

NexusMem records what actually happened on your machine (shell commands and their exit codes, git history down to the patch of each changed file, project docs, optionally your assistant transcripts) into a local SQLite database, and serves back a ranked, token-budgeted slice of it on demand. Everything stays on disk. No account, no cloud, no telemetry.

The shell history is the part worth caring about. Git tells an agent what shipped. Shell history tells it what was attempted, in what order, and which commands exited non-zero. That information exists nowhere else, and it disappears when your terminal scrollback rolls over.

Contents: Try it · Exact shell capture · Failure → fix chains · How retrieval works · Session summaries · GitHub issues & PRs · Use it from an agent · What it costs you · Staleness & provenance · Where it breaks · Commands · Cross-project recall · On disk · Development

Try it

From inside any git repository:

npx nexusmem init
npx nexusmem sync

Then ask it something. Real output from this repository, top 2 of 5 hits:

$ nexusmem query "windows spawn failure"

Relevant history for: windows spawn failure

- 2026-08-09 [observed] fix: distinguish a failed git spawn from "not a git repository"
  readRepoInfo collapsed three unrelated failures into one error: git running and reporting
  the path is not a work tree, git not being installed, and the process failing to spawn at
  all. Dogfooding hit the third case in two separate sessions...
- 2026-08-09 [authored] README.md — Before a tagged release
  - [ ] Retry on transient process-spawn failures on Windows

[observed]/[authored] is the provenance tag (see Staleness & provenance) — a commit is a directly observed event, a doc section is a written claim that could go stale.

A commit and a docs section, ranked against each other, inside whatever token budget you gave it. Nothing was summarized by a model on the way out; the ranker just decided what not to send. (One optional source, session summaries, does run a local model — but at ingest time, never on the way out. What you query is always stored text.)

For a sense of what actually accumulates, here is nexusmem status on this repo after two days:

527 node(s)  2026-08-08 .. 2026-08-09
       321  shell_command
       130  conversation_turn
        60  doc_section
        16  git_commit

Sixteen commits. Three hundred and twenty-one shell commands. The commits were already retrievable by any agent with a terminal. The rest was not.

That conversation_turn row only appears because this corpus was synced with --conversation. Assistant transcripts are the one source that is off by default and stays off until you opt in, since they are the likeliest place for a pasted credential to be sitting. A default install indexes git commits, their diffs, shell and docs.

Requirements: Node 22 or newer, and git. Node 20 will not work, because better-sqlite3 ships no 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:

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.

Optional: what your coding agent tried

The shell hook above only sees commands you type. Commands your coding agent runs go through its own tool, so they never reach an interactive prompt — which means the dead ends an agent hits, the thing worth remembering most, were exactly what NexusMem could not see.

nexusmem agent install     # writes Claude Code's hooks; --project keeps it to this repo

Restart Claude Code afterwards. From then on, in any repository NexusMem has been run in:

• it records each command the agent runs, its outcome, and the files edited just before it, so an attempt reads "edited a.ts, then npm test failed" rather than "npm test failed twice";
• when a command fails, it says — to the agent, at that moment — whether that exact command has failed here before, what was edited each time, and what eventually fixed it;
• when a session starts, it syncs in the background and names commands that failed with no recorded fix.

It stays quiet the rest of the time. There is no match, no message; at most one note per failure per session and five per session; no embedding, model or network call on that path. If NexusMem is missing or broken the hook prints nothing and exits 0, and the agent carries on as if it were not installed.

Commands are redacted before they are written, exactly like the shell hook, and matching is done on a hash of the raw command so two commands differing only by a secret are never confused.

nexusmem agent status shows whether the hooks are installed; nexusmem agent remove takes out NexusMem's own entries and leaves any other tool's hooks alone.

Install from the same environment Claude Code runs in. What gets written into the settings file is a literal command — an absolute path to a Node executable and an absolute path into this copy of NexusMem — and Claude Code hands that string to a shell in its environment. Install inside WSL while Claude Code is the Windows binary (or the reverse) and the hooks are configured, look installed, and capture nothing: the paths do not resolve on the side that runs them, and a hook that cannot start produces no error anywhere. nexusmem agent status names any path in the installed command that does not exist on the machine you ask from, which is also what it says after the NexusMem it points at is moved, upgraded to a different location, or uninstalled.

Failure → fix chains (opt-in)

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 [observed] shell: npm whoami  (exit 1)
- 2026-08-12 [observed] 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 section compete on equal terms. Retrieval runs BM25 over FTS5 and, if an embedding model is reachable, a vector search over sqlite-vec, fused with Reciprocal Rank Fusion on rank position only, never raw scores — a BM25 cost and a vector distance live on unrelated, unbounded scales, and position is the only thing they agree on.

Ranking then multiplies three factors:

score = relevance × signal^0.215 × recency^0.288

relevance comes from the query. signal (a fix: commit outranks a chore:; a failed command outranks a successful one) and recency are priors that hold before any query exists. Each factor is floored into [floor, 1] rather than [0, 1], so one weak dimension can't zero out a strong match.

The exponents bound how far signal and recency, together, may overturn relevance: at most a 2× gap across their whole range, applied jointly rather than per-prior. That's deliberate — the score multiplies the two priors, so capping each at 2× separately still let the pair overturn 4×, and that hit hardest on fresh, high-signal commits made during an active working day. The bug that exposed this: two unrelated same-day fix: commits outranked the docs section that actually answered the query. See retrieval/rank.ts for the full derivation.

Without Ollama, vector search is skipped and you get BM25 only — fully supported, not a degraded state; sync and query both succeed and simply do less.

Session summaries (optional, local model)

With sources.session.enabled, each finished session becomes one distilled node next to the raw exchanges — what was decided and why, rather than forty individual turns. It runs a local Ollama chat model (qwen2.5:3b by default); nothing is downloaded automatically and nothing leaves the machine.

nexusmem scan-session --dry-run

That prints the exact prompt a session would produce, after redaction and budget trimming, without calling the model.

Three things bound the cost. A session is only summarized once it has been quiet for settleMinutes (default 30), so a session in progress is not re-summarized on every sync. The prompt is hashed, and an unchanged hash skips the model entirely — on this repo a steady-state sync of 14 summarized sessions takes 0.25s and makes no model calls. And maxSessions (default 10) caps how many reach the model per run; the rest are reported as queued and picked up next sync.

What it is actually like, measured on 14 real sessions with qwen2.5:3b. The summaries themselves are good: decisions with their reasons, in the shape the prompt asks for. Titles are less reliable — the model returned a usable one about a third of the time, and otherwise produced a conversational preamble, a stray bullet, or a bare "Summary of the Session". Those are rejected and the title falls back to the first line of the question that opened the session, which is always specific even when it is not elegant. Compliance was worst on long sessions and on transcripts not in English. A larger model (qwen2.5:7b) is the lever if the titles matter to you; set sources.session.model.

GitHub issues & PRs (optional)

With sources.github.enabled, each issue and PR on this repo's github.com remote becomes one node (title, opening post and every comment, folded together) alongside the raw discourse a discussion already leaves in shell/conversation history. Off by default — not for a sensitivity reason, but because it's the first source with a real external dependency: it reads via the gh CLI, so it needs gh installed and authenticated (gh auth login), and it makes live network calls instead of only reading what's already on disk. A repo with no github.com remote, or an unauthenticated gh, is a silent no-op either way.

nexusmem scan-github

previews the nodes a sync would produce, same as the other scan-* commands. maxThreads (default 100) and maxCommentsPerThread (default 100) bound one sync's cost; since is tracked as its own cursor, so a repeat sync only re-reads threads that changed. Dogfooded against this repo's own 14 real issues/PRs: ingest took under a second, and a query for "labelled retrieval regression corpus" correctly ranked issue #8 — the one that asked for it — first.

Use it from an agent

{
  "mcpServers": {
    "nexusmem": {
      "command": "npx",
      "args": ["-y", "nexusmem", "mcp"]
    }
  }
}

Three tools over stdio: search_memory returns the packed context block, sync_project ingests, and get_status reports what is currently remembered. Each takes an explicit projectRoot, because an MCP tool call carries no shell working directory. sync_project runs init for you if the repository has not been set up.

What it costs you

Two numbers get conflated in tools like this, so they are kept apart here.

Packer efficiency is how much the ranker trims from its own candidate set. On this repository's corpus it runs 81–84%. It is useful for tuning the ranker and useless as a claim about your bill, 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 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 (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	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 — it's a narrower claim than it looks:

• Graded against NexusMem's own ranking, not an outside answer key: the file set is whichever files the packed nodes for that query touch. This measures what the pack step saves once retrieval already picked a candidate set; it doesn't independently verify that set was the right one.
• Query sets are mechanical, not cherry-picked (see scripts/benchmark.ts): vite's is an even sample of well-explained fix/feat/perf/refactor commits plus rationale-bearing doc headings; this repo's reuses real historical prompts verbatim, several of which are broad task instructions rather than narrow questions — part of why its number sits below vite's.
• git log -p baselines can be enormous — one vite query's baseline hit 7.5M tokens because a file in its resolved set has that much history. At that scale, "just read the file's history instead" stops being a viable alternative at all.
• Supersedes the old ~40% figure, which was hand-tallied from two hand-picked queries against this repo alone with an unstated baseline. Not wrong, just underspecified — this replaces it with a stated method and a script that reproduces it.

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.

For how these numbers compare to a similar tool's own claims, see docs/competitor-comparison.md (vs. projectmem) and docs/competitor-comparison-yesmem.md (vs. YesMem, including native Windows support vs. its documented WSL2 requirement).

Latency on a ~530-node corpus, warm, p50 over 10 runs:

Operation
BM25 retrieval (FTS5)	~1.1 ms
Vector KNN (sqlite-vec)	~3.2 ms
Fuse, rank, pack	~0.6 ms
Query embedding (local Ollama)	~55–77 ms
End-to-end hybrid	~56 ms

All the SQLite work totals about 5 ms. The embedding call is the only thing on this path worth optimizing, and it is somebody else's process.

Staleness & provenance

Two things a memory layer needs and this one only partly has: a way to tell an observed fact from a guess, and a way to retire a conclusion once something contradicts it. This section is what exists and what doesn't.

Every node carries a provenance, a four-tier trust hierarchy set once per collector at ingest time: observed (a commit that landed, a shell command's real exit code) > authored (a doc section — a human's own written claim) > recorded (a conversation turn — verbatim, but talk about events rather than the events) > derived (a session summary — a model's distillation). The tier is shown as a tag on every query result and decays retrieval weight — the lower the trust, the faster a node fades from ranking as it ages. The ordering is the design claim; the exact decay ratios are judgment calls, not measured optima.

nexusmem stale

Lists non-observed nodes old enough (45+ days by default) that nothing has confirmed they still hold — a heuristic on age and provenance, not on content. It writes nothing; you decide which candidates are actually wrong. Any candidate the SLM has already flagged (see below) is decorated with its standing likely superseded by suggestion — reading those costs nothing, so the plain command stays instant and offline.

nexusmem mark-stale <oldNodeId> --supersedes <newNodeId>

Links newNodeId as the replacement for oldNodeId. The ranker down-weights the old node from then on (it stays queryable, just usually loses to its replacement) — nothing is deleted, unlike forget.

nexusmem stale --check-contradictions

For each candidate, finds the most similar newer node (local embedding search) and asks a local SLM (Ollama, qwen2.5:3b by default) whether it actually contradicts the older one — real content comparison, not just age. A match is printed as likely superseded by <id> <title> -- <reason> under the candidate. Every judgment (either verdict) is memoized, so a judged pair is never sent to the model again; nothing else is written — supersedes stays yours to set via mark-stale.

This also runs automatically during sync — at most 3 new judgments per run (configurable via the contradictions block in .nexusmem/config.json; set autoCheck: false to turn it off), only when the embedding provider was reachable anyway, and free on repeat syncs thanks to the memoization. New and open suggestions show up in the sync summary, nexusmem status (a flagged line), and plain nexusmem stale.

What this doesn't do: it is one small model's yes/no judgment on one older/newer pair, not a verified fact — treat a match as a lead to check, not a conclusion. It also only ever compares a candidate against nodes found by embedding similarity; a contradiction from an unrelated-sounding node would never surface. Comprehensive contradiction detection (not just for the pair the vector search happens to surface) is still an open problem, and nothing here supersedes a node on its own.

provenance is a separate question from trust_state: provenance says where a claim came from, never whether anyone checked it.

nexusmem review <nodeId> --verify
nexusmem review <nodeId> --reject

Records your own verdict on one node, independent of the SLM contradiction checker above (which only ever writes a suggestion, never a verdict). --reject down-weights the node in ranking — same demote-not-delete rule as mark-stale, it stays queryable, just usually loses to better matches — and both verdicts are shown as a [verified]/[rejected] tag on every query result that returns the node afterward. --verify is a label only; it does not boost ranking. Every node starts candidate (untagged) until reviewed, and a re-sync never overwrites a verdict once one is set.

Where it breaks