# ArchMemory MCP

> **Give AI coding agents a memory of your architecture.**

Open source MCP server built with **Laravel** that gives AI coding agents (Cursor, Claude Code, etc.) structured access to your project's architecture, rules, modules, and technical decisions.

## Features (MVP)

- **5 MCP Tools** — project context, rules, modules, ADRs, change validation
- **Artisan CLI** — init, analyze, update
- **`.archmemory/` storage** — Markdown + JSON, Git-versionable
- **Rules Engine** — validates code changes against architecture rules
- **DDD Architecture** — Memory, Mcp, Rules, Analysis domains

## Quick Start

```bash
composer install
cp .env.example .env
php artisan key:generate

# Initialize architecture memory (if not already present)
php artisan archmemory:init

# Analyze project and update architecture.md
php artisan archmemory:analyze
```

## Cursor Integration

Add to `.cursor/mcp.json` (included in this repo):

```json
{
  "mcpServers": {
    "archmemory": {
      "command": "php",
      "args": ["artisan", "mcp:start", "archmemory"],
      "cwd": "${workspaceFolder}",
      "env": {
        "ARCHMEMORY_PATH": "${workspaceFolder}/.archmemory"
      }
    }
  }
}
```

Then restart Cursor. The agent can call:

| Tool | Description |
|------|-------------|
| `get_project_context` | Project stack, architecture, rules summary |
| `get_architecture_rules` | Full rules from `rules.md` |
| `get_module_info` | Module details and dependencies |
| `get_decision_history` | ADR decision records |
| `validate_change` | Check code against architecture rules |

## Artisan Commands

```bash
php artisan archmemory:init      # Create .archmemory/ structure
php artisan archmemory:analyze   # Generate architecture.md from project
php artisan archmemory:update    # Refresh context after changes
php artisan mcp:start archmemory # Start MCP stdio server
```

## Project Structure

```
app/Domains/
├── Memory/     # Read/write .archmemory files
├── Mcp/        # MCP server + tools
├── Rules/      # Rules engine
└── Analysis/   # Project analyzer

.archmemory/    # Architecture memory (committed to Git)
docs/           # Design documents
```

## Documentation

- [PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md) — Full project specification
- [architecture-design.md](docs/design/architecture-design.md) — System architecture
- [mcp-tools-design.md](docs/design/mcp-tools-design.md) — MCP tool specs

## Testing

```bash
php artisan test          # 32 tests
vendor/bin/pint --test    # Code style check
vendor/bin/pint           # Auto-fix style
```

CI runs on push via GitHub Actions (`.github/workflows/tests.yml`).

## License

MIT