attune-ai MCP Server

Attune AI

Persistent memory and receipt-verified workflows for Claude Code.

🌐 Docs & guides: attune-ai.dev

---

Your agent stops starting from zero, its word stops being the evidence, and it asks you with structure instead of prose.

Memory: a stash → recall → promote loop carries decisions, bugs, and hard-won lessons from one session into the next, and surfaces the right lesson at the exact moment a prompt needs it. Local-first, from a plain pip install attune-ai. Recall loads a few hundred exactly-relevant tokens instead of your whole corpus — 67× fewer tokens on our own 800+ lesson store, retrieved at P@3 96% on a frozen benchmark (details).

Receipts: state the outcome you want and how to verify it, and get back a receipt — not a promise:

attune fix "imports resolve after the rename" \
  --scope src/attune/cli_minimal.py \
  --probe "pytest tests/unit/test_cli_minimal.py" \
  --run

The probes are re-run independently of the workflow that claims it finished. Exit 0 means the probes passed — not that the agent felt good about it.

Interactive forms: the agent asks with structure, not prose — a decision card with its recommendation and tradeoffs, a pushback card when it disagrees, a progress report, a ranking or triage — one tap each, validated on the way back. One form renders to whatever surface your client draws: a native dialog, a rich widget, or a plain menu (the vocabulary).

Around that core: 21 workflows and 59 MCP tools dispatching 2–6 domain-specific subagents behind Socratic quality gates, RAG grounding with a citation-per-claim contract, and generation fact-checking — one install, one MCP server. We run our own knowledge base on it: the docs and 800+ engineering lessons at attune-ai.dev are authored, grounded, and maintained by Attune's own stack.

Contents: Install · Costs · Memory · Receipts · Multi-LLM · Workflows & tools · Forms · Accuracy · Install options · Privacy

---

Get Started in 60 Seconds

Plugin (works standalone)

claude plugin marketplace add Smart-AI-Memory/attune-ai
claude plugin install attune-ai@attune-ai

Then say "what can attune do?" in Claude Code.

Add the Python package (unlocks CLI + MCP)

pip install attune-ai
attune            # shows your next steps

Then check your setup with attune validate and run your first workflow: attune workflow run code-review --path src/.

Setup fight you? Tell me where — I'm actively fixing this.

What each layer adds

---

What this costs

The one thing people get wrong: a Claude Pro/Max subscription does not include API credits — they are separate products. If you only use the plugin, this never comes up. Free on either path (they never call a model): elicitation forms, security hooks, path validation, memory storage and recall, and every local transform.

---

New in 15.0.0 — one obvious way to do each thing

Every attune surface now has exactly one name, one contract, and one place to register. 15.0.0 completes a consolidation that has run across the last several releases: what the docs describe is what the library has, with no second spelling of it kept alive out of habit.

What that buys you:

• One entry point per extension. Workflows register under attune.workflows, plugins under attune.plugins. That is the whole rule. Three groups used to be in play and only some were actually read, so a registration that looked correct could quietly never load — that class of silent miss is gone.
• One name for the MCP server, AttuneMCPServer, everywhere it appears.
• Nothing vestigial to learn. The 1–5 level dial is retired from every public API — the plugin contract, both agent configs, the registries, and the two MCP tools that read it. Its meaning came from a framework attune no longer ships, so every new user had to ask what it did. Now nobody has to. The core MCP tool surface is 48 tools, all of them live.
• A smaller surface to hold in your head, which is the whole point: less API, and all of it real.

Upgrading is a no-op if you use the CLI, the plugin, or the MCP tools. If you write third-party plugins or workflows, the 15.0.0 upgrade guide opens with an "are you affected?" table — ten rows, each with its one-line fix, and two that need nothing from you at all: a legacy empathy_level: key in agents.md is now ignored rather than an error, and an existing metrics database migrates itself on first open.

Every workflow in your catalog comes with evidence behind it. 14.1.0 shipped a planted-defect validation harness: each workflow is run against a fixture carrying a known bug — a real eval call, a real CVE pin, a module with no docstrings — and has to find it to keep its "working" badge. Not "exited 0": actually caught the planted defect, with the cost and verdict recorded in a tracked registry you can read.

That shows up in three places: secure-release reads its sub-audits' real findings (a planted-critical fixture that used to sail through as GO comes back NO_GO); the documentation orchestrator detects missing docstrings and says "not assessed" rather than fabricating "no gaps found"; and every discovery-sweep lane gets a measured-cost budget floor, so a lane either runs with enough money to finish or tells you it skipped. The few workflows still being repaired are hidden from the dashboard, CLI list, and MCP catalog until their probes pass — so everything you can click actually works.

---

The memory suite — measured

Stash on stop. Recall at the door. Promote what endures.

• Stash — a Stop hook extracts decisions, bugs, and references from the session and writes them to the memory store (local file by default, Redis Agent Memory Server when reachable).
• Recall — a SessionStart hook surfaces the most recent findings for your project; /recall <topic> searches on demand.
• Promote — a reviewed stash→curated path lands git-tracked .md files in your corpus. Files are the store; Redis serves them.
• Lessons at the trap moment — hooks retrieve the exact lesson a prompt or tool call needs, budget-capped no matter how large the corpus grows.

Memory is local-first — nothing leaves your machine, and without Redis everything degrades to the file backend with clear guidance. The economics are measured, not promised (2026-07-05 snapshot; ratios improve as the corpus grows):

Numbers from benchmarks/memory_savings.py on our dogfood store.

---

Receipts, not promises

If you know acceptance-test-driven development, this is that rebuilt for agent workflows: acceptance probes are declared up front, and the agent's own word is never the evidence.

• Fix Receipts (attune fix) — outcome-first fixing. Preview a contract (done conditions, constraints, probes) with nothing executing; add --run for an attributed diff whose probes are re-run independently. Exit 0 only when the probes pass.
• Spec Ladders (/spec) — goal-driven specs you approve rung by rung: requirements, design, and a gated task ladder, every ruling recorded in a decision file that outlives the session.
• Guided intakes — /fix and /spec compose their contracts through a form: goal pre-filled, scope picker from paths you've touched, probe suggestions from matching tests.
• Receipts all the way down — a failed or absent security auditor fails the Security gate; spec-closure claims draw a rotating skeptic seat; risk-class diffs authored by the lead model are reviewed by a different model before promotion.

---

Multi-LLM collaboration

As of 10.6.0, attune treats Claude Code, OpenAI Codex, and Google Antigravity as seats at the same table — with the discipline that a claim without a receipt doesn't ship:

• /roundtable — the three models deliberate a question on a Redis-backed board; you chair what gets promoted.
• /cross-review — an advisory second opinion on a real diff from a different model than the one that wrote it.
• Cross-provider handoff + shared session memory — portable resume briefs and a provider-neutral stash/recall surface with a PII/secrets gate that redacts at rest and fails closed.
• A projected collaboration contract — one master file projects to AGENTS.md and per-provider mirrors.

Codex installs the same plugin from its marketplace (codex plugin install attune-ai@attune-ai); Antigravity connects over MCP. The 10.6.1 release exists because a cross-provider receipt probe caught a protocol bug the primary client silently tolerated.

---

Workflows and MCP tools

Skills trigger from natural language — "review my code", "scan for vulns", "generate tests", "plan this feature" — and every workflow dispatches 2–6 subagents (Opus for deep reasoning, Sonnet for analysis, Haiku for fast scanning), synthesized by an orchestrator. Ready-made Claude Code subagents (security-reviewer, spec-author, refactor-planner, …) appear in your /agents list on install.

Workflow (22): security_audit code_review bug_predict discovery_sweep performance_audit refactor_plan simplify_code deep_review test_generation test_audit test_gen_parallel doc_gen doc_audit doc_orchestrator release_notes health_check dependency_check secure_release research_synthesis analyze_batch analyze_image rag_knowledge_query

Help (5): help_lookup help_init help_status help_update help_maintain

Memory (4): memory_store memory_retrieve memory_search memory_forget

Personal Memory (4): personal_memory_capture personal_memory_recall personal_memory_topics personal_memory_forget

Utility (8): auth_status auth_recommend telemetry_stats context_get context_set attune_get_level attune_set_level list_capabilities

Elicitation (5): elicitation_ask elicitation_render_form elicitation_collect_response elicitation_render_widget chart_render_widget

Handoff (2): handoff_create handoff_resume

Redis memory (11): session_memory_*, redis_memory_*, redis_health_check

---

Interactive forms — the agent asks with structure

Agent↔you exchanges are interactive forms, not prose Q&A. The agent presents a decision with its recommendation, rationale, and per-option tradeoffs; disagrees through a pushback card (your approach vs. its alternative, side by side); reports progress as done / in-flight / blocked; and has you rank, triage, confirm, deliberate, or review its assumptions — one tap each. Every question is validated on the way back, so a malformed answer is re-asked, not silently accepted.

One declarative form, written once, renders to the richest surface your client supports — a native dialog, a rich HTML widget, or a plain multiple-choice menu on a text-only surface — so the same question works everywhere and degrades gracefully. The full construct vocabulary ships via attune-forms 0.7.0 (new in 13.0.0). Chart specs render through the same sealed SVG kernel (chart_render_widget, nine chart types).

---

Accuracy & Faithfulness

RAG generation enforces citation-per-claim: 0.98 mean per-claim faithfulness, CI-gated at ≥ 0.97 (40-query golden set, N=20 runs). The contract was chosen by A/B measurement — the per-query hallucination bucket rate dropped from 46.7% to 6.7% with it (methodology). Retrieved passages are sentinel-wrapped against prompt injection. The help resolver passes 48/48 benchmark queries at P@1 (golden set).

---

Installation Options

pip install attune-ai works out of the box — the CLI, all workflows, the MCP server, RAG (attune-rag and attune-verify are core dependencies), cross-session memory, and the Agent SDK. Memory features activate when a Redis Stack server is reachable and degrade with guidance when not. Add extras only for the surfaces you use:

Extras combine — pip install 'attune-ai[developer,ops]'. Keep the quotes: zsh and bash treat square brackets as glob characters.

Contributing? Clone and install the dev toolchain instead:

git clone https://github.com/Smart-AI-Memory/attune-ai.git
cd attune-ai && pip install -e '.[dev]'

API mode

The CLI and MCP tools call the Anthropic API directly (the plugin never needs this):

export ANTHROPIC_API_KEY="sk-ant-..."      # requires API credits
export REDIS_URL="redis://localhost:6379"  # optional

Model routing assigns Opus/Sonnet/Haiku by task complexity (ATTUNE_AGENT_MODEL_* to override); depth budgets run $0.50 / $2.00 / $5.00 (ATTUNE_MAX_BUDGET_USD to override); --cheap forces pattern-matching workflows onto Haiku. Live spend tiles on the dashboard (attune ops).

Redis has no native Windows build — use Docker (docker run -d -p 6379:6379 redis:7-alpine). Without reachable Redis, memory degrades gracefully to the file backend and attune.memory.session_stash.backend_status() reports fallback: true.

---

Ecosystem

---

Security, Privacy & Telemetry

Path traversal protection on all file ops, a PreToolUse guard that blocks eval/exec, MCP rate limiting, prompt sanitization, and automated scanning (CodeQL, bandit, detect-secrets) — details in SECURITY.md.

Usage data is local-first. An opt-in, anonymous usage ping (OFF by default) carries only package, version, workflow name, OS, Python version, a resettable anonymous id, and a timestamp — never paths, code, prompts, or filenames; the payload is frozen in source and guarded by a regression test. attune telemetry status|enable|disable; DO_NOT_TRACK=1 always wins.

---

Links

• Full Documentation
• Plugin Setup
• GitHub Repository

Apache License 2.0 — Free and open source.

If you find Attune useful, give it a star — it helps others discover the project.

Acknowledgments

• Anthropic — For Claude AI, the Model Context Protocol, and the Agent SDK patterns behind the multi-agent orchestration layer
• Boris Cherny — Creator of Claude Code, whose workflow posts validated Attune's plan-first, multi-agent approach
• Affaan Mustafa — For battle-tested Claude Code configurations that inspired the hook system

View Full Acknowledgements

---

Built by Patrick Roebuck using Claude Code.