CONTEXT
It reads everything.
9,000 tokens to answer a question worth 900.
— LOCAL-FIRST · NO MODEL CALLS · MIT
Durable project memory, real blast-radius analysis before an edit, and a gate that runs the checks instead of claiming they passed. Nothing leaves your machine.
— 01 / THE PROBLEM
CONTEXT
9,000 tokens to answer a question worth 900.
BLINDNESS
Four other modules depended on that file.
TRUST
It never ran them.
— 02 / THE LOOP
Ask what's already known.
Before grepping, before reading. A verified fact costs 30 tokens.
$ nexus recall "auth token refresh"
[100.0] refresh-tokens-are-single-use (project/verified) — src/auth/session.py:4 [ 86.4] refresh-failures-fall-through-to-re-login (project/verified) — src/auth/middleware.py:5 [ 71.2] the-15-minute-window-predates-mobile (project/observed) 3 result(s) in 2 ms
Find the blast radius.
Dependents, risks, owning role, missing ADR.
$ nexus plan src/auth/session.py
# Plan 20261117T043054 **Targets:** src/auth/session.py **Workflow:** full (target path matches a risky pattern) **Blast radius:** 4 ## Roles - developer — every change needs one - security — touches authentication, secrets or input handling - qa — 4 dependent(s) can break ## Dependents that must keep working - src/auth/middleware.py · src/api/refresh.py · tests/test_session.py ## What we already know - refresh-tokens-are-single-use [verified]
Run the checks.
Diff, secrets, lint, types, vulnerabilities, API breaks, tests.
$ nexus verify
# Post-edit gate: FAIL ## Breaking API changes (1) - rotate_token — parameter removed or renamed: before: rotate_token(token, grace=...) after: rotate_token(tok) ## Tests `pytest` PASSED in 0.3s ## Static checks - lint: `ruff check .` FAILED (exit 1) in 0.4s - types: NOT RUN — no types tool is configured for this project - vulnerabilities: NOT RUN — no tool is configured
Write down what you learned.
Anchored to a file, graded verified / observed / assumed.
$ nexus remember "refresh tokens are single-use; reuse revokes the family" --confidence verified --source src/auth/session.py:142
created: refresh-tokens-are-single-use [project/verified] mem_01M7KWAQDP7DQPJE35V0 anchored to src/auth/session.py — this fact is marked stale the moment that file's contents change.
$ nexus recall "auth token refresh"
[100.0] refresh-tokens-are-single-use (project/verified) — src/auth/session.py:4 [ 86.4] refresh-failures-fall-through-to-re-login (project/verified) — src/auth/middleware.py:5 [ 71.2] the-15-minute-window-predates-mobile (project/observed) 3 result(s) in 2 ms
— 03 / MEASURED
nexus context "refactor nexus/record.py to support tags" --budget 4000 · counted with cl100k_base
Questions only the graph can answer · recall@1
1.00 is not a general accuracy claim. One fact per file, asked one hop away. What it proves is the direction: a class of question keyword search answers zero times, the graph answers.
grep · 4 files
nexus · 7 files
nexus · mem 42 · graph 628 · full:developer,security · saved~28,045 · 3 dirtyUnder the chat input, continuously. Registered by nexus install claude-code.
In the conversation: the running saved total, every new session.
The full actual / baseline / saved breakdown, inline with the result.
You never have to run a command to see what you saved.
— 04 / HOW IT WORKS
.nexus/*.mdthe truth · Git-friendly, diffable, human-readableSQLite FTS5 indexa cache · delete it, reindex, lose nothingkeyword recallgraph expansion the joincode graphNEXUS reads graphs. It does not build them.Keyword search answers "what did we say about auth." Graph expansion answers "what do we know about the code this file depends on" — a question with no shared vocabulary at all. Anchor a fact to a file and it becomes reachable through the import graph, and goes stale on its own when that file changes.
A question keyword search cannot answer
is it safe to shorten the rotation window?
src/auth/session.pyOn a benchmark built entirely from questions of this shape, keyword search scores 0.00 and keyword + graph scores 1.00 — a direction, not an accuracy claim. The caveat is in docs/BENCHMARK.md.
A fact is one file with YAML front matter and a sentence. That means a change to what the project believes shows up in `git diff` and gets reviewed in a pull request like any other change. Make the database the truth instead and memory becomes a binary nobody can read, review or merge. The index exists only because FTS5 is faster than grep — delete `.nexus/index.db`, run `nexus reindex`, and nothing is lost.
Rejected for this reason: Mem0, Letta, claude-mem — each owns the store, and two of them own the agent loop as well.
Nothing is overwritten and nothing is deleted. A contradicting fact supersedes the old one, which moves to `.nexus/superseded/` and stays readable — history is the point. Separately, a fact recorded with `--source src/auth/session.py:4` stores a hash of that file's contents. When the hash stops matching, retrieval says so out loud rather than serving a fact whose ground has moved.
A fact graded `observed` or `assumed` never claims currency in the first place, so it is never marked stale.
Four sources answer “what else breaks”, because each one is blind where another sees. The import graph misses dynamic dispatch. A language server misses references that are not code — SQL, config, templates. Text search finds those and over-matches on comments. Test files tie a change to the thing that proves it. NEXUS unions all four and labels which source found what, so a weak hit never reads like a parsed one.
Measured against grep on the same target: grep found 4 files, NEXUS found 7, and dropped grep's one false positive — a match inside a comment.
Global facts are conventions that follow you between projects and live in `~/.nexus/global/`. Project facts are the stack, the architecture, the known bugs. Episodic records are what happened in a session and decay — `nexus consolidate` folds them into monthly summaries. Semantic facts are reusable and graph-linked. Procedural records are how to build, test and run the thing. One index spans all five, so a single recall reaches every tier at once.
All of it is plain Markdown under `.nexus/`, except the global tier, which is shared across every repository on the machine.
— 05 / THE INVARIANT
if self.exit_code == 0 and not self.log.strip():
raise ValueError("refusing to record a passing check with no captured output")It is structurally impossible to construct a passing result without the output that proves it. “Configured but not installed” is reported as a broken setup, never as a pass.
— 06 / SURFACE
nexus recallConfidence-graded facts in Markdown, retrieved by keyword and by graph.
nexus impactParsed import edges across graph, text, tests, and optionally a language server.
nexus contextA brief under a hard token budget instead of whole files.
nexus verifyLint, types, vulnerabilities, API-shape diff, and the tests actually running.
nexus serveClaude Code, Cursor, Codex, VS Code. One command to wire it up.
nexus dashboard127.0.0.1 only, unreachable from the MCP server, zero agent tokens. Enforced by a test.
— 07 / LIMITS
Stated here because a tool that hides these is worse than one that has them.
— 08 / DOCUMENTATION
Including the parts that did not work. Each phase log records what broke before it shipped, each benchmark carries the command that produced it, and both decision records argue against building more.
What it is, what it measured, and where it runs.
docs/BLUEPRINT.mdArchitecture, the five memory tiers and their lifecycle, the storage decision, the security model, and the token-accounting rules — including the upgrade trigger written down before the data arrived.
docs/BENCHMARK.mdEvery number on this page, with the command that produced it and a paragraph on how to read it honestly. Includes the section titled “what these numbers are not.”
docs/COMPATIBILITY.mdHost support, row by row. Each one says tested or untested — one of four MCP hosts has actually been handshaken, and the table says so rather than implying four.
Two records, both of which argue against building more.
docs/adr/0001Most of NEXUS already existed as mature tools. This records the decision to build only the join nobody had, and to reject Mem0, Letta and claude-mem with the reasoning for each.
docs/adr/0002recall@5 landed at 0.70 against a trigger of “below 0.70”, pre-registered before the benchmark ran. The threshold was not moved afterwards. The reopening conditions are listed.
Six phases, each recording what failed before it worked.
docs/PHASE1.mdThe store, the record format, scrubbing, discovery. Shipped with an unstable recall order that had to be fixed with an id tiebreaker.
docs/PHASE2.mdThe graph join and blast radius. Two deliverables were scoped down here because a dependency could not do what the plan assumed.
docs/PHASE3.mdThe gates. Where NEXUS stopped only knowing things and started refusing careless ones.
docs/PHASE4.mdMCP server, host adapters, hooks, dashboard. The handshake failed first because the server invented a protocol version instead of echoing the client's.
docs/PHASE5.mdGraph expansion in retrieval — the half of the blueprint that had never been built — plus staleness and consolidation.
docs/PHASE6.mdLint, types, vulnerabilities, breaking-change detection. Also where a self-audit found a command injection in NEXUS's own test runner, and fixed it.
docs/RESEARCH.mdWhat already existed before any code was written: the tools, their licences, and the reuse-versus-build call for each.
docs/PHASES.mdThe plan and its acceptance criteria. The brief suggested ten phases; this collapsed them to four, and says why.
Read them in the repository — github.com/jainrakshit24/nexus
— 08 / INSTALL
One command. Runs locally. MIT.
skills.sh
npx skills add jainrakshit24/nexusClaude Code
/plugin marketplace add jainrakshit24/nexuspip
pip install "nexus-eims @ git+https://github.com/jainrakshit24/nexus.git"