— LOCAL-FIRST · NO MODEL CALLS · MIT

Your codebase remembers.Your agent stops re-learning it.

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.

View on GitHub
0 model calls·44 ms cold start·Python 3.10+
store.pybilling.pywebhooks.pyADR-0002
import graph · confidence-graded memory
SCROLL

— 01 / THE PROBLEM

Every session starts from zero.
The agent re-reads the same files, re-derives the same constraints, and re-makes a decision your team settled six months ago.

CONTEXT

It reads everything.

9,000 tokens to answer a question worth 900.

BLINDNESS

It edits without looking.

Four other modules depended on that file.

TRUST

It says the tests pass.

It never ran them.

— 02 / THE LOOP

01

RECALL

Ask what's already known.

Before grepping, before reading. A verified fact costs 30 tokens.

nexus — project/

$ 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
02

PLAN

Find the blast radius.

Dependents, risks, owning role, missing ADR.

nexus — project/

$ 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]
03

VERIFY

Run the checks.

Diff, secrets, lint, types, vulnerabilities, API breaks, tests.

nexus — project/

$ 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
04

REMEMBER

Write down what you learned.

Anchored to a file, graded verified / observed / assumed.

nexus — project/

$ 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 — project/

$ 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

Numbers, with the command that produced them.

A

Context packing

Reading files whole
9,122
NEXUS context
916

nexus context "refactor nexus/record.py to support tags" --budget 4000 · counted with cl100k_base

B

Graph expansion

keyword only0.00
keyword + graph1.00

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.

C

Impact vs grep

grep · 4 files

  • session.py
  • middleware.py
  • api/login.py
  • comments.mdfalse positive — matched a comment

nexus · 7 files

  • session.py
  • middleware.py
  • api/login.py
  • api/refresh.py + transitive
  • tasks/cleanup.py + transitive
  • tests/test_session.py + transitive
D

Where the numbers show up

nexus · mem 42 · graph 628 · full:developer,security · saved~28,045 · 3 dirty
  • Status line

    Under the chat input, continuously. Registered by nexus install claude-code.

  • Session start

    In the conversation: the running saved total, every new session.

  • Every pack

    The full actual / baseline / saved breakdown, inline with the result.

You never have to run a command to see what you saved.

10,101 files·101 ms discovery·44 ms MCP init·318 ms impact, no graph

— 04 / HOW IT WORKS

Markdown is the truth. The index is a cache.

.nexus/*.mdthe truth · Git-friendly, diffable, human-readable
SQLite FTS5 indexa cache · delete it, reindex, lose nothing
keyword recall
graph expansion the join
code graphNEXUS reads graphs. It does not build them.

The join is the point.

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

You ask
is it safe to shorten the rotation window?
The fact
“refresh tokens are single-use; reuse revokes the family”
anchored to src/auth/session.py
Keyword
no match. Not one word of the question appears in the fact.
+ Graph
found it. The question names the file; the file is where that fact was verified; the graph walks from one to the other.

On 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.

01

Why Markdown is the truth and SQLite is not

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.

02

How a fact dies

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.

03

Why impact is a union, not a lookup

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.

04

Five tiers, one store

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

A pass with no captured evidence is not a pass.

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

One interface. A local project graph.

nexus recall

Memory that survives the session.

Confidence-graded facts in Markdown, retrieved by keyword and by graph.

nexus impact

Know what breaks first.

Parsed import edges across graph, text, tests, and optionally a language server.

nexus context

Packed, not pasted.

A brief under a hard token budget instead of whole files.

nexus verify

Evidence, not assertions.

Lint, types, vulnerabilities, API-shape diff, and the tests actually running.

nexus serve

Five MCP tools.

Claude Code, Cursor, Codex, VS Code. One command to wire it up.

nexus dashboard

Watch it for free.

127.0.0.1 only, unreachable from the MCP server, zero agent tokens. Enforced by a test.

— 07 / LIMITS

What it does not do.

Stated here because a tool that hides these is worse than one that has them.

LANGUAGE
Breaking-change detection parses Python only. Other languages get the diff and the tests.
STALENESS
Graph freshness is by mtime, not content hash. A touched-but-unchanged file reads as stale. False-stale is the safe direction.
DEAD CODE
Counts text occurrences, so it is blind to dynamic access. Treat a hit as a question, not a verdict.
BENCHMARKS
Every number here is synthetic and self-authored. Weak evidence by construction. A floor and a direction, not a measurement of your repo.
SCALE
Not yet run against a large third-party codebase. Only against itself and fixtures.
UNTRUSTED REPOS
A cloned project's .nexus/ was written by whoever wrote the project, and it enters your agent's context at session start. NEXUS fences and labels that block, but read .nexus/ before trusting a clone — the same way you would read its Makefile.
EMBEDDINGS
Considered and declined at recall@5 = 0.70 against a pre-registered trigger of "below 0.70". The threshold was set before the data and was not moved after.

— 08 / DOCUMENTATION

Everything is written down.

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.

Start here

What it is, what it measured, and where it runs.

Decisions

Two records, both of which argue against building more.

Build log

Six phases, each recording what failed before it worked.

Read them in the repository — github.com/jainrakshit24/nexus

— 08 / INSTALL

Stop re-explaining your codebase.

One command. Runs locally. MIT.

skills.sh

npx skills add jainrakshit24/nexus

Claude Code

/plugin marketplace add jainrakshit24/nexus

pip

pip install "nexus-eims @ git+https://github.com/jainrakshit24/nexus.git"