ShellBrain logo

ShellBrain

Long-term Memory for AI Agents.

ShellBrain gives AI agents memory, so they can store and reuse what they learn over time.

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 builds memory in three grounded layers:

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

Each higher layer links to evidence in the layer below it. Agents receive a compact orientation first, then request more detail when needed.

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": []
}

The brief lets the working agent focus on the current task.

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:
Newer release available (0.1.58)

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.56.tar.gz (502.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.56-py3-none-any.whl (680.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: shellbrain-0.1.56.tar.gz
  • Upload date:
  • Size: 502.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.56.tar.gz
Algorithm Hash digest
SHA256 6ab661cb349ca626a681c9a8518993829cae75eb9a9a75b8a4887b6ca94c5f72
MD5 afd5c5ae20aff2dd44bf75526cc1fac9
BLAKE2b-256 03f94bc0a291d3c8d691c2116ce6b2654656de05e25d49d304e0361f111da1cb

See more details on using hashes here.

Provenance

The following attestation bundles were made for shellbrain-0.1.56.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.56-py3-none-any.whl.

File metadata

  • Download URL: shellbrain-0.1.56-py3-none-any.whl
  • Upload date:
  • Size: 680.5 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.56-py3-none-any.whl
Algorithm Hash digest
SHA256 b8fd5874bf339df760db90fcef678d6cf3fd6ae982f41844a85f9d92853694f2
MD5 d5e70f6f9639591fb0196b820e85b535
BLAKE2b-256 4d3a7ee2f6ac9e2e04dade3fabaa22a066a50218de2ed4a06c143f58b64d92bd

See more details on using hashes here.

Provenance

The following attestation bundles were made for shellbrain-0.1.56-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

0.1.58

2 files

0.1.57

2 files

This release

0.1.56 This release

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