# Shellbrain > Use when an agent should remember to ask Shellbrain for targeted recall at task start, subproblem changes, repeated failures, hypothesis changes, or closeout. - Skill: `cucupac/shellbrain` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add cucupac/shellbrain` - Raw SKILL.md: https://api.skillmd.com/api/skills/cucupac/shellbrain/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: cucupac (https://skillmd.com/u/cucupac) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cucupac/shellbrain --- # 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. If you changed any files since your last user-facing response, run this exactly once after validation and immediately before your next user-facing response: ```bash shellbrain snapshot ``` Snapshot stores exact repo code state in repo-local shadow Git so the knowledge builder can later attach exact solution deltas to solved problem runs. 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 one targeted natural-language query. 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 Query Pass one self-contained question as a quoted positional argument. Recall receives only this query, so include relevant task context naturally. ```bash shellbrain recall "Have we seen this architecture guardrail failure or subsystem boundary before?" ``` ## 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"}}' ``` ## Snapshot Habit If you changed any files since your last user-facing response, run `shellbrain snapshot` exactly once after validation and immediately before your next user-facing response. Do this on every response cycle where files changed; skip only when no files changed. It does not need `--json`. Use standard repo targeting only when your shell is outside the repo: ```bash shellbrain snapshot --repo-root /absolute/path/to/repo ``` ## Query Guidance Good recall queries are concrete. Name the failure mode, subsystem, decision, file area, or constraint. Good examples: ```bash shellbrain recall "I'm debugging a migration lock timeout. What prior context matters?" ``` ```bash shellbrain recall "What architectural constraints matter before moving this CLI handler?" ``` ```bash shellbrain recall "What user preferences matter while simplifying Shellbrain onboarding assets?" ``` 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. ## Resources - Read [references/session-workflow.md](references/session-workflow.md) for the detailed recall cadence and attention habit.