ADRFlow

An MCP server that captures architectural decisions while you code. Works with Claude Code, Cursor, Windsurf, and Codex.

What it does

When you're working with an AI assistant and make decisions like "let's use Postgres" or "we should cache this", ADRFlow records them. Later you can search "why did we pick Postgres?" and get the full context back.

The AI detects decisions automatically and asks if you want to save them. You can also explicitly ask it to record something.

Installation

npm install -g adrflow

Setup

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "adrflow": {
      "command": "npx",
      "args": ["-y", "adrflow"]
    }
  }
}

Or add it globally to ~/.claude.json:

{
  "mcpServers": {
    "adrflow": {
      "command": "npx",
      "args": ["-y", "adrflow"]
    }
  }
}

Restart Claude Code. You should see adrflow in /mcp output.

Cursor

Go to Settings > MCP and add:

{
  "adrflow": {
    "command": "npx",
    "args": ["-y", "adrflow"]
  }
}

Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "adrflow": {
      "command": "npx",
      "args": ["-y", "adrflow"]
    }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.adrflow]
command = "npx"
args = ["-y", "adrflow"]

For project-specific config, create .codex/config.toml in your project:

[mcp_servers.adrflow]
command = "npx"
args = ["-y", "adrflow"]
env = { ADRFLOW_STORAGE_PATH = ".adrflow/decisions.mv2" }

VS Code + Continue

Add to your Continue config:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "adrflow"]
        }
      }
    ]
  }
}

Storage

By default, decisions are stored in .adrflow/decisions.mv2 in your current directory. Change this with:

ADRFLOW_STORAGE_PATH=/path/to/decisions.mv2 npx adrflow

Or in your MCP config:

{
  "adrflow": {
    "command": "npx",
    "args": ["-y", "adrflow"],
    "env": {
      "ADRFLOW_STORAGE_PATH": ".adrflow/decisions.mv2"
    }
  }
}

Usage

Recording decisions

The AI will offer to record decisions when it detects them. You can also ask directly:

Record a decision: We're using Zustand for state management because Redux has too much boilerplate

Searching

Search decisions about authentication

What technology decisions have we made?

Show me decisions from the last week

Filtering

List all accepted decisions

Show technology decisions since yesterday

Exporting

Export all decisions to markdown

Export ADR-0001 in MADR format

Tools

| Tool | What it does | |------|--------------| | record_decision | Save a new decision | | search_decisions | Find decisions by text | | list_decisions | List with filters (status, category, date range) | | get_decision | Get full details of one decision | | update_decision | Modify an existing decision | | accept_decision | Mark as accepted | | deprecate_decision | Mark as deprecated | | supersede_decision | Replace with a new decision | | ask_decisions | Ask questions about past decisions | | export_decision | Export to markdown | | export_all_decisions | Export everything |

Categories

When recording, decisions are categorized:

• technology - libraries, frameworks, languages
• architecture - system structure, patterns
• api_design - endpoints, contracts
• data_model - schemas, storage
• security - auth, encryption
• performance - caching, optimization
• refactoring - code reorganization
• infrastructure - deployment, CI/CD
• testing - test strategy
• other - everything else

Decision states

proposed -> accepted -> deprecated
                    \-> superseded

New decisions start as proposed. Accept them after review. Deprecate when no longer relevant, or supersede when replaced by a better approach.

Export formats

MADR - Full format with front matter, alternatives, consequences. Good for documentation.

Nygard - Michael Nygard's original format. Simple: status, context, decision, consequences.

Minimal - Just the essentials. Good for quick reference.

CLI

# Start MCP server (this is what the AI tools call)
adrflow serve

# Show stats
adrflow stats

# Help
adrflow help

Development

git clone https://github.com/memvid/adrflow.git
cd adrflow
npm install
npm run build
npm test

How it works

ADRFlow is an MCP (Model Context Protocol) server. When you configure it in Claude Code/Cursor/etc, the AI gets access to tools for recording and searching decisions.

Storage uses memvid, which provides full-text search and efficient storage in a single .mv2 file.

The AI is instructed to watch for architectural decisions in conversation and offer to record them. This happens through the MCP instructions field, so the AI knows to be proactive.

License

Apache 2.0. See LICENSE.