Don’t let your AI agent step in the same hole twice.
Recently came across a pretty interesting open‑source project: RoBrain (https://github.com/adelinamart/robrain).
RoBrain is the “decision memory layer” for AI coding teams. It records every technical choice made during coding sessions, the reasoning behind it, the alternatives that were ruled out, affected files, and session metadata. Tools like Claude Code, Cursor, and Copilot then suffer a little less amnesia in new sessions.

For example, one person decides in Cursor to use Zustand for shopping cart state management because Redux was causing re‑render issues. The next day, another person starts a new task in Claude Code and the agent is about to suggest Redux again.
That’s where RoBrain shines: it captures the decision, the rationale, the rejected options, and the related files — and stuffs that context right back in the next time.

I think its three most noteworthy features are:

1. rejected[] – it turns “why we didn’t pick Redux / GraphQL / some other approach back then” into a structured field. This is way more valuable than a plain memory store that only records conclusions, because in engineering the real time‑waster is often everyone forgetting why a particular solution was vetoed.

2. Cross‑tool team memory – the example in the README shows Alice making a decision in Cursor, and Bob the next day being able to pull that context into Claude Code and continue from there.

3. Synthesis – it does batch scans over the long‑term accumulation of decisions, looking for drift, contradictions, and recurring entities. It’s essentially an “after‑action review + conflict radar” layered on top of your team’s agent workflow.

adelinamart/robrain

Source: https://github.com/adelinamart/robrain

RoBrain

Stop watching your AI agent repeat the same mistakes.

Open-source shared memory for teams using AI agents. Captures every decision and the alternatives your team ruled out, and flags when a new decision contradicts an old one — so your team revisits past decisions intentionally, instead of re-litigating from zero. Works across Claude Code, Cursor, and Copilot.

RoBrain is built by Rory Plans (https://roryplans.ai), an agent orchestration platform; it is the memory layer that keeps multi-agent, multi-developer work coherent over time.

Contents

• How it works
• What ships today
• Install and usage
• Quick start - self-hosted
• Install details
• Synthesis
• CLI commands
• Free / self-hosted vs Rory Plans cloud
• Comparisons
• Troubleshooting
• Follow-ups (TODO)
• Reference

How it works

Session 1 — Tuesday afternoon, Alice in Cursor:
Alice and her agent are working on the shopping cart. They consider Redux for state management, but settle on Zustand because Redux was causing re-render performance issues in the cart component. RoBrain captures this automatically:

json { "decision": "Use Zustand for state management", "rationale": "Redux caused re-render issues in cart", "rejected": [{ "option": "Redux", "reason": "re-render perf issues in cart" }], "files_affected": ["src/store/cart.ts"] }

No notes written. No commands run. The capture is part of the session, not on top of it.

Session 2 — Wednesday morning, Bob opens Claude Code:
Bob is working on a new cart feature in Claude Code. His agent, in a fresh session with no memory of Alice’s work, is about to suggest Redux. Bob runs npx robrain inject --query "state management" --copy before his next prompt. RoBrain returns:

Chose Zustand over Redux (re-render perf issues in cart) — Mar 15, high confidence

The agent now knows the team’s prior reasoning, surfaces it in the conversation, and Bob’s Claude Code session continues from informed context — instead of re-litigating Alice’s Cursor decision from scratch.

That’s the loop. Alice can make a decision in Cursor on Tuesday and Bob can pick it up in Claude Code on Wednesday. Decisions and their vetoes flow from one developer’s session into every other developer’s sessions. Captured automatically; surfaced automatically via the always-on summary, with inject for focused pull in Free / self-hosted mode (or task-boundary auto-injection in the cloud).

Why this matters

Six months into a project, every architectural decision your team has made — and every alternative they ruled out — is queryable as structured data. New developers join and inherit the full decision history. Old decisions stay queryable after you change your mind (“what did we decide in March?” returns a real answer). Contradictions across sessions get flagged for review instead of silently overwriting each other.

• Because rejected[] is structured, RoBrain can surface “don’t do that again” context before an unsafe, performance-breaking, or architecturally incompatible choice turns into shipped code or a post-merge cleanup.

Captured:

• Architectural decisions made during AI coding sessions
• The rationale and rejected alternatives for each decision
• Which files were in scope when the decision was made
• Session metadata (timestamp, confidence score)

Not captured:

• Your actual code or file contents
• Passwords, tokens, or secrets
• Personal information
• Anything outside of conversation turns with your AI agent

Does code leave your machine?

In self-hosted mode: no. Conversation turns are processed by your local Perception API running in Docker and stored in your local Postgres instance. Nothing is sent to Rory Plans or any external service.

When using Rory Plans cloud: conversation turns are sent to Rory Plans’ hosted Perception API for extraction. The extracted decision object is stored on Rory Plans infrastructure. Raw conversation text is not retained after extraction.

Why are there two API keys in self-hosted mode?

RoBrain uses Anthropic (Haiku) for decision extraction/classification and a separate embeddings provider (openai, voyage, or cohere) for semantic vector search. That is why you may see both ANTHROPIC_API_KEY and an embedding key in setup.

Cheapest recommended combo: ANTHROPIC_API_KEY (Haiku) + EMBEDDING_PROVIDER=openai with OPENAI_API_KEY (text-embedding-3-small).

How RoBrain compares

After you’ve seen the loop, you may want to know how RoBrain fits the broader landscape of AI memory tools. The short version:

• Claude Code Auto-Memory captures per-user, per-machine. Bob’s machine has no idea what Alice’s machine learned.
• Mem0 stores facts and resolves contradictions at the moment of insertion. It doesn’t periodically scan the whole corpus for contradictions that emerge later.
• Cloudflare Agent Memory offers shared team memory profiles but runs as a managed service on Cloudflare’s infrastructure.
• RoBrain captures decisions + rejected alternatives as structured data in your Postgres, runs a scheduled scan over the whole corpus to catch contradictions, and keeps both sides queryable when decisions change.

See RoBrain vs Claude Code Auto Memory and Comparisons for the detailed breakdown.

How memory gets back into your next session

There are two retrieval paths, and the automatic one is the default:

• Automatic, cross-tool via the always-on summary. At session start, Sensing fetches the project’s always-on summary from Perception, so the next session begins with approved decisions already in context. That is how Alice can make a decision in Cursor and Bob can open Claude Code later with the same decision already loaded.

For Claude Code specifically, npx robrain export-memory can also project approved decisions into Claude auto-memory files, and Synthesis can refresh that export after compiled_truth updates.

• On-demand semantic pull via npx robrain inject. Use this when you want context for a specific topic, file, or stale decision that does not belong in the always-loaded summary. This is the manual paste path in Free / self-hosted mode; Rory Plans cloud automates that targeted retrieval step at task boundaries via Control.

Why isn’t retrieval just another MCP tool? You usually don’t need to run anything. The always-on summary loads automatically at session start. inject is for the cases where you want something narrower than that default block. In Rory Plans cloud, Control automates that second path at task boundaries.

Reference: export-memory vs always-on summary vs Synthesis

What ships today

The launch story is what you can run now (Free / self-hosted and CLI), not roadmap vapor:

• Systematic passive capture — Sensing records turns; Perception extracts decisions without the agent deciding what to remember.
• rejected[] as structured, queryable data — vetoes are first-class fields in Postgres, not prose buried in markdown.
• Decision lifecycle — active vs superseded rows, linked history, and review flows so memory can stay honest over time.
• Team-shared store — Postgres as the source of truth across machines and editors (with MCP on Claude Code, Cursor, Copilot-capable setups).
• Automatic session-start recall — Sensing fetches the always-on summary so approved decisions can follow the next session automatically, including cross-tool handoffs like Cursor on Tuesday → Claude Code on Wednesday.
• npx robrain inject for focused retrieval — semantic or file-scoped context when the always-on summary is not enough for the task in front of you.
• npx robrain explain <file> — file-scoped “why does this exist?” from stored decisions.
• Conflict visibility — decisions can be flagged for contradiction; robrain review resolves them in Free / self-hosted mode. Rory Plans cloud adds proactive warnings at task boundaries (see Free / self-hosted vs Rory Plans cloud).

That combination already goes beyond most “agent memory” products that stop at capture or grep.

Install and usage

You install one thing — the Sensing MCP — and run one Docker command. That’s the whole setup.

Quick start — self-hosted

From a fresh clone, copy .env.example to .env, add your ANTHROPIC_API_KEY plus one embedding-provider key, then run:

bash pnpm install && pnpm build pnpm docker:up

These first three commands run once from the robrain clone.

bash npm install -g robrain npx robrain install --self-hosted --repo-root "$(pwd)"

These commands install the Robrain package and then set-up everything so Robrain can run.

bash cd /path/to/your/project && npx robrain init-project

The last command runs once per application repo.

Install details

pnpm docker:up brings up Postgres + Perception in the background; the user-facing surfaces are Sensing and the robrain CLI.

npx robrain init-project writes the project instructions that tell Claude Code to call the Sensing tools at session start and end.

Self-hosted setup usually needs two keys: ANTHROPIC_API_KEY for extraction and one embedding-provider key for semantic retrieval. If that surprises you, see Why are there two API keys in self-hosted mode?.

Prerequisites

• Docker + Docker Compose
• Node.js 18.18+ (older 18.x + npm 9.6 can break npx bin permissions; upgrade Node or use pnpm dlx robrain), pnpm
• Anthropic API key (for Haiku extraction)
• OpenAI, Voyage, or Cohere API key (for embeddings)

Repo setup and .env

From the repository root:

bash git clone https://github.com/adelinamart/robrain cd robrain cp .env.example .env

Edit .env at the repo root (the same keys power Perception in Docker and the CLI install prompts). Paste real keys from Anthropic (https://console.anthropic.com) and your embedding provider — do not commit that file.

ANTHROPIC_API_KEY= EMBEDDING_PROVIDER=openai OPENAI_API_KEY=

Keep EMBEDDING_PROVIDER identical between this file and what you select when running install (or set EMBEDDING_PROVIDER in .env and install will pick it up without prompting).

What init-project writes

robrain init-project writes mode-aware instructions:

• Free / self-hosted (robrain install --self-hosted): generated CLAUDE.md / Cursor rule uses only sensing_* tools.
• Cloud / Control-enabled: generated instructions include both sensing_* and control_* calls.

CLI on your PATH (optional)

If you prefer not to use npx every time, install the package globally, then use the robrain command directly:

bash npm install -g robrain

Open a new terminal, or in zsh run rehash so your shell picks up the new binary. Then:

``bash
robrain install –self-hosted

…and the same for other commands: robrain init-project, robrain review, etc.

``

If you get command not found: robrain, either use npx robrain ... or ensure your global npm bin directory is on your PATH (see npm prefix -g).

Cursor-specific setup (most reliable path)

robrain init-project automatically writes .cursor/rules/robrain.mdc with alwaysApply: true, so Cursor loads the RoBrain session-lifecycle instructions every session. No copy-paste step is required.

To verify:

bash cat .cursor/rules/robrain.mdc

If decisions stop landing: the rule file is present, but Cursor’s agent sometimes ignores rule content turn-to-turn. Check the Cursor MCP panel for the robrain-sensing server status, then see Decisions captured in the editor but robrain review shows nothing. Adding more rules will not fix a compliance gap. That is a Cursor-side behavior that Rory Plans cloud layers additional safeguards against (see Free / self-hosted vs Rory Plans cloud).

Synthesis

Synthesis does not create or capture anything new. It only reads what is already in the decisions table (plus sessions for project_id) and writes derived artefacts — mainly planning_blocks, conflict_flag / decision_relations, and logs. The reactive pipeline (Sensing → Perception) still owns every new decision row.

The gap Synthesis fills

Sensing and Perception are reactive: a session runs, one decision is extracted and written, done. Each write is considered in isolation. Nothing in that path ever reads the whole corpus after six months of work. So you can end up with hundreds of rows nobody has read as a single picture: contradictions accumulate, the team’s stance on testing shifts across sessions, Redux shows up fifteen times as a rejected alternative without any one place that answers “what role does Redux play here?” — and none of that surfaces unless someone goes looking by hand.

Synthesis is the job that looks at the full table.

Three passes at a glance

Synthesis is a batch job that runs three passes over the