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.

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: npx (Fastest — Zero Install)

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

# That's it. It auto-detects Claude, Cursor, VS Code, Windsurf, Antigravity, Zed, Continue.dev

Method 2: Global Install

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 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)

npx 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": "npx",
      "args": ["-y", "ai-mind-map"]
    }
  }
}

This tells the agent: "When you need MCP tools, run npx ai-mind-map". It downloads from npm on first use, then uses cache.

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!