yaminbkk/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:
Then ask it something. Real output from this repository, top 2 of 5 hits:
[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:
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:
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.
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