If the README felt overwhelming, use this section first.
Hoofy is an MCP server that gives your AI persistent memory + spec-driven workflow.
It prevents the classic AI failure modes: forgetting context, hallucinating requirements, and skipping planning.
Hoofy — AI development companion MCP server. Persistent memory, spec-driven development, adaptive change pipeline, Clarity Gate. 32 tools, single Go binary, zero deps.
星标
16
工具
—
可用率
—
It works with Claude Code, Cursor, VS Code Copilot, OpenCode, Gemini CLI (and any MCP-compatible tool).
You can use it for new projects, ongoing changes, or existing projects without specs.
Install, connect MCP, and start with a small change.
60-Second Quick Start
Install Hoofy: brew install HendryAvila/hoofy/hoofy (or use the install script below).
Connect MCP: claude mcp add --scope user hoofy hoofy serve (or use your editor's MCP config).
Ask your AI to implement a change — Hoofy guides planning + memory automatically.
What Is Hoofy? — AI Development Companion for MCP
Hoofy solves three recurring AI-dev problems: memory loss between sessions, hallucinated implementations, and unstructured workflows. It's a single MCP (Model Context Protocol) server written in Go — one binary, zero external runtime dependencies.
Choose your path
New project → run the full project pipeline (sdd_init_project → ... → sdd_validate)
Existing project, adding/fixing something → start with sdd_change
Existing project with no specs yet → sdd_reverse_engineer + sdd_bootstrap
Just need context/review quickly → sdd_suggest_context, sdd_review, sdd_audit
Core systems (at a glance)
System
What it does
Tools
Memory
Persistent context across sessions using SQLite + FTS5 full-text search.
mem_* tools
Change Pipeline
Adaptive flow for ongoing work based on change type × size (12 variants).
sdd_change*, sdd_adr
Project Pipeline
Full greenfield specification flow with Clarity Gate (9 stages).
sdd_* project tools
Bootstrap
Reverse-engineer existing codebases into requirements, rules, and design artifacts.
sdd_reverse_engineer, sdd_bootstrap
Key features (most important)
Principles-first pipeline — define non-negotiables before requirements.
Clarity Gate — blocks vague specs before implementation starts.
Context-check on every change — catches conflicts early.
Spec-aware review/audit — compare code against requirements and rules.
Project Charter — The old "proposal" stage is now a charter with domain context, stakeholders, vision, boundaries, success criteria, existing systems, and constraints.
Spec-vs-Code Audit — sdd_audit compares specifications against source code to detect missing implementations and drift.
Facade-First Tooling — unified memory entry points: mem_save and mem_session.
Business Rules Stage — BRG + DDD extraction before Clarity Gate.
Pre-pipeline Exploration — sdd_explore captures goals/constraints/unknowns before formal pipeline work.
Wave Assignments — task dependency waves for parallel execution planning.
Decision: "Switched to JWT" →(caused_by)→ Discovery: "Session storage doesn't scale"
↑(implements) ↑(relates_to)
Bugfix: "Fixed token expiry" Pattern: "Retry with backoff"
Why Hoofy?
AI coding assistants are powerful but forgetful and overconfident. Studies show experienced developers are 19% slower with unstructured AI (METR 2025), and AI adoption without structure causes 7.2% delivery instability (DORA 2025). Hoofy fixes this by making your AI remember context, follow specifications, and validate understanding before coding.
# Go install (requires Go 1.25+)
go install github.com/HendryAvila/Hoofy/cmd/hoofy@latest
# Or build from source
git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build
2. Connect to your AI tool
MCP Server vs Plugin — what's the difference?
The MCP server is Hoofy itself — the binary you just installed. It provides memory, change pipeline, project pipeline, bootstrap, and standalone tooling through MCP and works with any MCP-compatible AI tool.
The Plugin is a Claude Code-only enhancement that layers additional capabilities on top of the MCP server:
Component
What it does
Agent
A custom personality (Hoofy the horse-architect) that teaches through concepts, not code dumps. Enforces SDD discipline — the AI won't skip specs.
Skills
Loadable instruction sets for specific domains (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). The agent auto-detects context and loads the right skill before writing code.
Hooks
Lifecycle automation — PreToolCall and PostToolCall hooks that trigger memory operations automatically (e.g., saving session context, capturing discoveries after tool use).
The plugin is optional — you get full Hoofy functionality with just the MCP server. The plugin just makes the experience smoother in Claude Code.
MCP Server — one command, done:
claude mcp add --scope user hoofy hoofy serve
Plugin (optional, Claude Code only) — adds agent + skills + hooks on top of the MCP server:
Just talk to your AI. Hoofy's built-in instructions tell the AI when and how to use each system.
4. Update
hoofy update
Auto-checks on startup, updates when you say so.
5. Reinforce the behavior (recommended)
Hoofy already includes built-in server instructions, but a short policy block in your agent instructions file reinforces the workflow.
Note:sdd_init_project auto-generates this in agent files. Add manually only if you run Hoofy in MCP-only mode.
Put this in your tool-specific instruction file:
Claude Code: CLAUDE.md
Cursor: .cursor/rules/hoofy.md
OpenCode: AGENTS.md
VS Code Copilot: .github/copilot-instructions.md
Gemini CLI: GEMINI.md
## Hoofy — Spec-Driven Development
Before coding any non-trivial change, use Hoofy specs first.
- New projects: `sdd_init_project` -> full pipeline
- Existing projects without specs: `sdd_reverse_engineer` -> `sdd_bootstrap`
- Ongoing work: `sdd_change` (size/type adaptive)
- Ad-hoc sessions: `sdd_suggest_context`
- Reviews: `sdd_review`
- Spec/code drift checks: `sdd_audit`
- Memory: `mem_save`, `mem_session`
Best Practices
1. Specs before code — always
The AI will try to jump straight to coding. Don't let it. For any non-trivial work:
New project? → sdd_init_project and walk through the full 9-stage pipeline
New feature? → sdd_change(type: "feature", size: "medium") at minimum
Bug fix? → Even sdd_change(type: "fix", size: "small") gives you context-check → describe → tasks → verify
The cheapest stages (context-check + describe + tasks + verify) take under 2 minutes and save hours of debugging hallucinated code.
2. Explore before you plan
Before jumping into a pipeline, use sdd_explore to capture context from your discussion — goals, constraints, tech preferences, unknowns, decisions. It saves structured context to memory so the pipeline starts with clarity, not guesswork. Call it multiple times as your thinking evolves — it upserts, never duplicates.
3. Bootstrap existing projects
Working on a project that never went through SDD? Don't skip specs — bootstrap them. Run sdd_reverse_engineer to scan the codebase, then sdd_bootstrap to generate the missing artifacts. This takes under a minute and means the change pipeline works with full context instead of flying blind. Medium/large changes are blocked without specs — and that's intentional.
4. Right-size your changes
Don't use a large pipeline for a one-line fix. Don't use a small pipeline for a new authentication system.
You don't need to tell the AI to use memory — Hoofy's built-in instructions handle it. But you'll get better results if you:
Start sessions by greeting the AI — it triggers mem_context to load recent history
Mention past decisions — "remember when we chose SQLite?" triggers mem_search
Confirm session summaries — the AI writes them at session end, review them for accuracy
6. Connect knowledge with relations
Hoofy's knowledge graph lets you connect related observations with typed, directional edges — turning flat memories into a navigable web. The AI creates relations automatically when it recognizes connections. You can also ask it to relate observations manually. Use mem_get(id=..., depth=...) to explore the full graph around any observation.
7. Use topic keys for evolving knowledge
When a decision might change (database schema, API design, architecture), use topic_key in mem_save. This updates the existing observation instead of creating duplicates. One observation per topic, always current.
8. One change at a time
Hoofy enforces one active change at a time. This isn't a limitation — it's a feature. Scope creep happens when you try to do three things at once. Finish one change, verify it, then start the next.
9. Trust the Clarity Gate
When the Clarity Gate asks questions, don't rush past them. Every question it asks represents an ambiguity that would have become a bug, a hallucination, or a "that's not what I meant" moment. Two minutes answering questions saves two hours debugging wrong implementations.
10. Hoofy is the architect, Plan mode is the contractor
If your AI tool has a plan/implementation mode, use it after Hoofy specs are done. Hoofy answers WHO and WHAT. Plan mode answers HOW.
Hoofy (Requirements Layer) → "WHAT are we building? For WHO?"
Plan Mode (Implementation) → "HOW do we build it? Which files?"
The Research Behind SDD
Hoofy's specification pipeline isn't built on opinions. It's built on research. Every feature maps to a specific recommendation from Anthropic Engineering or industry research — see the full research foundations document for the complete mapping.
METR 2025: Experienced developers were 19% slower with AI despite feeling 20% faster — unstructured AI usage introduces debugging overhead and false confidence.
Harness Engineering (OpenAI 2026): Structured wrapping of AI improves output quality by constraining context, enforcing workflows, and making state explicit. Hoofy v1.0's identity redesign was directly inspired by this paper's philosophy of "user brings content, AI complements/organizes/validates."
Structure beats speed.
Contributing
git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build # Build binary
make test # Tests with race detector
make lint # golangci-lint
./bin/hoofy serve # Run the MCP server
Areas for contribution
More clarity dimensions (mobile, API, data pipeline)
More change types beyond fix/feature/refactor/enhancement
Template improvements and customization
Streamable HTTP transport for remote deployment
Export to Jira, Linear, GitHub Issues
i18n for non-English specs
Acknowledgments
Hoofy's memory system is inspired by Engram by Gentleman Programming — the original persistent memory MCP server that proved AI assistants need long-term context to be truly useful. Engram laid the foundation; Hoofy built on top of it.
Hoofy — AI development companion MCP server. Persistent memory, spec-driven development, adaptive change pipeline, Clarity Gate. 32 tools, single Go binary, zero deps.
上次检查时间:2026-10-28。 Hoofy — AI development companion MCP server. Persistent memory, spec-driven development, adaptive change pipeline, Clarity Gate. 32 tools, single Go binary, zero deps.