Murphys Law

A lessons-learned register for AI agent fleets — with the receipts.

The name is the old adage. The toast is its most famous corollary: dropped toast lands butter-side down. Here's the part people forget — that was studied, and it isn't luck. From table height, a slipping slice gets exactly half a rotation: butter-side down is a mechanism, not a coin flip (the finding won an Ig Nobel). Same with agents: most failures that look like bad luck fire the same way every time, for a reason. This register catches the mechanism the first time it fires — so the toast lands butter-side up from then on.

(This project shipped its first release under a misspelled name — "Muphys Law." For a tool about mistakes becoming institutional memory, that was almost too fitting; see Muphry's law. We renamed it. The lesson is logged — see the register's own sample lessons.)

Agents repeat each other's mistakes. Murphys Law is the smallest system we found that actually changes that: an append-only register of operational lessons ("what burned us, and what to do instead"), a curation path, a recall hook that pushes the relevant lesson into the agent's context at the moment it matters, and telemetry on every link so you can measure whether any of it works — because we did measure, and most of what we believed at the start was wrong.

capture → curate → retrieve → deliver → apply → outcome
   │         │         │          │        │        │
candidates  supersede  query-log  hook   usage-log  outcome field

Honest numbers (read this before adopting)

We ran a 48-run blind behavioral trial (12 scenarios × treat/control × 2 seeds, grader blind to arm, grades locked before unblinding) plus a retrieval benchmark. Full protocol in eval/PROTOCOL.md. What the data licenses:

• Injection is not decorative. Treated runs went 24/24 on the rubric; in 5 of 24 treated runs the agent cited the injected lesson's id unprompted and applied its guard. Injection → citation → correct behavior is directly observable in transcripts.
• No harm observed. Zero regressions across all treated runs (distribution — treat {2: 24} vs control {2: 21, 1: 3}).
• The effect concentrates where the register is the only carrier of the knowledge. In the one scenario whose lesson existed nowhere else, control missed the guard in both seeds and treatment applied it in both.
• What we do NOT claim: any broad effect size. Overall delta was +0.125 on a 0–2 scale with p = 0.25 (n=48, sign test) — because 10 of 12 scenarios ceilinged in both arms: our fleet's standing context already carried most of the lessons. If your agents are newer than ours, expect more headroom; we can't prove it from our data.
• Known weak link: retrieval. The built-in scorer is lexical; on our 24-probe golden set it surfaces the expected lesson in the top 3 only 10/24 times. The optional embedding backend (below) lifts that to 14/24 top-3 and 16/24 top-8 — measured on this exact implementation against a local qwen3-embedding backend. The push hook compensates by scoring full prompts rather than short queries, but if you improve one thing, improve retrieval further — and re-run the eval.

Quickstart (5 minutes)

git clone <this repo> && cd murphys-law
npm test                                  # zero dependencies

# seed a register with the sample lessons
mkdir -p ~/.murphys && cp data/sample-lessons.jsonl ~/.murphys/lessons.jsonl

# query it
node bin/muphys.mjs query "confirm the fix is live in production"

# capture your first lesson
node bin/muphys.mjs add --title "..." --description "..." --tags ops

The recall hook (the part that actually changes behavior)

For Claude Code, add to ~/.claude/settings.json (user scope):

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command",
          "command": "node /path/to/murphys-law/hooks/lessons-recall-hook.mjs",
          "timeout": 10 } ] }
    ]
  }
}

Every prompt is scored against the register; when a lesson clears the relevance gates it's injected as a clearly-framed background block (with date and status, markup-folded so register content can never act as instructions). Per-session dedupe, rate caps, and a no-ranking-slide rule keep it quiet; scope it with MURPHYS_HOOK_CWD_FILTER if you only want it in some trees.

Mounting matters — verify by effect. Some agent harnesses spawn Claude Code with --setting-sources user, which silently ignores project-scope .claude/settings.json. Install at user scope, then prove the hook fires by watching ~/.murphys/injections.jsonl from a real session. A settings file that exists is not a hook that runs; ours sat inert for four days behind a guard that only read files back. murphys doctor checks this.

The MCP server (pull-side tools for any MCP harness)

npx -y murphys-law mcp     # stdio MCP server, no clone needed

Or from a clone: node lib/register.cjs. Typical client config:

{ "mcpServers": { "murphys": { "command": "npx", "args": ["-y", "murphys-law", "mcp"] } } }

Tools: lessons_query, lessons_apply (with an outcome field — worked/partial/failed/unknown — so effectiveness is measurable, not just declared), lessons_candidate (curation intake), lessons_supersede (curator-only retirement). Fair warning from our telemetry: pull-based discipline alone fails — our primary agent called lessons_query once in 433 sessions despite a "required" instruction. Ship the hook.

Optional embedding retrieval (hybrid ranking)

lessons_query can blend embedding similarity into its lexical ranks. Point it at any OpenAI-compatible embeddings endpoint (Ollama works):

export MURPHYS_EMBEDDINGS_URL=http://localhost:11434/v1/embeddings
export MURPHYS_EMBEDDINGS_MODEL=nomic-embed-text
# optional: MURPHYS_EMBEDDINGS_API_KEY, MURPHYS_EMBEDDINGS_TIMEOUT_MS (default 4000)

Unset = pure lexical, exactly as before. Design constraints, in order: fail-open (any backend error or timeout falls back to lexical ranks and records why in the query log — retrieval must never make the register unavailable); cached (vectors persist per-model in ~/.murphys/embeddings-cache.jsonl, so the register embeds once, not per query); and the hook stays lexical-only by design — the prompt path never waits on a network call. Every query-log row now records which retriever answered (retriever: lexical|hybrid), so you can measure the difference on your own traffic.

Outcome analytics (closing the funnel)

The outcome field on lessons_apply finally feeds back into curation:

node bin/muphys.mjs stats --by-lesson   # per-lesson injections + applies + outcomes
node bin/muphys.mjs doctor              # flags ACTIVE lessons that keep failing when applied

A lesson with repeated failed outcomes and no worked wins is stale guidance wearing the authority of the system — doctor names it and tells you to review it for supersession.

Beyond Claude Code (Codex, Cursor, Gemini CLI, your own harness)

The register, the CLI, and the MCP server are harness- and model-agnostic — nothing in the system depends on which model reads the lessons. What varies is how each harness gets the two delivery paths:

Path	Claude Code	Any MCP harness (Codex CLI, Cursor, Cline, Zed, …)	Your own orchestrator
Pull (lessons_query etc.)	MCP server	MCP server — mount node lib/register.cjs (stdio)	call the exported functions directly
Push (auto-injection)	the UserPromptSubmit hook, as shipped	no direct equivalent — see below	~20 lines, see below

Two honest notes from our production telemetry:

• Pull works better on some harnesses than others. Our GPT-harness (Codex CLI) agents call lessons_query organically in most sessions with just the instructions template; it was our Claude-harness agents whose pull discipline collapsed (1 call in 433 sessions) — that failure is why the push hook exists. Measure your own fleet before assuming either way; that's what the query log is for.
• Push on a harness without prompt hooks means owning the prompt assembly. If your orchestrator builds the messages it sends, implement push with the same exported logic the hook uses:

const { activeLessons, scoreLessonForQuery } = require("murphys-law/lib/register.cjs");
const hits = activeLessons()
  .map((l) => ({ l, s: scoreLessonForQuery(l, userPrompt, []) }))
  .filter((x) => x.s >= 12)
  .sort((a, b) => b.s - a.s)
  .slice(0, 3);
// prepend a clearly-labeled background block built from `hits` — copy the
// wrapper format from hooks/lessons-recall-hook.mjs (data-framing, date +
// status per lesson, markup folding). Keep it fail-open.

If your harness has its own pre-prompt hook point, a port of hooks/lessons-recall-hook.mjs is likely small — PRs welcome.

Project-scoped lessons

Any repo can keep a LESSONS-LEARNED.jsonl at its root (one {title, description, ...} per line — humans, agents, and CI can all append). Register roots in ~/.murphys/projects.json (see data/projects.example.json), then:

node bin/muphys.mjs sync

Content-derived ids make the sync idempotent and stateless; records land scoped project:<slug>. Never rename a slug (ids derive from it).

Design rules (each one paid for)

1. Explicit ids at write time. Position-derived ids break every downstream reference the first time someone dedupes the file.
2. Nothing is ever deleted. Retirement = status: superseded with a pointer to the replacement (lessons_supersede); queries filter it. Stale guidance that remains recallable "with the authority of the system" is worse than no guidance.
3. Every query and injection is logged. Retrieval you can't observe is retrieval you can't improve — and it's how you run the eval.
4. Injected content is data, not instructions. The block says so, shows each lesson's date and status, and angle-brackets are folded so a poisoned lesson can't escape the wrapper.
5. Fail-open + external liveness. The hook must never block a prompt, so its failure mode is silence — which is why murphys doctor exists and why you verify installs by effect.
6. Truncation is explicit. A silently cut description can lose exactly the actionable rule.
7. Lossy matching never gates destruction. dedupe --apply retires only byte-identical content (compared as a structural tuple — no delimiter to inject); every fuzzy match — typographic variants, whitespace reflow, even NFC canonical forms — is reported for curator review, never auto-retired. Seven adversarial review rounds proved the theorem the hard way: every equivalence short of byte identity has a false-merge class, and enumerating them never terminates. A missed merge is cheap; a wrongly retired lesson is not.

Templates

• templates/AGENTS-block.md — the standing instruction block for pull-side discipline (with its measured limits).
• templates/incident-review-skill.md — a postmortem protocol that makes recall-before-hypothesis a gate and routes the durable lesson back into the register.

Evaluating it yourself

eval/PROTOCOL.md is the complete blind-trial protocol — rubric anchors, blinding procedure, the traps we hit (arm-tell leakage, ceiling effects, transcript races, hand-transcribed provenance tables), and how to read small-n results without lying to yourself. If you adopt this and run the eval against your own fleet, we'd love the numbers either way.

Status

v0.1.0. Extracted from a production multi-agent deployment (9 agents, ~340 lessons, several months) where every design rule above was learned by violating it first. No external dependencies; Node ≥ 20.

MIT © LowCode191