git:20260714.47ac030 to git:20260923.a8028d7

1 added, 24 removed. Audit A to A.

---

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 "<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:

- ```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.

+ Use `shellbrain recall` with a targeted query. Run `shellbrain upgrade` to repair an existing installation.

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 | <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.

```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.