Hoofy

The AI coding assistant that remembers everything and never hallucinates specs.
An MCP server that gives your AI persistent memory, structured specifications,
and adaptive change management — so it builds what you actually want.

Blog Post · Workflow Guide · Tool Reference · Research Foundations ·

🐴 Explore the Interactive Documentation →

---

What Is Hoofy? — AI Development Companion for MCP

Hoofy is an AI coding tool that solves the three biggest problems with AI-assisted development: memory loss between sessions, hallucinated implementations, and unstructured AI workflows. It's a single MCP (Model Context Protocol) server written in Go — one binary, zero dependencies — that works with Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode, and any MCP-compatible AI tool.

Hoofy is three systems in one MCP server:

System	What it does	Tools
Memory	Persistent context across sessions using SQLite + FTS5 full-text search. Decisions, bugs, patterns, discoveries — your AI remembers what happened yesterday.	19 mem_* tools
Change Pipeline	Adaptive workflow for ongoing dev. Picks the right stages based on change type × size (12 flow variants). Now includes a context-check stage in every flow.	5 sdd_change* + sdd_adr
Project Pipeline	Full greenfield specification — from vague idea to validated architecture with a Clarity Gate and business rules extraction that blocks hallucinations.	9 sdd_* tools

One binary. Zero external dependencies. SQLite embedded at compile time. Works with any MCP-compatible AI coding assistant — Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode. 34 tools total.

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 assistant remember context, follow specifications, and prove it understood before writing code.

Key Features

Knowledge Graph — Memory observations aren't flat notes. You can connect them with typed, directional relations (depends_on, caused_by, implements, supersedes, relates_to, part_of) to build a navigable web of project knowledge. Use mem_build_context to traverse the graph from any observation and pull in related decisions, bugs, and patterns automatically.

Decision: "Switched to JWT"  →(caused_by)→  Discovery: "Session storage doesn't scale"
    ↑(implements)                               ↑(relates_to)
Bugfix: "Fixed token expiry"              Pattern: "Retry with backoff"

Context Check — Every change pipeline flow now starts with a mandatory context-check stage. Before writing a single spec or line of code, Hoofy scans your existing specs, completed changes, memory observations, and convention files (CLAUDE.md, AGENTS.md, CONTRIBUTING.md, etc.) to detect conflicts and ambiguities. Zero issues = green light. Issues found = must resolve before proceeding. Even a one-line fix can break an existing business rule.

Business Rules — In the greenfield project pipeline, a dedicated business-rules stage extracts declarative rules from your requirements using BRG taxonomy (Definitions, Facts, Constraints, Derivations) and DDD Ubiquitous Language — before the Clarity Gate evaluates them. Rules inform the gate, not the other way around.

Pre-pipeline Exploration — Before committing to a pipeline, use sdd_explore to capture unstructured thinking — goals, constraints, tech preferences, unknowns, decisions. It saves structured context to memory via topic key upsert (call it multiple times as your thinking evolves — it updates, never duplicates). It also suggests a change type and size based on keywords, so you start the right pipeline.

Wave Assignments — When creating tasks (in either pipeline), the AI can group them into parallel execution waves derived from the dependency graph. Wave 1 has no dependencies, Wave 2 depends only on Wave 1, and so on. This tells you exactly which tasks can run in parallel and which must wait — useful for team coordination or just knowing the critical path.

How it flows

flowchart TB explore["sdd_explore\n(goals, constraints, unknowns)"]

subgraph project ["New Project (greenfield)"]
    direction LR
    P1[Init] --> P2[Propose] --> P3[Requirements] --> P3b["Business\nRules"]
    P3b --> P4{Clarity Gate}
    P4 -->|Ambiguous| P3
    P4 -->|Clear| P5[Design] --> P6[Tasks] --> P7[Validate]
end

subgraph change ["Existing Project (changes)"]
    direction LR
    C1["sdd_change\n(type × size)"] --> C1b["Context\nCheck"]
    C1b --> C2["Opening Stage\n(describe/propose/scope)"]
    C2 --> C3["Spec + Design\n(if needed)"]
    C3 --> C4[Tasks] --> C5[Verify]
end

subgraph memory ["Memory (always active)"]
    direction LR
    M1[Session Start] --> M2["Work + Save Discoveries"]
    M2 --> M3["Connect with Relations"]
    M3 --> M4[Session Summary]
end

explore -.->|"captures context before"| project
explore -.->|"captures context before"| change

style explore fill:#8b5cf6,stroke:#7c3aed,color:#fff
style P4 fill:#f59e0b,stroke:#d97706,color:#000
style P3b fill:#e879f9,stroke:#c026d3,color:#000
style C1b fill:#e879f9,stroke:#c026d3,color:#000
style P7 fill:#10b981,stroke:#059669,color:#fff
style C5 fill:#10b981,stroke:#059669,color:#fff

Full workflow guide with step-by-step examples · Complete tool reference (34 tools)

---

Quick Start

1. Install the binary

macOS (Homebrew)

brew install HendryAvila/hoofy/hoofy

macOS / Linux (script)

curl -sSL https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.ps1 | iex

Go / Source

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 34 tools (memory, change pipeline, project pipeline) 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.

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:

/plugin marketplace add HendryAvila/hoofy-plugins
/plugin install hoofy@hoofy-plugins

Cursor

Add to your MCP config:

{ "mcpServers": { "hoofy": { "command": "hoofy", "args": ["serve"] } } }

VS Code Copilot

Add to .vscode/mcp.json:

{ "servers": { "hoofy": { "type": "stdio", "command": "hoofy", "args": ["serve"] } } }

OpenCode

Add to ~/.config/opencode/opencode.json inside the "mcp" key:

{ "mcp": { "hoofy": { "type": "local", "command": ["hoofy", "serve"], "enabled": true } } }

Gemini CLI

3. Use it

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 adding a short block to your agent's instructions file reinforces the habit — the AI will think about specs before it even sees the tools.

Claude Code — CLAUDE.md (only needed for MCP-only setup)

Using the plugin? Skip this — the plugin's hooks and agent already enforce SDD behavior automatically.

Hoofy — Spec-Driven Development

Before coding any new feature or significant change, use Hoofy to create specs first.

• New projects: use the SDD pipeline (sdd_init_project → sdd_validate)
• Ongoing work: use the change pipeline (sdd_change) — it adapts stages to the size of the change
• Memory: save decisions, bugs, and discoveries with mem_save so future sessions have context Do NOT start coding without specs for any non-trivial change.

Cursor — .cursor/rules/hoofy.md

OpenCode — AGENTS.md

VS Code Copilot — .github/copilot-instructions.md

Gemini CLI — GEMINI.md

---

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 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. 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.

If the change...	It's probably...
Touches 1-2 files, clear fix	small (4 stages — context-check + describe + tasks + verify)
Needs requirements or design thought	medium (5 stages)
Affects architecture, multiple systems	large (6-7 stages)

4. Let memory work for you

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

5. 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_build_context to explore the full graph around any observation.

6. 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.

7. 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.

8. 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.

9. 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.

Anthropic Engineering:

• Building Effective Agents — ACI design, tool patterns, orchestrator-worker architecture
• Effective Context Engineering — Persistent memory, progressive disclosure, context as finite resource
• Writing Effective Tools — Tool namespacing, response design, token efficiency
• Multi-Agent Research System — Session summaries, filesystem output, token budget awareness
• Long-Running Agent Harnesses — Progress tracking, incremental delivery, JSON over Markdown for state
• Claude Code Best Practices — CLAUDE.md scanning, structured workflows

Industry Research:

• METR 2025: Experienced developers were 19% slower with AI despite feeling 20% faster — unstructured AI usage introduces debugging overhead and false confidence.
• DORA 2025: 7.2% delivery instability increase for every 25% AI adoption — without foundational systems and practices.
• McKinsey 2025: Top performers see 16-30% productivity gains only with structured specification and communication.
• IEEE 720574: Fixing a requirement error in production costs 10-100x more than fixing it during requirements — worse with AI-generated code.
• IREB & IEEE 29148: Structured elicitation, traceability, ambiguity detection — Hoofy's Clarity Gate implements these frameworks.
• Business Rules Group: The Business Rules Manifesto — rules as first-class citizens. Hoofy uses BRG taxonomy.
• EARS: Research-backed sentence templates that eliminate requirements ambiguity.
• DDD Ubiquitous Language: Shared language eliminates translation errors — Hoofy's business-rules glossary.

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.

---

License

MIT

---

Stop prompting. Start specifying.
Built with care by the Hoofy community.