shellbrain 0.1.9

Repo-scoped Shellbrain CLI with explicit evidence-backed writes.

Building a Brain

Shellbrain gives agent sessions repo-scoped long-term memory. It stores what happened, what worked, what failed, and what the human prefers — then retrieves the relevant pieces the moment a similar problem surfaces. Every session compounds into the next.

---

Install

curl -L shellbrain.ai/install | bash

One command on supported machines. The installer provisions the local runtime, installs the Codex and Claude skills, wires the Claude SessionStart hook, and runs shellbrain init for you when the managed-local prerequisites are met. Repos register themselves on first use.

Managed-local requirements

• macOS or Linux
• Python 3.11+ required
• Docker installed and the daemon running
• first init downloads a local embedding model
• PostgreSQL + pgvector run inside the managed Docker runtime
• Windows is not supported yet
• external Postgres remains an advanced/operator-managed path for now

The repo Dockerfile is for packaging and development smoke coverage. It is not the end-user runtime path.

---

Upgrade

shellbrain upgrade

Upgrades the package and reruns init. Skills, hooks, and the managed runtime all refresh in one pass.

The install script also works as an upgrade path — curl -L shellbrain.ai/upgrade | bash if you prefer. Manual alternative: pipx upgrade shellbrain && shellbrain init.

---

Use it

You use shellbrain by launching a skill in your agent.

Codex: Use $shellbrain-session-start to get up to speed in this repo with shellbrain and record durable evidence-backed learnings.

Claude Code: Use Shellbrain Session Start to get up to speed in this repo with shellbrain and record durable evidence-backed learnings.

The agent handles everything from there — reading prior context, gathering evidence, writing durable memories at session end. You don't manage any of this directly.

---

Four operations

read retrieves durable memories related to a concrete problem. Re-run whenever the search shifts.

events syncs the active transcript. Returns episode event ids to cite as evidence. Run before every write.

create writes one durable memory. At least one evidence reference required.

update records utility votes, truth-evolution links, explicit associations, or archive state.

The rhythm: read first, events before writes, create/update at session end. Do not rerun shellbrain init every session.

---

Repair

shellbrain admin doctor is the inspect path when something feels wrong.

shellbrain init is the repair path if doctor says repair_needed. The installer already ran it once — you only rerun it to fix things.

If shellbrain isn't found in a tool shell, retry through the shell-specific path the installer configured:

zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'
bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'

Fish PATH setup is written to ~/.config/fish/conf.d/shellbrain.fish.

---

Docs

• shellbrain.ai/humans — install, upgrade, getting started
• shellbrain.ai/agents — how agents use shellbrain, with a sitemap to every page
• shellbrain.ai/recall — how the read pipeline works