# Brain > Use when working on a project with Brain agent memory management. Triggers on memory_commit, memory_branch tool usage, or when the project has a .memory/ directory. - Skill: `whamp/brain` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add whamp/brain` - Raw SKILL.md: https://api.skillmd.com/api/skills/whamp/brain/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: whamp (https://skillmd.com/u/whamp) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/whamp/brain --- # Brain — Agent Memory ## Initialization When the `` tag loads this file, it includes a `location` attribute with the absolute path to this SKILL.md. Use that to derive the init script path: ```bash bash "/absolute/path/to/skills/brain/scripts/brain-init.sh" ``` Replace `/absolute/path/to/skills/brain` with the skill directory shown in the `` tag's `location` attribute (strip the `/SKILL.md` suffix). ### Committer Configuration `memory_commit` runs its distiller as a child Pi process. By default, it inherits the currently selected model and thinking level from the active Pi session. To choose a dedicated committer, add `.memory/config.yaml`: ```yaml committer: model: google/gemini-3.6-flash thinking: low extensions: - ./custom-provider.ts ``` Omit `model` or `thinking` to inherit the active session value. By default the committer child starts with `--no-extensions` (so it does not reload Brain onto the log it is distilling), then Brain re-adds session extensions from `pi -e`, `.pi/settings.json`, `~/.pi/agent/extensions/`, and `/.pi/extensions/`, skipping this package. Set `committer.extensions` to replace that list — a YAML list of specs, or a comma-separated string. Pi resolves provider authentication normally; do not put API keys or other credentials in this file. ### After Init 1. **Write `.memory/main.md`** — the project roadmap (see below). 2. **Make your first commit** when you reach a meaningful milestone. > **Note:** No `/reload` is needed. The memory tools lazily detect `.memory/` > on every call via `tryLoad()`. ### Writing main.md — Greenfield vs Brownfield **New project (no existing code):** Write goals, intended architecture, and open questions as you understand them from conversation with the user. **Existing project:** Orient yourself first: - Read `AGENTS.md`, `README.md`, `package.json` (or equivalent) - Scan recent git history (`git log --oneline -20`) - Read any specs or plans in `docs/` Then write the roadmap covering: project purpose, current state, key decisions already made, completed milestones, and planned work. ## Context Retrieval Memory status is **automatically injected** at session start (via the `before_agent_start` hook) and appended to every successful `memory_branch` and `memory_commit` result. Automatic status is compact and may truncate long roadmaps, so keep the newest critical context near the top of `.memory/main.md`. You do not need to call a separate tool to see status. For deep retrieval, use `read` directly: - `read .memory/branches//commits.md` — full branch history - `read .memory/branches//log.md` — OTA trace since last commit - `read .memory/branches//metadata.yaml` — structured metadata - `read .memory/main.md` — project roadmap - `read .memory/AGENTS.md` — full protocol reference ## When to Commit - You've reached a stable understanding or decision - You've completed an exploration and have a conclusion - You're about to change direction significantly - A meaningful amount of work has accumulated (use judgment, not a fixed interval) - Before ending a session if significant progress was made - **When the extension warns that log.md is large** — even mundane activity is worth distilling. A commit that records "routine maintenance, no significant decisions" tells future agents what was already explored. ## How to Write Good Commits - Focus on decisions and rationale, not implementation details - Capture "why" more than "what" — the code captures "what" - Be specific: "Chose PostgreSQL over MongoDB because ACID compliance is required for financial transactions" not "Chose database" A subagent handles commit distillation — it reads your `log.md` and prior commits, then produces the structured commit entry. You just provide a good `summary` string. ## After Every Commit **Re-read `.memory/main.md` and rewrite stale sections.** The roadmap is the first thing a new session reads — if it's stale, every future session starts with a wrong picture. This means genuine review, not mechanical edits. After `memory_commit` returns: 1. Read `.memory/main.md` in full. 2. Rewrite the **Current State** section to describe what is true _right now_ — remove historical context that has migrated to Key Decisions or Milestones. 3. Add any new entries to **Key Decisions Made**. 4. Move completed items in **Milestones** and add new planned ones. 5. Remove or rewrite anything a new reader would find misleading. The goal is curation, not accumulation. A reader of Current State should understand the project as it exists today without wading through history. For trivial commits that don't change the project's state, decisions, or milestones (e.g., minor refactors, typo fixes), you can pass `update_roadmap: false` to skip the reminder. Most commits should update the roadmap. ## When to Branch - You want to explore an alternative approach without contaminating current thinking - You're prototyping something uncertain - You want to compare two design hypotheses ## When to Merge - A branch has reached a conclusion (positive or negative) - The branch's findings should inform the main line of thinking - Include what was learned even if the approach was abandoned **Important:** Always review the source branch history BEFORE calling merge. Use `read .memory/branches//commits.md` for full branch history. You need the full context to write a good synthesis.