Self-hosted decision memory for AI coding agents; warns before re-proposing a rejected approach.
io.github.adelinamart/robrain MCP Server
RoBrain is a self-hosted decision memory for AI coding agents, designed to warn before re-proposing an approach that was previously rejected. It uses shared memory across a team and agents, supports multiple coding tools, and focuses on memory management and contradiction scanning. Data is described as residing on a local Postgres instance.
π οΈ Key Features
Self-hosted on your own Postgres
Passive capture of memory
Structured vetoes and βreceiptsβ
Corpus-wide contradiction scans
Warns before re-proposing a rejected approach
π Use Cases
Improve coding agent decisions by using shared context
Avoid costly mistakes caused by repeating rejected approaches
Integrate with coding agent tooling for memory reuse
β‘ Developer Benefits
Works with Claude Code, Cursor, GitHub Copilot (VS Code), Codex CLI, Hermes, and more
Keeps activity on your machine (βnothing leaves your machineβ per excerpt)
Includes measured results via a VetoBench badge
β οΈ Limitations
Only an excerpt is provided; full implementation details and tool interfaces are not included
Shared memory, decision provenance, and architectural guardrails for multi-agent systems.
RoBrain isn't just another memory layer. It is the governance layer that was missing around AI agents: perimeter tools check who an agent is, but they cannot tell whether an agent is about to repeat a mistake the team already ruled out, or whether it is acting inside the team's constraints. RoBrain records what your team and its agents decided, what they rejected and why, who decided and when, and which rule reached which agent, and surfaces it before the agent acts again.
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 production agents built on Vercel's eve.
Measured: without the rejection in context, every frontier model we ran re-proposed an approach the team had already rejected, in 3 to 9 of 9 tasks per run. With RoBrain veto warnings in context: 0 of 159 across six models from four vendors, every answer naming the prior rejection β 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, the author and date, and the session turn it came from.
Most agent-memory tools stop at capture: they store what happened and hope you query it later. RoBrain adds judgment and provenance. Batch Synthesis reads the whole corpus to flag contradictions, stance drift, and recurring entities that no single session could see. Every memory can be traced back: who decided it, when, from which turn, and (on cloud) who pushed it to which production agent.
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 store now governs production agents: each agent built on eve gets its own memory project on first run, and the team pushes reviewed rules to it from the same RoBrain its coding agents use.
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 (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.
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.
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 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:
bash
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:
bash
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. Each machine you install on gets its own key, so setting up a second laptop does not sign out the first; a machine you have not used for 90 days is signed out the next time you install, and running the installer on it again brings it back.
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. An admin gives each agent its own key (npx robrain agent-keys create): it can read and capture but not change rules, and it stops working when that admin loses access. The commands are in the CLI reference; self-hosted RoBrain keeps one project by design.
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.
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:
bash
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:
bash
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.
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.
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, and the original reason. See Editor integration and the Claude Code plugin.
How do I share memory across Claude Code, Cursor, Copilot, and Codex?
One npx robrain install --self-hosted wires every detected editor to the same Postgres store; npx robrain init-project registers a repo once. A decision made in Cursor on Tuesday reaches a teammate's Claude Code on Wednesday.
Is the data stored in files or a database β and does it leave my machine?
Everything lives in PostgreSQL (with pgvector for embeddings) β structured rows, not flat files. Self-hosted, the database runs in Docker on your machine, and nothing leaves it except calls to the LLM/embedding provider you configure (a local model works too). In Rory Plans cloud, only extracted decision objects are stored; raw conversation text is not retained after extraction.
How is RoBrain different from a vector database or RAG?
A vector store retrieves what is similar; RoBrain also knows what was rejected. Rejections are first-class structured data (rejected[]), surfaced as warnings before the agent acts β and the corpus is actively judged: contradiction scans, drift detection, and git-outcome feedback that sinks decisions reality has already reverted. VetoBench measures the difference.
When should I use Rory Plans cloud instead of self-hosting?
Self-host when you want everything on your own infrastructure, free. Choose Rory Plans cloud when you want nothing to host and no API keys to manage β included with every paid Rory Plans plan, with memory shared across your team's org.
Does it work for production agents, not only coding agents?
Yes. @robrain/eve is a memory provider for Vercel's eve agents: veto warnings and the project summary at turn start, capture at turn end, and a check_prior_decisions tool. Each agent gets its own memory project on first run. On Rory Plans cloud, admins push reviewed rules from the coding memory to one agent, one kind of agent (by tag) or all of them with robrain promote, and every push is recorded with who did it.
How does RoBrain relate to Rory Plans?
Rory Plans is the Cloud Office for humans and AI agents β where workflows are designed and humans and agents are orchestrated together. RoBrain is its open-source memory layer: standalone and self-hostable forever, managed as part of Rory Plans for teams.
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 found Mem0's ingestion dropped the recorded rejection from 38% of retrieved contexts on identical input. Full comparison β
Provenance on every memory β source session, turn, excerpt; compiled blocks carry source decision ids
β
β
Who decided β author email and date on every decision, in review, search, the summary and veto warnings
β git user.email
β from the signed-in identity, never client-sent
npx robrain search and hand-written rules (rules add, confidence 1.0, approved on insert)
β
β
Production agent memory β a project per agent, org rules pushed by admins to all agents, one tag of agents, or one agent (promote); tags derived from the tools an agent uses (tags map)
β
β
Governance ledger β who registered, pushed, tagged or changed what (robrain audit, dashboard)
β
β
Keys for production agents β one per agent, created by an admin, always a member, ended when that admin loses access (robrain agent-keys)
Team memory β orgs, API keys, roles, scoped isolation
β
β
Web dashboard
β
β
Self-hosted gives capture, judgment batch jobs, outcomes feedback, and session-start recall; you pull focused context with inject when needed. Cloud adds Planning + Control so vetoes and conflicts surface automatically at task boundaries β same CLI surface, wire-compatible with Sensing capture. Details: Concepts β Free / self-hosted vs Rory Plans cloud.
VetoBench
Memory benchmarks usually ask "did the right item come back?" VetoBench asks what that misses: given a task that invites an approach the team already rejected, does the agent propose it again?
Memory condition
Re-proposed a rejected approach
Could cite the prior rejection
No memory
8β9 of 10 tasks
0β10%
Conventions file (choices only β what most teams have today)
1β2 of 10
80β90%, but inferred: the reasons aren't there
Mem0 β full pipeline, 5 archived runs
0β2 of 10 per run
50β90%
RoBrain β full pipeline, 5 archived runs
0 of 10, every run
100%
(claude-haiku-4-5, 2026-07-07/08; every condition measured as a five-run archived series, ranges because runs vary. Mem0 and RoBrain ingested byte-identical transcripts, each through its own real production extraction.)
Two findings behind the table. Mem0's ingestion dropped the recorded rejection from 38% of retrieved contexts, and violations concentrated exactly there β 26% when the veto was absent vs 3% when present: the agent avoided Express in all five runs but could never say why, and where the axios veto was lost it re-proposed axios outright in 3 of 5 runs. RoBrain's production extractor, on the same input, kept 100/100 vetoes β keeping the veto is the extraction prompt's job, not a side effect of fact summarization.
Meta Muse Spark 1.1 (2026-07-14, five archived runs). Meta's newly launched agentic flagship, via Vercel AI Gateway. Without memory it re-proposed rejected approaches in 4β6 of 9 tasks per run β Redux, Prisma, Jest, and GraphQL in all five runs. With RoBrain decision memory: 0 violations in all 45 cells, naming the prior rejection every time β quoting the recorded reason and date verbatim where it elaborated. The cleanest cell: asked to cut mobile overfetching, the no-memory run proposed a full GraphQL rollout (the approach the team had ruled out) five runs out of five; with RoBrain in context it proposed REST sparse fieldsets and quoted the recorded rejection. Honest notes: this is not a Muse Spark problem β every frontier model we baselined violates without memory on the same nine scenarios (claude-opus-4.8: 3β4, gpt-5.5: 5, gemini-3-pro-preview: 6β7, Haiku 7β8; Prisma and Jest fell to every model in every run β and with RoBrain context those same three models went 0 violations in 54/54 cells, for 99/99 across four vendors β receipts), a bare conventions file also prevented violations for this model at this corpus size (the RoBrain delta is verbatim citations vs inferences, automatic capture, and retrieval at scale), and one scenario is excluded (n=9) because Meta's content filter deterministically blocks a benign session-caching prompt. Receipts and caveats: results/muse-spark-1.1-series/ Β· write-up: docs/blog/2026-07-14-muse-spark-forgets-your-vetoes.md.
Every retrieved context, agent reply, and verdict is committed in packages/vetobench/results/ β check the work before quoting it. The retrieval layer runs offline with no API key and gates CI (pnpm --filter @robrain/vetobench bench); judging is deterministic β no LLM judge. Any memory system plugs in through one adapter interface; PRs welcome, including ones that make us look bad. Methodology, honesty caveats, and fixtures: packages/vetobench/README.md.
Security
The memory corpus is guarded by PERCEPTION_API_KEY β a random secret in the repo-root .env that every client (Sensing MCP, CLI, Synthesis) sends as a Bearer token and Perception verifies on every request except /health. It is not issued by any service: pnpm docker:up generates one automatically on first run, or set your own (e.g. openssl rand -hex 32). Installing (pnpm robrain install --self-hosted from a clone, npx robrain install --self-hosted otherwise) copies the same value into your editor configs so clients authenticate.
Perception refuses to start when the key is empty β running unauthenticated requires an explicit opt-in. Upgrading from a version that ran without a key: add one to .env (or re-run pnpm docker:up to auto-fill it), then re-run install (pnpm robrain install --self-hosted from a clone, npx robrain install --self-hosted otherwise) so editors pick it up. Details and the opt-in flag are documented in .env.example.
Also on by default: secrets redaction (API keys, tokens, private keys, connection-string passwords are scrubbed at capture and again at ingest, before anything is embedded or stored), and a fully-local mode where extraction and embeddings run on an OpenAI-compatible local server (Ollama / LM Studio / vLLM) β see CLI β Fully-local LLM and .env.example.
What's next
robrain outcomes feeds git reverts back into memory quality on both tiers; next is widening that to incidents and cycle time, so RoBrain can surface when a team is optimizing for the wrong thing in its own codebase.
Requirements
Docker + Docker Compose (runs Postgres and Perception locally)
Node.js with pnpm (build and CLI)
An LLM key for the classifier β Anthropic Haiku or OpenAI β or a local OpenAI-compatible server (see Fully-local LLM)
An embedding key (e.g. OpenAI) β or the same local server for embeddings
No data leaves your machine in self-hosted mode
Docs
Concepts (how it works, two pillars, Synthesis, comparisons) β docs/concepts.md
CLI reference (explain, install, upgrading, editor setup, full command table, project id naming convention) β docs/cli.md
Deprecation policy (additive routes and migrations, nothing retired without a replacement) β docs/deprecation.md
eve memory provider (@robrain/eve β team decision memory for Vercel's eve agents via eve's memory-provider contract; built on eve 0.82 to 0.84, typechecks against 1.0.0-rc.7) β packages/eve/README.md
Apache 2.0. PRs welcome for extraction accuracy, new editor integrations, and embedding providers. See Concepts β Reference for tradeoffs and schema.