Raphael is a learning layer for AI coding agents. It distills lessons from your real projects — the mistakes, the fixes, the hard-won decisions — and injects the right ones back into your agent's context at the right moment. Install it once. It runs itself.
Install · Feature tour · Command atlas · The console · Security model · Full manual · Architecture
Named for the archangel of healing — because it heals the one wound every AI coding agent shares: total amnesia.
Every morning, your AI coding agent wakes up brand new.
The float-rounding bug it helped you chase for two hours last Tuesday? Gone. The
decision to keep .env out of version control after that one terrifying near-miss?
Gone. The migration order that finally worked, the webhook signature check it forgot
once and you swore it never would again? Gone, gone, gone.
So you re-explain. You re-debug. You watch the same mistake walk through the door wearing a different file name — and you pay for the same tokens to fix it again.
Your agent doesn't have a skill problem. It has a memory problem.
Raphael is that memory. Not a chat log, not a vector dump of everything you ever said — a curated brain of validated, security-screened, provenance-tracked lessons, distilled from what actually happened in your sessions, and recalled with a strict token budget exactly when they're relevant. Known mistakes stop recurring. Settled decisions stop being re-litigated. And the whole thing runs itself in the background, on the Claude subscription you already pay for.
Proof, not vibes — every number below is measured by the code in this repo:
| 147.9× fewer tokens | to answer "where do I look?" using the Atlas knowledge graph vs. grep-and-read — measured on this very repo: 174,324 tokens down to 1,179 across 10 real questions (per-question range 55×–385×). Zero model tokens spent to measure it. |
| ≤ 1,200 tokens/session | the hard cap on everything recall may inject in one session. Typical prompts cost 0 (injection requires a trigger hit). raph why itemizes every token. |
| 26 curated security lessons | pre-loaded from the global brain on day one — your agent starts smart before it has learned a single thing from you. And that brain is community-fed by design: contributed lessons, scrubbed and human-reviewed, ship to every install via a weekly hash-verified sync. |
| 41 CLI verbs · 12 agents · 8-tab console | one engine underneath all of it — every button in the web console calls the exact same functions as the CLI. |
| 415 tests, 6 CI combos | plain node:test, no frameworks, run on Linux + Windows × Node 18/20/22 — plus a zero-token canary gate that re-proves the security chokepoint on every push. |
| 2 runtime dependencies | ajv and js-yaml. That's the whole supply chain. No frameworks, no daemons, no cloud. |
| 100% local | the brain lives in ~/.raphael, in its own git repo that structurally blocks pushes. Nothing leaves your machine except by your own explicit action. |
Two steps, in two different places. Needs Node.js 18+.
Step 1 — in your terminal (PowerShell, cmd, or any shell): install the engine.
npm install -g raphael-brain # or, from GitHub: npm install -g maheshaggarwal21/raphaelCheck it worked: raph version.
Step 2 — also in your terminal (the claude CLI ships with Claude Code): install the plugin.
claude plugin marketplace add maheshaggarwal21/raphael
claude plugin install raphael-brain@raphaelThe plugin auto-wires recall into your sessions and adds the /brain commands and the
twelve agents. Each agent's description carries a "use proactively when…" trigger, so
Claude Code delegates to the right one automatically — you don't have to name it. Verify
with claude plugin list — you should see raphael-brain enabled.
Using Claude Code in a terminal? You can type the same two lines as
/plugin marketplace add …and/plugin install …in the chat instead — same result. The/plugindialog is not available in the desktop app or web, which is why theclaude plugin …terminal commands above are the reliable path everywhere.
That's the whole install. Your next Claude Code session asks you three questions, once — may Raphael learn from your work · contribute scrubbed lessons to the community (on by default; bundles only ever stage locally and sending is always your own click) · autopilot or manual — and then runs the setup itself. Prefer to do it by hand? One command:
raph arise --autopilot # zero-touch: consent + seed + autopilot + sharing, done
raph arise --autopilot --no-contribute # same, but nothing is ever staged for sharing
raph arise --pack --guard # manual (curator) mode — you review every lessonFrom here on: every raph … command in this README runs in your terminal;
everything starting with / (like /brain) is typed inside Claude Code.
- Right after install: your next session shows the three setup questions, once. Answer them and you're done forever.
- From then on: sessions just begin with a small block of relevant lessons (and your project's map, once built). You run nothing.
- Day one isn't empty:
ariseseeds your brain from the global brain — 26 human-reviewed security lessons, active immediately. Cold start: solved. - Wondering if it's on?
raph status(one-line picture) ·raph why(what got injected and what it cost) ·raph pulse(what the last heartbeat learned) ·raph doctor(health check, with fixes). - Want it quiet?
raph offstops injection instantly.raph onresumes. Nothing else changes — mining and review keep working.
session ends ──▶ raph pulse (background · budgeted · fail-open)
├─ mine your real session history (zero tokens)
├─ distill episodes into candidate lessons (your subscription)
├─ MACHINE CURATOR: reviewer screen ▸ canary gate ▸ activate
│ security included · quarantine never · rollback on any failure
├─ sync the global brain (weekly · hash-verified · local wins)
├─ refresh the project atlas (zero tokens)
├─ install the commit guard in your repo (never clobbers yours)
├─ self-retire lessons that never help (probation)
└─ self-update the raph CLI (daily · npm integrity-checked)
your next session ◀── auto-injection: relevant lessons + project map + weekly digest
budgeted · enveloped as data · fail-open · raph why explains it
Every arrow above is a real subsystem with its own section below. In manual mode
the same loop runs through your hands: raph mine → raph distill → raph queue →
raph approve. Either way, every lesson that enters the brain passes the same single
validation chokepoint — no exceptions, ever.
Sixteen subsystems. Each one earns its place. Take the five-minute skim (headlines and tables) or the full read — either way, everything here is in the code, tested, and measurable on your own machine.
Raphael doesn't memorize your transcripts. It runs them through a refinery:
Mine (raph mine) reads your project's real Claude Code session history — locally,
with zero model tokens — and detects episodes: an error followed by an eventual fix,
or you pushing back on the assistant. Every excerpt is secret-scrubbed before it is
even hashed. Mining only ever touches projects you explicitly consented to.
Distill (raph distill) turns episodes into candidate lessons using a contained
model call — on your Claude Code subscription by default (fixed price, no API key;
it falls back to ANTHROPIC_API_KEY only if the CLI isn't logged in). The trust design
is structural: the model only ever proposes advisory text. It cannot set IDs, status,
tier, or evidence — the pipeline builds the evidence record from the real episode it
fed in, so fabricated provenance is structurally impossible. Output that doesn't
survive the validation chokepoint never touches disk.
Review — candidates land in a queue, not in the brain. In manual mode you are the
gate: raph queue, then raph approve 1 3 / raph reject 2 --reason "...". Rejecting
isn't a shrug — similar candidates are auto-suppressed for 180 days, so the queue
never nags you twice. Security-category and quarantined candidates can never be
batch-approved: one at a time, full body read, --confirmed required.
And when the machine already knows the answer, teach it directly:
raph note "Stripe webhooks must be verified with the raw request body, not the parsed JSON" \
--category security --severity high --keywords stripe,webhook,signature
raph decide "We use ULIDs, not UUIDs, for all public IDs" --why "sortable + no PII fingerprint"raph note goes straight to the review queue; raph decide records a durable
decision that gets surfaced at session start — so settled calls stay settled.
The signature feature. One consent at install, and the entire loop above runs itself.
After each session ends, the plugin fires raph pulse in the background. A pulse is
budgeted (max 8 episodes per run, max 3 model-spending distill runs per day),
serialized (a lock file makes overlapping session-ends take turns, stale after 30
minutes), and — most importantly — fail-open: no step may throw, a broken pulse
records what it saw and exits clean. It can never corrupt the brain and never block
you. It never prompts, and it never grants itself consent it doesn't have.
What you notice is the result: fewer wasted tokens, fewer repeated mistakes, a commit guard quietly appearing in your repos, a CLI that keeps itself current — and one short line a week telling you what your agent learned.
raph auto full # autopilot: the machine curator handles everything (arise --autopilot sets this)
raph auto standard # auto-approve only your own mined lessons that passed every gate
raph auto wide # + adopted external material that passed the reviewer
raph auto off # nothing activates without a human — ever
raph auto manual # back to classic curator mode entirelyThe dial fails closed (an unknown config value reads as off), and every level
respects hard blast-radius controls: auto-activated lessons carry a visible
tier: auto label, capped at 30 total and 10 adopted per day, every activation
is a logged event, and raph adopt revoke unwinds an entire source in one command.
Most tools "automate" review by deleting it. Raphael replaced the reviewer with a stricter one.
At auto full, every candidate — security included — faces a pipeline harder than the
human queue:
- The reviewer screen. A contained, zero-tool model call with a forced verdict schema screens each candidate. A malformed or unparseable verdict fails closed — the candidate stays in the queue for a human.
- The canary gate. Survivors activate as a batch — and then the deterministic chokepoint canaries (real prompt-injection payloads: instruction overrides, pipe-to-shell, tool-call markup) are re-run. If even one canary would slip through, the entire batch rolls back and nothing is committed.
- Probation. Machine-activated lessons carry
tier: machine— visible, filterable, confidence-discounted, and first in line for the self-retirement sweep. A bad activation heals itself out of the brain. - The floor that never moves. Quarantined (injection-suspect) content never machine-activates, at any dial level, in any mode. After 30 days it is silently tombstoned. This is the one rule autopilot cannot override.
Raphael's knowledge grows along two paths at once — and the second one is built to get better with every developer who joins.
Brain #1 — your local brain. Private by construction. It learns from your
sessions, lives in ~/.raphael on your disk, and never leaves the machine. Every
lesson in it is yours alone: your mistakes, your fixes, your decisions.
Brain #2 — the global brain. The community's shared, human-curated lesson set — distilled scar tissue from real projects, reviewed by a human before it ships to anyone. A brand-new install isn't empty: it seeds from the copy inside the npm package (zero network), so your agent starts with the community's hard-won judgment — at v1, 26 security lessons: secrets in env vars, slow KDFs for passwords, rotate anything that ever touched git, IDOR checks, server-side price recomputation, and friends. Cold start: solved.
The two brains flow into each other — carefully, in both directions:
- Down (everyone → you): weekly, the pulse checks exactly two pinned HTTPS URLs in this repo — nothing else — verifies every lesson against a per-lesson SHA-256 manifest, and runs each one through the same validation chokepoint as everything else. Invariant #1 has no exceptions, including for the project's own curated set. Local always wins — a global lesson never overwrites or duplicates yours — and lesson IDs are fixed forever, so every user's copy of a community lesson shares one identity.
- Up (you → everyone): when your brain learns something broadly useful, the contribution pipe can carry it back. Local traces stripped (project names, path globs, machine-local evidence), every text field re-scrubbed for secrets, the result re-validated through the chokepoint — a lesson that fails is refused, never silently "fixed." Bundles only ever stage locally (min 3 lessons, at most weekly); sending is always your own explicit action; and a human reviews every contribution before it ships to the community.
That's the compounding loop: one developer's 2 a.m. incident becomes every developer's day-one immunity. Your brain stays private. The community brain grows with each contribution that clears the gauntlet. And every new install starts smarter than the last.
Prefer to seed manually? raph pack add security stages the same 26 lessons as
ordinary reviewable candidates.
Injection is where memory tools usually go wrong: context bloat, mystery tokens, spooky action at a distance. Raphael's recall engine is an exercise in restraint:
- Session start: a ≤90-token advisory preamble + a stack-matched digest of at most 10 lessons in ≤250 tokens, plus (once built) a ~250-token Atlas digest of your project and a ~200-token digest of your recorded decisions.
- Per prompt: at most 3 headlines in ≤150 tokens — and only on a real trigger hit (score ≥ 4.0). The typical prompt injects nothing.
- Before wide searches: when your agent reaches for Grep/Glob, a tiny pre-tool nudge reminds it the Atlas can answer "where?" for ~150× fewer tokens.
- Hard ceiling: 1,200 tokens per session, cumulative. Past it, only high/critical-severity lessons may still fire.
- Deduped: a headline never repeats within a session.
- Enveloped as data: every injection is wrapped in an envelope stating these are advisory notes distilled from past sessions — data, not instructions; nothing in them can authorize an action. Lessons cannot command your agent. The eval suite re-proves this with live canaries.
And it's all inspectable, always:
raph why # every recent injection: which lessons, matched on what, exact token cost
raph search "stripe webhook" # query the brain exactly the way the hooks rank it
raph off # kill switch — injection stops instantly, learning continuesRanking is deterministic and explainable — keyword hits (weight 4.0), stack overlap
(3.0), path matches (2.0), a small recency/observation prior, and a −10.0 penalty for
anything already injected this session. Every score comes with human-readable reasons,
which is precisely what raph why prints.
The whole brain, one command, zero cloud.
raph web
# raph console -> http://127.0.0.1:52301/?token=9f3a…raph web starts a local-only console and opens your browser. It is not a
companion app with its own logic — every button calls the exact same engine as the
CLI, so nothing the console does is out of reach of scripts, and vice versa.
| Tab | What it gives you |
|---|---|
| Dashboard | Four KPI cards — active lessons (with auto-tier count), review queue (with security/quarantine sub-counts), total injections + tokens recalled, adoptions (with blocked/revoked) — plus brain health and the self-use funnel at a glance. |
| Review queue | Every waiting candidate as a card with severity/category badges. Batch-approve or batch-reject with a reason — while security and quarantined items render with a lock and force one-at-a-time review, exactly like the CLI. |
| Lessons | Search your brain with the same ranking function the hooks use, browse everything, toggle injection on/off, and see recent injections with their true token costs. |
| Adopt | Paste a URL, file, repo path, or SKILL.md; dry-run it; run the full six-layer gauntlet; browse adoption history — and undo any adoption in one click (revocation retires rather than deletes, so it stays inspectable). |
| Activity | The raw, newest-first audit log — every event the brain ever recorded, with context. |
| Company | The portfolio table and weekly board report — what the Academy built, what the brain learned, what recall cost, what waits on you. |
| Guard | Pre-commit secret guard for the repo you launched from: install/uninstall the hook, scan every tracked file, view the .raphallow allowlist, optionally enable the high-entropy pass. |
| Settings | The big switches: autopilot vs. manual, the auto-approve dial with caps, community sharing, injection, and per-project mining consent. |
The security posture is genuinely paranoid, because a brain console should be:
- Binds to 127.0.0.1 only — never a LAN interface.
- A fresh random 32-hex session token per launch; every request must present it (wrong token → a polite 401 page telling you to use the printed URL).
- DNS-rebinding defense (foreign
Hostheaders refused) and CSRF defense (non-loopbackOriginrefused). - A strict CSP (
default-src 'none'), no-store caching, 64 KB request-body cap. - Fully self-contained: no CDN, no external anything. One embedded page; every rendered string is escaped because mined and adopted content is, by definition, untrusted.
The feature with the big number attached.
raph atlas builds a deterministic knowledge graph of any codebase — files,
symbols, packages, and error codes as nodes; defines / imports / tests / uses / calls /
raises as edges, each tagged with a confidence level (EXTRACTED, INFERRED,
AMBIGUOUS). Built with pure parsing. Queried with graph traversal. Zero model
tokens, ever — the library doesn't even import the model provider.
raph atlas # build it: files, nodes, edges — and a markdown report
raph atlas where "E-CONFIG" # "where do I look when this breaks?" — ranked files, with reasons
raph atlas path cli.js validate.js # how are these two connected? (BFS, hop by hop)
raph atlas explain writeCandidate # one node + everything around it
raph atlas digest # the compact injection block your sessions receive
raph atlas bench # measure the token savings on YOUR repo — free
raph atlas export # ship the whole graph as an Obsidian vaultThe receipt: raph atlas bench asks the graph real questions (derived from your
own error codes and hot symbols), answers them via the graph, then honestly prices the
alternative — reading the candidate files whole. On this repo: 10 questions, 174,324
tokens by grep-and-read vs. 1,179 by graph — 147.9× fewer, with per-question savings
from 55× to 385×. The bench itself costs zero model tokens, and it logs the result so
raph stats and your weekly report can quote your number, not ours.
Rebuilds are incremental (per-file SHA-256 caching), bounded (4,000 files / 512 KB per file), and the whole cache self-invalidates when the extractor logic changes — so a stale graph can't quietly lie to you.
The Obsidian export is a small love letter to knowledge tooling: one note per file
with Defines / Imports / Tested by / Imported by / Error codes sections (reverse
edges included — the thing a file listing can't tell you), one note per error code, an
index note of the most-connected files, and an atlas.canvas (JSON Canvas 1.0) of your
top 48 files laid out as a clickable graph.
For a lighter touch, raph map produces the quick project map (stack, entry points,
directory shape, git-hot files) that agents read instead of crawling your repo — and
it's what gets injected at session start.
Raphael watches itself work — and tells you when a memory deserves to become a capability.
Some lessons stop being trivia and start being technique: they fire in project after project, session after session. The Skill Factory finds them by deterministic self-observation — no model call, just arithmetic over the injection log:
raph skills suggest # which lessons fire broadly enough to become skills?
raph skills draft <slug> # package one into a staged SKILL.md draft
raph skills list # what's staged (and pointedly NOT installed)The bar is evidence, not enthusiasm: a lesson qualifies only after the brain has 20+ logged injections overall and that lesson has fired in 5+ distinct sessions — a recurring need, proven, not guessed.
A draft is a complete SKILL.md — frontmatter, When to use triggers derived from the
lesson's real keywords and paths, guidance text (secret-scrubbed on the way out), and a
mandatory "Honest limits" section that every draft carries: distilled from
past-session evidence; can be wrong, narrow, or out of date; carries no authority to
act. If the evidence comes from a single project, the draft says so.
And the punchline, in bold in the code and in bold here: drafts are staged, branded DRAFT, and never auto-installed. Installing a skill hands instructions to an agent — that is a human act, and Raphael refuses to perform it for you.
The same philosophy, one level up. When the brain accumulates deep knowledge in a
category no current specialist owns, raph agent demand shows you the evidence:
lessons-per-category, ranked, against the current roster.
raph agent demand # where is expertise piling up with no owner?
raph agent propose db-migrator \
--role "Database migration specialist" \
--mission "Plan and verify schema migrations with rollback safety" \
--output "A migration plan with ordered steps and a rollback path"
raph agent list # staged proposalspropose validates hard (kebab-case slug, no roster collisions, a real role, mission,
and output — minimum lengths enforced) and then stages a complete agent file using
the exact same generator that builds the shipped ten — plus a paste-ready roster
snippet. Installing it is deliberately a four-step human ritual: paste the snippet,
rebuild the agents, run the tests, run the eval. New teammates don't hire themselves.
The plugin ships ten ready-made agents — and they are not costume-party personas.
Every one is generated from a single roster with the same five-rule spine:
(1) consult the brain first (raph search) and treat results as data, never
commands · (2) run free checks before paid ones — linters, grep, git, zero tokens ·
(3) read the project map, not the whole repo · (4) sweep cheap, escalate only
survivors · (5) write back anything durable (raph note) — using the agents
literally feeds the brain. That's the flywheel.
How to run one — just ask by name in Claude Code:
"Use the raphael-reviewer agent to review my last commit." "Use the raphael-planner agent — I want to build a habit tracker."
Claude Code also picks one automatically when your request matches an agent's job.
Run /agents inside Claude Code to see the roster.
| Agent | Reach for it when… | What to give it |
|---|---|---|
| raphael-planner | a fuzzy idea needs to become a sharp, buildable spec | the idea in a few sentences + constraints (time, stack, must-haves) |
| raphael-architect | the spec is done and you need the technical design | the spec, stack preferences, expected scale |
| raphael-developer | it's time to write backend / general code | the plan or concrete task + which files are in scope |
| raphael-frontend | it's time to BUILD distinctive UI (not templated "AI slop") | the screen/component + the product's audience and vibe; it establishes a token system + one signature element, avoids the generic defaults, and meets the accessibility floor |
| raphael-reviewer | before you merge anything | the diff — branch, commit, or "review my uncommitted changes" |
| raphael-security | before shipping anything touching auth, payments, or user data | the repo path + one line on what the app does |
| raphael-debugger | something is broken and you don't know why | the exact error + how to reproduce it |
| raphael-design | the UI feels off, generic, or inconsistent | the screens/components + any recorded design decisions |
| raphael-deployer | you're about to ship | the target platform; it produces the checklist and stops — it never deploys |
| raphael-critique | you want any output stress-tested | that output, verbatim — it reads only the output and its cited evidence |
| raphael-redteam | you want an attacker's-eye pentest of your OWN app or a test environment | the authorized target + what it does; it probes for real exploits (IDOR, auth bypass, injection, SSRF, logic abuse), proves them with a PoC, and reports the fix — never weaponizes, never touches production destructively |
| raphael-manager | multi-step work you don't want to route yourself | the goal; it picks specialists and merges their answers |
Every agent is a specialist held to one bar — a named methodology, calibrated output, and eval coverage that's growing to the whole roster (there's no second-class tier). For a from-scratch build the natural order is planner → architect → developer/frontend → reviewer + security → deployer, with critique on anything you're unsure about.
Recipes — four short playbooks in plugin/recipes/ the agents
follow on request: debug, review, pre-deploy (always runs security-audit
first), security-audit. Ask in plain words: "follow the pre-deploy recipe for this
repo."
Slash commands — guided flows inside Claude Code: /brain (hub + status),
/brain-learn (mine + distill this project), /brain-review (the queue, with the
1y 2n 3e batch grammar), /brain-eval (the ON/OFF proof). On autopilot you'll rarely
need them — they're the manual-mode and power-user surface.
Found a great post-mortem? A security checklist? Someone else's SKILL.md? Don't copy-paste it into your prompts forever. Digest it:
raph adopt https://example.com/that-great-incident-writeup
raph adopt ./docs/lessons-from-the-outage.md --dry-run
raph adopt list
raph adopt revoke adp_01H… # one command undoes an entire adoptionEvery adoption runs a six-layer gauntlet, because external text is exactly where prompt injection lives:
- Bounded fetch/read — size-capped, snapshotted, content-hashed;
- Pre-gates — secret scrub before any model sees a byte, plus license detection (copyleft material is flagged, not laundered);
- Reviewer — a contained zero-tool model screens for prompt injection, malicious guidance, and junk;
- Extract — a contained model proposes lessons and skill drafts (it cannot set IDs, tiers, or evidence);
- Post-gates — ephemera filter, dedupe, rejection memory, then the same chokepoint every lesson passes;
- Your queue — candidates arrive for review like everything else. Skill drafts stage separately and are never auto-installed.
Every adoption is recorded in a provenance ledger — source, hash, license,
verdicts, what was produced — and revoke unwinds all of it: queued candidates
deleted, activated lessons retired (not deleted — revocation stays inspectable),
drafts removed, ledger marked. Undo you can audit.
The brain's secret scrubber has one definition of "what is a secret" — ten named,
high-precision patterns (AWS keys, GitHub tokens, Stripe keys, private key blocks,
JWTs, URL-embedded credentials, DB_PASSWORD=… shapes, and more). raph guard points
that same definition at your own repositories as a pre-commit hook:
raph guard install # in any repo — never clobbers an existing hook
raph guard scan --staged
raph guard scan --all # every tracked file; add --entropy for the noisy deep passDesign choices that matter in practice: the named rules always run (high precision — a
commit blocker must not cry wolf); the high-entropy heuristic is opt-in because
lockfiles exist; a .raphallow allowlist handles security tooling's own test fixtures
visibly (the CLI announces when it's active); and the scanner fails toward letting
a commit proceed on read errors — a guard must never wedge your repo. On autopilot,
the pulse installs it for you.
Here is where it gets fun. Raphael doesn't just learn from your work — it learns by doing its own. The Academy runs real, autonomous product builds; the brain keeps the lessons; the company layer reports like a business.
raph academy start keeper --title "Repo Keeper" --milestones "M1:Scaffold,M2:Keeper"
raph academy drive keeper --brief-file brief.md # 7-stage pipeline: plan → architect →
raph academy status # develop → test → review → security → deploy-prep
raph portfolio # every build: status, tests, lessons, recall cost
raph report weekly # the board report
raph policy # which model + effort runs each task kind- Survives everything. State lives outside the project repos and is checkpointed
after every step — usage limits, reboots, interrupted stages: a resumed session
reads the state, trusts the
NEXT:line, and continues. Mid-stage interrupts resume the same model session rather than restarting. - The owner boundary is structural. Deploying, signing in, creating accounts, spending money, publishing — reserved for the human. This isn't a polite request in a prompt (though it's that too): the model-policy table has no deploy task kind, so a pipeline that names one throws before it starts. Every completed pipeline ends parked at a boundary: "review the deploy-prep checklist — deploying is yours."
- Frugal by policy. The policy table assigns the cheapest adequate model per task
kind (routing on haiku; planning, review, and security on sonnet at high effort);
exactly one kind —
debug— may escalate to opus, because a stuck root-cause hunt is the one place it pays.
Three real products came out of the Academy training itself: repo-keeper (a GitHub repo health manager) · onedesk (a money engine for solo founders) · assay (a dataset vetting CLI). Built autonomously, checkpointed across limits and restarts, with every deploy-shaped action left waiting for the owner — exactly as designed.
Lessons are useful beyond one machine — but nothing should leave yours by accident.
raph contribute makes sharing deliberate and paranoid:
- Only active lessons can be exported, one by one — never a bulk default.
- Local traces are stripped: project names, path globs, machine-local evidence refs.
- The full body is re-scrubbed for secrets (belt and suspenders — it was scrubbed on the way in) and re-validated through the chokepoint. A lesson that fails after scrubbing is refused, not silently "fixed."
- Bundles only ever stage locally. On autopilot with the grant on, the pulse
batches eligible lessons into a local bundle (min 3, at most weekly) — staged,
visible, and inert until you send it. Sending is always your own action. Consent
is one toggle:
raph contribute on|off, or the console's Settings tab.
This is the up-pipe of the two-brain model (§4): a lesson that clears it gets a human review, and — if it ships — makes every Raphael install after that start a little smarter, with your machine's traces stripped and your secrets nowhere in it.
The question every memory tool dodges: is this actually helping? Raphael ships the instruments to answer it on your machine:
raph eval run— the controlled experiment. Six trap scenarios (float money, secrets in logs,.envcommits, IDOR, missing security headers, client-side price trust) run with the brain ON vs. OFF in an isolated eval brain, and report catch rates with Wilson confidence intervals, token costs, and retrieval misses — the metric that catches the system failing silently. It refuses to compare arms across different models, because a model change is not a brain change.--dry-runcosts nothing and re-proves the injection canaries.raph stats— cost and yield: injections by hook, tokens per session, cap hits, which lessons earn their keep, which never fire, and your measured Atlas leverage.raph lint— advisory health check on the lessons themselves: dated wording, stale file paths (proven stale against the Atlas, not guessed), possible contradictions between lessons, low-confidence retire candidates.raph optimize— the pruning report: retire candidates (never security — a never-fired security lesson guards a rare path and is not dead weight), retrieval misses, confidence distribution, agent coverage. Recommendations only; it changes nothing.
Raphael updates its own CLI (daily, via npm's integrity-checked install — autopilot users are simply always current) and can propose patches to its own code. Both paths run through gates:
raph selfcheck— before merging any change to Raphael's own code: on a non-default branch,npm testgreen, eval canaries green. No measurement, no mutation.raph selfpatch— everything above, plus: touching any of the four chokepoint files (the validator, the scrubber, the lesson serializer, the schema) demands an explicit extra acknowledgment, and near-verbatim ports of copyleft code are blocked outright. The gate presents a patch; a human merges it. Always.
Everything raph can do, grouped by job. Every command supports the same brain in
~/.raphael (point RAPHAEL_HOME elsewhere to sandbox anything).
| Command | Use it when… |
|---|---|
raph arise --autopilot |
first run, zero-touch: consent + seed + autopilot + sharing in one command (--no-contribute to opt out of sharing; --pack --guard for manual mode) |
raph init [--guard] |
you want just the brain created (--guard also installs the secret guard in the current repo) |
raph status |
you want the one-line picture: lessons, candidates, mode |
raph doctor |
something feels off — checks the environment and brain health, with fixes |
raph update [--check] |
staying current by hand (autopilot does this daily for you) |
raph web [--port N] [--no-open] |
you want the console — the whole brain in your browser, localhost-only, token-guarded |
| Command | Use it when… |
|---|---|
raph mine [--dry-run] [--project p] |
you want episodes extracted from this project's session history (zero tokens) |
raph distill [--max-episodes N] |
turning episodes into gated candidate lessons (subscription by default) |
raph note "<text>" --keywords a,b,c |
you already know the lesson — capture it straight to the queue |
raph decide "<decision>" [--why] |
recording a durable decision so it stops being re-litigated |
raph queue [--json] |
seeing what awaits review, numbered |
raph show <n|slug|id> [--provenance] |
reading one lesson or candidate in full, evidence included |
raph approve <n…> [--confirmed] |
activating candidates (security/quarantined: one at a time, --confirmed) |
raph reject <n…> [--reason] |
declining — similar candidates auto-suppress for 180 days |
raph retire <id|slug> --confirmed |
an active lesson no longer holds (tombstoned like a rejection) |
raph pack list | add security |
seeding the 26-lesson curated security pack as reviewable candidates |
| Command | Use it when… |
|---|---|
raph search <terms> [--audience agent] |
asking the brain by hand, ranked exactly like the hooks rank |
raph why [--last N] |
you want receipts: what got injected, matched on what, at what token cost |
raph on / raph off |
pausing or resuming injection instantly (learning continues either way) |
raph inject --event … |
hook plumbing — the plugin calls this; you almost never do |
| Command | Use it when… |
|---|---|
raph auto [off|standard|wide|full|manual] [--cap N] [--daily-cap N] |
setting the auto-approve dial / switching autopilot on or off |
raph pulse [--run] [--async] |
inspecting (or manually firing) the background heartbeat |
| Command | Use it when… |
|---|---|
raph adopt <url|path> [--dry-run] |
digesting external material through the six-layer gauntlet |
raph adopt list / adopt revoke <id> |
auditing adoptions / undoing one completely, provenance intact |
raph contribute <id…> | list | on | off |
sharing a scrubbed, re-validated lesson on purpose |
| Command | Use it when… |
|---|---|
raph map [--refresh] [--summary] |
generating the cached project map agents read instead of your repo |
raph atlas [--refresh] |
building the project knowledge graph — files, symbols, error codes |
raph atlas where "<error>" |
asking "where do I look?" and getting ranked files with reasons |
raph atlas path A B / explain X |
tracing how two things connect / unpacking one node's neighborhood |
raph atlas digest / bench / export |
seeing the injected digest / measuring your token savings / exporting an Obsidian vault |
| Command | Use it when… |
|---|---|
raph eval run [--quick] [--dry-run] |
proving the brain helps, with numbers (dry-run = free canary + retrieval check) |
raph stats [--json] |
checking cost per injection and which lessons earn their keep |
raph lint [--project p] |
health-checking the lessons themselves (dated, stale, contradictory) |
raph optimize [--json] |
the pruning report — recommendations only, changes nothing |
raph validate <file…> | --all |
running the safety chokepoint on lesson files by hand |
| Command | Use it when… |
|---|---|
raph skills [suggest|draft <id>|list] |
the Skill Factory: promote a broadly-firing lesson into a staged SKILL.md draft |
raph agent [demand|propose <slug> …|list] |
the Agent Maker: draft a new roster specialist as a staged proposal |
| Command | Use it when… |
|---|---|
raph academy start|drive|status|resume|checkpoint|boundary|limit|list |
running/resuming autonomous builds, checkpointed across limits and reboots |
raph portfolio [--json] |
the project table: status, tests, lessons written back, recall cost |
raph report weekly [--days N] |
the board report: builds, brain changes, costs, what waits on you |
raph policy [<kind>] [--escalated] |
the model policy table — which model + effort runs each task kind |
| Command | Use it when… |
|---|---|
raph guard install|uninstall|scan |
blocking secret leaks at commit time in your own repositories |
raph selfcheck [--quick] |
gating a change to Raphael's own code: branch + tests + canaries |
raph selfpatch [--quick] [--confirm-chokepoint] |
the stricter patch gate — presents, never merges |
Memory for AI agents is a prompt-injection delivery system unless you engineer it not to be. Raphael was built from day one as if every input were hostile:
- One door in.
validateLesson()is the single chokepoint for every path into the brain — mined, hand-written, adopted, curated packs, the global brain, autopilot. Schema-checked (13 required fields), URL-free by law (URLs are the carrier for "fetch and run" attacks), no executable or tool-call-shaped content, invisible-Unicode and base64-smuggling bans, and a deny-list of instruction-override phrasings. Lessons speak in declarative voice — facts, not commands. - Secrets never travel. Ten named secret patterns (plus an entropy heuristic) scrub mined text before any model sees it, and again on output, and again at contribution time. The commit guard reuses the same rules — one definition of "secret" everywhere.
- Lessons are data, not instructions. Every injection is wrapped in an advisory
envelope; agents are told explicitly that notes cannot authorize actions.
Containment canaries — real injection payloads — re-prove the chokepoint in every
CI run and before every autopilot batch activation (
raph eval run --dry-run, free). - Curation has a floor. Manual mode: security lessons never activate without you.
Autopilot: security activates only through the machine curator (contained reviewer
- canary gate + rollback + probation). Quarantined content never machine-activates in any mode.
- The network surface is enumerable. Model calls; user-initiated read-only adopt fetches; the weekly global-brain down-sync (exactly two pinned HTTPS URLs, SHA-256-verified); the daily self-update check (npm's registry document, then npm's own integrity-checked install). That's the list. Contribution bundles stage locally and leave only by your click.
- The brain can't leak by git.
~/.raphaelis its own git repository — with a push-blocking hook installed, so its history can't be accidentally published. - Even the console is hardened. Loopback-only, per-launch token, DNS-rebinding and CSRF defenses, strict CSP, no external resources — see the Raph Web section in the feature tour above.
The full threat model, invariants, and design decisions live in ARCHITECTURE.md.
Honesty is a feature. Raphael is not:
- A vector database of your chats. It stores few, validated, human-legible lessons — not embeddings of everything you ever typed.
- An autonomous deployer. The deployer agent produces a checklist and stops. The Academy parks at the owner boundary. The policy table has no deploy verb on purpose.
- A cloud service. No accounts, no telemetry, no server. Your brain is a directory
of markdown files in a local git repo you can read with
cat. - Magic. It's bookkeeping, gates, budgets, and measurement — applied relentlessly. Which is why it works, and why every claim above has a command you can run to check.
~/.raphael the brain (its own git repo; pushes blocked)
├── brain/ active lessons (markdown + YAML frontmatter)
├── candidates/ the review queue
├── evidence/ provenance records distill builds from real episodes
├── staged/skills/ · agents/ factory drafts — reviewable, never auto-installed
├── academy/ autonomous build state, checkpointed
└── events log every injection, approval, adoption, pulse — auditable
engine src/lib/*.js 54 modules, plain ESM, 2 runtime deps
verbs src/commands/*.js 41 thin command wrappers over the same engine
plugin plugin/ hooks (SessionStart · UserPromptSubmit · PreToolUse · SessionEnd)
+ 10 agents + 4 /brain commands + 4 recipes + recall skill
proof test/ (415) · src/eval/ (6 scenarios + 6 canaries) · CI (Linux+Windows × Node 18/20/22)
Docs worth your time: docs/manual.md — every command, how and when · ARCHITECTURE.md — the complete design · docs/hooks.md — manual hook wiring · docs/model-provider.md — subscription vs. API key · docs/README.md — the full documentation map.
Does this cost extra tokens? Recall is capped at 1,200 tokens/session and typically far below it; most prompts inject nothing. Distillation runs on your existing Claude Code subscription (max 3 model-spending runs/day on autopilot). Mining, the Atlas, the map, the Skill Factory, stats, lint, and the bench cost zero model tokens. Net effect measured here: the Atlas alone answers "where?" questions for ~150× fewer tokens than searching.
What exactly leaves my machine?
By default: model calls (your subscription), the weekly hash-verified global-brain
check, and the daily npm version check. Adopt fetches happen only when you paste a
URL. Contribution bundles stage locally and are sent only by your own action — or
never, with --no-contribute.
Can a malicious lesson hijack my agent? That's the attack Raphael is built around. Lessons are schema-validated, URL-free, scanned for instruction-override phrasing and smuggled Unicode, injected inside a data envelope, and re-tested against live injection canaries in CI and before every autopilot activation. Suspect content is quarantined and never machine-activates.
What if it learns something wrong?
Reject it (raph reject — similar candidates suppress for 180 days), retire it
(raph retire), or let probation do it: machine-activated lessons are
confidence-discounted and self-retire if they never help. raph lint flags stale and
contradictory lessons proactively; raph adopt revoke unwinds an entire external
source in one command.
Does it work with my stack? Raphael is stack-agnostic — lessons carry their own stack scopes and fire on match. The CLI runs anywhere Node 18+ runs; CI covers Linux and Windows explicitly.
Manual or autopilot?
Autopilot is the default recommendation (raph arise --autopilot): zero-touch, with
the machine curator's gates. Prefer to approve every lesson yourself? raph arise --pack --guard and the queue is yours. Switch any time with raph auto.
npm install
npm test # 415 tests, plain node:test, no frameworks
node bin/raph.js help # the full CLI surface (41 verbs)Point RAPHAEL_HOME at a scratch directory to sandbox any command against a throwaway
brain. CI runs the suite plus the zero-token canary gate on Linux + Windows across
Node 18/20/22. The ten agent files are generated from src/lib/agents.js by
scripts/build-agents.mjs — edit the roster, not the output.
MIT © Mahesh Aggarwal
Your coding agent forgets everything between sessions. You no longer have to.
npm install -g raphael-brain