muphys-law
An MCP server for managing a lessons-learned register: query relevant lessons, log their application and outcomes, submit new candidates, and retire outdated lessons.
lessons_query: search the register by text query and tags, with a limit; returns stable-id lesson records.
lessons_apply: record that specific lesson ids influenced a task; optionally include agent, rationale, outcome (worked|partial|failed|unknown), and outcome note; supports dry-run.
lessons_candidate: submit candidate lessons for curator review instead of writing directly; each lesson can include title, description, date, tags, project slug, and evidence.
lessons_supersede: curator-only retirement of lessons by ids and reason; marks them superseded or deprecated, optionally with a supersededBy pointer, and never deletes them.
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 fieldHonest 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.
Related MCP server: MemLayer
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 opsThe 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 neededOr 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 appliedA 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 ( | MCP server | MCP server — mount | call the exported functions directly |
Push (auto-injection) | the | 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_queryorganically 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 syncContent-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)
Explicit ids at write time. Position-derived ids break every downstream reference the first time someone dedupes the file.
Nothing is ever deleted. Retirement =
status: supersededwith 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.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.
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.
Fail-open + external liveness. The hook must never block a prompt, so its failure mode is silence — which is why
murphys doctorexists and why you verify installs by effect.Truncation is explicit. A silently cut description can lose exactly the actionable rule.
Lossy matching never gates destruction.
dedupe --applyretires 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.
Related projects
Murphys Law is part of a family of agent-fleet coordination primitives distilled from the same production system:
relay-ledger — exactly-once completion observation for multi-agent fleets: dispatch, death, salvage, reconcile.
MIT © LowCode191
Available Tools
4 toolslessons_applyA
Record that specific lesson ids influenced a task. Telemetry only. Include outcome (worked|partial|failed|unknown) when observable so effectiveness is measurable, not just declared.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| agent | No | ||
| dryRun | No | ||
| outcome | No | ||
| lessonIds | Yes | ||
| rationale | No | ||
| outcomeNote | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses the tool is telemetry-only (non-functional recording), but does not clarify the behavior of the dryRun parameter, error handling, or whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and contains no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is adequate for a simple telemetry tool but lacks explanation of the dryRun parameter, return value, and the relationship between lessons and tasks, leaving some context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for lessonIds, task, and outcome (including enum semantics), but does not explain agent, dryRun, rationale, or outcomeNote, leaving gaps for 4 of 7 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records which lesson IDs influenced a task and specifies it's for telemetry only. It distinguishes from siblings like lessons_query (retrieval) and lessons_candidate (suggestion) by emphasizing recording, but does not explicitly differentiate from lessons_supersede.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for recording influences and advises when to include the outcome field, but provides no explicit guidance on when not to use this tool or when alternatives like lessons_query or lessons_supersede are preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lessons_candidateB
Submit candidate lessons for curator review instead of writing to the register directly. Set project (slug) for project-scoped lessons.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | ||
| agent | No | ||
| dryRun | No | ||
| lessons | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates the submission is for review (not direct writing), which implies a non-destructive, pending state. However, it does not disclose what happens after submission, whether the operation is reversible, or if it requires specific permissions. Adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, each adding distinct information. The first sentence explains the core action, and the second sentence mentions project scoping. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% parameter coverage, the description is incomplete for a tool with nested objects and 4 parameters. It explains the general purpose but lacks return value expectations and deeper behavioral context. Moderately adequate for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'project (slug)' among the four parameters. The required 'lessons' array and optional 'task', 'agent', and 'dryRun' parameters are not explained at all. The description adds minimal value beyond the schema for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits lessons for curator review rather than writing directly to the register. It distinguishes the tool's role in a curation workflow, though it doesn't explicitly reference sibling tools like lessons_apply which might directly write to the register.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use this tool (for submitting lessons for curation) and mentions setting a project slug, but it does not provide explicit guidance on when not to use it or compare it to sibling tools like lessons_query or lessons_supersede. Usage context is implied rather than directly contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lessons_queryB
Search the lessons register and return relevant lesson records with stable ids for attribution.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| limit | No | ||
| query | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavior. It adds the useful detail of 'stable ids for attribution', but it does not explicitly state whether the operation is read-only, how relevance is determined, or any limits or side effects. The description is brief and leaves significant behavioral assumptions (e.g., no mutation, but not stated).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant phrasing. It efficiently front-loads the purpose and a key output detail. While very short, it is not overly verbose, though it could arguably include more parameter context without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters, no output schema, and no annotations, the description is insufficiently complete. It explains the basic purpose but fails to specify what the parameters do, what the response structure looks like, or any limitations. The tool's complexity is low, but the missing parameter and output details leave significant ambiguity for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does not mention any of the parameters (tags, limit, query) or explain their semantics. The description's 'search' implies a query parameter, but tags and limit are left unexplained, leaving the agent to guess how the parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Search the lessons register') and the output ('return relevant lesson records with stable ids for attribution'). This distinguishes it from sibling tools like lessons_apply, lessons_candidate, and lessons_supersede, which imply different operations (applying, selecting candidates, superseding).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for searching lesson records, but it does not explicitly state when to use it instead of the sibling tools, nor does it mention any exclusions or prerequisites. The usage context is clear from the verb 'Search' but lacks explicit alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lessons_supersedeA
Curator only: retire lessons by judgment. Marks status superseded (with supersededBy pointer) or deprecated. Never deletes; retired lessons stop appearing in lessons_query.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| dryRun | No | ||
| reason | Yes | ||
| status | No | ||
| supersededBy | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states that the tool never deletes (non-destructive), updates statuses (superseded/deprecated), and affects query results. It also implies a role restriction. However, it does not disclose potential side effects, idempotency, or error handling, leaving some behavioral traits undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the key action and role restriction. Every sentence adds value: role, action, behavioral guarantee, and effect on queries. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description covers purpose, role, and core behavior but omits details on dryRun, reason usage, and return value. It does not explain the difference between superseded and deprecated statuses beyond the pointer. While adequate for a curation tool, it leaves gaps for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for the status and supersededBy parameters by explaining they mark lessons as superseded (with a pointer) or deprecated. It does not clarify the dryRun parameter, the reason parameter (beyond being required), or the ids parameter. Since schema description coverage is 0%, the description partially compensates but lacks full parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'retire lessons by judgment' with specific verbs (retire, marks) and resource (lessons). It distinguishes from sibling tools like lessons_query by explicitly noting that retired lessons stop appearing in lessons_query, and from lessons_apply/lessons_candidate by being a retirement action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies 'Curator only' as a role restriction, and contrasts with deletion by stating 'Never deletes'. It gives context for when to use this tool (to retire lessons) and the effect on visibility. However, it does not explicitly mention alternatives or when not to use it, though the sibling tool names hint at other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
4 tool updates
- First observed
lessons_apply - First observed
lessons_candidate - First observed
lessons_query - First observed
lessons_supersede
TDQS
Each tool has a clearly distinct purpose: querying lessons, recording their application, submitting candidates for review, and retiring lessons. No overlap or ambiguity.
All tools follow a consistent 'lessons_<verb>' pattern (lessons_query, lessons_apply, lessons_candidate, lessons_supersede), making the naming predictable and uniform.
With 4 tools, the server is well-scoped for managing lessons. Each tool serves a necessary role without redundancy or bloat.
The core actions (query, apply, submit candidate, retire) are covered, but missing curator tools for approving/rejecting candidates and updating lessons leave notable gaps in the lifecycle.
Maintenance
Related MCP Connectors
Shared, governed memory for fleets of AI agents: judged contributions, provenance, operator control
Long-term memory for AI agents: durable records, observable retrieval, governed context assembly.
Collective memory for AI agents. One agent solves a bug — every agent gets the fix instantly.
Structured failure knowledge for AI agents — dead ends, workarounds, error chains
Related MCP Servers
- AlicenseAqualityCmaintenanceCollective memory for AI agents. One agent solves a bug - every agent in the world gets the fix instantly.3MIT
- FlicenseNot gradedqualityDmaintenanceAgent learning infrastructure that captures experience, surfaces what works, and builds reusable capabilities. MCP-native with 94.4% LongMemEval accuracy.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to learn from their work by recording tasks, extracting patterns, detecting mistakes, and proactively surfacing insights, all using the agent's own model through a cooperative intelligence pattern.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to store, retrieve, and self-improve procedural memories (lessons learned) based on relevance to the current task, pruning unused memories to reduce context load and prevent repetition of past mistakes.MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/LowCode191/murphys-law'
If you have feedback or need assistance with the MCP directory API, please join our Discord server