智能工作流

Install and usage

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

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:

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

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

Stale Perception Docker image (migrations / schema out of sync)

If you pulled new code but did not rebuild the perception service, the container may still run an older Perception binary than packages/perception-self-hosted on disk. Then startup migrations (for example reviewed_at on decisions) never run, robrain review approval can fail against the DB the CLI is using, and features that assume the new schema break in confusing ways.

From the repo root (same directory as .env and docker/docker-compose.yml):

pnpm docker:up:build

That runs prepare-env and docker compose … up -d --build perception — rebuilds the Perception image and recreates the container.

To build only, then start Perception yourself:

pnpm docker:build
docker compose -f docker/docker-compose.yml --env-file .env up -d perception

If Docker reused layers and you still see old behavior, force a clean rebuild (no pnpm shortcut for --no-cache yet):

docker compose -f docker/docker-compose.yml --env-file .env build --no-cache perception
docker compose -f docker/docker-compose.yml --env-file .env up -d perception

Sanity check:

curl -sf "http://localhost:${PERCEPTION_PORT:-3001}/health"

After shared types change (packages/shared): downstream packages read @robrain/shared types from dist/. From repo root run pnpm --filter @robrain/shared build (or pnpm -r build) before relying on pnpm typecheck or publishing — otherwise packages/*/dist/*.d.ts can lag packages/shared/src.

Verify the running container matches your checkout: tail Perception logs while exercising capture — you should see current behavior (for example embedding dedupe logs as POST /signals deduped with matched decision text when a near-duplicate is skipped):

docker compose -f docker/docker-compose.yml logs -f --tail=80 perception

Note: A brand-new Postgres volume applies packages/shared/schema.sql on first boot. Existing volumes rely on Perception’s idempotent startup migrations when you run an up-to-date image — so after upgrading, rebuild and restart perception once.

---

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:

pnpm install && pnpm build
pnpm docker:up

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

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

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

CLI commands

All commands accept --help for full flag details. Repo-level pnpm scripts live in package.json; CLI commands live in packages/cli.

Or via Perception API (Authorization required)

curl -s -H "Authorization: Bearer <PERCEPTION_API_KEY>" \ "http://localhost:3001/decisions?project_id=<project_id>&history=true&limit=20" ```

Reference

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.

Free / self-hosted vs Rory Plans cloud

Comparisons

RoBrain vs Claude Code Auto Memory

Claude Code Auto memory is Anthropic’s native persistence: Claude writes notes as it works into machine-local markdown under ~/.claude/projects/…/memory/ (official docs). Roughly the first ~200 lines or 25 KB of MEMORY.md loads every session; deeper notes live in topic files Claude reads on demand with normal file tooling. It ships with Claude Code v2.1.59+ and needs no Docker or Postgres. That makes it the closest competitor to RoBrain’s “capture things without writing MEMORY.md yourself” story — but the shape of the data differs.

When Auto memory is enough: solo dev, single editor (Claude Code), repo younger than ~6 months, and you’re fine curating markdown when notes drift.

When RoBrain is worth the overhead: you need vetoes and file-level provenance as data, semantic recall across months of history, invalidation when decisions reverse, multiple editors, or a shared / auditable store.

The two can coexist: Auto memory for lightweight scratch notes; RoBrain for canonical decisions you want to query, explain, and review.

RoBrain vs Zep

RoBrain and Zep answer different questions and work well together.

RoBrain captures architectural decisions — what was chosen, why, and what was explicitly ruled out as a structured queryable field. It answers: "what did we decide about this module, and what did we reject?"

Zep / Graphiti captures conversation history and entity relationships — it stores sessions, extracts facts, builds a temporal knowledge graph, and supports semantic retrieval across all of it. Zep can implicitly capture decisions too — the difference is that RoBrain surfaces rejected alternatives as a structured rejected[] field you can query directly, whereas in Zep they would live in conversation prose. For relationship queries — "how does the auth module connect to everything else?" — Zep's multi-strategy retrieval (semantic + graph traversal + BM25) is particularly strong.

A combined setup:

```bash

Troubleshooting

After setup, Sensing runs automatically whenever Claude Code is open. The MCP server is registered in ~/.claude/mcp.json, so Claude Code starts it automatically on launch. The CLAUDE.md instructions tell Claude to call sensing_start_session at the beginning of each session and sensing_record_turn after every exchange.

The one thing that can break it:

Claude Code doesn't always follow CLAUDE.md instructions reliably — this is the compliance problem from pre-launch testing. If Claude stops calling sensing_record_turn, Sensing goes silent. The way to check:

npx robrain status

That prints Perception connectivity and a Decisions: count for the current project (from GET /projects). If Decisions: 0 after a session where you expected captures, Claude may not have called the Sensing tools, or Perception rejected writes — run npx robrain review to confirm what is stored. The fix is often to make CLAUDE.md more explicit or remind Claude: "follow the RoBrain instructions in CLAUDE.md."

The practical reality:

The developer needs two habits: - npx robrain review after sessions where important decisions were made - npx robrain inject --copy before starting a new task that builds on prior work

Everything else — capture, extraction, storage, embedding — happens without you doing anything.