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" \
  --workflow fix \
  --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 61 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

Recommended: install both — still free, no API key needed.

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

Then say "what can attune do?" in Claude Code, and run attune in your terminal — it shows your next steps (attune validate checks the setup). The plugin runs on your Claude subscription, and memory, forms, and hooks never call a model; an API key is only for direct CLI workflow runs (What this costs).

Just want the skills? The plugin alone (the first two commands) works standalone — no Python required.

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 16.1.0 — harness-lite lands

16.0.0 executed the destructive half of the harness-lite architecture ruling: nine dead framework-era modules deleted (~2,200 lines, each verified caller-free before removal), every 15.x deprecation executed on schedule, and the ceremony entry-point seams collapsed to direct registration. 16.1.0 closes the loop on the removal: an extension still declaring the removed attune.plugins / attune.wizards entry points used to fail by silent non-loading — now a once-per-process warning names the package and points at the migration guide.

Upgrading is a no-op if you use the CLI, the plugin, or the MCP tools. The 16.0.0 upgrade guide opens with the one grep that tells you whether any of this touches your code. The constructive half — the extension system — ships later in 16.x.

Every attune surface has exactly one name, one contract, and one place to register. 15.0.0 completed a consolidation that ran across several releases: what the docs describe is what the library has, with no second spelling of it kept alive out of habit. One name for the MCP server (AttuneMCPServer); one registration path per extension (collapsed further to direct registration in 16.0.0); the 1–5 level dial retired from every public API. A smaller surface to hold in your head, which is the whole point: less API, and all of it real.

---

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) — spec-driven development, with receipts: the approved spec drives the agents — Claude Code, Codex, or Antigravity alike. Requirements, design, and a gated task ladder the agent executes between your approvals — workflows dispatched, 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.
• Workflows prove they work — a planted-defect harness runs every catalog workflow against a fixture carrying a known bug (a real eval call, a real CVE pin, a module with no docstrings); finding it is what keeps the workflow's "working" badge, with cost and verdict recorded in a tracked registry. Workflows under repair are hidden from the dashboard, CLI list, and MCP catalog until their probes pass.

---

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 (6): auth_status auth_recommend telemetry_stats context_get context_set list_capabilities

Elicitation (7): elicitation_ask elicitation_render_form elicitation_collect_response elicitation_render_widget chart_render_widget fix_workspace_preview fix_workspace_collect_action

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 question, five control types — a recommended decision card with per-option tradeoffs, multi-select, dropdown, bounded number, free text. An empty submit is caught by validation, never silently accepted. Rendered by the production widget pipeline (regenerate); try it live.

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 — powered by the bundled attune-rag engine — enforces citation-per-claim: 0.97 mean per-claim faithfulness, CI-gated (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.