project-brain

Every Claude Code session, in every project, captured into one plain-Markdown brain you own.

Claude Code forgets. Its transcripts are deleted after 30 days, its memory is scoped per-project and per-machine, and Anthropic has declined to build cross-device memory. project-brain fixes that with the simplest thing that works: Markdown files in a folder you control.

• 🧠 One brain, all projects — a single vault with an index; ask about any past project from anywhere
• 📼 Nothing is ever lost — every session auto-archived as readable Markdown before Claude Code deletes it
• 🔒 Redaction by default — API keys, tokens, private keys, and <private>-tagged text stripped before anything is written
• 📝 Notes, not noise — sessions are distilled into decision/fact/open-thread notes, compiled into living project pages
• 💰 Flat token cost — only a tiny index is injected per session; knowledge loads on demand. No vector DB, no service, no subscription
• 🗑️ Deletable engine — if you uninstall everything tomorrow, your knowledge is still plain Markdown

Quickstart (60 seconds)

/plugin marketplace add vikasgrac/project-brain
/plugin install project-brain@project-brain

Then, inside a Claude Code session (the brain CLI ships with the plugin and is on PATH in sessions, not in your plain terminal — just ask Claude to run it):

brain init            # required, once — scaffold the vault (default: ~/claude-brain)

Capture starts with your next session — from then on everything is automatic: archive, redact, distill, compile.

Optional — import the session history you already have (do this soon: Claude Code deletes transcripts after 30 days):

brain backfill        # rescue + archive your existing session history
brain distill-all     # distill that history into notes & project pages (uses your Claude subscription)

Only backfilled history needs distill-all — new sessions are distilled automatically.

Also strongly recommended — stop Claude Code deleting your transcripts (~/.claude/settings.json):

{ "cleanupPeriodDays": 3650 }

That's it. From now on: end a session → it's archived, redacted, distilled, and compiled into your brain automatically. Start a session → the brain's index is injected automatically. Ask /project-brain:recall <topic> for deep lookups.

How it works

 session ends ──► SessionEnd hook (enqueue, <20ms) ──► background worker
                                                          │
        ┌─────────────────────────────────────────────────┤
        ▼                    ▼                    ▼       ▼
   1. ARCHIVE           2. REDACT            3. DISTILL   4. COMPILE
   JSONL → readable     keys/tokens/PEM/     headless     merge notes into
   Markdown             <private> stripped   claude -p    project page +
                                             → session    MEMORY.md index,
                                             note         auto-commit

 session starts ──► SessionStart hook injects MEMORY.md (a ~20-line index)
                    Claude opens only the 1–2 relevant files on demand

The vault (all plain Markdown, YAML frontmatter compatible with OKF):

<vault>/
├── MEMORY.md              the index — one line per project/topic (injected each session)
├── projects/<name>.md     living page per project: state, decisions, open threads
├── topics/<name>.md       knowledge promoted when it recurs across projects
├── sessions/<project>/    one distilled note per session (status: generated)
├── archive/<project>/     full redacted transcripts — grep-able episodic memory
├── log.md                 append-only audit: what the engine changed and why
└── projects.json          project-identity registry (nested folders, collisions)

This is the "LLM wiki" pattern: raw sources → agent-maintained wiki → index, with the engine's lint keeping it healthy. Retrieval is index-first + grep — the same mechanism coding agents actually use, no embeddings required.

Configuration

~/.config/claude-brain/config.json (or BRAIN_DIR env var for the vault path):

Key	Default	Meaning
vault_path	~/claude-brain	Where the brain lives. Put it in a synced folder for cross-machine memory.
archive_verbosity	minimal	user-only | minimal | full — how much of each session to archive
exclude_projects	[]	Projects never captured
project_map	{}	Manual path→name overrides for project identity
redact_extra_patterns	[]	Additional regexes to redact
distill_mode	llm	llm (headless claude -p, covered by your subscription) | off
distill_model / compile_model	haiku / sonnet	Models for note extraction / page compilation
inject	index-only	index-only | index+project — what SessionStart injects
inject_budget_chars	8000	Hard cap on injected context
auto_commit	true	Git-commit the vault after each capture/compile

Privacy

• Local by default. Nothing leaves your machine. The vault's git repo has no remote unless you add one. Distillation runs through your own Claude Code login.
• Redaction at write time: Anthropic/OpenAI/GitHub/AWS/Slack key patterns, JWTs, Bearer tokens, private-key blocks, password=/token= assignments — plus your own patterns. Wrap anything in <private>…</private> in chat and it is dropped entirely.
• Honest caveat: redaction is pattern-matching, not a guarantee. archive/ contains your conversations. Treat the vault as private; if you back it up to a remote, make it a private one.
• Raw unredacted spool files (queue, pre-compaction snapshots) stay machine-local in ~/.claude/brain-spool/ and never enter the vault.

Commands

brain init · brain status · brain backfill · brain distill-all [n] · brain lint · brain archive <jsonl> — plus skills /project-brain:recall and /project-brain:status.

FAQ

Where does my data live? In the vault at ~/claude-brain (or wherever vault_path points) — not inside the plugin. Uninstalling the plugin leaves your vault untouched. Sessions run outside any project directory are bucketed under a project named home.

Doesn't Claude Code have memory already? Per-project, per-machine, read-once-at-startup, and silently truncated. project-brain is cross-project, cross-machine (via any folder sync), captures conversations not just facts, and keeps the full episodic record grep-able.

Why not a vector database? For a personal-scale brain, an index + grep over well-structured Markdown outperforms RAG in practice and can't hallucinate a wrong chunk. If you outgrow grep, add a rebuildable BM25 index on top — the Markdown stays the source of truth.

What does it cost? Tokens: a ~20-line index per session start. Distillation uses headless Claude Code under your existing subscription. No services, no fees.

Machine requirements? Linux/macOS, Python 3.8+ (stdlib only), git, and Claude Code. Cross-machine sync is whatever folder sync you already use (Syncthing, iCloud, Dropbox, git).

License

MIT