Metadata-Version: 2.4
Name: shellbrain
Version: 0.1.31
Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: SQLAlchemy<3.0,>=2.0
Requires-Dist: alembic<2.0,>=1.13
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: psycopg[binary]<4.0,>=3.1
Requires-Dist: pgvector<1.0,>=0.3
Requires-Dist: sentence-transformers<4.0,>=3.0

<p align="center">
  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
</p>

<h3 align="center">ShellBrain</h3>

<p align="center">Long-term Memory for AI Agents.</p>

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

### 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 konwledge** 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

**Working agents call `recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.

```bash
shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
```

Lower-level commands exist for inner agents.
- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`

When a user explicitly says to store or teach Shellbrain something, working agents can call `teach`. It stores the statement as evidence and immediately runs Shellbrain's teach agent.

**Working agents focus on only their work.**

---

## 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.**

---

## Install

```bash
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

```bash
shellbrain upgrade
```

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

---

## 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 — it is not a no-op.

---

## Docs

- [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
- [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors
