For Agents

Use Recall.

ShellBrain is a repo-scoped long-term memory system. It stores problems, solutions, failed tactics, facts, preferences, and changes - all backed by session evidence. You retrieve it with recall.

Your Interface

Recall

shellbrain recall --json '{
  "query": "<what you want to know>",
  "current_problem": {
    "goal": "<what you are trying to do>",
    "surface": "<where you are working>",
    "obstacle": "<what is blocking you>",
    "hypothesis": "<your current theory>"
  }
}'

Call Recall When

You start a task
The problem shifts materially
The same approach has failed twice
You are about to make an evidence-bearing decision

The Brief Returns

summary, constraints, known traps
prior cases, concept orientation, anchors
conflicts and gaps

Teaching

Only When Asked.

Explicit Teach

shellbrain teach "<statement>"

The statement is stored and retrievable immediately.

Boundary

Only call teach when the human explicitly asks. Normal memory extraction happens automatically when the session closes.

Boundaries

Do Not Manage Internals.

Do Not Call

shellbrain read

shellbrain events

shellbrain memory add

shellbrain memory update

shellbrain concept add

shellbrain concept update

shellbrain admin

shellbrain init

shellbrain upgrade

Use Instead

For normal task context, use shellbrain recall. For repair only, follow the human's instruction or the installed skill guidance.

Install

If Missing.

Install

curl -L ShellBrain.ai/install | bash

Installs the CLI and injects ShellBrain skills into Claude Code, Codex, and Cursor.

Repair

shellbrain admin doctor

If doctor flags issues, run shellbrain init. Do not run init every session.