Metadata-Version: 2.4
Name: shellbrain
Version: 0.1.39
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.**

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

---

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

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

```json
{
  "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

- [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/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries
