--- name: shellbrain description: Use when an agent should remember to ask Shellbrain for targeted recall at task start, subproblem changes, repeated failures, hypothesis changes, or closeout. --- # Shellbrain Recall Workflow ## Purpose Shellbrain is a persistent memory system for agent work. As the working agent, your interface is: ```bash shellbrain recall ``` Recall returns a compact brief synthesized from prior memories, concepts, scenarios, and recent episode context. It is meant to reduce wasted exploration and help you decide where to look next. When the user explicitly asks you to store or teach Shellbrain something, use: ```bash shellbrain teach ``` Teach stores the user-provided statement as evidence and immediately asks Shellbrain's teach agent to turn it into durable memories or concept graph updates. Do not call Shellbrain internal commands directly. `read`, `events`, `memory`, `concept`, and `scenario` are for Shellbrain's internal agents. ## Quick Start Do not run `shellbrain init` at the start of every session. Use this order: 1. If Shellbrain is missing or broken, run `shellbrain admin doctor`. 2. If doctor says repair is needed, run `shellbrain init`. 3. Otherwise, use `shellbrain recall` with a targeted query and `current_problem`. If `shellbrain` is not found, do a one-time PATH check: ```bash zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain' ``` If the host shell is bash instead of zsh, use: ```bash bash -lc 'source ~/.bash_profile >/dev/null 2>&1; command -v shellbrain' ``` Once found, use plain `shellbrain ...`. Do not keep sourcing the login profile on every Shellbrain command. If the one-time login-shell retry still cannot find `shellbrain`, inspect Python's user script directory: ```bash python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))" ``` If that directory contains `shellbrain`, call it directly or add that directory to the login profile PATH and retry. If it does not, reinstall the Shellbrain CLI. ## Repo Targeting - Use the current working directory when already inside the repo. - Pass `--repo-root /absolute/path/to/repo` when your shell is elsewhere. - Treat repo path as operational context. Shellbrain normally derives durable repo identity from normalized git remote. ## Attention Programming Maintain this tuple while you work: `goal | surface | obstacle | hypothesis` Pause and emit an `SB:` line when the tuple changes or a boundary state occurs. Boundary states: - The goal changed. - The surface changed. - The obstacle changed. - The hypothesis changed. - The same approach failed twice. - An error is repeating. - You are switching subsystems or files. - You are about to make an important implementation decision. - You are closing out a task. If recall might help: `SB: recall | | | | ` Then call recall. If recall would not add information: `SB: skip | same signature | ` Then continue. ## Recall Payload `current_problem` is required. All four fields must be non-empty strings. If you do not have a hypothesis yet, use `"none yet"`. ```bash shellbrain recall --json '{"query":"Have we seen this failure mode or subsystem before?","current_problem":{"goal":"fix failing architecture guardrail test","surface":"tests/config/test_architecture_boundaries.py and app layer imports","obstacle":"entrypoint handler appears to import startup wiring","hypothesis":"dependency shape should move out of startup"}}' ``` ## Teach Payload Use `teach` only for explicit user teaching, not for ordinary closeout. ```bash shellbrain teach --json '{"text":"In this repo, startup wires dependencies but should not own workflow behavior.","current_problem":{"goal":"record architecture preference","surface":"startup and clean architecture","obstacle":"agents may put behavior in startup","hypothesis":"teach should become a durable preference or concept claim"}}' ``` ## Query Guidance Good recall queries are concrete. Name the failure mode, subsystem, decision, file area, or constraint. Good examples: ```bash shellbrain recall --json '{"query":"Have we seen this migration lock timeout before?","current_problem":{"goal":"fix migration test failure","surface":"database migrations and schema setup","obstacle":"migration blocks waiting on lock","hypothesis":"a previous test leaves a transaction open"}}' ``` ```bash shellbrain recall --json '{"query":"What architectural constraints matter before moving this CLI handler?","current_problem":{"goal":"move CLI handler without breaking clean architecture","surface":"entrypoints, startup, and handler dependency wiring","obstacle":"handler currently imports startup types","hypothesis":"startup should construct dependencies but handler should receive protocols"}}' ``` ```bash shellbrain recall --json '{"query":"What user preferences matter for this refactor?","current_problem":{"goal":"clean up Shellbrain onboarding assets","surface":"AGENTS.md and shellbrain skill","obstacle":"old guidance teaches internal commands to workers","hypothesis":"worker guidance should only teach recall"}}' ``` Avoid vague queries: - `what should I know about this repo?` - `what should I do?` - `anything relevant?` ## How To Use The Brief Treat recall as advisory memory, not ground truth. Use the brief to identify: - relevant prior cases - files or functions worth inspecting - constraints and preferences - known traps - concept orientation - gaps where Shellbrain found nothing useful Current repo state remains the source of truth. ## What Not To Do Do not use `teach` as a substitute for recall or as a generic session summary. Use it when the user explicitly says to store, remember, or teach Shellbrain a specific point. Do not call: ```bash shellbrain read shellbrain events shellbrain memory add shellbrain memory update shellbrain concept add shellbrain concept update shellbrain scenario record ``` Those are internal-agent commands. Do not manually write memories at closeout. Shellbrain's knowledge-builder agent consolidates episodes after the session lifecycle.