project-brain

Project Brain

Persistent project memory you (Claude) navigate through a small index instead of re-reading large docs every session. Only the index is ever loaded eagerly; detail lives in topic files read on demand. The index is your token budget — keep it small.

Where the brain lives

A .project-brain/ directory at the workspace (or repo) root:

.project-brain/
  index.md                  # THE MAP. Small. Read this FIRST. Projects -> topics -> status + pointer
  projects/
    <project>/
      <topic>.md            # Detail: problem, solution, status, version, tags
  people/
    <slug>.md               # Agreements with humans (client/partner/vendor): who, context, status

One brain can catalog many projects (a server hosting several repos) or just one (a single repo). Multi-project is the default shape — each project is a section in index.md.

How to behave every session

If the brain exists, read its index first — it is small by design and tells you what each project is, its stack, and what has already been done. Prefer .project-brain/index.compact (a token-cheap, generated view); if it is missing or older than index.md, read index.md instead — they carry the same information, so the fallback never loses anything. Drill into a topic file only when you actually need that detail.

When this skill is invoked, choose the mode that matches the request:

Mode: init — create the brain

Use when no .project-brain/ exists, or the user says "set up / init project brain".

Default is a LIGHT init — keep it cheap. Do NOT read the codebase.

1. Create .project-brain/ and .project-brain/projects/.
2. Detect projects from cheap signals only: top-level dirs, git repos, package.json, pyproject.toml, go.mod, Cargo.toml, composer.json. Infer name + stack from those files — do not read source to do this. Skip non-project directories — node_modules, venv, .venv, target, dist, build, .cache, snap, android-sdk, flutter, .git — and anything that is clearly a toolchain or data dump, not a codebase. When unsure, ask rather than adding noise.
3. Write index.md from templates/index.md, one section per project with the stack filled in and the topic list empty. Topics get filled as real work happens (via save).
4. Append a tiny pointer to the workspace CLAUDE.md (create it if missing) using templates/CLAUDE-snippet.md — this is what makes future sessions read the map first. Keep the pointer to a few lines; never duplicate the map into it.
5. Defer this workspace's native memory to the brain (optional, non-destructive). Claude Code's own per-project memory (MEMORY.md) competes with the brain and roughly doubles the per-session token cost. With the user's ok, seed a small conditional redirect into THIS workspace's native MEMORY.md so it points at the brain instead of duplicating facts. Same contract as the brain-bootstrap tool:
   • Idempotency marker <!-- project-brain-redirect v1 -->.
   • Native memory empty/absent → write just the redirect stub.
   • Marker already present → leave it untouched.
   • It holds the user's own notes → back them up (.bak-<timestamp>) and prepend the redirect; never delete or reorder their text. Keep the stub generic ("if this workspace has a .project-brain/, it is the source of truth") so it carries no absolute path and stays correct on any machine. To migrate native memory across other existing projects on the machine, point the user at the on-demand brain-bootstrap script — it only touches projects you ask it to, never silently.
6. Tell the user what you created, and that the brain fills in as you work.