{"slug": "project-brain-persistent-memory-index-for-ai-coding", "title": "Project Brain – Persistent memory index for AI coding", "summary": "A new open-source skill for Claude Code called Project Brain creates a persistent memory index of a developer's projects, storing architecture, decisions, and status in a `.project-brain/` folder of markdown files. The tool aims to eliminate the need for developers to re-explain their projects in every AI session by having Claude read a small index first and load detailed topic files only when needed. This approach reduces token usage, prevents the AI from mixing up project details, and preserves multi-month memory of what was done, what worked, and what failed.", "body_md": "**Stop re-explaining your projects to the AI every session.**\n\nProject Brain is a [Claude Code](https://claude.com/claude-code) skill that gives Claude a\nsmall, navigable map of your projects — their stack, decisions, pitfalls, and what's already\nbeen done — so it stops forgetting, stops mixing projects up, and stops re-reading a\n1000-line README into context on every single task.\n\nIt is **not** a database, a server, or another AI wrapper. It's a convention plus a skill:\na `.project-brain/`\n\nfolder of plain markdown that Claude reads through an index, loading\ndetail only when it's actually needed.\n\nEvery new Claude Code session, on every project:\n\n- explain the architecture\n- explain the deployment\n- explain the stack\n- explain the history\n- explain the known pitfalls\n\n…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.\n\n```\n.project-brain/\n  index.md                  # a small MAP: projects → topics → status + pointer\n  projects/\n    <project>/\n      <topic>.md            # the detail, read only when needed\n```\n\nClaude reads the **small index** first. When you ask *\"how did we solve the cache issue?\"* it\nfollows one pointer to one file — not the whole knowledge base. When you ask it to *\"swap the\nlogo\"* and the map says that was done and verified three days ago, it tells you and asks\nwhether you want to repeat it or do something new.\n\n**Before**\n\nEvery session:re-explain architecture, deployment, stack, history, pitfalls.\n\n**After**\n\nClaude 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.\n\nBe honest with yourself about why you'd use this:\n\n**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.\n\n**Status carries the outcome, not just \"done\":**`✓ verified`\n\nvs`✗ failed`\n\nvs`⚠ in-progress`\n\n. 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 superseded note — so the trail of*what was tried and why it changed*survives.\n\n```\ngit clone https://github.com/OoneBreath/claude-code-project-brain.git\ncd claude-code-project-brain\n./install.sh        # copies the skill into ~/.claude/skills/  (run on each machine)\n```\n\n**Start a new Claude Code session after installing** — skills are loaded at session start, so the\nskill won't show up in a session that was already open.\n\nThen, in a session inside your workspace:\n\n```\n/project-brain        →  \"init\"     set up .project-brain/ and detect your projects\n/project-brain        →  \"how did we solve X?\"   recall through the index\n```\n\nRun `init`\n\nonce **per workspace**. The skill is installed per machine (`~/.claude/skills/`\n\n), but the\nmemory (`.project-brain/`\n\n) lives per project — so on a server hosting several repos, point `init`\n\nat\nthe workspace root and it catalogs them all in one brain.\n\nAfter 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.\n\nA note on the first run.`init`\n\nis light by design — it detects your projects from`package.json`\n\n/`pyproject.toml`\n\n/ git and writes a small index. It doesnotread 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.\n\nThe 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.\n\n- The skill lives in\n`~/.claude/skills/project-brain/`\n\n(personal scope, per machine). `init`\n\ncreates`.project-brain/`\n\nin your workspace, detects projects (git repos,`package.json`\n\n,`pyproject.toml`\n\n, …), and drops a tiny pointer into your`CLAUDE.md`\n\nso future sessions read the map first.- One brain can catalog\n**many projects on one server** or just a single repo. - Everything is plain markdown you can read, edit, and commit yourself.\n- A bundled\n`brain-check`\n\nvalidator (`python3 ~/.claude/skills/project-brain/brain-check`\n\n) catches broken pointers, malformed frontmatter, and index↔topic status drift — run it after big changes. **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`\n\nthat 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.\n\nYour brain is yours — and it's private by default.A real`.project-brain/`\n\nends 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`\n\nthat ignores`.project-brain/`\n\nprecisely so the skill's own repo never accidentally carries a real brain.\n\nProject Brain came out of running several independent SaaS products at once — among them\n[Sentinel AI](https://sentinel-ai.info) (server security & database autopilot) and\n[24ad.info](https://24ad.info) (an AI-assisted classifieds platform), alongside a multi-server\nfleet-intelligence backend, an anti-spam service and a content tool. When every project carries\nthousands of lines of context, the cost of the AI forgetting — or quietly mixing two projects up\n— is real. This is the working memory that keeps them straight. The pattern isn't theoretical.\n\nMIT — see [LICENSE](/OoneBreath/claude-code-project-brain/blob/main/LICENSE).", "url": "https://wpnews.pro/news/project-brain-persistent-memory-index-for-ai-coding", "canonical_source": "https://github.com/OoneBreath/claude-code-project-brain", "published_at": "2026-06-02 23:12:59+00:00", "updated_at": "2026-06-02 23:46:44.821614+00:00", "lang": "en", "topics": ["ai-tools", "large-language-models", "ai-agents", "ai-products"], "entities": ["Claude Code", "Project Brain", "Claude"], "alternates": {"html": "https://wpnews.pro/news/project-brain-persistent-memory-index-for-ai-coding", "markdown": "https://wpnews.pro/news/project-brain-persistent-memory-index-for-ai-coding.md", "text": "https://wpnews.pro/news/project-brain-persistent-memory-index-for-ai-coding.txt", "jsonld": "https://wpnews.pro/news/project-brain-persistent-memory-index-for-ai-coding.jsonld"}}