ShellBrain logo

ShellBrain

Long-term Memory for AI Agents.

ShellBrain carries useful lessons from one agent task to the next. It preserves decision reasons, failed approaches, product direction, and preferences that the resulting code does not explain.

Install

curl -L shellbrain.ai/install | bash

Works for Codex, Claude Code, and Cursor. The installer runs shellbrain init for you. Repos register themselves on first use.

Requirements.

  • macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.

Upgrade for latest capabilities

shellbrain upgrade

You can also run curl -L shellbrain.ai/upgrade | bash. Manual alternative: pipx upgrade shellbrain && shellbrain init.

Recall in one command

ShellBrain recall uses vector search and BM25 to search your memories. An inner recall agent summarizes the search results.

Architecture

ShellBrain stores evidence and two forms of reusable knowledge:

  • Episodic knowledge records evidence. It stores prompts, agent steps, tool calls, and outputs from each session.
  • Empirical knowledge extracts concrete memories. It organizes problems, solutions, failed tactics, facts, preferences, and changes in a semantic graph for case-based reasoning.
  • Conceptual knowledge abstracts reusable ideas. Its concept graph connects claims, relations, and implementations to empirical knowledge.

Memories and concept claims link to supporting evidence. A concept can express a product principle without a duplicate memory. Current code remains the source of truth for implementation details.

How Agents Use ShellBrain

Recall

Working agents run shellbrain recall to get one compact brief for the current task.

Recall receives only the quoted query. Include the relevant task, failure, subsystem, or decision in the question.

shellbrain recall "What is ShellBrain, and how does it help a working coding agent?"

Response format:

{
  "status": "ok",
  "data": {
    "brief": {
      "summary": "...",
      "constraints": ["..."],
      "known_traps": ["..."],
      "prior_cases": ["..."],
      "concept_orientation": ["..."],
      "anchors": ["`README.md`"],
      "conflicts": ["..."],
      "gaps": ["..."],
      "next_checks": ["..."]
    },
    "fallback_reason": null
  },
  "errors": []
}

Recall selects an evidence pack in code, then asks an inner agent to summarize it. Source attribution comes from the selected records. Fast mode and provider failures return a brief directly from that same pack.

Teach

Run shellbrain teach only when you explicitly want ShellBrain to remember something important.

Memory Discipline

ShellBrain keeps memory grounded in evidence and narrow in scope. Agents request memory when they need it.

Memory that cannot justify itself should not persist.

Use ShellBrain

Use Shellbrain with your preferred agent. Then work as usual.

  • Claude Code: Use /shellbrain to recall context at task boundaries.
  • Codex: Use $shellbrain to recall context at task boundaries.
  • Cursor: Use /shellbrain to recall context at task boundaries.

Repair

Run shellbrain admin doctor to inspect the installation. If it reports a problem, run shellbrain init. Do not run init every session.

Docs

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for shellbrain from gravatar.com shellbrain

Requires

Python >=3.11

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shellbrain-0.1.58.tar.gz (469.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

shellbrain-0.1.58-py3-none-any.whl (642.1 kB view details)

Uploaded Python 3

File details

Details for the file shellbrain-0.1.58.tar.gz.

File metadata

  • Download URL: shellbrain-0.1.58.tar.gz
  • Upload date:
  • Size: 469.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for shellbrain-0.1.58.tar.gz
Algorithm Hash digest
SHA256 94346d9977aa7b94954221bef782b6af75a0b07f06be4dabcf3a7a9452627284
MD5 f60922b138a2ee2f6d7f1f683d05b899
BLAKE2b-256 8a519a81f2881953d61d7a0f09fe13a476800150cb73571a6d278c9c62919447

See more details on using hashes here.

Provenance

The following attestation bundles were made for shellbrain-0.1.58.tar.gz:

Publisher: release.yml on cucupac/shellbrain

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file shellbrain-0.1.58-py3-none-any.whl.

File metadata

  • Download URL: shellbrain-0.1.58-py3-none-any.whl
  • Upload date:
  • Size: 642.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for shellbrain-0.1.58-py3-none-any.whl
Algorithm Hash digest
SHA256 f7b3aa3508b7f4fc3e64f89a5a72b8f0b9dbc7ec99bba294d6c87ed04fca39ce
MD5 a5d7bf050375a82fa5b15e77a978e376
BLAKE2b-256 927c156074165e42c3746e969314c4537b977b4b0b7c65a6f8cc29b0f1b41b31

See more details on using hashes here.

Provenance

The following attestation bundles were made for shellbrain-0.1.58-py3-none-any.whl:

Publisher: release.yml on cucupac/shellbrain

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.58 This release

2 files

0.1.57

2 files

0.1.56

2 files

0.1.55

2 files

0.1.54

2 files

0.1.53

2 files

0.1.52

2 files

0.1.51

2 files

0.1.50

2 files

0.1.49

2 files

0.1.48

2 files

0.1.47

2 files

0.1.46

2 files

0.1.45

2 files

0.1.44

2 files

0.1.43

2 files

0.1.42

2 files

0.1.41

2 files

0.1.40

2 files

0.1.39

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

0.1.29

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page