start here.
shellbrain gives your AI agents durable, structured long-term memory. every problem solved, every failed attempt, every lesson learned—stored locally, retrieved automatically when something similar surfaces again. agents that remember solve faster and repeat mistakes less.
install.
one command on supported machines. the installer installs the shellbrain CLI, sets up PATH for zsh, bash, or fish, auto-installs skills into Claude Code, Codex, and Cursor, and runs shellbrain init. on first bootstrap, shellbrain init asks where shellbrain should store data.
curl -L shellbrain.ai/install | bash
view requirements
- macOS and Linux
- Python 3.11+
- first init asks you to choose a storage mode
- managed local: Docker installed and running
- external: PostgreSQL with pgvector
- first init downloads a local embedding model (~few hundred MB)
- Windows not yet supported
we ship often. run the upgrade command when you want newer capabilities.
shellbrain upgrade
use the skill with every thread.
shellbrain only activates when you tell the agent to use it. paste the prompt below at the start of every new conversation thread. the skill tells the agent how to read context, gather evidence, and write durable memories. you don't manage any of this directly—the agent does.
Use Shellbrain Session Start to get up to speed in this repo with shellbrain and record durable evidence-backed learnings.
what the agent does.
read retrieves durable context about the problem at hand. events syncs the active transcript so evidence exists for writes. create and update turn session work into reusable long-term memory.
the agent re-queries read whenever the problem shifts. it runs events before every write. it stores problems, solutions, failed tactics, facts, preferences, and changes at session end.
if something feels wrong.
run shellbrain admin doctor. it inspects your local setup and reports what needs attention. only rerun shellbrain init directly if doctor says repair is needed—the installer and upgrader already handle init for you.