ai-mind-map

<p align="center"> <h1 align="center">🧠 AI Mind Map</h1> <p align="center"> <strong>MCP Server that reduces AI coding agent token usage by 80-99%</strong> </p> <p align="center"> <a href="https://github.com/shdra06/ai-mind-map/actions/workflows/ci.yml"><img src="https://github.com/shdra06/ai-mind-map/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/shdra06/ai-mind-map/releases"><img src="https://img.shields.io/github/v/release/shdra06/ai-mind-map?label=release" alt="Release"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/shdra06/ai-mind-map" alt="License"></a> <a href="https://www.npmjs.com/package/ai-mind-map"><img src="https://img.shields.io/npm/v/ai-mind-map" alt="npm"></a> <a href="https://www.npmjs.com/package/ai-mind-map"><img src="https://img.shields.io/npm/dm/ai-mind-map" alt="npm downloads"></a> </p> <p align="center"> Stop wasting tokens re-reading your codebase. Give your AI agent a persistent memory. </p> </p>

---

🌐 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.

| Test | Priority | Status | |------|----------|--------| | Live brain graph renders real codebase data | P0 | ✅ passed | | Homepage hero + comparison cards | P0 | ⚠️ inconclusive (agent: PASS, D3 render overhead) | | Tools explorer search filtering | P1 | ✅ passed | | Token savings calculator sliders | P1 | ✅ passed | | Install wizard agent switching | P1 | ✅ passed | | Full site navigation | P2 | ✅ passed |

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.

---

<p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-how-it-works">How It Works</a> • <a href="#-50-mcp-tools">All 50+ Tools</a> • <a href="#-connect-to-your-ai-agent">Connect</a> • <a href="#-cli-commands">CLI</a> • <a href="#-configuration">Config</a> </p>

---

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

| Feature | What It Does | Token Savings | |---------|-------------|---------------| | 🗺️ Knowledge Graph | Parses your entire codebase into a queryable graph of functions, classes, and relationships | 99% | | 📝 Change Tracker | Knows exactly what changed since the AI's last session | 80% | | 🧠 Persistent Memory | Remembers architecture decisions, conventions, and context across sessions | 90% | | 🗜️ Smart Compression | Compresses build logs, test output, stack traces intelligently | 50-98% | | 📊 Progressive Loading | Loads only what's needed — signatures first, full code only when asked | 90% | | ⚡ Real-time Sync | File watcher keeps the graph updated as you code | Always fresh |

Inspired By The Best

This project combines proven techniques from:

| Source | Technique | Their Result | |--------|-----------|-------------| | codebase-memory-mcp | Knowledge Graph + SQLite | 99% reduction (120x fewer tokens) | | Aider | PageRank-based Repo Map | 90%+ reduction | | Mem0 | Persistent Memory with Decay | 3-4x cost reduction | | context-mode | Context Sandboxing + BM25 | 98% context reduction | | context-mem | Progressive Disclosure | 90%+ savings |

---

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

<details> <summary><b>Claude Code</b> — <code>~/.claude/claude_desktop_config.json</code></summary>

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

</details> <details> <summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>

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

</details> <details> <summary><b>VS Code</b> — Settings JSON (<code>Ctrl+Shift+P</code> → "Open User Settings JSON")</summary>

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

</details> <details> <summary><b>Antigravity (Gemini)</b> — <code>~/.gemini/config/mcp.json</code></summary>

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

</details> <details> <summary><b>Windsurf</b> — Settings JSON</summary>

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

</details> <details> <summary><b>Any MCP-Compatible Agent</b></summary>

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

</details>

💡 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

| Client | Works? | How AI Learns Our Tools | |--------|:------:|------------------------| | Claude Code / Desktop | ✅ | instructions + tools/list + prompts + rules file (CLAUDE.md) | | Cursor | ✅ | tools/list + rules file (.cursorrules) | | VS Code Copilot | ✅ | tools/list + rules file (.github/copilot-instructions.md) | | Windsurf | ✅ | tools/list + rules file (.windsurfrules) | | Antigravity (Gemini) | ✅ | tools/list + rules file (.agents/AGENTS.md) | | Zed | ✅ | tools/list + MCP config | | Continue.dev | ✅ | tools/list + MCP config | | Any MCP client | ✅ | tools/list (universal MCP spec) | | Ollama / LM Studio | ⚠️ | Not MCP clients natively — use via Continue.dev or Open WebUI | | Codex (OpenAI) | ⚠️ | Not MCP natively — requires MCP bridge |

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

| Tool | What It Does | Token Savings | |------|-------------|:---:| | mindmap_session_resume ⭐⭐ | Resume from last session — returns what was worked on, what changed, project stats | 15-30K/session | | mindmap_session_start | Start tracking a new AI coding task | — | | mindmap_session_end | End session with summary for next agent | — | | mindmap_changelog ⭐ | Symbol-level diffs — added/modified/deleted functions since a time | 20-50K/session | | mindmap_hotspots | Most frequently changed files + symbols | 5-10K | | mindmap_digest ⭐ | Full project summary in <2000 tokens | 10-25K/session | | mindmap_file_digest ⭐ | Understand a file WITHOUT reading it | 3-10K/file | | mindmap_verify | Hash-based content verification — check if cached code is still valid | 3-10K/file |

🗺️ Knowledge Graph (6)

| Tool | What It Does | |------|-------------| | mindmap_search | Search codebase by function/class name or free text | | mindmap_get_structure | Project architecture overview in ~100 tokens | | mindmap_trace_dependencies | Trace call chains — who calls what | | mindmap_get_signature | Function signature without reading the file | | mindmap_find_references | Find everywhere a symbol is used | | mindmap_get_file_map | All symbols in a file with line ranges |

⭐ Smart Tools (3) — 99% Token Savings

| Tool | What It Does | |------|-------------| | mindmap_explain | Everything about a symbol in 1 call — signature, callers, callees, layer, blast radius, git hist