01 · Capture
Hook is a file append.
Stop, SessionEnd, and PreCompact each fire a sub-50ms append into a queue. No LLM, no commit, no waiting — you can't feel it. Plus 5 source ingests (gmail, gcal, gdrive, slack, claude) on schedule.
v2.1 · research preview
The second brain
that thinks like you.
A knowledge corpus that captures your decisions, voice, and relationships while you work. Read by every AI agent. Yours forever.
This isn't memory. It's a knowledge corpus.
Memory is "what did I say last Tuesday." Vendor memory features handle that fine.
The actual problem is your knowledge corpus lives half in your head, half in scattered notes, half in a thousand AI sessions you can't get back. Your voice. Your taste. The decisions you've made and the why behind them. Your relationships and how you talk to each one. Every AI agent you start fresh has to be brought up to speed.
nanobrain captures that corpus while you work, distills it in your voice, and lets every agent read it. The brain builds itself. You don't have to remember to remember.
Built on Karpathy's LLM Wiki pattern
In April 2026, Andrej Karpathy described the pattern: three-layer corpus (raw / wiki / schema), immutable raw firehose, LLM-owned wiki, schema co-evolution via ADRs, git-native, source-dated entries. What he described as a personal practice, nanobrain ships as a framework.
how it works
Three loops. Always-on capture. Idle-time distill.
Each loop is bash-only and reversible. None of them ever block your terminal.
02 · Distill
LLM only when you're idle.
A background drainer wakes every 30 minutes. If you're typing, it skips. If you've been quiet 5+ minutes, it pulls one queued session and distills it into your brain — in your voice. Hard timeout 3 min per call.
03 · Query
Read from any agent.
/brain who is jane. Or wire any MCP-aware agent
(Claude, Cursor, Codex, Gemini, Aider) at code/mcp-server/.
Context-filtered: agents only see their declared scope.
Claude session → ┌────────────────────────────────────────────────┐ Gmail thread → │ hook (50ms) → data/<src>/INBOX.md (firehose) │ Calendar → │ drainer → brain/<file>.md (distilled) │ Google Drive → │ raw mirror → brain/raw.md (full copy) │ Slack → │ graph → brain/_graph.md (auto-link) │ └────────────────────────────────────────────────┘ │ ▼ /brain who is jane /brain links project-x /brain spawn branding-agent /brain compact ← weekly /brain evolve ← monthly
Plus per-entity pages (brain/people/<slug>.md, brain/projects/<slug>.md),
[[wikilink]] backlink graph, operation log, auto-generated brain index, lint, integrity hash,
agent foundry. Full surface in the 17 commands.
how it compares
Every other "memory" tool locks you in. This one outlives them.
| nanobrain | Anthropic Memory | OpenAI Memory | Mem0 / Letta | Notion / Reflect | Vector RAG | |
|---|---|---|---|---|---|---|
| Markdown native | ● | — | — | — | — | — |
| Works without internet | ● | — | — | ○ | — | — |
| You own the data | ● | — | — | ○ | — | ○ |
| Readable in 50 years | ● | — | — | — | — | — |
| Self-improving | ● | ● | ● | ○ | — | — |
| Multi-agent (Claude / Cursor / Codex / Gemini) | ● | — | — | ○ | — | ○ |
| Token cost is constant | ● | n/a | n/a | n/a | n/a | — |
| Readable by grep | ● | — | — | — | — | — |
| Open source | ● MIT | — | — | mixed | — | mixed |
17 commands
Three groups. Daily use. Maintenance. Recovery.
All idempotent. All reversible via git revert (except /brain-redact, which rewrites history by design).
Daily use · the loop you live in
/brain
Query the brain. Subcommands: paths (where files live), status (last commit + corpus sizes), links <entity> (every [[backlink]] across the corpus).
/brain-save
Force-save a decision or learning mid-session. Routes to the right category file, redacts secrets, mirrors to raw.md, commits. Optional --page <slug> appends to a per-entity page.
/brain-ingest
Pull one source into its INBOX.md (gmail, gcal, gdrive, slack, claude). Resolver auto-tags each entry with {context: work | personal}. Secrets stripped before write.
/brain-distill
Read a source's INBOX.md, run an LLM pass to extract signal, append targeted blocks to brain/<file>.md + a full mirror to raw.md. The drainer chains ingest → distill automatically.
/brain-spawn
Mint a specialized agent with declared context_in, reads, writes. A branding agent on the work side. An investing agent on personal. Boundary-locked, refuses firehoses by default.
/brain-init
Bootstrap a new brain. Scaffolds brain/_contexts.yaml, builds resolver patterns from your work / personal email flags. install.sh calls it for you.
/brain-doctor
Health check. Validates contexts, lists configured sources, pings the MCP server, surfaces failed queue entries with retry hints, and reports GitHub push failures.
Maintenance · sleep cycles + integrity
/brain-compact
Weekly cleanup. Dedupes duplicate dated headers, archives entries older than 365 days, regenerates the graph, verifies the integrity hash, commits. Mechanical only — no LLM.
/brain-evolve
Monthly self-improvement. Reads the last 30 days of signal, proposes ONE targeted edit to a brain file, written to code/agents/_proposed/. You review and mv to apply. Single-shot, never auto-applied.
/brain-checkpoint
Force-capture mid-session. Bypasses the throttle. For risky changes, end of long sessions, or guaranteed capture before disconnecting.
/brain-graph
Rebuild brain/_graph.md — inverted index of every [[wikilink]] across the corpus, organized by entity with file:line backlinks. Excludes raw.md and interactions.md.
/brain-index
Rebuild brain/index.md — categorized catalog of every brain file with one-line summaries, per-entity tally, sources table. The TOC for the corpus.
/brain-lint
Static analysis. Catches orphan pages, broken refs, TODO/FIXME markers, duplicate dated headers, missing {context:} tags. --strict exits 1 for CI.
/brain-log
Append one operation line to brain/log.md in ## [YYYY-MM-DD HH:MM] op | title format. Greppable. Called automatically by every other skill.
/brain-hash
Build or verify BRAIN_HASH.txt — hash of canonical brain files (excludes raw.md and archives). Detects accidental corruption or drift.
Recovery · when something goes wrong
/brain-restore
Non-destructive time travel. Lists all git tag checkpoints, creates a new restore/<sha> branch from any chosen point. Never resets HEAD, never force-pushes, never destroys current work.
/brain-redact
Last-resort secret scrub. Pattern-matches a leaked secret across all of git history, rewrites blobs, force-pushes the cleaned history, logs the redaction. Destructive by design — always --dry-run first.
bootstrap
Two minutes to install. The brain takes it from there.
You need Claude Code, a GitHub account, macOS or Linux. Sessions queue instantly; the first distilled entry lands the next time your keyboard is idle 5+ minutes.
01
# Clone the framework
git clone https://github.com/siddsdixit/nanobrain ~/nanobrain02
# Create a PRIVATE repo for YOUR brain content
gh repo create my-brain --private --clone03
# Install (capture hooks + idle distill drainer + skills)
bash ~/nanobrain/install.sh ~/my-brain \
--work [email protected] \
--personal [email protected] \
--gh-repo my-brain04
# Use Claude Code normally. Step away from the keyboard.
# A few minutes after you go idle:
cat ~/my-brain/brain/decisions.md
Capture wires into Claude Code's Stop, SessionEnd, and
PreCompact hooks. Each is a sub-50ms file append, invisible to you.
The distill drainer runs every 30 min via launchd, but only does LLM work
when your keyboard's been idle for 5+ minutes (or your lid is closed). The brain builds
itself in the background. You never wait on it.
works with
Read from any agent. Capture from Claude today, the rest in v2.2.
Claude Code
Native capture via Stop, SessionEnd, PreCompact hooks. Read via MCP.
read · captureCodex CLI
Read via MCP today. AGENTS.md auto-loads. Capture wrapper in v2.2.
Cursor
Read via MCP today. .cursorrules auto-loads. Capture wrapper in v2.2.
Gemini CLI
Read via MCP today. GEMINI.md auto-loads. Capture wrapper in v2.2.
Aider
Read via MCP today. AGENTS.md inherits. Capture wrapper in v2.2.
Setup per tool: docs/COMPATIBILITY.md.
faq
Questions you'd ask before installing.
How is this different from Anthropic Memory / ChatGPT Memory / Gemini Memory?
Those are vendor-locked. Switch tools and you lose your memory. nanobrain is markdown plus git in your own repo. Read by Claude today, readable by any agent or human tomorrow.
Does it leak my secrets to Anthropic when capture runs?
No. code/lib/redact.sh runs over every transcript delta before claude -p ever sees it, stripping common token formats (OpenAI, Anthropic, GitHub, AWS, Slack, JWT, Bearer, inline api_key=). Tested in CI. Best-effort — use /brain-redact <pattern> if anything slips through.
Why not Obsidian / Logseq / Reflect?
Great UIs. Not multi-agent context substrates. nanobrain is the substrate. Obsidian works fine on top since it reads the same markdown.
Why not a vector DB?
Token-budget protected, deterministic, greppable, inheritable. Add a vector layer later if you want. Markdown stays the source of truth.
Why not just CLAUDE.md?
CLAUDE.md is one file. nanobrain is a corpus that grows, distills, self-lints, and protects itself.
Will my brain leak through commits?
Two repos. The public framework never sees your content. Your private brain is yours. Push failures surface immediately in /brain-doctor.
What if I want to leave?
cat brain/self.md. That is your exit strategy. No migrations, no exports, no vendor permission required.
Does it work on Linux?
The bash core works on Linux 3.2+. The launchd cron plists are macOS-only — on Linux, add equivalent cron entries manually. See code/cron/.
roadmap
Where it's going.
- v2.0 17 skills, 5 sources, MCP server, Karpathy alignment, 173/173 tests green
- v2.1 Multi-tool activation files (AGENTS.md, GEMINI.md, .cursorrules); read-side support via MCP for Codex / Cursor / Gemini / Aider
- v2.1.1 Split capture from distill (idle-gated drainer); 50ms hooks that never block you
- v2.2 Capture wrappers for Codex CLI / Cursor / Gemini CLI / Aider (session → distill on close)
- v2.3 Source plugins — voice memos, Granola meeting notes, repos
- v2.4 Browser extension for claude.ai / chatgpt.com / gemini.google.com
- v3.0 Optional vector sidecar (markdown stays source of truth), encrypted
data/_sensitive/
lineage
Standing on the shoulders of.
- Andrej Karpathy's LLM Wiki gist · the seed idea. Three-layer corpus, immutable raw, LLM-owned wiki, git-native.
- Karpathy's
autoresearch· git history as agent memory. - Vannevar Bush's memex (1945) · the original associative trail.
- Obsidian, Logseq, Roam · wikilinks as a primitive.
Stop teaching every agent who you are.
Capture once. Read everywhere. Forever.