neuron is shared memory for your team's coding agents: every fix, convention and decision recorded once, as markdown in the repo, reviewed in pull requests, and injected automatically into Claude Code, Codex, Cursor and Copilot when it's relevant.
curl -fsSL https://raw.githubusercontent.com/kovartravis/neuron/main/install.sh | shnpm install -g @kovartravis/neuron# yesterday, on Alice's machine: her agent hit a flaky test, fixed it, and recorded why $ neuron memory add --category learning "Fix for false-positive Bash-command match: the pattern was a bare substring test, so any command that merely quoted the phrase got logged as a real invocation. Anchor it to a shell separator." {"id":"e9d606cd…","status":"created"} # today, on Bob's machine, after a git pull: his agent runs a shell command. Before it # executes, Claude Code's PreToolUse hook calls neuron and injects what's relevant. $ npm test PreToolUse:Bash hook additional context: - [learning] Fix for false-positive Bash-command match: the pattern was a bare substring test, so any command that merely quoted the phrase got logged as a real invocation. Anchor it to a shell separator. # nothing to paste into CLAUDE.md. no "remember to check memory" instruction. no third debugging session.
Every number below comes from a re-runnable harness checked into the repo. Click any card for the methodology and raw results.
Same agent, same SWE-bench Lite tasks, memory hook on vs. off. Pooled across 16 sessions.
The savings are not bought with worse answers — a deterministic grader passed every session.
A lexical filter plus a local cross-encoder reranker gate every injection, measured on an out-of-corpus test.
Local ONNX embeddings and SQLite. No API key, no account, no telemetry.
Token figures: SWE-bench Lite instances matplotlib-24265 and django-11019, real checkouts pinned before the fix landed, k=4 sessions per arm, deterministic grading. npm run bench:swebench-ab:dry-run validates the fixtures for free.
Three moving parts. None of them depend on the model remembering to do anything.
neuron initDetects Claude Code, Codex CLI, Cursor or Copilot CLI, pre-downloads the local models, and registers the recall hooks. One command, no config to hand-write.
neuron memory add --category learning "…"Fixes, conventions and decisions land in .neuron/*.md as schema-checked entries, committed with the code. A pre-stop hook nudges the agent to record before it ends the turn.
# next session — nothing to rememberAfter a pull, on every prompt and before every shell command, the hook queries the store and injects only what clears the relevance gate. No prompt instruction the model can skip.
Harness-native memory is yours alone, on your machine, invisible to review. neuron's is the team's.
The store is .neuron/*.md in the repo. Every clone, every teammate, every CI agent reads the same fixes and conventions — not a per-user cache in someone's home directory.
Read more →A memory change lands in the same PR as the code change that motivated it. Reviewers see the new lines in .neuron/learning.md next to the fix, and can reject them like any other diff.
Read more →Declare required and enum fields per category in neuron.yaml. A write missing a ticket or a reviewer is refused with an error naming exactly what is missing — regardless of the prompt.
Read more →On Claude Code and Codex CLI the harness itself runs the lookup on SessionStart, UserPromptSubmit, PreToolUse and PreCompact. The model never gets a chance to forget.
Read more →Claude Code, Codex CLI, Cursor and Copilot CLI adapters, plus an MCP server for Windsurf, Zed, Claude Desktop and Roo Code — all reading and writing the same markdown.
Read more →Local ONNX embeddings and a cross-encoder reranker gate every injection; nothing leaves your machine. Also in the box: neuron scan, an architecture card you can gate CI on.
Read more →A fix and the memory of the fix ship together. Reviewers see three new lines in.neuron/learning.md next to the code change — readable, greppable, and rejectable like any other diff. No database you need a viewer for.
Declare a field as required in neuron.yaml and the CLI refuses any write that omits it, from a human or an agent. neuron status --check catches anything that drifts afterwards; run it in CI next to your tests.
This isn't a toy example: neuron's own repository runs on its own .neuron/ store, and its memory changes are reviewed in pull requests like everything else.
src/test/server.ts afterEach(async () => { await server.close(); + await waitForPortRelease(server.port); }); .neuron/learning.md +--- +id: 4c1e7a2b-… importance: 4 +tags: [failure-fix, testing] +--- +Fix for ECONNRESET in the integration suite: the +mock server's port is reused before the OS frees +it. Wait for release in afterEach; a fixed sleep +hid the race on CI runners.
$ neuron memory add --category decisions "Chose Postgres" Error: --ticket is required for category "decisions" (neuron.yaml categories.decisions.fields.ticket). Pass --ticket <value>, or add a "default:" in neuron.yaml.
neuron init detects what's installed and wires the deepest hook each harness exposes. Where a harness has no per-turn hook, neuron says so instead of pretending.
| Harness | Memory recall | Pre-command lookup | Write nudge |
|---|---|---|---|
| Claude Codedeterministic | Every turn, automatically | Every shell command | Yes |
| OpenAI Codex CLIdeterministic | Every turn, automatically | Every shell command | Yes |
| GitHub Copilot CLIsession-start | Once per session | Via neuron exec | Yes |
| Cursorsession-start | Once per session + MCP | Via neuron exec | Yes |
| Windsurf, Zed, Claude Desktop, Roo CodeMCP | MCP tools | MCP tools | — |
Per-harness details, hook points and known limits: harness adapters.
You can keep your CLAUDE.md, and your harness's own memory. neuron is the part neither of them can be: shared, reviewed, and enforced.
It's one file, read in full on every prompt whether it's relevant or not, and nobody prunes it. neuron injects only the entries that clear a relevance gate and enforces structure on what goes in. Keep your CLAUDE.md for standing instructions; neuron handles what the agent learns.
That memory lives in your home directory — per user, per machine. Your teammate's agent never sees it, and it never appears in a pull request. neuron's memory is the team's: in the repo, in the diff, on every harness. Source.
Those are hosted APIs for general-purpose agents. neuron is offline, in git, and built only for coding agents.
Measured on real SWE-bench Lite tasks with the same agent, memory hook on vs. off: 57.7% fewer tokens, and every session in both arms answered correctly. See the numbers.
| CLAUDE.md / AGENTS.md | Harness built-in memory | Hosted memory API | neuron | |
|---|---|---|---|---|
| Where the memory lives | One growing prose file | Your home directory | Behind a hosted API | Markdown in your repo |
| Shared with the team | Yes, if committed | No | Via the vendor | Yes — it is in git |
| Works across harnesses | Per file name | No | Via SDK | Claude Code, Codex, Cursor, Copilot, MCP |
| What goes into each prompt | The whole file, every time | First N lines of an index | Whatever the API returns | Only what clears a relevance gate |
| Structure | None | None | Vendor schema | Your schema, enforced at write time |
| Review changes | git diff | Not reviewable | Vendor dashboard | git diff, same as code |
| Works offline | Yes | Yes | No | Yes — no API key, ever |
| Recall is guaranteed | Only if the model reads it | Only if the model reads it | Only if the agent calls it | Harness hook runs it |
Named comparisons — Mem0, Zep, claude-mem, agentmemory, Beads, and harness-native memory — on the alternatives page.
No. neuron runs 100% offline — it embeds text locally with ONNX models and stores everything in a local SQLite/markdown store. No API keys, no telemetry, nothing leaves your machine.
neuron ships harness adapters for Claude Code, OpenAI Codex CLI, Cursor, and GitHub Copilot CLI. Claude Code and Codex CLI get memory injected automatically on every turn; Cursor and Copilot CLI get it once per session, since those harnesses only expose a session-start hook. Any MCP-aware editor can use the neuron mcp server.
They can coexist, but they solve different problems. Claude Code's auto memory is stored per user under ~/.claude/projects/<repo>/memory/ and loaded for you alone; neuron's store is committed to the repo, so every teammate's agent — on Claude Code, Codex, Cursor or Copilot — reads the same entries, and changes to it go through code review.
A CLAUDE.md or AGENTS.md file is static prose an agent rereads in full every prompt, whether it's relevant or not, and it only grows over time. neuron stores memory as structured, schema-enforced entries and surfaces only what's relevant to the current query, instead of dumping one file into every prompt. You can keep both.
The recall hook runs a local hybrid search (SQLite FTS plus ONNX embeddings) and typically returns in well under a second on a warm cache. The first neuron init pre-downloads the models so there is no cold start mid-session.
Yes. neuron scan --check exits non-zero when the codebase drifts from the stored architecture card, and neuron status --check validates the store against your declared schema — both are ordinary CI steps.
Yes. neuron is MIT-licensed and installs via npm or a standalone curl/PowerShell binary, with no account or API key required.
Install, run neuron init in a repo, commit .neuron/ — and the next session, on anyone's machine, already knows what the last one learned.
npm install -g @kovartravis/neuron && neuron init