robrain

# RoBrain

[![VetoBench](https://img.shields.io/badge/VetoBench-0%2F50_violations_·_receipts_in--repo-2ea44f)](#vetobench)

**Shared memory across your team and your AI agents — with judgment!**

RoBrain isn't just another memory layer — it's the brain that helps you and your agents make better decisions and avoid costly mistakes.

Self-hosted on your own Postgres. Passive capture, structured vetoes, corpus-wide contradiction scans — nothing leaves your machine. Works with Claude Code, Cursor, GitHub Copilot (VS Code), Codex CLI, Hermes and more.

Measured: without decision memory, a coding agent re-proposes an approach your team already rejected in up to **9 of 10** tasks. Through RoBrain's full pipeline: **0 of 50**, across five archived runs — [VetoBench](#vetobench).

## What it is

RoBrain records what your team and its agents decide — and the alternatives they ruled out — without anyone tagging anything by hand. Sensing captures session turns; Perception extracts each decision into Postgres, where every row can carry a structured `rejected[]` field.

Most agent-memory tools stop at capture: they store what happened and hope you query it later. RoBrain adds judgment. Batch **Synthesis** reads the whole corpus to flag contradictions, stance drift, and recurring entities that no single session could see.

The point is the handoff. Someone makes a deliberate call in Cursor on Tuesday — say, keeping Perception on Hono instead of porting to Express. A new teammate opens Claude Code on Wednesday with no memory of it and asks to make exactly that change. RoBrain surfaces the recorded rationale before the agent steers down a path you already rejected — same Postgres store, same vetoes, captured passively.

> The cost of forgetting a rejection isn't inefficiency. It's the auth bypass you already patched, the migration you already rolled back, the dependency you already removed for a CVE — re-suggested by an agent with no memory of why you said no.

Coding is the first vertical because the feedback loops are tight — reverts, incidents, and rework make the cost of a forgotten rejection measurable. The same architecture applies wherever agents make decisions that outlast a session.

How it works, the two pillars (capture + judgment), and the full walkthrough: [docs/concepts.md](docs/concepts.md#how-it-works).

## Install

Two ways to run RoBrain — pick one:

- **Option 1 · Self-hosted** (free, open source): everything runs on your machine — your Postgres, your API keys, nothing leaves your laptop.
- **Option 2 · [Rory Plans cloud](#option-2--rory-plans-cloud-managed)** (managed): nothing to host, no keys — included with every paid Rory Plans plan.

### Option 1 · Self-hosted (free, open source)

No clone needed — `robrain up` pulls the published Perception image and generates credentials into `~/.robrain/stack/.env`:

```bash
export ANTHROPIC_API_KEY=... OPENAI_API_KEY=...   # or add them to ~/.robrain/stack/.env after the first run
npx robrain@latest up                             # start Postgres + Perception from ghcr.io
npx robrain install --self-hosted                 # wire Sensing MCP into your editors
```

<details>
<summary>From a clone instead (development, or building the image yourself)</summary>

First `pnpm docker:up` auto-creates `.env` and fills `PERCEPTION_API_KEY` / `POSTGRES_PASSWORD`. Perception still needs your LLM + embedding keys before it stays up.

```bash
git clone https://github.com/adelinamart/robrain
cd robrain
pnpm install && pnpm build
pnpm docker:up                 # first run: creates .env; Perception won't start yet
# open .env, add ANTHROPIC_API_KEY + your embedding key (e.g. OPENAI_API_KEY)
pnpm docker:up                 # second run: Perception now boots
npx robrain install --self-hosted --repo-root "$(pwd)"
```

</details>

#### Claude Code plugin (self-hosted)

Claude Code users on the self-hosted stack can add hook-based capture and pre-task warnings about previously rejected approaches — no CLAUDE.md protocol needed:

```bash
claude plugin marketplace add adelinamart/robrain
claude plugin install robrain@robrain
```

Details: [plugins/claude-code](plugins/claude-code/README.md). `robrain init-project` also recommends the plugin to collaborators via the project's `.claude/settings.json`, so teammates get an install prompt from Claude Code itself (opt out with `--skip-claude-plugin`).

### Option 2 · Rory Plans cloud (managed)

On any paid Rory Plans plan, RoBrain runs without hosting anything:

```bash
npx robrain install          # no flags — cloud mode
```

Sign in at [roryplans.ai](https://roryplans.ai), create an API token on your profile page, and paste it when the installer asks. That's the whole setup: no Docker, no database, no LLM or embedding keys — extraction and search run on our side. Your editors (Claude Code, Cursor, Copilot, Codex CLI) are wired automatically, and teammates on your Rory Plans team share the same memory.

Every paid plan qualifies — individual standard or annual, Teams, and enterprise. Solo subscribers get a private memory space; teams share one. Self-hosting stays free and fully supported (see Install above); the [comparison table](#self-hosted-vs-rory-plans-cloud) shows what each tier adds.

OpenAI-only: set `LLM_PROVIDER=openai` and `OPENAI_API_KEY` instead of Anthropic — see [Concepts — Prefer not to use Anthropic](docs/concepts.md#prefer-not-to-use-anthropic-run-openai-only).

Upgrading a self-hosted install on a new release — no-clone stack: just re-run `npx robrain@latest up`. From a clone: `git pull` → `pnpm install && pnpm build` → `pnpm docker:up:build` → `npx robrain install --self-hosted --repo-root "$(pwd)"` → fully restart editors. Full checklist: [CLI reference — Upgrading](docs/cli.md#upgrading).

## Quickstart

After either install (self-hosted or cloud):

```bash
# Wire capture into an application project (run inside the repo)
cd /path/to/your/project
npx robrain init-project          # writes CLAUDE.md, AGENTS.md, .cursor/rules/robrain.mdc

# Capture and recall are automatic from here:
#   - every session turn is classified, no tagging
#   - prior decisions load at session start via the always-on summary

# Explain any file's decision history
npx robrain explain path/to/file

# Inspect / approve captured rows (both modes)
npx robrain review

# Run corpus judgment — self-hosted only; cloud runs judgment server-side
npx robrain synth                 # drift, contradictions, entity promotion
```

After `init-project`, every repo gets `CLAUDE.md` and `AGENTS.md` (Codex CLI), and Cursor also gets `.cursor/rules/robrain.mdc` with `alwaysApply: true`. If captures don't land, run `npx robrain doctor` — see [Troubleshooting](docs/troubleshooting.md).

## Synthesis

Synthesis runs three passes over the full `decisions` table — **drift** (stance moving without an explicit reversal), **contradictions** (incompatible decisions from different sessions), and **entity promotion** (recurring tools/patterns condensed into `planning_blocks`). It writes flags and edges into your DB; it does not capture new decisions — it judges the corpus you already have.

```bash
pnpm synthesis:build && pnpm synthesis:run
# or: npx robrain synth
```

Review what it finds with `npx robrain review`. Deep dive (three passes, cron, env vars): [Concepts — Synthesis](docs/concepts.md#synthesis).

## Editor integration

One cross-tool setup covers **Claude Code, Cursor, GitHub Copilot (VS Code), and Codex CLI** against the same Postgres store. The classifier LLM is your choice — Anthropic Haiku or OpenAI. Decisions carry a lifecycle (active / superseded / invalidated) and a graph (`conflicts_with` / `extends` / `related_to`).

**Codex CLI / IDE** also gets hook-based capture and pre-task veto warnings — the same lifecycle hooks as the Claude Code plugin, wired automatically by `robrain install` into `~/.codex/config.toml` (Codex asks you to trust them on first run). Docs: [plugins/codex](plugins/codex/README.md).

Running [Hermes](https://github.com/NousResearch/hermes-agent)? `npx robrain install --hermes` drops a standalone memory-provider plugin into `~/.hermes/plugins/` — passive capture and veto-aware recall through the same Perception API. Docs: [integrations/hermes](integrations/hermes/robrain/README.md).

Decision ledger for git (opt-in):

```bash
npx robrain export-memory --ledger
# custom path: npx robrain export-memory --ledger docs/decisions.md
```

## Compared to other tools

Versus **Mem0**, **Cloudflare Agent Memory**, and **Claude Code Auto-Memory**: only RoBrain stores rejected alternatives as structured fields and runs corpus-wide contradiction scans (manual or cron). And we measured what that difference costs: [VetoBench](#vetobench) found Mem0's ingestion dropped the recorded rejection from **38% of retrieved contexts** on identical input. [Full comparison →](docs/concepts.md#comparisons)

### Self-hosted vs Rory Plans cloud

| Feature | Free / self-hosted | Rory Plans cloud |
|---------|-------------------|------------------|
| Passive session capture | ✓ | ✓ |
| `rejected[]` field as structured data | ✓ | ✓ |
| Decision lifecycle (active / superseded / invalidated) | ✓ | ✓ |
| Cross-tool MCP — Claude Code, Cursor, Copilot, Codex CLI, Hermes | ✓ | ✓ |
| Classifier LLM choice — Anthropic Haiku or OpenAI | ✓ | ✓ |
| Always-on summary at session start | ✓ | ✓ |
| `npx robrain review` / `inject` / `explain` / `export-memory` | ✓ | ✓ |
| Synthesis — drift, contradictions, entity promotion | ✓ | ✓ |
| Decision graph (`conflicts_with` / `extends` / `related_to`) | ✓ | ✓ |
| Provenance on every memory — source session, turn, excerpt | ✓ | ✓ |
| Memory quality feedback — used/ignored counters, auto-demotion | ✓ | ✓ richer: helpful/pushback per injection |
| Outcome linking — git reverts feed back into memory rank | ✓ | ✓ |
| Secrets redaction at capture and ingest | ✓ | ✓ |
| Memory interchange export (`robrain-memory/v1` JSONL) | ✓ | ✓ |
| Open retrieval