Stop re-explaining your projects to the AI every session.

Project Brain is a Claude Code skill that gives Claude a small, navigable map of your projects — their stack, decisions, pitfalls, and what's already been done — so it stops forgetting, stops mixing projects up, and stops re-reading a 1000-line README into context on every single task.

It is not a database, a server, or another AI wrapper. It's a convention plus a skill: a .project-brain/ folder of plain markdown that Claude reads through an index, loading detail only when it's actually needed.

The problem

Every new Claude Code session, on every project:

• explain the architecture
• explain the deployment
• explain the stack
• explain the history
• explain the known pitfalls

…again. And after a few hours of work the model starts mixing details between projects — this one is FastAPI + Postgres, that one is Node + tRPC + MySQL — and quietly redoing things you already finished last week.

The fix

.project-brain/
  index.md                  # a small MAP: projects → topics → status + pointer
  projects/
    <project>/
      <topic>.md            # the detail, read only when needed

Claude reads the small index first. When you ask "how did we solve the cache issue?" it follows one pointer to one file — not the whole knowledge base. When you ask it to "swap the logo" and the map says that was done and verified three days ago, it tells you and asks whether you want to repeat it or do something new.

Before

Every session: re-explain architecture, deployment, stack, history, pitfalls.

After

Claude already knows: the stack, what was done, what worked, what failed, what's in progress — and reads only the one topic relevant to your question.

What it actually saves

Be honest with yourself about why you'd use this:

• Fewer tokens — when it applies. If you currently keep everything in a giant always-loaded doc, splitting into a small index + on-demand topic files genuinely cuts per-session context. If you don't, the token win is modest.
• Fewer hallucinations. The map is an anchor. The model stops inventing your deployment or swapping one project's stack for another's.
• Multi-month memory. Come back to a project after three months and Claude still knows how it works — without you pasting a kilometre of README.

What makes it better than a flat notes file

1. Status carries the outcome, not just "done": ✓ verified vs ✗ failed vs ⚠ in-progress. The model knows the difference between "done and works" and "we tried that and it broke."
2. Versioning, not overwriting. When an approach is replaced, the old one is kept as a superseded note — so the trail of what was tried and why it changed survives.
3. Provenance — it knows what it doesn't know. Every note can be marked trust: human (a person confirmed it) or ai-inferred (the model wrote it without confirmation). A flat notes file blurs the two, so a model's guess hardens into "fact" just by being written down. Two distinct things keep them apart: brain-check validates that the field carries a real value (human/ai-inferred), and then Claude weighs it at read time — trust the confirmed, double-check the inferred. That weighing is a behavioral rule in the skill's recall instructions, not something the validator enforces; the validator only guarantees the label is there and well-formed.
4. Staleness — memory with an expiry date. Facts age: credentials rotate, versions move, "current" stops being current. Topics carry a review_by date (or fall back to a ~180-day horizon), and the validator flags anything past it as "re-confirm before trusting" instead of serving last year's note as gospel.
5. A cross-project guard. The multi-project case is where memory rots into wrong answers — a fact from project A applied to project B. The validator catches misfiled notes (a project: that doesn't match its folder). An opt-in --strict mode additionally flags a topic that name-drops another project without declaring it — left off by default on purpose: in tightly-coupled setups projects reference each other legitimately, so on a real interconnected brain it produces false positives. Turn it on only when you want strict project isolation.
6. A save reminder that suggests, never auto-saves. An optional Stop hook fires at the end of a turn and, when the workspace changed files but the brain wasn't updated, reminds you to save if it's worth it — throttled, so it nudges once after you've done work, not on every turn. It can't write to the brain and can't act on its own — because auto-dumping every session would turn the map into a swamp. A human still decides what's worth remembering.

The validator (brain-check) is what keeps the structure honest: run it any time to catch index/topic drift, stale facts (#4), misfiled cross-project notes (#5), and a trust: field set to a bad value (#3) — no dependencies, plain Python 3. Note the scope: it checks structure and freshness; the trust-weighing in #3 and the save nudge in #6 are behaviors at read/turn time, not validator checks.

Install

git clone https://github.com/OoneBreath/claude-code-project-brain.git
cd claude-code-project-brain
./install.sh        # copies the skill into ~/.claude/skills/  (run on each machine)

Start a new Claude Code session after installing — skills are loaded at session start, so the skill won't show up in a session that was already open.

Then, in a session inside your workspace:

/project-brain        →  "init"     set up .project-brain/ and detect your projects
/project-brain        →  "how did we solve X?"   recall through the index

Run init once per workspace. The skill is installed per machine (~/.claude/skills/), but the memory (.project-brain/) lives per project — so on a server hosting several repos, point init at the workspace root and it catalogs them all in one brain.

After that you mostly don't think about it: Claude reads the map at the start, checks it before redoing work, and updates it when a unit of work is done.

A note on the first run. init is light by design — it detects your projects from package.json / pyproject.toml / git and writes a small index. It does not read your source, so it's cheap. The brain then fills in gradually as you actually work.

If you want Claude to pre-populate the brain by reading an existing codebase ("deep backfill"), that's a one-time upfront token cost — Claude has to read your code and docs to summarise them. Think of it as an investment: you pay tokens once to get organised, and every later session is cheaper and sharper. Scope it to one project at a time. The skill will warn you before doing it.

The result reflects what your project actually documents — a repo with a solid README/CHANGELOG backfills richer than a bare one. It summarises what's there; it doesn't invent context. So expect the depth to vary by project, not a fixed result.

How it works

• The skill lives in ~/.claude/skills/project-brain/ (personal scope, per machine).
• init creates .project-brain/ in your workspace, detects projects (git repos, package.json, pyproject.toml, …), and drops a tiny pointer into your CLAUDE.md so future sessions read the map first.
• One brain can catalog many projects on one server or just a single repo.
• Everything is plain markdown you can read, edit, and commit yourself.
• A bundled brain-check validator (python3 ~/.claude/skills/project-brain/brain-check) catches broken pointers, malformed frontmatter, index↔topic status drift, stale facts, an invalid trust: value, and misfiled (cross-project) notes — run it after big changes. Add --strict for stricter cross-project isolation (flags inter-project mentions; noisy on coupled brains, so off by default).
• An optional brain-nudge Stop hook fires at the end of a turn and reminds you to save when the workspace changed files but the brain wasn't updated — throttled, so it nudges once after work, not every turn. Auto-wired if you install as a Claude Code plugin; skill-only users can add a one-line Stop hook to settings.json (see the skill's own SKILL.md). It only suggests — it never writes to the brain.
• It doesn't bloat over time. Topic files are cold storage — only the index is ever loaded eagerly, so the per-session cost is bounded by the index, not by how much history you keep. Unlike a flat notes.md that gets heavier every session, the brain stays light. To tidy a dead topic you archive it (drop its one line from the index, keep the file) — nothing auto-deletes.

Your brain is yours — and it's private by default. A real .project-brain/ ends up holding infra details (DB names, ports, server paths, hostnames). Decide per project whether to commit it (travels with the repo, shared with your team) or keep it out of version control. This repo ships a .gitignore that ignores .project-brain/ precisely so the skill's own repo never accidentally carries a real brain.

Background

Project Brain came out of running several independent SaaS products at once — among them Sentinel AI (server security & database autopilot) and 24ad.info (an AI-assisted classifieds platform), alongside a multi-server fleet-intelligence backend, an anti-spam service and a content tool. When every project carries thousands of lines of context, the cost of the AI forgetting — or quietly mixing two projects up — is real. This is the working memory that keeps them straight. The pattern isn't theoretical.

Author

Built and maintained by Slawomir Luzny — fixflex.co.uk/project-brain.html.

License

MIT — see LICENSE. Copyright (c) 2026 Slawomir Luzny.