A free, project-centric second brain for developers. Experimental and evolving.
Everyone building an AI second brain does it differently — and that's the point. Just like no two human brains are wired the same, there's no single "correct" folder structure or workflow. This is my implementation: lean, developer-first, and built around how I actually code rather than how productivity influencers think I should.
Most setups I've seen are either too aesthetic to be practical or too complex to maintain. This one lives inside your project repo, stays out of git, and gives Claude exactly what it needs — nothing more.
⚠️ Still experimental. I'm actively iterating on this. Feedback welcome.
Your project gets a .brain/ folder sitting alongside your actual code:
my-project/
├── src/ ← your code (git tracked)
├── package.json
└── .brain/ ← Claude's context layer (gitignored)
├── CLAUDE.md ← who, what, status, rules
├── context/
│ ├── architecture.md ← how the system is built
│ ├── decisions.md ← why you made the choices you made
│ ├── stack.md ← tech, versions, commands, gotchas
│ ├── status.md ← current phase, blockers, next up
│ └── subcontext/ ← atomic knowledge nodes (graph view)
└── skills/
├── project-setup.md ← run once to initialize
├── populate-brain.md ← run to save context checkpoints
└── evolve-brain.md ← run to build the knowledge graph
No code lives in .brain/. It's purely markdown — context about your project, not a mirror of it.
- Claude Code — free, runs in your terminal
- Obsidian — free desktop app
Download or clone this repo and rename the PROJECT_NAME/ folder to your actual project name.
Add this to your .gitignore:
.brain/
Open Obsidian → Open folder as vault → point it to .brain/
This gives you the graph view, linking, and visual navigation across all context files.
Open your terminal in the project root and run Claude Code:
claudeThen tell it:
"Run the project-setup skill from .brain/skills/"
Claude will interview you about your project. Answer in detail — the more context you give, the better Claude performs across all future sessions. It will fill in every file in context/ from your answers.
You can point Claude at your existing codebase, raw files, or start completely fresh — all three work.
Interviews you and populates all context files. Sets the foundation. Run this when starting a new project or when .brain/ is still empty placeholders.
As you work, your Claude session fills up with back-and-forth. When you're running low on context window, tell Claude:
"Run the populate-brain skill"
It scans what's changed, updates status.md, logs new decisions, and checkpoints your progress. Next session, you paste the session template and Claude is instantly caught up — no re-explaining needed.
Think of it as saving your game.
Once your context files have real depth, evolve-brain atomizes everything into small, interlinked markdown files inside context/subcontext/. Each file covers exactly one concept — a technology, a component, a feature, a decision.
Every file links to related files using Obsidian [[wikilinks]]. Open the Obsidian graph view (Ctrl+G) and you'll see a web of your entire project as connected nodes.
This is particularly useful when running subagents — instead of feeding an agent your entire context, you point it at the specific atomic files relevant to its task. Right context for the right agent.
Session start:
→ Paste session template into Claude (session-vault/SESSION_TEMPLATE.md)
→ Claude reads it, instantly grounded in your project
During session:
→ Build, debug, ship
Running low on context:
→ "Run populate-brain" → checkpoint saved
End of week:
→ "Run populate-brain" with weekly pulse questions
→ Context files updated across the board
When project grows complex:
→ "Run evolve-brain" → subcontext/ populated
→ Open Obsidian graph view → navigate visually
The brain is not a code mirror. Your source code lives in git. The brain holds why you made decisions, what's currently broken, where you're going next — the things Claude can't infer from code alone.
Claude has no memory between sessions. Every conversation starts blank. The .brain/ folder is the bridge — it's what makes Claude feel like a collaborator who knows your project rather than a stranger you have to re-onboard every time.
Start lean, grow naturally. Don't fill in every file on day one. project-setup gets you started, and the context grows as you build. Run populate-brain whenever something significant changes.
- Be verbose during project-setup. The quality of Claude's help scales directly with the detail in your context files.
- Update
status.mdreligiously. It's the first thing Claude reads. Stale status = stale advice. - Log decisions as you make them. Six months later you'll thank yourself for the "why".
- Graph view filter: In Obsidian, filter by path
subcontextto isolate just the project knowledge graph. - Multiple projects: Each project gets its own
.brain/. Open each one as a separate Obsidian vault.
Experimental. I'm actively using and refining this on real projects. The skill files are the most likely thing to change as I figure out what actually works in practice.
If you try it and find something broken or a better way to do something — open an issue or reach out.