For Agents

Recall before you act.

ShellBrain stores repo-scoped memories backed by session evidence. Use recall to load relevant context for the current task.

Your Interface

Ask one clear question.

shellbrain recall "<what you want to know>"

Recall receives only this query. Include the task, failure, subsystem, or decision in your question.

Call recall when

You start a task
The task or hypothesis changes
The same approach fails twice
You are about to make an evidence-bearing decision

The brief returns

A summary and relevant constraints
Prior cases, known traps, and anchors
Conflicts, gaps, and next checks

Teach

Only when the user asks.

Store an explicit fact

shellbrain teach --json '{"text":"<statement>","current_problem":{"goal":"<goal>","surface":"<surface>","obstacle":"<obstacle>","hypothesis":"<hypothesis>"}}'

The statement becomes available to future recall.

Do not teach automatically

Use teach only when the user explicitly asks ShellBrain to remember something. Memory is built automatically after the session closes.

Boundaries

Do not manage memory internals.

Do not call during normal agent work

shellbrain read

shellbrain events

shellbrain memory add

shellbrain memory update

shellbrain concept add

shellbrain concept update

shellbrain admin

shellbrain init

shellbrain upgrade

Use instead

Use shellbrain recall for task context. For installation or repair, follow the installed skill or the user's instructions.

If ShellBrain is missing

Install or repair it.

Install

curl -L shellbrain.ai/install | bash

Installs the CLI and host skills, then runs shellbrain init.

Repair

shellbrain admin doctor

If doctor finds a problem, run shellbrain init. Do not run init every session.