🧠 AI Mind Map

MCP Server that reduces AI coding agent token usage by 80-99%

Stop wasting tokens re-reading your codebase. Give your AI agent a persistent memory.

🌐 Live Website

ai-mind-map-website.vercel.app — Interactive landing page with a live D3.js knowledge graph of the real codebase (120 nodes, 300 edges), token savings calculator, tools explorer, and one-command install wizard.

🧪 TestSprite Hackathon — Season 3

This project is a submission for the TestSprite Season 3 Hackathon. The TestSprite verification loop ran against the live website across 2 rounds, finding and fixing 4 real product bugs.

Bugs found by TestSprite:

• 🐛 Brain graph search input had no ARIA — invisible to accessibility tree
• 🐛 Install page: 3 identical Copy buttons with no unique identifiers
• 🐛 D3 drag handler fired on every mousedown — hover selected nodes incorrectly
• 🐛 Homepage hero + CTA both had identical Copy buttons — agent blocked

See LOOP.md for the full iteration log, root cause analysis, and fixes.

CI/CD: TestSprite runs automatically on every push via GitHub Actions.

⚡ Install in One Command

npx ai-mind-map install

Auto-detects Claude, Cursor, VS Code, Windsurf, Antigravity, Zed, Continue.dev — configures all of them instantly. No config files. No manual setup. Just run and restart your agent.

Quick Start • How It Works • All 50+ Tools • Connect • CLI • Config

❓ The Problem

Every time an AI coding agent (Claude Code, Cursor, Copilot, Windsurf, Antigravity) processes a request, it re-reads your entire codebase from scratch. This wastes massive amounts of tokens:

Without AI Mind Map:
  ❌ Agent reads auth.ts        → 5,000 tokens
  ❌ Agent reads auth.ts AGAIN  → 5,000 tokens (same file!)
  ❌ Agent reads auth.ts AGAIN  → 5,000 tokens (still the same file!)
  Total: 15,000 tokens for 3 questions about ONE file

With AI Mind Map:
  ✅ mindmap_get_signature("authenticate")        → 50 tokens
  ✅ mindmap_get_signature("validateToken")        → 40 tokens  
  ✅ mindmap_trace_dependencies("authenticate")    → 100 tokens
  Total: 190 tokens — that's a 99% reduction

Industry research shows ~42% of all tokens consumed by AI coding agents are avoidable waste — repeated file reads, re-discovering architecture, re-debating settled decisions.

✨ What AI Mind Map Does

AI Mind Map is an MCP (Model Context Protocol) server that gives your AI agent:

Inspired By The Best

This project combines proven techniques from:

🚀 Quick Start

Method 1: Global Install (Recommended — Most Reliable)

npm install -g ai-mind-map

# Auto-detect and configure all your AI agents
ai-mind-map install

# Check everything is working
ai-mind-map doctor

Method 2: npx (Quick — No Install)

# Run directly without installing anything
npx ai-mind-map install

# ⚠️ If you get "bindings.js" errors, use Method 1 instead (npx cache can corrupt native modules)

Method 3: Clone (For Development)

git clone https://github.com/shdra06/ai-mind-map.git
cd ai-mind-map
npm install --legacy-peer-deps
npm run build
node dist/cli.js install

What install Does

1. ✅ Scans your system for AI coding agents (Claude, Cursor, VS Code, Windsurf, Antigravity, Zed, Continue.dev)
2. ✅ Writes MCP config to each agent's config file
3. ✅ Deploys rules files so agents know about our 41 tools
4. ✅ Runs diagnostics to verify everything works

Verify It Works

ai-mind-map doctor

Output:

🩺 AI Mind Map — Diagnostics
────────────────────────────────────────────────────────
  ✔ Node.js           v24.x (>= 18 required)
  ✔ SQLite             In-memory test passed
  ✔ TypeScript Build   dist/index.js exists
  ✔ Agents             3 detected, 3 configured

🔌 Connect To Your AI Agent

Automatic (Recommended)

npm install -g ai-mind-map
ai-mind-map install

This auto-detects all 7 agents and writes the config for you. Done.

What Gets Written

After running install, each agent's config file contains:

{
  "mcpServers": {
    "ai-mind-map": {
      "command": "ai-mind-map",
      "args": []
    }
  }
}

💡 Note: If you installed globally, the command is ai-mind-map. If using npx, it writes "command": "npx", "args": ["-y", "ai-mind-map"]. Both work, but global is more reliable for native dependencies.

Manual Setup (If You Prefer)

If you want to configure manually, add this to your agent's config:

{
  "mcpServers": {
    "ai-mind-map": {
      "command": "npx",
      "args": ["-y", "ai-mind-map"]
    }
  }
}

{
  "mcpServers": {
    "ai-mind-map": {
      "command": "npx",
      "args": ["-y", "ai-mind-map"]
    }
  }
}

{
  "mcp.servers": {
    "ai-mind-map": {
      "command": "npx",
      "args": ["-y", "ai-mind-map"]
    }
  }
}

{
  "mcpServers": {
    "ai-mind-map": {
      "command": "npx",
      "args": ["-y", "ai-mind-map"]
    }
  }
}

{
  "mcp.servers": {
    "ai-mind-map": {
      "command": "npx",
      "args": ["-y", "ai-mind-map"]
    }
  }
}

Command:   npx
Args:      -y ai-mind-map
Transport: stdio

💡 After configuring, restart your AI agent so it picks up the new MCP server.

🔧 50+ MCP Tools

Once connected, your AI agent automatically gets all tools + a built-in guide telling it which tool to call first and when to use each one.

How AI Agents Discover Our Tools

AI Agent connects → Server sends 3 things:

1. ✅ instructions    → "Call mindmap_session_resume FIRST" (auto-loaded)
2. ✅ tools/list      → All 50 tools with descriptions + schemas (auto-loaded)
3. ✅ prompts/list    → Interactive guides (on request)

🌐 Client Compatibility

Key: tools/list works with every MCP client. Rules files (CLAUDE.md, .cursorrules, etc.) are deployed by npx ai-mind-map install as a fallback for clients that don't honor the instructions field.

⚡ Code Memory Engine (v1.4.0) — NEW

🗺️ Knowledge Graph (6)

⭐ Smart Tools (3) — 99% Token Savings

🔍 Semantic Search (3)

📝 Change Tracking (3)

🧠 Memory (5)

🔬 Advanced Analysis (7)

🏗️ Flow Analysis (4)

🔍 Debug (3)

🧬 Self-Evolving (3)

💻 CLI Commands

All commands work with npx (no install) or after global install (npm install -g ai-mind-map):

# Setup & Diagnostics
npx ai-mind-map install              # Auto-configure all AI agents
npx ai-mind-map doctor               # Check everything is working
npx ai-mind-map install --uninstall  # Remove configs from all agents

# Index & Search
npx ai-mind-map index /path/to/project  # Index a codebase
npx ai-mind-map search "authenticate"   # Search the knowledge graph
npx ai-mind-map trace "processOrder"    # Trace call chains

# Memory
npx ai-mind-map recall "authentication"  # Recall past knowledge
npx ai-mind-map remember "We use JWT"    # Store a convention

# Status
npx ai-mind-map status               # Show index stats
npx ai-mind-map changes              # Show recent changes

⚙️ Configuration

Project-Level Config (Optional)

Create a .mindmap.json file in your project root to customize behavior:

{
  "languages": ["typescript", "python", "javascript"],
  "ignore": ["node_modules", "dist", "*.test.*", "coverage"],
  "tokenBudgets": {
    "graphResults": 2000,
    "changeSummary": 1000,
    "memoryRetrieval": 1500,
    "fileContent": 3000,
    "totalContext": 10000
  },
  "memory": {
    "maxMemories": 500,
    "decayRate": 0.95,
    "importanceThreshold": 0.1,
    "maxDecisions": 200
  },
  "compression": "moderate",
  "watchEnabled": true
}

CLI Options

node dist/index.js [options]

Options:
  --project-root <path>   Root of the project to index (default: auto-detect from git)
  --db-path <path>        SQLite database location (default: .mindmap/mindmap.db)
  --log-level <level>     debug | info | warn | error (default: info)

🌐 Language Support

Tree-sitter AST parsing with automatic regex fallback:

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│              AI Mind Map MCP Server                  │
│                                                       │
│  ┌─────────────────┐  ┌────────────────┐  ┌────────┐ │
│  │ Knowledge Graph  │  │ Change Tracker │  │ Memory │ │
│  │ ─────────────── │  │ ────────────── │  │ ────── │ │
│  │ Tree-sitter AST │  │ Chokidar Watch │  │  Mem0  │ │
│  │ SQLite + FTS5   │  │ Git Diff       │  │  Style │ │
│  │ PageRank        │  │ BM25 Search    │  │ Decay  │ │
│  └────────┬────────┘  └───────┬────────┘  └───┬────┘ │
│           │                   │                │      │
│  ┌────────┴───────────────────┴────────────────┴────┐ │
│  │              Context Engine                       │ │
│  │  Content-Aware Compression (9 types)              │ │
│  │  Progressive Disclosure (3 tiers)                 │ │
│  │  Token Budget Manager                             │ │
│  └──────────────────────┬────────────────────────────┘ │
│                         │                               │
│                  41 MCP Tools                           │
└─────────────────────────┼───────────────────────────────┘
                          │ stdio
                ┌─────────┴──────────┐
                │   Your AI Agent    │
                │  Claude / Cursor / │
                │ Copilot / Windsurf │
                └────────────────────┘

How the Memory System Works

AI Mind Map uses a three-tier memory architecture (inspired by cognitive science):

Memories have importance scores that:

• 📈 Increase when accessed (+0.1 per access, capped at 1.0)
• 📉 Decay over time (configurable, default 5% per day)
• 🗑️ Get pruned when importance drops below threshold

This means frequently-useful memories stick around, while stale ones naturally fade.

📊 Expected Token Savings

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repo
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run the build: npm run build
5. Commit: git commit -m "Add amazing feature"
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Development

# Watch mode (auto-recompile on changes)
npm run dev

# Type check without building
npx tsc --noEmit

# Run the server locally
node dist/index.js --project-root . --log-level debug

📄 License

MIT — use it however you want. See LICENSE.

🙏 Acknowledgments

Built on the shoulders of giants:

• codebase-memory-mcp — Knowledge graph architecture (99% token reduction)
• Aider — Repository map with PageRank ranking
• Mem0 — Persistent memory with importance decay
• context-mode — Context sandboxing with BM25
• context-mem — Progressive disclosure patterns
• CocoIndex — Incremental AST indexing
• Repomix — Codebase compression techniques
• Tree-sitter — Multi-language AST parsing
• MCP Protocol — The standard that makes this possible

⭐ Star this repo if it saves you tokens!