GitHub - OoneBreath/claude-code-project-brain: Persistent, navigable memory for Claude Code — stop re-explaining your projects to the AI every session. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
OoneBreath
claude-code-project-brain
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>10 Commits<br>10 Commits
docs
docs
examples/example-saas/.project-brain
examples/example-saas/.project-brain
skills/project-brain
skills/project-brain
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
install.sh
install.sh
View all files
Repository files navigation
Project Brain — persistent memory for Claude Code
Stop re-explaining your projects to the AI every session.
Project Brain is a Claude Code skill that gives Claude a<br>small, navigable map of your projects — their stack, decisions, pitfalls, and what's already<br>been done — so it stops forgetting, stops mixing projects up, and stops re-reading a<br>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:<br>a .project-brain/ folder of plain markdown that Claude reads through an index, loading<br>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 —<br>this one is FastAPI + Postgres, that one is Node + tRPC + MySQL — and quietly redoing things<br>you already finished last week.
The fix
.md # the detail, read only when needed">.project-brain/<br>index.md # a small MAP: projects → topics → status + pointer<br>projects/<br>.md # the detail, read only when needed
Claude reads the small index first. When you ask "how did we solve the cache issue?" it<br>follows one pointer to one file — not the whole knowledge base. When you ask it to "swap the<br>logo" and the map says that was done and verified three days ago, it tells you and asks<br>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 —<br>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<br>doc, splitting into a small index + on-demand topic files genuinely cuts per-session context.<br>If you don't, the token win is modest.
Fewer hallucinations. The map is an anchor. The model stops inventing your deployment or<br>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<br>works — without you pasting a kilometre of README.
Two things make it better than a flat notes file
Status carries the outcome, not just "done": ✓ verified vs ✗ failed vs ⚠ in-progress.<br>The model knows the difference between "done and works" and "we tried that and it broke."
Versioning, not overwriting. When an approach is replaced, the old one is kept as a<br>superseded note — so the trail of what was tried and why it changed survives.
Install
git clone https://github.com/OoneBreath/claude-code-project-brain.git<br>cd claude-code-project-brain<br>./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<br>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<br>/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<br>memory (.project-brain/) lives per project — so on a server hosting...