Neuron: Markdown-Backed Memory for AI Coding Agents
What neuron is
Section titled “What neuron is”Neuron is shared memory for a team’s coding agents. What one agent learns —
a fix, a convention, a decision — is recorded once into plain
.neuron/*.md files inside the repo, reviewed in pull requests like any
other change, and injected automatically into every teammate’s session on
Claude Code, Codex CLI, Cursor or GitHub Copilot CLI when it’s relevant.
That’s the difference from a harness’s own memory (per user, in your home
directory, invisible to review) and from a CLAUDE.md (one file, read in
full every prompt, never pruned). A schema declared in neuron.yaml is
enforced on every write — a malformed entry (missing a required field, an
invalid enum value) is refused by the CLI, not silently accepted. SQLite
sits underneath as a disposable semantic-search index, rebuilt from the
markdown automatically; delete it any time and nothing is lost.
Getting started
Section titled “Getting started”New to neuron? Install it via npm or a standalone binary, then work through the quickstart — initializing a project, recording a memory, and querying it back — in about five minutes.
Guides
Section titled “Guides”Task-oriented guides cover neuron.yaml configuration
end to end, and how neuron wires into your coding agent via
harness adapters — with a dedicated page
for each of the four shipped harnesses: Claude Code, Codex CLI, GitHub
Copilot CLI, and Cursor.
How it works
Section titled “How it works”For the mechanisms behind neuron’s behavior — not just the commands that trigger them — see the concept pages on hybrid search & RRF ranking, write-side enrichment, the declared field schema, and storage adapters.
Reference
Section titled “Reference”Every CLI command and every neuron.yaml field, listed exhaustively for
lookup rather than read-through, lives in Reference.
Weighing neuron against a cloud memory API or a CLAUDE.md/AGENTS.md file? See neuron vs. alternatives for an honest, sourced comparison.
Questions
Section titled “Questions”What does neuron actually store, and where?
Structured entries — learnings, decisions, architecture notes, tickets,
whatever categories a project declares in neuron.yaml — written to plain
.neuron/*.md files in your repo. A schema declared in neuron.yaml is
enforced on every write, and SQLite sits underneath only as a disposable
semantic-search index rebuilt from the markdown; deleting it loses nothing.
See storage adapters for the full mechanics.
Do I need an API key or internet connection to use neuron? No. Neuron embeds text locally with ONNX models and stores everything in a local SQLite/markdown store — no API keys, no telemetry, nothing leaves your machine.
How is neuron different from a CLAUDE.md or AGENTS.md file? 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 schema-enforced entries and surfaces only what’s relevant to the current query via relevance-gated recall, instead of dumping one file into every prompt. See the declared field schema for how that enforcement works.
Does neuron work with agents other than Claude Code? Yes — neuron ships harness adapters for Claude Code, OpenAI Codex CLI, Cursor, and GitHub Copilot CLI. Recall fidelity differs by harness: Claude Code and Codex CLI get memory injected automatically on every turn, while Cursor and Copilot CLI get it once per session, since those harnesses only expose a session-start hook. See harness adapters for the full comparison.