Robrain

RoBrain

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.

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.

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.

Default path uses Anthropic (extraction) + OpenAI (embeddings). Other setups (OpenAI-only, Gemini, other embeddings, fully local) — Concepts — Prefer a different provider setup?.

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

From a clone instead (development, or building the image yourself)

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.

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 LLM + embedding keys for the provider path you chose (default: ANTHROPIC_API_KEY + OPENAI_API_KEY)

pnpm docker:up # second run: Perception now boots pnpm robrain install --self-hosted --repo-root "$(pwd)"

pnpm robrain runs the CLI you just built (node packages/cli/bin/robrain.js). Use it instead of npx robrain everywhere in this clone — npx resolves to the published package or a stale global install, not your working tree.

Upgrading a self-hosted install

No-clone stack: re-run npx robrain@latest up (pulls the new Perception image and applies startup DB migrations) then npx robrain@latest install --self-hosted. From a clone: git pull → pnpm install && pnpm build → pnpm docker:up:build → pnpm robrain install --self-hosted --repo-root "$(pwd)" → fully restart editors. Full checklist: CLI reference — Upgrading.

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:

claude plugin marketplace add adelinamart/robrain

claude plugin install robrain@robrain

Details: plugins/claude-code. 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:

npx robrain install          # no flags — cloud mode

Sign in at 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 shows what each tier adds.

Cloud also governs memory for production agents: each agent gets its own project (the eve provider registers it on first run), org admins push rules to every production agent or to one kind of agent by tag (npx robrain promote), tags come from the tools an agent uses through an admin-kept mapping (npx robrain tags map), and every governance action is recorded with who did it. The commands are in the CLI reference; self-hosted RoBrain keeps one project by design.

Quickstart

After either install (self-hosted or cloud):

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

Tune what gets captured

By default the classifier stores decisions and the alternatives you rejected, and nothing else. When a project wants more, less, or something different, tell it in plain language. The settings are stored per project on Perception, so every teammate's sessions capture the same way:

npx robrain capture show

npx robrain capture set --instructions "Skip anything about the marketing site. Treat naming conventions as decisions." npx robrain capture set --min-confidence 0.75 # less noise npx robrain capture set --mode broad # every turn reaches the model, not only keyword hits npx robrain capture set --add-kind "run: The outcome of an agent run: what ran, when, and whether it succeeded." npx robrain capture test --file sample-turns.jsonl --compare # dry run before you commit to it

Extra kinds of memory sit beside decisions: each entry names a subject, and a newer entry about the same subject replaces the older one, so a kind can hold changing state (the last run of an agent) as well as rules. Only decisions carry vetoes. Flags and formats: CLI reference.

Search it, or write a rule by hand

Every stored decision records who decided it (the git user.email of the session) and when, and the summary and veto warnings say so. Search the memory like a person would, or add a rule without waiting for a session to capture it:

npx robrain search "confirm before sending"

npx robrain rules add "Never auto-send a plan; the customer confirms first." --because "trust" --rejected "auto-send: customers lost drafts"

Hand-written rules are stored like captured ones (same vetoes, summary and review), with confidence 1.0 and approved on insert. A repo gets its own project from init-project; a team that wants one memory across several repos creates a project and pins it in each (npx robrain projects create team-payments, then ROBRAIN_PROJECT_ID=team-payments). The id shapes in use are listed in the naming convention. Upgrades never retire a command or route without a replacement: deprecation policy.

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.

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.

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.

Running Hermes? 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.

Decision ledger for git (opt-in):

npx robrain export-memory --ledger

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

Common questions

How do I stop an AI coding agent from re-proposing something my team already rejected?

Record the rejection once — RoBrain captures it passively from the session where it happened — and every connected agent gets a veto warning before steering down that path again: the decision, the rejected option, an