# dev-brain-mcp

> Your AI agent's persistent brain. Coding standards that never get forgotten, stack detection, and project memory that survives across conversations.

Inspired by [ponytail](https://github.com/DietrichGebert/ponytail), [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp), and [Graft](https://github.com/NanoNets/Graft).

## The Problem

AI coding agents forget your rules in long conversations. Skills and instructions get truncated from the context window after many iterations. This MCP server solves that by:

1. **Embedding rules in tool descriptions** — tool descriptions live in the system prompt and NEVER get truncated
2. **Detecting your stack automatically** — no need to tell the agent "this is a React + RTK project" every time
3. **Persistent project memory** — notes, architectural decisions, and conventions survive across conversations

## Install

```bash
git clone https://github.com/YOUR_USERNAME/dev-brain-mcp.git
cd dev-brain-mcp
npm install
```

## Setup in Antigravity 2.0

### Global Configuration (recommended)

Go to **Settings → MCP Servers** and add:

```json
{
  "mcpServers": {
    "dev-brain": {
      "command": "node",
      "args": ["C:/Users/david/Documents/dev-brain-mcp/server.js"]
    }
  }
}
```

> **⚠️ Update the path** to wherever you cloned this repo.

### Per-Project Configuration

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

```json
{
  "mcpServers": {
    "dev-brain": {
      "command": "node",
      "args": ["C:/path/to/dev-brain-mcp/server.js"]
    }
  }
}
```

### Other Agents (Claude Code, Cursor, etc.)

Add to your MCP config:

```json
{
  "mcpServers": {
    "dev-brain": {
      "command": "node",
      "args": ["/path/to/dev-brain-mcp/server.js"]
    }
  }
}
```

## Tools

| Tool | Description | When to use |
|------|-------------|-------------|
| `get_coding_standards` | Returns ponytail rules + stack-specific rules | **Before** writing code |
| `detect_stack` | Detects language, framework, dependencies | Start of every session |
| `get_project_context` | Retrieves persistent notes, decisions, conventions | Start of every conversation |
| `save_project_context` | Saves context that survives across sessions | After learning something important |
| `validate_code` | Checks code against standards | **After** writing code |
| `list_known_projects` | Lists all previously analyzed projects | When switching projects |

## Why It Works

```
Skills (ponytail, RTK rules):
  → Instructions read into conversation context
  → Get TRUNCATED after ~30 iterations
  → Agent forgets them completely ❌

MCP Tool Descriptions:
  → Live in the system prompt alongside tool definitions
  → NEVER get truncated, no matter how long the conversation
  → Agent always sees them ✅

Persistent Memory (projects.json):
  → Stored on disk, survives across conversations
  → Agent retrieves context at start of each session
  → No re-exploration needed ✅
```

## Adding Your Own Rules

Edit `lib/rules.js`:

- **Universal rules**: Add to `UNIVERSAL_RULES.principles`
- **Stack-specific rules**: Add a new key to `CONDITIONAL_RULES`
- **Validation checks**: Add patterns to `validateCode()`

## License

MIT