MCP Servers

ai-mind-map

An MCP server that reduces AI coding agent token usage by 80-99% through a queryable knowledge graph of code, change tracking, and persistent memory across sessions.

README

<h1 align="center">🧠 AI Mind Map</h1> MCP Server that reduces AI coding agent token usage by 80-99% <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> 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.

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

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

✅ Scans your system for AI coding agents (Claude, Cursor, VS Code, Windsurf, Antigravity, Zed, Continue.dev)
✅ Writes MCP config to each agent's config file
✅ Deploys rules files so agents know about our 41 tools
✅ 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:

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

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

</details>

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

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

</details>

<details> <summary>VS Code — 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>Antigravity (Gemini) — <code>~/.gemini/config/mcp.json</code></summary>

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

</details>

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

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

</details>

<details> <summary>Any MCP-Compatible Agent</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 history
`mindmap_git_changes`	Git-aware symbol-level diffs — which functions changed, who's impacted
`mindmap_smart_search`	Rich search — returns full context so AI never reads files

🔍 Semantic Search (3)

Tool	What It Does
`mindmap_semantic_search`	Search by meaning — "authentication", "error handling", "data validation"
`mindmap_semantic_stats`	Vocabulary size, index coverage
`mindmap_synonyms`	Programming synonym lookup

📝 Change Tracking (3)

Tool	What It Does
`mindmap_what_changed`	Summary of recent code changes
`mindmap_session_diff`	What changed since last AI session
`mindmap_impact_analysis`	Blast radius of a change

🧠 Memory (5)

Tool	What It Does
`mindmap_recall`	Retrieve relevant memories
`mindmap_remember`	Store a fact or convention
`mindmap_get_decisions`	Past architectural decisions
`mindmap_decide`	Record a new decision
`mindmap_session_summary`	Previous session summaries

🔬 Advanced Analysis (7)

Tool	What It Does
`mindmap_query_graph`	Cypher-like graph queries
`mindmap_dead_code`	Detect unused functions
`mindmap_architecture`	Full architecture overview
`mindmap_get_code_snippet`	Read source by symbol name
`mindmap_search_code`	Grep-like text search
`mindmap_list_projects`	List indexed projects
`mindmap_health`	System diagnostics

🏗️ Flow Analysis (4)

Tool	What It Does
`mindmap_trace_flow`	Trace behavioral flows through layers
`mindmap_interaction_map`	Full interaction map of the codebase
`mindmap_classify_file`	Classify a file's architectural layer
`mindmap_layer_overview`	Layer distribution overview

🔍 Debug (3)

Tool	What It Does
`mindmap_debug_changes`	Detailed change analysis
`mindmap_file_before`	File content before changes
`mindmap_file_history`	Full file change history

🧬 Self-Evolving (3)

Tool	What It Does
`mindmap_teach`	AI teaches new patterns — persists per-project
`mindmap_get_learned`	View all rules the system has learned
`mindmap_forget`	Remove a learned rule

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

Language	AST Parsing	Regex Fallback	Extracts
JavaScript	✅	✅	Functions, classes, imports, exports
TypeScript	✅	✅	+ Interfaces, types, enums, decorators
Python	✅	✅	Functions, classes, decorators, docstrings
Java	✅	✅	Classes, methods, interfaces, annotations
Go	✅	✅	Functions, structs, interfaces, methods
Rust	✅	✅	Functions, structs, traits, impls, enums
C/C++	✅	✅	Functions, classes, structs, macros
C#	✅	✅	Classes, methods, interfaces, properties
Ruby	✅	✅	Classes, modules, methods, blocks
PHP	✅	✅	Classes, functions, traits, namespaces
Bash	✅	✅	Functions, variables, aliases
CSS/HTML	✅	✅	Selectors, classes, IDs

🏗️ 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):

Layer	What	Token Cost	Lifespan
Working Memory	Current task context	Full price	This conversation
Episodic Memory	Session summaries, recent decisions	On-demand retrieval	Days to weeks
Semantic Memory	Codebase graph, architecture, conventions	Queried, never dumped	Permanent (with decay)

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

Scenario	Without Mind Map	With Mind Map	Savings
Find a function signature	~5,000 tokens	~50 tokens	99%
Understand project structure	~50,000 tokens	~500 tokens	99%
Resume after session break	~20,000 tokens	~2,000 tokens	90%
Trace dependency chain	~30,000 tokens	~200 tokens	99%
Check what changed	~10,000 tokens	~500 tokens	95%
Compress build log	~8,000 tokens	~400 tokens	95%

🤝 Contributing

Contributions are welcome! Here's how:

Fork the repo
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run the build: npm run build
Commit: git commit -m "Add amazing feature"
Push: git push origin feature/amazing-feature
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!

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

ai-mind-map

README

⚡ Install in One Command

❓ The Problem

✨ What AI Mind Map Does

Inspired By The Best

🚀 Quick Start

Method 1: npx (Fastest — Zero Install)

Method 2: Global Install

Method 3: Clone (For Development)

What install Does

Verify It Works

🔌 Connect To Your AI Agent

Automatic (Recommended)

What Gets Written

Manual Setup (If You Prefer)

🔧 50+ MCP Tools

How AI Agents Discover Our Tools

🌐 Client Compatibility

⚡ 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

⚙️ Configuration

Project-Level Config (Optional)

CLI Options

🌐 Language Support

🏗️ Architecture

How the Memory System Works

📊 Expected Token Savings

🤝 Contributing

Development

📄 License

🙏 Acknowledgments

Recommended Servers

What `install` Does