ai-mind-map

---

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

---

---

Choosing the right tool

For exact repository comparisons without sending patches to a model, use the packaged git-diff skill. ai-mind-map diff HEAD~1 HEAD compares two commits; ai-mind-map diff --fetch compares current staged, unstaged, and non-ignored new files against the refreshed configured push destination. The command returns local patch and viewer paths. Generating and viewing the artifacts makes no LLM calls; chat and model analysis still use tokens.

AI Mind Map helps agents reuse indexed project knowledge, resolve supported symbol relationships, and inspect routes. Native search and bounded reads are often cheaper for exact names, literals, known files, and small configurations. The skill chooses between these paths rather than requiring extra index calls for every task.

Repeated local benchmarks compare actual MCP responses against ripgrep and targeted reads, including correctness checks and separate indexing/schema costs. See the benchmark report and run npm run benchmark -- --rounds 5 --files 250 to reproduce the comparison. Token counts are estimates, not billing measurements; there is no universal savings percentage.

---

✨ What AI Mind Map Does

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

Feature	What It Does	Boundary
🗺️ Knowledge Graph	Parses your entire codebase into a queryable graph of functions, classes, and relationships	Depends on task and baseline
📝 Change Tracker	Knows exactly what changed since the AI's last session	Source verification still matters
🧠 Persistent Memory	Remembers architecture decisions, conventions, and context across sessions	Depends on task and baseline
🗜️ Smart Compression	Compresses build logs, test output, stack traces intelligently	Lossy; inspect retained evidence
📊 Progressive Loading	Loads only what's needed — signatures first, full code only when asked	Depends on task and baseline
⚡ Real-time Sync	File watcher keeps the graph updated as you code	Size/mtime freshness is heuristic

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:

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

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 — targeted context

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.

---

Measuring context cost

Run npm run benchmark -- --rounds 5 --files 250 for a repeatable local comparison. The report records correct answers, UTF-8 bytes, estimated tokens, latency, and cold indexing cost. Native tools can win. Full-file-read illustrations are not evidence of savings against an agent that already searches narrowly.

---

🤝 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

---