# 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

```bash
npm install -g adrflow
```

## Setup

### Claude Code

Create `.mcp.json` in your project root:

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

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

```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:

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

### Windsurf

Add to your MCP configuration:

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

### Codex (OpenAI)

Add to `~/.codex/config.toml`:

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

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

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

### VS Code + Continue

Add to your Continue config:

```json
{
  "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:

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

Or in your MCP config:

```json
{
  "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

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

# Show stats
adrflow stats

# Help
adrflow help
```

## Development

```bash
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](https://github.com/memvid/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](LICENSE).