brain

args	[{"description":"The project-memory or Brain workflow task to perform.","name":"task","required":false}]
description	Use this skill when working with a project-local Brain workspace managed by the `brain` CLI, especially for repo memory, retrieval, compiled task context, session hygiene, and safe markdown updates.
name	brain
updated	2026-04-16T22:00:00Z
user-invocable	true

Brain

Use brain as the primary interface for AI-agent project-local memory and workflow.

Project-First Behavior

If the current repository has Brain context, use the repo-local Brain docs first:

1. Read AGENTS.md at the repo root.
2. Read .brain/policy.yaml.
3. Read the linked .brain/context/*.md files needed for the task.
4. If no validated session is active, run brain prep --task "<task>".
5. If a session is already active, run brain prep.
6. Use the brain CLI for durable project-memory operations.
7. Fall back to this generic skill only when repo-local context is absent.

Goals

• keep durable project knowledge in agent-readable markdown
• prefer explicit CLI operations over ad hoc memory files
• preserve backups, history, and undo for note changes
• keep retrieval focused on repo-managed docs instead of transient files
• support compiled context, durable memory, and session workflows inside the repo

First Checks

When starting work in a repo that uses Brain:

1. Run brain doctor.
2. Read project_migrations in brain doctor when the repo may be older or was just upgraded.
3. Read index_freshness in brain doctor when retrieval matters.
4. Run brain find <project> or brain search "<project> <task>" when project memory matters.
5. Use brain search status before retrieval debugging so you know whether the local index is fresh, stale, or missing.
6. Read the repo contract and relevant docs before substantial work.

Command Guide

Use these commands by default:

• brain init --project .
  • Create the local Brain workspace for a project.
• brain adopt --project .
  • Adopt an existing repo into the Brain-managed context model. Treat generated files as starter context, then scan the repo and enrich AGENTS.md, docs, or .brain notes with durable project-specific findings.
• brain doctor --project .
  • Validate the local workspace, sqlite state, project migration state, and embedder configuration.
• brain update --project .
  • Update the Brain binary, refresh already-installed Brain skills, and apply pending project migrations for the current Brain repo.
• brain context migrate --project .
  • Run project migrations explicitly with the current binary when upgrade hygiene matters.
• brain context guidance karpathy --status --project .
  • Inspect whether the user has accepted or declined Karpathy Guidelines for the current repo.
• brain context guidance karpathy --accept --project .
  • Record that the user wants Karpathy Guidelines and add them to the Brain-managed AGENTS.md.
• brain context guidance karpathy --decline --project .
  • Record that the user does not want Karpathy Guidelines so Brain does not ask again.
• brain read <path>
  • Read a managed markdown note.
• brain edit <path> ...
  • Update title, metadata, or body while preserving history and backups.
• brain find [query]
  • Search path, title, type, or note content.
• brain search "query"
  • Run hybrid retrieval over the local project index. With the default localhash provider, this is best understood as lexical search plus lightweight semantic hinting.
• brain search status
  • Inspect index freshness, indexed counts, and the local sqlite path without mutating the index.
• brain search --explain "query"
  • Show lexical and semantic score contributions plus the retrieval source classification for each result.
• brain search --inject "query"
  • Return ranked results plus an agent-ready ## Relevant Context block that can be reused directly.
• brain prep --task "..."
  • Start or reuse the validated session and compile the default startup packet in one step.
• brain prep --task "..." --budget small
  • Ask for a leaner startup packet while keeping the same startup orchestration.
• brain prep --task "..." --fresh
  • Bypass session-local packet reuse when you want the startup path to force a standalone full packet.
• brain context compile --task "..."
  • Compile the smallest summary-first working-set packet Brain can justify for the task when you need the lower-level compiler directly.
• brain context compile --task "..." --budget small
  • Ask for a leaner lower-level compile packet with a named preset or an explicit integer token target.
• brain context compile --task "..." --fresh
  • Bypass session-local packet reuse and force a standalone full packet when debugging or inspecting lower-level packet contents.
• brain context explain --last
  • Inspect the latest recorded compiled packet, including cache status, reuse or delta lineage, later expansions, and downstream session outcomes.
• brain context stats
  • Summarize likely signal, likely noise, repeated expansions, verification links, fresh-packet budget pressure, and recurring omitted markdown docs from local compiler telemetry.
• brain context effectiveness
  • Assess packet usage, cache behavior, budget pressure, outcome links, likely misses, telemetry gaps, and recommended packet-shaping follow-ups.
• brain context audit
  • Review whether durable Brain markdown still covers current architecture, config, CI, deploy, test, and docs surfaces. Writes nothing by default.
• brain context audit --since <git-ref>
  • Add diff-focused findings for context-sensitive changes since a base ref.
• brain context audit --proposal
  • Create a reviewed .brain/resources/changes/context-audit-...md proposal note without directly editing durable docs.
• brain distill --session
• brain distill --session --dry-run
  • Create a session-scoped promotion-review proposal with source provenance, promotion diagnostics, and suggested durable note updates.
• brain context structure
  • Inspect the derived structural repo map of boundaries, entrypoints, config surfaces, and test surfaces.
• brain context structure --path "..."
  • Focus the structural repo map on one subtree such as internal/search.
• brain context structure status
  • Inspect structural cache freshness and counts without rebuilding it.
• brain context live --task "..."
  • Inspect the current boundary-aware live-work packet for a task using the active session when available.
• brain context live --explain
  • Add rationale and missing-signal reporting for the live-work packet.
• brain context assemble --task "..."
  • Assemble a task-focused context packet from durable notes, generated context, structural repo context, and workflow/policy sources.
• brain context assemble --explain
  • Add rationale, omitted-nearby context, missing-group reporting, ambiguities, and confidence to the task packet.
• brain context load --level 0
  • Load the compatibility static bundle when an older level-based workflow is still required.
• brain context load --level 1
  • Add overview and workflows to the compatibility static bundle.
• brain context load --level 2
  • Load the full compatibility static context bundle.
• brain context load --level 3 --query "..."
  • Add search-injected relevant context to the compatibility bundle. If a session is active, the task can stand in for --query.
• brain context install --project .
  • Create or adopt the root contract plus .brain/context.
• brain context refresh --project .
  • Refresh generated project context while preserving local notes outside managed blocks.
• brain session start --project . --task "..."
  • Start a validated project session.
• brain session run --project . -- <command>
  • Execute and record required verification commands.
• brain session finish --project .
  • Enforce policy and close the active session.
• brain history
  • Inspect tracked note operations.
• brain undo
  • Revert the latest tracked note operation.

Operating Rules

• Prefer brain edit over direct mutation when the target is Brain-managed markdown.
• Keep durable project discoveries in AGENTS.md, docs/, or .brain/.
• Do not create sidecar memory systems when Brain already owns the workflow.
• Prefer updating an existing durable note over creating duplicates.
• Use human-readable filenames and titles.
• Run brain context audit after meaningful architecture, config, CI, deploy, test, or docs-surface changes.

Post-Adoption Enrichment

After brain adopt, the generated context is only starter context. Brain does not run an automatic deep LLM scan during adoption.

The AI agent should scan repo structure, docs, manifests, entrypoints, tests, CI, config, and deployment surfaces. Then update AGENTS.md, docs, or .brain notes with concrete project facts, add focused .brain/resources notes for architecture, workflows, risks, and references that do not belong in top-level templates, and keep generated managed blocks refreshable by putting hand-authored findings in Local Notes or dedicated notes.

Upgrade Workflow

• brain update refreshes already-installed global Brain skills, already-installed local Brain skills inside the current --project, and pending project migrations for the current Brain repo.
• Other Brain repos repair local Brain skills and apply only auto-safe project migrations lazily the next time app-backed Brain commands run there.
• Brain treats .brain/session.json, .brain/sessions/, .brain/state/, and .brain/policy.override.yaml as local runtime state. The durable shared layer is the markdown/docs surface, not the raw runtime trace.
• Explicit upgrade actions such as brain update and brain context migrate may refresh .gitignore and remove legacy tracked runtime-state files from the Git index while keeping them on disk. Review and commit that diff after the command reports it.
• If brain update --project . reports that an older Brain-managed AGENTS.md is missing Karpathy Guidelines, ask the user whether they want them added. Record the answer with brain context guidance karpathy --accept --project . or brain context guidance karpathy --decline --project .; Brain stores the local decision and will not ask again unless the user explicitly changes it.
• If automatic project migration fails, run brain doctor --project .; then brain context refresh --project .; run brain adopt --project . if existing local agent files still need their Brain-managed integration block refreshed or migrated.

Retrieval Workflow

1. brain find <keyword> for quick narrowing.
2. brain search "<task or concept>" for ranked results.
3. brain search status when results look stale, missing, or surprising.
4. brain search --explain "<task or concept>" when you need to inspect ranking behavior.
5. brain search --inject "<task or concept>" when you need a compact context block to pass straight into the next step.
6. brain read <path> for the winning notes when the injected block is not enough.
7. Re-run search after meaningful note updates when you need the latest local state reflected. Brain will rebuild the local index automatically only when it is stale or missing.
8. If retrieval quality matters, check which provider is active in brain doctor or brain search status before assuming the project is using a strong hosted semantic model.

Context Workflow

1. brain prep --task "<task>" for the default startup path.
2. Run brain prep with no --task when a validated session is already active and you want Brain to reuse that task.
3. Add --budget small|default|large|<integer> when you need a tighter or wider startup packet and want Brain to explain budget pressure explicitly.
4. Add --fresh when you need to bypass session-local reuse or delta behavior and force a standalone full packet.
5. Use brain context compile --task "<task>" when you need the lower-level compiler directly without the startup orchestration.
6. brain context explain --last when you need to inspect why the latest packet looked the way it did, whether Brain reused or delta-linked it, which items were expanded later, or which downstream verification and closeout outcomes were recorded.
7. brain context stats when you are tuning compiler behavior and want a compact view of likely signal, likely noise, repeated expansions, verification-link patterns, fresh-packet budget pressure, and recurring omitted docs from local telemetry.
8. brain context effectiveness when you need a higher-level read on whether packet telemetry suggests useful context, likely misses, low-signal includes, telemetry gaps, or concrete packet-shaping follow-ups.
9. brain context audit after meaningful architecture, config, CI, deploy, test, or docs-surface changes so durable context stays aligned with the repo.
10. brain context audit --proposal only when audit findings should become a tracked review note for the active branch or PR.
11. brain context structure when you need repo boundaries, entrypoints, config surfaces, or test surfaces before deeper retrieval.
12. brain context live --task "<task>" when you need current session, changed-file, touched-boundary, nearby-test, verification-recipe, or policy signals, not just compiled startup context.
13. brain context assemble --task "<task>" when you need the broader typed packet instead of the compiler-first working set.
14. brain context assemble --explain when you need to inspect why Brain chose its broader packet and what it left nearby.
15. brain context load --level ... only when you need the older static-bundle compatibility view.

Distillation Workflow

1. Run brain distill --session --dry-run when you need the full promotion review during closeout without creating a repo-owned file.
2. Run brain distill --session only when a working session surfaced decisions, tradeoffs, bugs, or discoveries that should become a tracked proposal note.
3. Review the proposal note under .brain/resources/changes/, including the promotion review section and the suggested targets that were actually classified as promotable.
4. Apply the durable note updates with brain edit or by updating the target notes directly after review.
5. If the proposal note belongs to the active task, keep it in the same feature branch and PR instead of leaving it behind on develop or main.
6. If the proposal note does not belong to the active task, review it and intentionally remove it before switching back to develop, release/*, or main.
7. Treat distill as a proposal generator, not as an auto-write path.

Session Recovery

• If brain session finish blocks, inspect the promotion suggestions in the closeout output first.
• Run brain distill --session --dry-run when you need the full promotion review before deciding what to keep.
• Run brain distill --session only when you intentionally want a tracked proposal note to carry in the active branch or PR.
• Run brain context audit --since <baseline> when closeout points at architecture, config, CI, deploy, test, or docs-surface changes that may need context maintenance.
• Review the proposal, update the durable notes that matter, then retry brain session finish.
• Before switching branches or returning to a protected branch, run git status --short and resolve repo-owned leftovers such as .brain/resources/changes/*, .brain/, docs/, or contract files.
• If the session changed no durable knowledge after review, use brain session finish --force --reason "<why>" explicitly instead of pretending there was a durable update.
• Keep using brain session run -- <command> for required verification commands before closeout.

When Not To Use This Skill

• pure software engineering tasks unrelated to project memory
• cases where the user explicitly wants raw filesystem work instead of Brain-managed notes
• repos that do not use Brain and do not need project-local memory workflow