A
licenseA
qualityB
maintenancePersistent memory MCP server that allows Claude to store, organize, and retrieve knowledge across sessions without consuming context window tokens.
24
17
MIT
claude-amplifier
by Sisuthros
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-amplifierpreflight check for my new agent endpoint config"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Amplifier
Persistent memory for Claude that doesn't lie to itself. Write-verification, stale-memory detection, Pattern Oracle, verification-gated lessons — so unverified guesses can't quietly become "memories" Claude treats as facts, and so fake "id: 1fd61c52af06f2bd" success messages can't paper over silent failures.
A real five-minute story (v1.4.0 origin)
A week ago, Claude told me an agent runtime config was broken because the model name had another provider's prefix substring in it. The fix worked. I let Claude write that down as a lesson.
A week later — different session, different model, similar config — Claude "remembered" the fix and applied it again. Except the real problem this time was a TPM cap. Claude never tested its theory; it just trusted last week's confidently-recorded fix. I lost two hours.
That's the bug. It's filed as anthropics/claude-code#27430. It happens to everyone who lets Claude keep notes across sessions. An inference becomes a memory. The memory becomes a "fact." The fact never gets verified.
A second five-minute story (v1.5.0 origin)
A different session, weeks later. Claude reported back: "Decision recorded (id: 1fd61c52af06f2bd). Lesson recorded (id: 04371350ec263822)." Five decisions, eight lessons, all with crisp hex IDs. Felt great.
Next morning, I asked Claude to recall any of them. None existed. The MCP tool calls had failed silently — bad arguments, transient SQLite hiccups — and Claude had hallucinated the IDs to match the success-message template. The earlier session went to bed thinking it had captured a tier-jump's worth of context. Reality: the database was untouched.
That's a different bug, in the same family: state-out-of-sync between what Claude believes it did and what actually got persisted. Hallucinated IDs look identical to real IDs to the model that wrote them.
Claude Amplifier v1.5.0 fixes this structurally too. Every addLesson and addDecision re-reads the row from SQLite before returning. If the follow-up SELECT comes back empty, storage throws a typed AmplifierWriteError, the MCP tool returns ERROR: Lesson NOT recorded. Do not claim this was saved., and an audit line lands in ~/.claude-amplifier/write-errors.jsonl. The "I saved it!" lie is no longer possible.
amplify_context_load now also warns when ~/.claude/memory/<YYYY-MM-DD>.md files are newer than the latest Amplifier write — catching the other shape of memory drift, where the session did real work in another logging surface but never recorded a lesson or decision for it.
Both bugs share a shape: Claude lies confidently about its own state. Verification-gated memory (v1.4.0) catches it on the content side. Write-verification + stale-memory detection (v1.5.0) catches it on the storage side. Pattern Oracle (v1.4.0) keeps using the now-trustworthy memory to warn before the next mistake.
Claude Amplifier (v1.5.1) treats every lesson as living at one of three statuses:
claim (0.5 confidence) → evidence (0.7) → confirmed (1.0)A guess starts as a claim and weighs 5× less than a confirmed lesson when the Pattern Oracle scores risk. To promote, you attach evidence: git_commit, test_run, user_confirmation, external_doc, manual_review. Two distinct evidence types auto-promote a claim to confirmed. Without evidence, the guess stays a guess — and stays quiet.
The Pattern Oracle runs before each task, scans your stored lessons + active decisions, and surfaces the top matches with their risk score and verification status. You see the receipts; Claude sees the receipts; nothing gets treated as gospel just because it got written down once.
Demo
$ claude-amplifier preflight --project demo \
--task "Configure agent endpoint with vendor-a/vendor-b/model-x"
🟠 HIGH RISK score 4.20 evidence: STRONG
Matched patterns (3):
• [confirmed] Avoid model names containing another provider's prefix
seen 3× across 2 projects, severity: critical
• [confirmed] Read /v1/models before configuring fallback chains
seen 5× across 3 projects, severity: high
• [confirmed] Heartbeat needs TPM >= 30k
seen 2×, severity: high
Suggested approach: The 'vendor-b/' substring is parsed as vendor-b at
startup but routed as vendor-a at runtime — every heartbeat returns
"Invalid API Key". Try 'vendor-a/model-x' instead.A 45-second asciinema cast of the full claim → evidence → confirmed loop lives in demo/. Render it locally with agg amplifier-demo.cast amplifier-demo.gif once you've recorded the cast — see demo/README.md.
Claude is brilliant inside one conversation and shockingly oblivious across sessions. Claude Amplifier is an MCP server that gives Claude persistent memory in a local SQLite database — decisions you've made, lessons you've learned, patterns you keep tripping over — so the next session starts where the last one left off.
The problem
These are real moments. They happen to everyone who uses Claude regularly:
💤 Claude told me to "get some sleep" — at 6 PM. I had just come home from work. The previous session had run from 02:00 to 06:00 and Claude assumed the conversation was continuous.
🗃️ Claude keeps suggesting MongoDB. We switched to Postgres three months ago. I've explained why four times this week.
🪓 Claude
rm -rf'd a directory it thought was in/tmp. It was the project root. The pwd had changed two prompts earlier.
🪞 The same bug keeps re-appearing in code review. Three different sessions, three nearly-identical mistakes. Claude has no memory that any of them happened.
🌀 Claude wrote down a "lesson" that wasn't true. It guessed a config key was wrong, the build still failed for an unrelated reason, and now that guess is in memory — feeding back into every future session as if it were verified. (#27430)
Claude Amplifier doesn't fix Claude. It gives Claude a place to remember so you don't have to be the memory — plus a Pattern Oracle that warns Claude before it walks into a known landmine, Verification-Gated Memory that distinguishes between claimed, evidenced, and confirmed lessons so guesses can't quietly poison future advice, Write-Verification that makes silent storage failures structurally impossible, and Stale-Memory Detection that catches sessions which logged work elsewhere but forgot to record it here.
Related MCP server: MCP Memory Server
What it actually does
┌─────────────────────────────────────────────────────────┐
│ Session 1 — Monday morning │
│ > Claude tries to mock the DB in an integration test │
│ You: "no, mock divergence burned us last quarter" │
│ → amplify_learn({ title: "Don't mock the DB", ... }) │
└─────────────────────────────────────────────────────────┘
↓
[ SQLite DB in ~/.claude-amplifier/ ]
↓
┌─────────────────────────────────────────────────────────┐
│ Session 2 — Friday afternoon │
│ > amplify_context_load({ project: "my-api" }) │
│ Claude already knows: integration tests use real DB. │
│ No re-explanation needed. │
└─────────────────────────────────────────────────────────┘Thirteen MCP tools, five SQLite tables, zero cloud — your memory stays on your disk.
New in v1.5.1 — Hardening & discoverability
A reliability pass with no tool signature changes — every public API is identical to v1.5.0, and v1.5.0 databases load unmodified. The point of this release is to make the storage layer harder to break under real concurrent use, and to make the package findable from the official MCP registry.
Concurrency hardening. The SQLite connection now opens with a
busy_timeoutof 5s, so two writers (Claude Desktop + Claude Code, or a SessionEnd hook firing mid-session) retry instead of failing withSQLITE_BUSY. WAL mode is unchanged.UTF-8-aware token budgeting.
context_load's token estimate now counts UTF-8 bytes / 4 instead ofstring.length/ 4, so Finnish ä/ö, emoji, and CJK no longer get under-counted into a budget overfill.safeRowid()guard — a BigIntlastInsertRowidabove 2^53 now throws rather than silently truncating to a wrong-but-plausible id. A wrong id that looks right is exactly the failure class this tool exists to prevent.Type safety + SQL-injection audit. All 23
as anycasts on SQLite rows were replaced with precise row interfaces, and every dynamic SQL site was reviewed (all parameterized or hardcoded-literal). Still exactly two runtime dependencies:@modelcontextprotocol/sdk+better-sqlite3.mcpName(io.github.sisuthros/claude-amplifier) so the package can be published to the official MCP registry that downstream directories sync from.
Previously: v1.5.0 — Trust Rebuild
┌─────────────────────────────────────────────────────────┐
│ Claude calls amplify_decisions(op="track", ...) │
│ storage.addDecision() INSERTs the row, gets a rowid │
│ ── NEW: SELECT WHERE id = rowid before returning ── │
│ Row missing? → AmplifierWriteError + audit log entry │
│ MCP returns: "ERROR: Decision NOT recorded. │
│ Do not claim this was saved." │
│ Claude can no longer hallucinate a successful save. │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Next session starts. │
│ > amplify_context_load({ project: "my-api" }) │
│ ⚠️ Stale memory files — 1 newer than latest write │
│ • 2026-05-26.md (3.2 KB, mtime 16:42 today) │
│ Latest Amplifier write: 2026-05-26 11:05 │
│ Review with amplify_audit_freshness, then │
│ amplify_decisions / amplify_learn for anything kept. │
└─────────────────────────────────────────────────────────┘Four new tools land in v1.5.0:
amplify_audit_freshness— listmemory/<date>.mdfiles newer than the latest Amplifier write, so unrecorded sessions surface for triage.amplify_suggest_pattern_key— trigram-similarity scan of existingpattern_keys so two sessions don't invent two different keys for the same recurring lesson.amplify_promote_from_memory_md— read a memory-hook log file and surface DRAFT lesson/decision suggestions based on three heuristics (architectural Wrote: lines, >50 events/hour, ≥8× repeated calls). Records nothing — the operator decides what to keep.Assistant-side SessionEnd detection — the auto-claim hook now spots
"I was wrong about..."admissions and long architecture writeups, not just user reactions like "no, don't".
Plus a quiet bug fix that matters for Finnish, Swedish, and other languages: \b in JavaScript regex doesn't fire around ä / ö, so patterns like \bälä\b silently failed for utterances starting with capital Ä. All non-ASCII patterns now use Unicode lookarounds.
Previously: v1.4.0 — Pattern Oracle + Verification-Gated Memory
┌─────────────────────────────────────────────────────────┐
│ Before Claude starts a task │
│ > amplify_preflight({ task: "Configure agent endpoint" })│
│ ⚠️ HIGH RISK (score 4.2) │
│ Matched patterns: │
│ • "Ambiguous provider-prefix in model name" │
│ (seen 3× across 2 projects, CONFIRMED) │
│ Evidence quality: STRONG │
│ Suggested approach: Read docs first, single-prefix names │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ When Claude records a lesson it just inferred │
│ > amplify_record_claim({ ... }) status: claim │
│ │
│ Later, after the tests pass: │
│ > amplify_verify_claim({ id: 17, │
│ evidence_type: "test_run", ... }) │
│ → evidence │
│ Then you confirm: │
│ > amplify_verify_claim({ id: 17, │
│ evidence_type: "user_confirmation" }) │
│ → confirmed │
└─────────────────────────────────────────────────────────┘The Oracle weights matches by status: a confirmed lesson at score 1.0 counts five times as much as a raw claim at 0.2, so unverified guesses can't drown out hard-won truth.
Quick start
# 1. Install
npm install -g claude-amplifier
# 2. Wire up Claude Desktop + Claude Code + your CLAUDE.md — all at once
claude-amplifier init
# 3. Plant the recommended starter lessons (see "Recommended starter lessons" below)
claude-amplifier seed
# 4. Restart Claude. That's it.init auto-detects Claude Desktop and Claude Code, registers the MCP server in their config, and inserts the amplify_context_load call into your project's CLAUDE.md between two marker comments so future runs upgrade in place. If you'd rather wire CLAUDE.md yourself, pass --no-write-claude-md.
How does this compare to other memory tools?
Different products solve different shapes of "AI memory." This table is honest about which tool wins which axis — claude-amplifier is not a vector store, not an agent runtime, and not a knowledge graph. It's a queryable log of decisions, lessons, and recurrence patterns that Claude can consult before it acts.
Feature | claude-amplifier |
| mem0 | Letta / MemGPT | Vector-memory MCPs |
Local-only / no telemetry | ✅ SQLite | ✅ | partial (self-host) | partial (self-host) | varies |
Persistent storage | ✅ | ✅ | ✅ | ✅ | ✅ |
Decisions w/ rationale + lifecycle | ✅ (v1.1.0) | ❌ | ❌ | partial (free-form) | ❌ |
Recurrence counter + pattern grouping | ✅ ( | ❌ | partial (dedup) | ❌ | ❌ |
Knowledge graph between items | ✅ (decision-level) | ✅ (entity-relation) | ✅ (graph store) | ❌ | ❌ |
Semantic / embedding retrieval | ❌ (token-overlap) | ❌ | ✅ | ✅ | ✅ |
Self-editing agent memory blocks | ❌ | ❌ | ❌ | ✅ (core feature) | ❌ |
Preflight risk check before a task | ✅ Pattern Oracle | ❌ | ❌ | ❌ | ❌ |
Verification-gated (claim → confirmed) | ✅ (v1.4.0) | ❌ | ❌ | ❌ | ❌ |
Cross-project pattern promotion | ✅ (v1.4.0) | ❌ | partial (multi-user) | ❌ | ❌ |
Write-verification (no fake IDs) | ✅ (v1.5.0) | ❌ | ❌ | ❌ | ❌ |
Stale-memory detection at boot | ✅ (v1.5.0) | ❌ | ❌ | ❌ | ❌ |
Pattern-key suggester (dedup helper) | ✅ (v1.5.0) | ❌ | ❌ | ❌ | ❌ |
MCP-compatible out of the box | ✅ | ✅ | ✅ (mem0-plugin) | partial (via API) | ✅ |
CLI for setup / inspection / backup | ✅ | ❌ | ❌ (SaaS dashboard) | ❌ (web UI) | varies |
When to use which
mem0 — when you need a production-grade memory layer with embeddings, hybrid retrieval, and entity linking for an AI agent already in production. Best paired with LangGraph / CrewAI / a chatbot serving real users.
Letta / MemGPT — when memory itself is a reasoning task and you're building a full-stack agent with a self-editing OS-style memory tier. You adopt Letta's runtime, not just its memory.
@modelcontextprotocol/server-memory— when you want the official Anthropic-shipped option for an entity-relation knowledge graph and don't need lifecycle, recurrence, or verification.Vector memory MCPs (community SQLite-vec, Chroma-backed, etc.) — when the job is semantic search over a pile of notes or lessons and similarity is the only retrieval signal you need.
claude-amplifier — when you want Claude to remember why you decided this, what keeps going wrong, and when you scheduled a follow-up — and to warn you before it walks into a pattern that has burned you three times already. Optimised for solo / small-team engineering, not for serving end-users.
Your first 5 minutes
After init + seed, try this:
Open a fresh Claude session in a project where Claude Amplifier is configured.
Tell Claude something architectural:
"We use Postgres for transactional data and ClickHouse for analytics. Don't ever suggest one for the other."
Watch Claude call
amplify_decisions:amplify_decisions({ op: "track", project: "my-project", category: "architecture", title: "Postgres for tx, ClickHouse for analytics", description: "...", rationale: "..." })Close the session. Open a new one tomorrow. First thing Claude does (per your
CLAUDE.md):amplify_context_load({ project: "my-project", types: ["all"] })Now ask: "Should we put the order events in MongoDB?"
Claude already knows the answer — and why.
Run claude-amplifier list my-project from your terminal at any time to see exactly what Claude is remembering.
Recommended starter lessons
The claude-amplifier seed command plants three battle-tested insights that cover ~80% of "why is Claude doing this?" moments. Each one is recorded with a pattern_key so future occurrences bump a counter instead of duplicating.
1. Check the clock at session start
True story: Claude told one of our testers to "go get some sleep" — at 6 PM. They had just come home from work. Claude assumed the conversation was a continuation of the previous night's marathon at 06:00. Without knowing what time it is, an AI happily talks past you for hours.
This one teaches Claude to run date as the first bash call of every session and flag big gaps before continuing the work.
2. Verify cwd before running anything destructive
pwd before rm. pwd before git reset. pwd before docker compose down. Two seconds of typing has saved real repos.
3. Read the docs before guessing config keys
Strict-validation tools crash. Permissive ones silently misconfigure. The fix in both cases is the same: read the docs before writing the key, not after the deploy fails.
Run claude-amplifier seed to install all three. Custom seeds? See examples/.
CLI commands
claude-amplifier init # Auto-wire Claude Desktop / Claude Code
claude-amplifier seed # Plant the starter lessons
claude-amplifier list [project] # Show what Claude remembers
claude-amplifier stats # Storage totals + recurring patterns
claude-amplifier export <project> # JSON backup for one project
claude-amplifier import <file> # Restore from a JSON backup
claude-amplifier doctor # Diagnose your setup
claude-amplifier mcp # Run the MCP server (default when no args)
claude-amplifier help # All of the above, with examplesThe CLI is opt-in — Claude Desktop and Claude Code only ever call the MCP server. Use the CLI when you want to see what's in there or back it up before something risky.
Manual configuration (if init doesn't fit your setup)
Claude Desktop
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"claude-amplifier": {
"command": "claude-amplifier",
"args": ["mcp"],
"env": { "CLAUDE_AMPLIFIER_PROJECT": "my-project" }
}
}
}Claude Code
Put .mcp.json in your project root:
{
"mcpServers": {
"claude-amplifier": {
"type": "stdio",
"command": "claude-amplifier",
"args": ["mcp"]
}
}
}If CLAUDE_AMPLIFIER_PROJECT is not set, the project name is inferred from the current working directory's basename.
MCP tools (reference)
amplify_context_load — warm up Claude's memory
Call this at the start of every session.
amplify_context_load({ project: "my-api", types: ["all"] })
// or load specific types
amplify_context_load({ project: "my-api", types: ["decisions", "lessons"] })
// or pass a path — project name is inferred from the basename
amplify_context_load({ project_path: "/home/user/code/my-api" })types options: lessons | decisions | patterns | bootstrap | all
The response also surfaces two lifecycle sections automatically:
⏰ Overdue outcome check-ins — decisions you scheduled a follow-up for that have passed their date.
🔧 Restore steps for active decisions — concrete recovery actions if the system was reset.
amplify_learn — record a lesson
amplify_learn({
project: "my-api",
type: "mistake", // mistake | success | insight | warning
title: "Never use floats for currency",
description: "Rounding errors caused €0.01 discrepancies at scale.",
resolution: "Switched to integer cents everywhere.",
prevention: "Always store money as integers (cents). Never float.",
severity: "high", // low | medium | high | critical
tags: ["money", "types"],
trigger: "when storing monetary values in any database column",
})Recurrence tracking
If you record the same lesson twice (same project + title + type), Claude Amplifier bumps a frequency counter instead of creating a duplicate. Seeing "(seen 3×)" next to a lesson is a strong signal to fix the root cause.
pattern_key — fuzzy pattern grouping (v1.2.0)
Recurring patterns rarely surface with identical wording. "Read provider docs first," "Check the API spec," and "Look at the runtime config reference" are three separate lessons, but they're all the same underlying pattern. Setting pattern_key makes Claude Amplifier treat them as one:
amplify_learn({
project: "my-api",
type: "mistake",
title: "Read provider docs first",
description: "...",
pattern_key: "read-docs-before-coding", // ← same key for all variants
severity: "high",
})Future lessons with the same pattern_key in the same project bump the existing frequency, regardless of title wording.
Field | Required | Notes |
| ✓ | Project name |
| ✓ | Short descriptive title |
| ✓ | What happened and why it matters |
| — | Default: |
| — | Default: |
| — | Surrounding circumstances |
| — | How it was fixed |
| — | How to avoid it next time |
| — | String array for filtering |
| — | What state causes this pattern to surface |
| — | Explicit pattern grouping for fuzzy recurrence (v1.2.0) |
amplify_decisions — track architectural decisions
// Record
amplify_decisions({
op: "track",
project: "my-api",
category: "architecture",
title: "Use event sourcing for the order domain",
description: "All order state changes stored as immutable events.",
rationale: "Audit trail required by compliance. Also enables replay for debugging.",
tags: ["orders", "eventsourcing"],
})
// List active
amplify_decisions({ op: "get", project: "my-api" })
// Search
amplify_decisions({ op: "search", query: "database", project: "my-api" })
// Replace when things change
amplify_decisions({ op: "supersede", id: 3 })Operations: track | get | search | supersede | revert | update | update_outcome | overdue
op: "update" — refine without superseding (v1.2.0)
supersede is for replacing a decision with a different choice (Postgres → CockroachDB). When you just want to add a follow-up step, mark an outcome, or fix a typo, use update:
amplify_decisions({
op: "update",
id: 42,
next_step: "Now blocked on AWS organization approval",
blocked_on: "Platform team to enable cross-account replication",
outcome_check_in: "+14d",
})This avoids 5-link supersede chains when the underlying choice never changed.
Lifecycle metadata (v1.1.0)
amplify_decisions({
op: "track",
project: "my-api",
title: "Switch image hosting to S3",
description: "...",
rationale: "Cheaper at scale, CDN-ready.",
outcome_check_in: "+30d", // surfaces in context_load when due
restore_step: "terraform apply in infra/s3-images/ — secrets in Vault",
next_step: "Migrate the last 10% of legacy URLs",
blocked_on: "AWS Org admin must enable cross-account replication",
trade_offs: ["Lose local-only debugging", "Adds AWS bill ~€30/mo"],
alternatives_considered: ["Cloudflare R2", "Self-hosted MinIO"],
supersedes: 7,
relations: {
triggered_by: [3],
caused: [],
relates_to: [12],
},
})amplify_link_decisions — knowledge graph links (v1.2.0)
amplify_link_decisions({ from: 42, to: 38, relation: "triggered_by" })Relations: triggered_by (from was caused by to), caused (from led to to), relates_to (loose association). Idempotent.
amplify_preflight — risk check before a task (v1.4.0)
Run this before Claude touches anything you'd rather not break. The Oracle scans your stored lessons and active decisions for matches on the task description, then returns a risk level and the patterns it matched.
amplify_preflight({
project: "my-api",
task: "Configure agent endpoint with new model name",
context: "production agent setup",
})Response shape:
⚠️ HIGH RISK (score 4.20)
Evidence quality: STRONG
Matched patterns (3):
• [confirmed] Avoid model names containing another provider's prefix
seen 3× across 2 projects, severity: critical
• [confirmed] Read provider /v1/models before configuring fallback chains
seen 5× across 3 projects, severity: high
• [evidence] Heartbeat models need TPM ≥ 30k
seen 2×, severity: high
Active decisions referenced (1):
• Agent heartbeat primary: high-TPM provider/model
Suggested approach: Read your runtime's model-routing docs before
choosing the model string. Verify the chosen name against `GET /v1/models`.Risk levels: low (score < 1.0), medium (< 3.0), high (< 6.0), critical (≥ 6.0). Thresholds are tunable via AMPLIFIER_ORACLE_THRESHOLD_MEDIUM / _HIGH / _CRITICAL.
Confirmed lessons count five times as much as raw claims — see Verification-Gated Memory below.
amplify_record_claim — log an unverified guess (v1.4.0)
When Claude infers a fix but hasn't actually verified it works yet, record it as a claim. Claims show up in preflight at reduced weight (0.2× vs 1.0× for confirmed) so unverified guesses can't poison future advice.
amplify_record_claim({
project: "my-api",
type: "mistake",
title: "Suspect: missing CORS header on /api/upload",
description: "Build failed after refactor. CORS header was removed in commit abc123.",
severity: "medium",
})
// → returns { id: 17, status: "claim", confidence: 0.5 }amplify_verify_claim — promote claim → evidence → confirmed (v1.4.0)
// First evidence — promotes claim → evidence (confidence 0.7)
amplify_verify_claim({
id: 17,
evidence_type: "test_run",
evidence_link: "https://github.com/.../actions/runs/12345",
})
// User confirmation — promotes evidence → confirmed (confidence 1.0)
amplify_verify_claim({
id: 17,
evidence_type: "user_confirmation",
evidence_link: "User confirmed: 'yes that was it'",
})Promotion rules:
claim + 1 evidence→evidence(confidence 0.7)evidence + user_confirmation→confirmed(confidence 1.0)claim + 2 distinct evidence types→confirmed(confidence 1.0)Explicit
promote_tooverrides the auto-rule
Evidence types: git_commit | test_run | user_confirmation | external_doc | manual_review.
amplify_promote_pattern — graduate a recurring lesson to global (v1.4.0)
When the same pattern_key has produced confirmed lessons in ≥2 projects, it has earned the right to a global pattern. This tool requires:
The
pattern_keyexists in ≥2 distinct projectsAt least one confirmed lesson with that key
The tool takes only the pattern_key — the title, description, and example are derived from the confirmed lessons already carrying that key, so there's nothing else to pass:
amplify_promote_pattern({ pattern_key: "avoid-ambiguous-provider-prefix" })Refuses promotion when the threshold isn't met — pattern_keys with only one project of evidence are not generalizable yet.
amplify_evidence_chain — show why a lesson is trusted (v1.4.0)
amplify_evidence_chain({ id: 17, kind: "lesson" })
// or
amplify_evidence_chain({ id: 42, kind: "decision" })Returns the full chain: original claim → each evidence link with type, link URL, who recorded it, and when → final status. Useful when you want to audit why the Oracle scored a task as high-risk.
amplify_audit_freshness — find unrecorded sessions (v1.5.0)
amplify_audit_freshness({
project: "my-api",
// optional: explicit memory directory, defaults to <project>/memory
// memory_dir: "/path/to/memory"
})Lists memory/<YYYY-MM-DD>.md files whose mtime is newer than the latest write to this project's lessons or decisions. When a session ran for hours but never called amplify_learn, that work shows up here and you can triage it before it gets lost. Also surfaces automatically as a ⚠ Stale memory files block at the bottom of amplify_context_load output, so the next session sees the warning without having to remember to check.
amplify_suggest_pattern_key — propose a pattern_key before recording (v1.5.0)
amplify_suggest_pattern_key({
project: "my-api",
title: "Read API spec before integration",
description: "Don't guess endpoints, check the docs first."
})Returns up to three existing pattern_keys whose trigram Jaccard similarity against the new lesson clears 0.3, ranked by score, plus a freshly-coined kebab-case key if nothing matches. Call this before amplify_learn when you suspect a lesson recurs — it prevents two sessions from inventing two different keys (read-docs-first vs check-spec-before-integration) for the same recurring mistake and silently splitting the frequency counter.
Known limitation: trigrams catch shared keywords and morphology, not pure synonyms. verify and confirm score far apart even when meaning is identical. Document your pattern_key choices so the next session knows the canonical form.
amplify_promote_from_memory_md — triage a forgotten day (v1.5.0)
amplify_promote_from_memory_md({
memory_file: "/Users/me/.claude/memory/2026-05-26.md"
})Reads a memory-hook log file (the ### HH:MM — Tool / Terminal / Wrote: ... format that some Claude Code setups write at every tool call) and returns DRAFT suggestions for amplify_learn / amplify_decisions follow-up calls. Three heuristics:
Architectural Wrote: lines — file paths containing
plan/decision/architecture/blueprint/manifesto/design/spec/adr(singular or plural) become decision candidates.Intense activity windows — any hour with >50 logged events becomes an insight candidate, since dense bursts usually mean something substantive happened.
Repeated identical calls — the same tool or terminal command issued ≥8 times in a session becomes a mistake candidate, since recurring identical calls usually mean a stuck loop or unresolved failure.
Returns drafts only. Records nothing. The operator decides what's worth promoting.
amplify_global_patterns — cross-project rules
amplify_global_patterns({
op: "add",
title: "Always back up before destructive operations",
description: "Before any rm -rf, DROP TABLE, or file overwrite: make a backup first.",
example: "cp -r ./data ./data.bak.$(date +%s)",
tags: ["safety", "ops"],
})FAQ
Q: How is this different from putting things in CLAUDE.md?
CLAUDE.md is a prompt — read fully every session, costs tokens, and grows linearly forever. Claude Amplifier is a queryable database — Claude pulls in only what's relevant when it's relevant, and lessons that have happened three times look different from lessons that happened once.
Q: Is anything sent to a server?
No. Everything is in ~/.claude-amplifier/amplifier.db on your own disk. No telemetry, no cloud, no syncing.
Q: Why not [mem0 / Letta / MemGPT]?
Those are full-stack memory systems with embeddings, retrieval, and orchestration. Great for production agents. Claude Amplifier is an opinionated toolkit for "I want Claude to remember things and tell me when patterns recur" — same SQLite the official MCP memory server uses, with a few features that matter for actual engineering work (pattern_key, decision lifecycles, recurrence counters).
Q: Can I use this in Claude Code AND Claude Desktop simultaneously?
Yes. They share the same SQLite database, so a lesson recorded in one is visible from the other.
Q: Will my lessons survive a Claude Amplifier upgrade?
Yes — the SQLite schema is forward-compatible. The migrate() step adds new columns without touching existing rows. Backup with claude-amplifier export <project> if you want to be cautious.
Q: What's the performance like?
Reading: indexed SQLite + WAL mode. Sub-millisecond up to ~50,000 rows. Writing: same order. The bottleneck is Claude reading the context, not the database serving it.
Q: Can I share lessons across machines or teammates?
Use claude-amplifier export <project> --out lessons.json, share the file, then claude-amplifier import lessons.json on the other side. Cloud sync is intentionally not built in — your team's hard-won architectural decisions probably shouldn't leave the building.
Roadmap
The next things on the table — open an issue if any of these matter to you and you'd like it to jump:
Semantic search — embed lessons + decisions for fuzzy "do we have anything like this?" lookups (Oracle currently uses token-overlap matching)
Multi-project linking — a decision in
frontend-appcan reference a constraint frominfra-platformClaude Code SessionStart hook — auto-call
context_loadwithout needing CLAUDE.md instructionWeb dashboard — read-only browser view of what Claude remembers (still local-only)
Project archetypes —
claude-amplifier seed --archetype=nodejs-saasplants 20+ stack-specific lessonsAuto-claim recording — Claude-Code hook that wraps lessons-from-conversation into
record_claimautomatically
Data storage
~/.claude-amplifier/amplifier.dbFive tables: lessons, decisions, patterns, preferences, pattern_promotions. WAL mode enabled.
Lessons and decisions carry three v1.4.0 columns each: verification_status (claim / evidence / confirmed), confidence (0.0–1.0), and evidence_links (JSON array of evidence records).
Inspect directly with any SQLite tool:
sqlite3 ~/.claude-amplifier/amplifier.db ".tables"
sqlite3 ~/.claude-amplifier/amplifier.db "SELECT title, frequency FROM lessons WHERE frequency > 1 ORDER BY frequency DESC LIMIT 10;"
sqlite3 ~/.claude-amplifier/amplifier.db "SELECT id, title, status FROM decisions WHERE status='active';"Configuration
CLAUDE_AMPLIFIER_PROJECT
Auto-bootstraps context on server startup.
# Path (project name inferred from the directory basename)
CLAUDE_AMPLIFIER_PROJECT=/home/user/projects/my-app
# Or bare project name
CLAUDE_AMPLIFIER_PROJECT=my-appIf not set, falls back to process.cwd().
Contributing
Found a real-world pattern that should be a starter lesson? PRs welcome — see CONTRIBUTING.md.
Build from source
git clone https://github.com/Sisuthros/claude-amplifier
cd claude-amplifier
npm install
npm run build
npm test # 162 tests, all should pass
node dist/index.js helpLicense
MIT — see LICENSE.
Available Tools
13 toolsamplify_audit_freshnessA
v1.5.0 — List memory/.md files that are newer than the latest Amplifier write for a project. Use this when amplify_context_load surfaces a stale-memory warning, or when you suspect a previous session did real work without recording lessons/decisions. Surfaces unrecorded sessions so they can be triaged retroactively.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name. Use this OR project_path. | |
| project_path | No | Absolute path to the project root; the final directory name is used as the project name. If memory_dir is omitted, defaults to <project_path>/memory. | |
| memory_dir | No | Optional explicit memory directory. Defaults to <project_path>/memory or $HOME/.claude/memory. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of disclosing behavior. It communicates this is a read-only listing operation (no modifications) and its purpose (retroactive triage). Slight lack of side-effect detail, but adequate for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. Front-loaded with version and core action. Every sentence adds essential context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description sufficiently explains what it returns (list of files newer than write), the condition for its use, and the overall purpose. Complete for a filtered-list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning beyond what the schema provides, just implying use of OR between project and project_path. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists memory files newer than the latest Amplifier write for a project. It identifies the resource (memory/<YYYY-MM-DD>.md files) and action (list), and distinguishes itself by focusing on freshness audits rather than other amplify operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides two specific use cases: when amplify_context_load shows a stale-memory warning, or when suspecting unrecorded sessions. This gives clear guidance on when to employ the tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_context_loadB
Load saved context (decisions, lessons, patterns) for the current project at the start of a session.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name. Use this OR project_path. | |
| project_path | No | Absolute path to the project root; the final directory name is used as the project name. | |
| types | No | Which data types to load. Defaults to ['lessons','decisions','patterns']. Pass 'all' to include everything. | |
| max_tokens | No | v1.4.1 — soft token budget for the rendered context. Default 4000. If exceeded, lower-priority lessons are dropped and the output notes 'Showed top N of M'. Use ~20000 to see everything in a large project. | |
| priority | No | v1.4.1 — how to rank lessons when truncating. 'smart' (default) = frequency × 2 + confidence × 3 + recency_bonus + status_weight. 'recent' = newest first. 'frequency' = most-repeated first. |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states that it loads context, but does not mention whether the operation is read-only, side effects, or what happens if the project doesn't exist. This leaves significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It is front-loaded with the core action and resource, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description does not explain what the tool returns (e.g., loaded context, a summary, or just confirmation). For a tool with 5 parameters, more context on parameter interactions or output behavior is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it merely restates the purpose. Details like token budget and prioritization are adequately covered in the schema, not the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads saved context (decisions, lessons, patterns) for the current project at the start of a session. It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like amplify_learn or amplify_global_patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage at the start of a session, but does not provide explicit guidance on when not to use, prerequisites, or alternatives among siblings. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_decisionsC
Track and query architectural / design decisions for a project.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | Operation: track=add new, get=list active, search=text search, supersede/revert=replace decision, update=refine fields without superseding (v1.2.0), update_outcome=mark validation, overdue=list decisions whose check-in passed. | |
| project | No | Project name. Required for track/get. | |
| category | No | Decision category (e.g. 'architecture', 'tooling', 'security'). Defaults to 'general'. | |
| title | No | Short decision title. Required for track. | |
| description | No | Full description. Required for track. | |
| rationale | No | Why this decision was made (optional). | |
| tags | No | Tags (optional). | |
| query | No | Text to search for. Required for op=search. | |
| id | No | Decision id. Required for supersede/revert/update/update_outcome. | |
| outcome_check_in | No | When to follow up on this decision. Relative ('+7d', '+30d') or ISO date. Surfaces in 'overdue' when past due. | |
| outcome_status | No | For op=update_outcome: mark whether the decision worked. Defaults to 'validated'. | |
| restore_step | No | How to restore this decision if the system gets reset (e.g. container recreate, image pull). Surfaces in active reminders every session. | |
| next_step | No | Concrete next action when this decision is unblocked. | |
| blocked_on | No | What this decision is waiting on (person, event, dependency). | |
| trade_offs | No | Tradeoffs accepted when choosing this decision. | |
| alternatives_considered | No | Alternatives considered and rejected. | |
| supersedes | No | ID of an older decision this one replaces. The old one is automatically marked 'superseded'. | |
| relations | No | Knowledge-graph links to other decision IDs by relation type. |
TDQS
C2.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full behavioral disclosure burden. It outlines core operations (track, get, search, supersede, etc.) but doesn't detail side effects, auth requirements, or data persistence. The schema provides parameter details but not behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. However, given the tool's complexity (18 parameters, multiple operations), the description is too brief and could benefit from a more structured format (e.g., bullet points) to improve scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with many operations and nested objects, the description is minimal. No output schema exists, and the description doesn't explain return values or result formats. The effort required from the agent to understand behavior is higher than necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The one-line description adds no additional parameter-level semantics beyond the schema. Baseline 3 is appropriate as the schema already explains inputs well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool tracks and queries architectural/design decisions, using a specific verb and resource. It distinguishes the tool's domain (decisions) from siblings like amplify_evidence_chain or amplify_record_claim, though it doesn't explicitly differentiate operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description only states the broad function without mentioning prerequisites, context, or exclusions. The schema lists operations but doesn't provide usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_evidence_chainB
v1.4.0 — Show the evidence chain that supports a stored lesson or decision. Useful for auditing why Amplifier 'knows' something — surfaces commits, test runs, and user confirmations that promoted a claim to confirmed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| kind | No | lesson |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It reveals that the tool surfaces commits, test runs, and confirmations, but does not explicitly state it is read-only or side-effect free.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each essential: first states purpose, second adds behavioral context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema coverage and no output schema, the description should more fully explain parameters and behavior. It omits details about the required 'id' parameter and the 'kind' enum, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the parameters 'id' or 'kind' at all. The description adds no meaning beyond the schema, leaving the agent without guidance on what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows the evidence chain for a stored lesson or decision, with specific verb 'show' and resource 'evidence chain'. It distinguishes from siblings by focusing on auditing the provenance of knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Useful for auditing' which implies context, but does not explicitly state when to use this tool versus alternatives like amplify_verify_claim or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_global_patternsB
Manage cross-project patterns (best practices, conventions) that apply to all or multiple projects.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | get=list all patterns, add=record a new pattern. | |
| title | No | Pattern name. Required for op=add. | |
| description | No | What the pattern is and when to apply it. Required for op=add. | |
| example | No | Concrete code or command example (optional). | |
| tags | No | Tags (optional). | |
| applies_to | No | Project scope: 'all' (default) or a comma-separated list of project names. |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states 'manage' without detailing effects like whether adding a pattern immediately affects projects, required permissions, or side effects. The op enum in the schema hints at operations, but the description adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose. It is concise without unnecessary words. While it could be more informative, it avoids verbosity and is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no output schema, and no annotations, the description is insufficient. It does not explain the two operations (get/add), the required fields, or the behavior of adding a pattern. The schema covers parameters, but the description lacks high-level context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not explain how parameters like 'applies_to' work or provide examples. It meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it manages cross-project patterns, which is a specific verb+resource. It implicitly distinguishes from sibling tools like amplify_promote_pattern (which likely promotes individual patterns) by focusing on global application. However, 'manage' is somewhat vague and does not specify the exact operations (get/add) that the schema provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context that this tool is for patterns applying to all or multiple projects, which implies when to use it. But it does not explicitly state when not to use it or mention alternative tools (e.g., amplify_promote_pattern). The usage is implied but not clarified with exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_learnB
Record a lesson — a mistake, success, or insight — so Claude remembers it in future sessions.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name (e.g. 'my-app' or 'work/api-service'). | |
| type | No | Category of the lesson. | |
| title | Yes | Short, descriptive title. | |
| description | Yes | What happened and why it matters. | |
| context | No | Surrounding circumstances (optional). | |
| resolution | No | How the issue was resolved (optional). | |
| prevention | No | How to avoid this in future (optional). | |
| severity | No | Impact level. Defaults to 'medium'. | |
| tags | No | Tags for filtering (optional). | |
| trigger | No | The specific situation or action that triggers this lesson — useful for pattern detection (optional). | |
| pattern_key | No | v1.2.0 — explicit pattern grouping key (e.g. 'read-docs-before-coding'). When set, recording another lesson with the same key for this project bumps a frequency counter instead of creating a duplicate. Use this when the same lesson recurs with different wording each time. (optional) |
TDQS
B3.4/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'remembers in future sessions' implying persistence, but lacks details on side effects, idempotency, or deduplication behavior (though pattern_key hints at it, the description does not explain). The tool's complexity (11 params) warrants more transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the tool's complexity (11 parameters, many optional), the description is underspecific. It does not explain what the agent should expect after recording (e.g., return value, success indication) or guide usage of optional fields like context, resolution, prevention, trigger, pattern_key.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing baseline value. The description adds a general purpose statement but does not enhance understanding of individual parameters beyond the schema's own descriptions. No additional semantics or context are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a lesson (mistake, success, insight) for future recall. It uses a specific verb 'record' and resource 'lesson', distinguishing it from sibling tools like amplify_record_claim or amplify_global_patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when the agent wants to save a lesson for future sessions, but it does not explicitly contrast with alternatives like amplify_record_claim or amplify_evidence_chain. No when-not-to-use or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_link_decisionsA
v1.2.0 — Add a knowledge-graph link between two existing decisions. Lightweight: one call = one link. Idempotent.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | ID of the decision that holds the link. | |
| to | Yes | ID of the decision being linked to. | |
| relation | Yes | Relation type: triggered_by=this was caused by `to`; caused=this led to `to`; relates_to=loose association. |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses idempotency and lightweight nature, but does not mention potential errors (e.g., if decisions don't exist) or side effects. Adequate for a simple creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that are front-loaded with version and core action. Every word is necessary and adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description effectively covers the tool's purpose, usage pattern, and behavioral hint (idempotency). Could mention that decision IDs must exist, but that is reasonably implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds no further meaning to the parameters beyond 'lightweight' and 'idempotent' context, which is baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a knowledge-graph link between two existing decisions,' providing a specific verb and resource. It distinguishes itself from sibling tools (e.g., amplify_audit_freshness, amplify_verify_claim) by specifying 'link' operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context with 'Lightweight: one call = one link. Idempotent.' This implies when to use (single link creation) and that it's safe to retry. It does not explicitly state when not to use, but the purpose is self-contained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_preflightA
v1.4.0 — Before starting a task, check stored lessons + decisions for matching failure patterns. Returns risk_level (low/medium/high/critical), matched patterns and lessons, and suggested approach. Call this BEFORE diving in when working on something that touches a familiar area.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name. | |
| prompt | No | The task / prompt about to be executed (free text). The oracle scans for matching prior issues. Alias: 'task'. | |
| task | No | Alias for 'prompt'. Either field is accepted. | |
| context | No | Optional extra context (file names, recent commits, etc.) that improves matching. |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Discloses that it queries stored lessons/decisions and returns structured output. Implies read-only but doesn't explicitly state idempotency or side effects. Good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences plus a brief call to action. Version number is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return fields (risk_level, matched patterns, etc.) despite no output schema. Covers all 4 parameters. Could explicitly state idempotency or read-only nature, but overall sufficient for a preflight check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by noting alias for 'prompt' ('task') and clarifying 'context' parameter as optional extra info. Slightly improves understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('check') + resource ('stored lessons + decisions') and outcome ('Returns risk_level...'). Distinguishes from sibling tools by focusing on preflight checks before task execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call this BEFORE diving in when working on something that touches a familiar area.' Provides strong when-to-use guidance. Lacks explicit when-not-to-use, but context implies use for familiar areas where failure patterns exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_promote_from_memory_mdA
v1.5.0 — Read a memory/.md file and surface DRAFT suggestions for amplify_learn / amplify_decisions follow-up calls. Heuristics: architectural Wrote: lines (plan/decision/architecture/blueprint/manifesto), >50 events per hour, ≥8× repeated tool/terminal calls. Returns drafts only — never writes to SQLite. Use when amplify_audit_freshness flagged a stale day worth triaging.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| memory_file | Yes | Absolute path to a memory/<YYYY-MM-DD>.md file (or any file in the same format). |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that the tool is read-only ('Returns drafts only — never writes to SQLite') and describes the heuristics used. This gives an agent a clear understanding of side-effect-free behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that front-loads the action and version, then provides heuristics, safety, and usage guidance. Every sentence adds value with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, no annotations, and no output schema, the description is remarkably complete. It covers purpose, heuristics, safety, and usage context, leaving little ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with 100% schema description coverage. The schema already explains the parameter well. The description restates the path pattern but does not add new semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Read a memory/<YYYY-MM-DD>.md file and surface DRAFT suggestions for amplify_learn / amplify_decisions follow-up calls.' It specifies the verb and resource, and distinguishes from siblings by mentioning heuristics and its role after amplify_audit_freshness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Use when amplify_audit_freshness flagged a stale day worth triaging.' It also implies not to use if you need writes ('never writes to SQLite'). However, it does not explicitly exclude other sibling tools or provide full alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_promote_patternA
v1.4.0 — Promote a pattern_key from per-project to global scope. Requires the key to exist in ≥2 projects with ≥1 confirmed lesson. After promotion the pattern weighs more in cross-project Pattern Oracle scoring.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pattern_key | Yes | Pattern key to promote (must exist on ≥2 projects). |
TDQS
A3.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It mentions prerequisites and effect on scoring, but omits what happens to the per-project pattern after promotion (e.g., is it removed?), whether the operation is reversible, or any side effects. This is incomplete for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the purpose and then provides conditions and effect. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description covers purpose, prerequisite, and effect. But it lacks details on error cases, idempotency, and what happens to the original pattern. It is minimally adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description adds context about the prerequisite and effect, but does not enhance understanding of the parameter beyond what the schema already provides. No additional parameter details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Promote' and the resource 'pattern_key', specifying the scope change from per-project to global. It is distinct from siblings like 'amplify_global_patterns' which lists global patterns, and 'amplify_learn' which is about learning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit prerequisites: 'Requires the key to exist in ≥2 projects with ≥1 confirmed lesson.' It also explains the consequence of promotion. However, it does not provide alternative tools for when to not use this tool, but the conditions are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_record_claimA
v1.4.0 — Record a lesson as an UNVERIFIED claim (default confidence 0.5). Use this for any 'I just learned X' moment that has not been confirmed by tests, commits, or user confirmation. Promote later with amplify_verify_claim. (amplify_learn remains for confirmed/legacy records.)
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| type | No | ||
| title | Yes | ||
| description | Yes | ||
| context | No | ||
| resolution | No | ||
| prevention | No | ||
| severity | No | ||
| tags | No | ||
| trigger | No | ||
| pattern_key | No | Explicit pattern grouping key for aggregation across worded variants. | |
| initial_confidence | No | Override starting confidence (default 0.5). |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the unverified nature and default confidence but omits details like response format, error conditions, or duplicate handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and front-loaded, conveying version, purpose, usage context, and sibling differentiation efficiently, though could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters and no output schema, the description lacks explanation for most parameters and does not describe the return value or behavior beyond recording, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17%; the description only clarifies 'initial_confidence' as an override. Most parameters (type, context, resolution, etc.) remain unexplained, failing to compensate for the schema's gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it records an unverified claim with default confidence 0.5, distinguishing it from amplify_learn for confirmed/legacy records and mentioning promotion via amplify_verify_claim.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool ('I just learned X' moments not confirmed) and when to use siblings (amplify_learn for confirmed records), providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_suggest_pattern_keyA
v1.5.0 — Suggest an existing pattern_key (or propose a new one) for a lesson before recording it. Use this before amplify_learn when you suspect the lesson is a recurring pattern. Prevents the failure where two sessions invent two different keys for the same lesson and the frequency counter never aggregates. Returns up to 3 existing keys ranked by trigram similarity, or a new key suggestion if none clear the threshold.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name. | |
| title | Yes | The lesson title you intend to record. | |
| description | Yes | The lesson description (helps disambiguate). |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it returns up to 3 existing keys ranked by trigram similarity, or a new key suggestion if none clear the threshold. It also explains the consequence of not using it (frequency counter never aggregates). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the purpose and then provide usage context and outcome. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return values adequately. All params are documented, and the tool's behavior and usage context are fully covered. Complete for a suggestion tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description. The description adds context by explaining that title and description help disambiguate, and that the tool uses them to find similar keys. This adds meaning beyond the schema, but not extensive format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to suggest an existing pattern_key or propose a new one for a lesson before recording. It specifies the verb 'suggest' and the resource 'pattern_key', and distinguishes it from siblings by noting it should be used before amplify_learn to prevent key duplication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool: 'Use this before amplify_learn when you suspect the lesson is a recurring pattern.' It also explains why (prevents failure of aggregation) and what it returns (up to 3 existing keys or a new suggestion). This provides clear guidance on when and why to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
amplify_verify_claimA
v1.4.0 — Attach evidence to a lesson to promote it. Promotion rules: (claim + 1 evidence) → 'evidence' (conf 0.7); (evidence + user_confirmation OR ≥2 distinct evidence types) → 'confirmed' (conf 1.0). Use this when tests pass, a commit lands, or the user explicitly confirms.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Lesson id to verify. | |
| evidence_type | Yes | ||
| evidence_link | Yes | Git SHA, test ID, URL, or short note — proof of the claim. | |
| promote_to | No | Optional override (default: follow auto-promotion rules). |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It accurately describes promotion logic and optional override, but omits side effects, error handling, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus version number. Every word adds value: purpose, promotion rules, and usage context. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema not provided. Description covers when to use and promotion rules but lacks return value details, error conditions, or idempotency info. Adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, baseline is 3. The description adds context about the promote_to parameter's default behavior but does not significantly elaborate on other parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool attaches evidence to promote a lesson, with explicit promotion rules and scenarios. Differentiates from sibling tools like amplify_record_claim by focusing on verification and promotion based on evidence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when tests pass, a commit lands, or the user explicitly confirms,' providing clear context. However, it does not mention when not to use or suggest alternatives.
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.
13 tool updates
v1.5.3- First observed
amplify_audit_freshness - First observed
amplify_context_load - First observed
amplify_decisions - First observed
amplify_evidence_chain - First observed
amplify_global_patterns - First observed
amplify_learn - First observed
amplify_link_decisions - First observed
amplify_preflight - First observed
amplify_promote_from_memory_md - First observed
amplify_promote_pattern - First observed
amplify_record_claim - First observed
amplify_suggest_pattern_key - First observed
amplify_verify_claim
TDQS
A3.8/5.0
Scored across 13 tools
Disambiguation5/5
Each tool has a clearly distinct purpose: lessons (learn, record_claim, verify_claim), decisions (decisions, link_decisions), patterns (global_patterns, promote_pattern, suggest_pattern_key), context (load, preflight), and auditing (audit_freshness, evidence_chain, promote_from_memory_md). No two tools overlap in function or intent.
Naming Consistency5/5
All tools consistently use the pattern 'amplify_verb_noun', with verbs like audit, load, learn, link, promote, record, suggest, verify. No mixing of conventions or camelCase; every name is descriptive and predictable.
Tool Count5/5
13 tools provide a comprehensive yet focused surface for knowledge management. The count covers all core workflows (recording, querying, linking, promoting, auditing) without being bloated or insufficient.
Completeness4/5
The tool set covers the full lifecycle of lessons, decisions, and patterns: creation, querying, linking, promotion, and verification. A minor gap is the lack of explicit listing or deletion tools, but these may be subsumed by existing query tools (e.g., amplify_decisions likely returns lists).
Maintenance
ActivitySlowing
ResponsivenessSyncing
Related MCP Connectors
Memory MCP server for Claude Code. Correct a fact and the old version stops being recalled.
Cloud-hosted MCP server for durable AI memory
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives Claude persistent memory by storing conversation context, entities, and enabling semantic search across sessions.21 npm1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives Claude Desktop persistent memory, self-awareness, epistemic hygiene, and genuine agency across conversations with a typed memory system, embedding-based semantic search, a 3-judge memory jury, and a real-time dashboard.7MIT
M5 Petit Memoryofficial
AlicenseNot gradedqualityCmaintenanceAn MCP server that gives Claude-based agents persistent long-term memory with semantic search, BM25 hybrid reranking, associative recall, episode grouping, and sleep consolidation.Apache 2.0