shellbrain

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:

shellbrain recall "<targeted natural-language question>"

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:

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:

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:

zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain'

If the host shell is bash instead of zsh, use:

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:

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 | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>

Then call recall.

If recall would not add information:

SB: skip | same signature | <one-line reason>

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.

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.

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:

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:

shellbrain recall "I'm debugging a migration lock timeout. What prior context matters?"

shellbrain recall "What architectural constraints matter before moving this CLI handler?"

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:

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 for the detailed recall cadence and attention habit.