ShellBrain logo

ShellBrain

Long-term Memory for AI Agents.

Agents forget across sessions. They rediscover the same problems, repeat the same mistakes, and relearn what you already taught them. ShellBrain makes their work compound.

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

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

Recall in one command.

Episodic, empirical, conceptual. Three categories, one retrieval surface.

Architecture

Episodic knowledge is the evidence layer.

  • What actually happened in the session: your prompts, the agent's steps, tool calls, and outputs.

Empirical knowledge is the concrete extracted layer.

  • An ontology of problems, solutions, failed tactics, facts, preferences, changes.
  • This is case-based reasoning in a semantic graph.

Conceptual knowledge is the abstractive layer.

  • A higher-level concept graph with claims, relations, and implementations that link back to the concrete layer.
  • Progressive disclosure. agents get oriented first, then ask for depth only where tasks require it.

The episodic layer is truth. Empirical memory extracts. Concept memory abstracts. Each layer is grounded in the one beneath it.

How Agents Use ShellBrain

Recall

Working agents call shellbrain recall. That is the normal interface they have to think about. One command, one carefully curated compact brief, with sources cited.

shellbrain recall --json '{"query":"What is ShellBrain and how does it help a working coding agent?","current_problem":{"goal":"understand ShellBrain","surface":"README","obstacle":"new readers do not know the product yet","hypothesis":"a real recall brief should show what agents get back"}}'

Response shape:

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

Working agents focus on only their work.

Teach

Working agents call shellbrain teach for explicit teaching. You can tell an agent to remember important ideas.

Principled and Disciplined

Memory that is grounded in evidence, small in scope, and asked for rather than pushed is memory that compounds. Everything else is noise for working agents.

A memory layer that cannot justify itself should not persist.

How to Use ShellBrain

Use Shellbrain in your agent of choice. Then, just work normally.

Claude Code: Use /shellbrain to remember Shellbrain recall at the right task boundaries.

Codex: Use $shellbrain to remember Shellbrain recall at the right task boundaries.

Cursor: Use /shellbrain to remember Shellbrain recall at the right task boundaries.

Repair

shellbrain admin doctor to inspect. shellbrain init to repair if doctor flags it. Do not rerun 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.47.tar.gz (558.7 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.47-py3-none-any.whl (751.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: shellbrain-0.1.47.tar.gz
  • Upload date:
  • Size: 558.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for shellbrain-0.1.47.tar.gz
Algorithm Hash digest
SHA256 cb7b8d5d2e93024bbaccdde661d9e17dbaa8e7cc7435785496d24717251fdef6
MD5 1bca54232f52996ffa160d6d85e6cd59
BLAKE2b-256 b7560e172ff43a188c648299bf8a1f2a4339aab3ccb88a1820c0761a481ffc6a

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: shellbrain-0.1.47-py3-none-any.whl
  • Upload date:
  • Size: 751.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for shellbrain-0.1.47-py3-none-any.whl
Algorithm Hash digest
SHA256 3cea8f8130401fe548102a67edac276394ef8667a4bccf33569fb66b3df55da7
MD5 d5140c339fc28e672bf6d6a4cd700a07
BLAKE2b-256 cdb72a1a65f33da755a0d31e4ddb1aaba37702fba7313905f026aed3daa30b91

See more details on using hashes here.

Provenance

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

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

This release

0.1.47 This release

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