# https://github.com/shdra06/ai-mind-map Project Manual Generated at: 2026-06-23 18:46:38 UTC ## Table of Contents - [Overview and System Architecture](#page-overview) - [Core Engine: Knowledge Graph, Change Tracking, Memory, and Context](#page-core-engine) - [MCP Tools and CLI Reference](#page-tools-cli) - [Installation, Configuration, and Operations](#page-ops) ## Overview and System Architecture ### Related Pages Related topics: [Core Engine: Knowledge Graph, Change Tracking, Memory, and Context](#page-core-engine), [MCP Tools and CLI Reference](#page-tools-cli), [Installation, Configuration, and Operations](#page-ops)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md) - [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json) - [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts) - [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts) - [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts) - [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts) - [src/change-tracker/change-log.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/change-log.ts)
# Overview and System Architecture ## Purpose and Scope AI Mind Map (v2.0.0) is an MCP (Model Context Protocol) server that gives AI coding agents — Claude, Cursor, Copilot, Windsurf — a structured, queryable view of a codebase so they can answer questions and make changes without dumping entire files into the context window. It is published as an MIT-licensed Node.js package and is consumed through `npx` / a local install by configuring an MCP client to launch the server over stdio. Source: [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json). The project's central problem is **token efficiency**. Instead of reading every file, an agent asks a high-level question ("where is authentication handled?", "what changed since my last session?") and receives a compact, structured answer. The README states the goal plainly: 41 MCP tools are exposed, grouped into Knowledge Graph, Smart Tools, Semantic Search, Change Tracking, Memory, and Advanced Analysis categories. Source: [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md). ## High-Level Architecture The server is built from four cooperating subsystems that all feed into a shared **Context Engine**. The Context Engine is responsible for assembling, compressing, and budgeting whatever context is returned to the agent. The Knowledge Graph, Change Tracker, and Memory layers are the data sources; the Context Engine is the policy layer that decides what actually goes out on the wire. Source: [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md). ```mermaid flowchart TB subgraph Server["AI Mind Map MCP Server"] KG["Knowledge Graph
tree-sitter AST · SQLite+FTS5 · PageRank"] CT["Change Tracker
chokidar watcher · git diff · BM25"] MEM["Memory
3-tier store · importance · decay"] CE["Context Engine
Compressor · Progressive Disclosure · Token Budget"] end KG --> CE CT --> CE MEM --> CE CE -->|"41 MCP tools over stdio"| Agent["AI Agent
Claude / Cursor / Copilot / Windsurf"] ``` The Knowledge Graph parses source files with `tree-sitter` (multiple language grammars are listed as optional dependencies in `package.json`) and persists symbols, references, and edges in SQLite with FTS5 full-text indexing; PageRank scores identify architecturally important symbols. Source: [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json). The Change Tracker watches the filesystem with `chokidar` and runs git-aware diffs through `simple-git`, falling back to filesystem timestamps when the project is not under version control. Source: [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts). The Memory subsystem is a three-tier store modeled on cognitive science: working (current task), episodic (session summaries, decisions), and semantic (codebase graph, conventions). Each memory has an importance score that increments on access and decays over time, with stale entries pruned automatically. Source: [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md). ## Core Subsystems in Detail ### Knowledge Graph Parses code into a graph of functions, classes, methods, and modules across 20+ languages (the `tree-sitter-*` grammars are declared as `optionalDependencies` in `package.json`, so only the languages actually present in a project are loaded). Symbols and their relationships live in SQLite, and full-text search uses FTS5 with BM25 ranking. PageRank ranks nodes so the tools can return the most important results first when the budget is tight. Source: [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json). ### Change Tracker The `DiffEngine` (in `src/change-tracker/diff-engine.ts`) is stateless: every public method takes what it needs and returns a `DiffSummary` containing per-file `FileChange` records plus aggregate counts of lines added/removed and the number of files affected. When git is available, diffs come from `simple-git`; otherwise the engine reads filesystem mtimes. The companion `ChangeLog` (in `src/change-tracker/change-log.ts`) is a SQLite-backed history store with FTS5 full-text search, BM25-ranked retrieval, session grouping, time-range queries, pruning, and aggregate stats — directly supporting the `mindmap_changelog`, `mindmap_what_changed`, and `mindmap_session_diff` tools. Source: [src/change-tracker/change-log.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/change-log.ts). ### Context Engine The Context Engine is the policy layer that turns raw subsystem output into a token-bounded reply. It has three cooperating components: - **Content-Aware Compressor** (`src/context/compressor.ts`) auto-detects content type from a prioritized list of heuristics — diff, stack trace, test output, build log, JSON, config, markdown, source code, plain text — and applies one of three levels: `minimal` (whitespace/comment cleanup), `moderate` (content-specific compression such as replacing function bodies with `{ ... }` for source), or `aggressive` (signatures-only, errors-only, etc.). The result includes the compressed text and a `ratio` metric for observability. - **Token Budget Manager** (`src/context/token-budget.ts`) divides the response budget across four components — `graphResults`, `changeSummary`, `memoryRetrieval`, and `fileContent` — enforces per-component caps, smart-truncates at logical boundaries, supports dynamic reallocation, and emits a human-readable report. - **Progressive Disclosure** (`src/context/progressive-disclosure.ts`) loads context in three tiers: Tier 1 (always loaded, ≤ 500 tokens — project identity, structure, conventions, current task), Tier 2 (searchable, ≤ 2 000 tokens — ranked graph results, recent changes, relevant memories), and Tier 3 (on-demand, full file contents). Tier 2 nodes are sorted by query relevance before the budget is applied so the most relevant items survive truncation. Source: [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts), [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts), [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts). ## Memory Architecture The memory layer is intentionally separated from the knowledge graph: the graph is structural (what code exists and how it connects), while memory is experiential (what the agent has learned, decided, and observed). Three layers are documented in the README: | Layer | Contents | Token Cost | Lifespan | |-------|----------|-----------|----------| | Working | Current task context | Full price | This conversation | | Episodic | Session summaries, recent decisions | On-demand retrieval | Days to weeks | | Semantic | Codebase graph, architecture, conventions | Queried, never dumped | Permanent (with decay) | Memories have an **importance score** that increases by ~0.1 per access (capped at 1.0) and decays by a configurable percentage per day (default 5%); entries below the prune threshold are removed. Source: [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md). ## Deployment and Versioning The current release, **v2.0.0**, is described in the project's changelog as a "production-grade upgrade" adding a CLI, Cypher-like graph queries, a test suite, CI/CD, and installers. A CI fix in the same release adds `package-lock.json` to the reproducible-build pipeline. Runtime requires Node.js ≥ 18.0.0 (declared in `engines` in `package.json`), and the project advertises support for any MCP-compatible agent. Source: [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json). ## See Also - [Knowledge Graph and Tree-sitter Parsing](#) - [Change Tracking and Git Diffing](#) - [Memory System and Decay](#) - [Context Engine: Compression, Budget, and Progressive Disclosure](#) --- ## Core Engine: Knowledge Graph, Change Tracking, Memory, and Context ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [MCP Tools and CLI Reference](#page-tools-cli)
Related Source Files The following source files were used to generate this page: - [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json) - [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts) - [src/change-tracker/change-log.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/change-log.ts) - [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts) - [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts) - [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts) - [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)
# Core Engine: Knowledge Graph, Change Tracking, Memory, and Context ## Overview The AI Mind Map core engine is a Model Context Protocol (MCP) server that turns a codebase into a queryable, token-efficient knowledge layer for AI coding assistants (Claude, Cursor, Copilot, Windsurf, etc.). It exposes 41 tools across four cooperating subsystems: - **Knowledge Graph** — AST-derived graph of functions, classes, and relationships - **Change Tracking** — Git-aware diffing and a persistent change history - **Memory** — long-lived facts, decisions, and session summaries - **Context Management** — content-aware compression, token budgeting, and progressive disclosure This page focuses on the subsystems whose source is available in the repository: **Change Tracking** and **Context Management**, with references to the related Knowledge Graph and Memory modules. The project is published as the npm package `ai-mind-map`, depends on `@modelcontextprotocol/sdk`, `better-sqlite3`, `tree-sitter`, `simple-git`, and `chokidar`, and is licensed under MIT. Source: [package.json:33-46]() ## Architecture ```mermaid flowchart TD A[AI Agent - Claude / Cursor / Copilot] -->|stdio / MCP| B[ai-mind-map Server] B --> C[Knowledge Graph
tree-sitter + SQLite] B --> D[Change Tracking
simple-git + FTS5] B --> E[Memory Layer
SQLite + BM25] B --> F[Context Engine] F --> F1[Content-Aware Compressor] F --> F2[Token Budget Manager] F --> F3[Progressive Disclosure] C --> F D --> F E --> F F -->|compressed context| A ``` ## Change Tracking Subsystem The change tracking subsystem answers "what changed since the AI last looked?" It is composed of two modules. ### Diff Engine `src/change-tracker/diff-engine.ts` provides git-aware diff analysis using `simple-git`, with a filesystem-timestamp fallback when the project is not under version control. The stateless engine returns a `DiffSummary` containing a human-readable multi-line text block, per-file `FileChange` records, aggregate line counts, and a `usedGit` flag. Source: [src/change-tracker/diff-engine.ts:18-34]() The engine accepts `includePatterns` and `excludePatterns` glob filters, and the public API is designed to be invoked per-call so it can be reused without holding long-lived state. The fallback path uses `node:fs/promises` `stat` and `readdir` to derive changes from mtime deltas. Source: [src/change-tracker/diff-engine.ts:51-58]() ### Persistent Change Log `src/change-tracker/change-log.ts` is a SQLite-backed store using `better-sqlite3` with FTS5 full-text search and BM25-ranked retrieval. It supports session management, time-range queries, and pruning. Source: [src/change-tracker/change-log.ts:1-17]() Query options include `sessionId`, `filePath`, `symbol`, `changeType`, `since` / `until` epoch bounds, plus `limit` and `offset` for pagination. Results are returned as `RankedChangeResult` objects pairing a `FileChange` with a BM25 rank (lower is more relevant in SQLite FTS5). Source: [src/change-tracker/change-log.ts:21-49]() ## Context Management Subsystem The context subsystem is what directly delivers the headline token savings. It is organized as three collaborating modules. ### Content-Aware Compression `src/context/compressor.ts` detects content type via heuristics (diff, stack trace, test output, build log, JSON, config, markdown, source) and applies one of three levels: `minimal` (whitespace cleanup), `moderate` (content-specific), or `aggressive` (signatures-only, errors-only). Source: [src/context/compressor.ts:1-21]() `detectContentType` is exported for callers that want to bypass auto-detection. For source code, `compressSourceModerate` walks lines tracking brace depth: imports, exports, doc comments, and type declarations are kept verbatim; function and class bodies are replaced with `{ ... }` placeholders. Source: [src/context/compressor.ts:128-152]() ### Token Budget Manager `src/context/token-budget.ts` implements explicit per-component budgets, inspired by Aider's `--map-tokens` approach. Four component buckets are tracked: `graphResults`, `changeSummary`, `memoryRetrieval`, and `fileContent`. Source: [src/context/token-budget.ts:14-30]() The manager enforces budgets, records usage, supports smart truncation at logical boundaries, and produces a `BudgetReport` with per-component used / budget / remaining figures plus an estimated savings percent. Source: [src/context/token-budget.ts:46-66]() ### Progressive Disclosure Engine `src/context/progressive-disclosure.ts` is a three-tier context loading system. Tier 1 (≤ 500 tokens) is always loaded and contains project identity, directory skeleton, conventions, and the active task. Tier 2 (≤ 2,000 tokens) is searchable and contains graph results, recent changes, relevant memories, and active decisions. Tier 3 is on-demand and contains full file contents, detailed test output, historical diffs, and full decision rationale. Source: [src/context/progressive-disclosure.ts:1-23]() | Tier | Budget | Content | When Loaded | |------|--------|---------|-------------| | Tier 1 | ≤ 500 tokens | Project identity, skeleton, conventions, task | Always | | Tier 2 | ≤ 2,000 tokens | Graph results, changes, memories, decisions | Searchable | | Tier 3 | Variable | Full files, test output, diffs, decisions | On demand | `buildContextPackage` assembles a `ContextPackage` from the three tiers, sorts Tier 2 graph nodes by query relevance so important matches are not dropped first, and records per-component token usage in the breakdown. Source: [src/context/progressive-disclosure.ts:96-127]() ## Related Systems - **Knowledge Graph** — referenced throughout [README.md](README.md) as the AST-derived graph of functions, classes, and relationships that powers tools like `mindmap_search`, `mindmap_trace_dependencies`, and `mindmap_explain`. PageRank is applied to surface important symbols. - **Memory** — described in the README as a three-tier cognitive model (working, episodic, semantic) with importance-based decay and pruning, exposed through `mindmap_recall`, `mindmap_remember`, `mindmap_decide`, and related tools. The Change Tracking and Context subsystems are tightly coupled to these: change-log entries reference graph symbols, and the context engine draws on graph nodes and memories to populate Tier 2. Source: [src/context/progressive-disclosure.ts:140-156]() ## Common Failure Modes - **Non-git projects** — `diff-engine` falls back to mtime-based detection, which cannot compute added/removed line counts. Callers should treat `usedGit: false` summaries as approximate. - **Unbounded Tier 3** — if `fileContents` is large, the on-demand section is truncated to its remaining budget; callers wanting full content must request it explicitly per file. - **FTS5 not available** — `change-log` relies on SQLite FTS5 for BM25 ranking; on builds without FTS5, `mindmap_what_changed` and similar tools degrade to linear scans. Source: [src/change-tracker/change-log.ts:1-12]() - **Empty queries** — `detectContentType` returns `'plain_text'` for empty or whitespace-only input, which means `minimal` compression is a no-op. Source: [src/context/compressor.ts:79-82]() ## See Also - [README.md](README.md) — high-level overview and tool catalog - [package.json](package.json) — dependencies, scripts, and npm metadata - `src/knowledge-graph/` — AST parsing, indexing, PageRank, and semantic search - `src/memory/` — persistent memory, decisions, and session summaries - `src/server.ts` — MCP tool registration and request routing --- ## MCP Tools and CLI Reference ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [Core Engine: Knowledge Graph, Change Tracking, Memory, and Context](#page-core-engine), [Installation, Configuration, and Operations](#page-ops)
Related Source Files The following source files were used to generate this page: - [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json) - [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md) - [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts) - [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts) - [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts) - [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts) - [src/utils/logger.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/utils/logger.ts)
# MCP Tools and CLI Reference ## Overview AI Mind Map v2.0.0 ships as an [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a knowledge graph, change tracker, and memory subsystem to AI coding agents over stdio. The package is published as `ai-mind-map` and is launched via `npx ai-mind-map` (or `npx ai-mind-map install` for setup). The runtime is Node.js `>=18.0.0` and depends on `@modelcontextprotocol/sdk` ^1.12.1 plus a SQLite FTS5 store via `better-sqlite3` for persistence. Source: [package.json]() The release notes describe v2.0.0 as a "Production-grade upgrade — CLI, Cypher, tests, CI/CD, installers," indicating that the public surface consists of a **Command Line Interface** plus a catalog of **41 MCP tools** grouped into seven functional families. Source: [README.md]() (v2.0.0 changelog section). ## MCP Tool Catalog The 41 tools are organised by purpose. The table below is the consolidated reference; full per-tool behaviour is described in the inline JSDoc of each `src/tools/*` module. | Family | Count | Representative Tools | |--------|:----:|----------------------| | Code Memory Engine | 7 | `mindmap_session_resume`, `mindmap_session_start`, `mindmap_session_end`, `mindmap_changelog`, `mindmap_hotspots`, `mindmap_digest`, `mindmap_file_digest`, `mindmap_verify` | | Knowledge Graph | 6 | `mindmap_search`, `mindmap_get_structure`, `mindmap_trace_dependencies`, `mindmap_get_signature`, `mindmap_find_references`, `mindmap_get_file_map` | | Smart Tools (99% token savings) | 3 | `mindmap_explain`, `mindmap_git_changes`, `mindmap_smart_search` | | Semantic Search | 3 | `mindmap_semantic_search`, `mindmap_semantic_stats`, `mindmap_synonyms` | | Change Tracking | 3 | `mindmap_what_changed`, `mindmap_session_diff`, `mindmap_impact_analysis` | | Memory | 5 | `mindmap_recall`, `mindmap_remember`, `mindmap_get_decisions`, `mindmap_decide`, `mindmap_session_summary` | | Advanced Analysis | 7 | `mindmap_query_graph` (Cypher-like), `mindmap_dead_code`, and 5 others | Source: [README.md]() (the "Tools" section enumerates all 41 names with per-tool token-saving estimates). Each tool is a thin JSON-RPC method exposed by the MCP SDK; the server implementation funnels them through three internal engines (Knowledge Graph, Change Tracker, Memory) before returning compact, budget-bounded responses. Source: [README.md]() (architecture diagram in "How the Memory System Works"). ## CLI Commands The v2.0.0 installer adds two entry points to the user experience: - `npx ai-mind-map install` — auto-detects supported agents (Claude Code, Cursor, VS Code, Windsurf, Antigravity, Zed, Continue.dev) and writes an `mcpServers` block plus a rules file (`CLAUDE.md`, `.cursorrules`, etc.) into each one's config directory. Source: [README.md]() (sections "Install in One Command" and "What Gets Written"). - `ai-mind-map doctor` — runs diagnostics across Node.js version, SQLite availability, the compiled `dist/index.js` artefact, and detected agent configs. Source: [README.md]() (section "Verify It Works"). Local development uses the underlying Node entrypoint: ```bash node dist/index.js --project-root . --log-level debug ``` Source: [README.md]() (section "Development"). The logger module accepts the same `debug` / `info` / `warn` / `error` levels and writes to stderr so it never collides with MCP JSON-RPC traffic on stdout. Source: [src/utils/logger.ts:11-22]() ## How the Engines Compose The three engines (Knowledge Graph, Change Tracker, Memory) feed a shared **Context Engine** that applies content-aware compression, progressive disclosure, and an explicit token budget before any tool result reaches the agent. The flow is: ```mermaid flowchart LR A[AI Agent
Claude / Cursor / Copilot] -->|JSON-RPC| B(MCP Server
41 tools) B --> C[Knowledge Graph
tree-sitter + SQLite FTS5] B --> D[Change Tracker
chokidar + simple-git] B --> E[Memory
Mem0-style decay] C --> F[Context Engine] D --> F E --> F F --> G[Compressed + Budgeted Response] G --> A ``` Source: [README.md]() (architecture block diagram). ### Token Budget Manager The Context Engine enforces four per-component budgets — `graphResults`, `changeSummary`, `memoryRetrieval`, `fileContent` — and reports a `savingsPercent` against the naive "read the whole file" baseline. Source: [src/context/token-budget.ts:23-45]() ### Content-Aware Compression The compressor auto-detects nine content types (source code, JSON, YAML, markdown, build logs, configs, etc.) and applies a level-appropriate strategy: `minimal` (whitespace), `moderate` (signatures + doc comments for code, error lines for logs), or `aggressive` (signatures-only, errors-only). Source: [src/context/compressor.ts:31-80]() ### Progressive Disclosure Context is assembled in three tiers: Tier 1 (≤ 500 tokens, always loaded — project identity, skeleton, conventions), Tier 2 (≤ 2 000 tokens, searchable — graph hits, recent changes, decisions), and Tier 3 (variable, on-demand — full file bodies, historical diffs). Source: [src/context/progressive-disclosure.ts:21-50]() ## Common Failure Modes - **Non-MCP clients** (Ollama, LM Studio, raw Codex): the README marks these as ⚠️ and routes users through Continue.dev or Open WebUI, which do speak the MCP spec. Source: [README.md]() (compat table). - **CI reproducibility**: v2.0.0 added a fix to commit `package-lock.json` so deterministic builds are restored on fresh runners. Source: [README.md]() (v2.0.0 changelog). - **Git-less projects**: the diff engine transparently falls back to filesystem `mtime` comparisons when no `.git` directory is found, so `mindmap_what_changed` and friends still work. Source: [src/change-tracker/diff-engine.ts:18-28]() ## See Also - [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md) — full tool descriptions, install steps, and architecture overview - [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json) — dependency graph, Node engine, npm scripts - [src/context/](https://github.com/shdra06/ai-mind-map/tree/main/src/context) — compressor, token-budget, and progressive-disclosure modules - [src/change-tracker/](https://github.com/shdra06/ai-mind-map/tree/main/src/change-tracker) — git-aware diff engine - [GitHub Actions CI](https://github.com/shdra06/ai-mind-map/actions/workflows/ci.yml) — pipeline that gates releases --- ## Installation, Configuration, and Operations ### Related Pages Related topics: [Overview and System Architecture](#page-overview), [MCP Tools and CLI Reference](#page-tools-cli)
Related Source Files The following source files were used to generate this page: - [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json) - [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md) - [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts) - [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts) - [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts) - [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts) - [src/change-tracker/change-log.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/change-log.ts)
# Installation, Configuration, and Operations ## Purpose and Scope AI Mind Map is an MCP (Model Context Protocol) server that gives coding agents a persistent, queryable memory of a codebase. The Installation, Configuration, and Operations surface covers everything needed to get the server running, wire it into supported agents, and keep it healthy in day-to-day use. The v2.0.0 release promoted the project to production-grade by adding a CLI, installer scripts, diagnostics, and a Cypher-style query layer on top of the existing MCP tools. Source: [package.json:1-30]() The project targets Node.js >= 18 and bundles a curated set of native and parsing dependencies. Core runtime dependencies include `@modelcontextprotocol/sdk` for the MCP transport, `better-sqlite3` for the embedded knowledge-graph and change-log store, `chokidar` for filesystem watching, `tree-sitter` plus optional language grammars for AST parsing, and `simple-git` for git-aware diffing. Source: [package.json:31-50]() ## Installation Three installation paths are supported, each suited to a different audience. ### 1. Automatic (npx, recommended) The fastest path delegates both the fetch and the agent wiring to the installer: ```bash npx ai-mind-map install ``` This detects all seven supported agents (Claude, Cursor, VS Code, Windsurf, Antigravity, Zed, Continue.dev), writes the MCP server entry into each agent's config file, deploys the rules file so the agent knows about the 41 MCP tools, and runs diagnostics to verify the installation. Source: [README.md:1-30]() ### 2. Platform installers The repository ships shell and PowerShell installers for users who prefer explicit setup. After running the installer, the project is ready to launch via the published binary on PATH. The same entry — `npx -y ai-mind-map` — is what the agents invoke, so they will fall back to the npm registry if the binary is not on PATH. Source: [README.md:31-60]() ### 3. Manual / from source For development or offline use, the project can be built from source. After cloning: ```bash npm install npm run build node dist/index.js ``` This produces the same MCP server that the packaged binary exposes, and is the configuration used by the CI workflow. Source: [package.json:51-70]() ## Agent Configuration Once installed, each agent loads the server through its own MCP config block. The canonical snippet written by the installer is: ```json { "mcpServers": { "ai-mind-map": { "command": "npx", "args": ["-y", "ai-mind-map"] } } } ``` This contract is intentionally minimal: there are no per-project secrets, API keys, or endpoints to manage. The server is local, stateless from the network's perspective, and resolves the project root from the agent's working directory. Source: [README.md:31-60]() Project-level configuration is provided through a `.mindmap.json` file at the repository root. It controls which paths are indexed, language filters, and token-budget defaults used by the context engine. The example file in the repository documents the full schema and is the recommended starting point for tuning. Source: [.mindmap.example.json]() ## Operations and Diagnostics The CLI introduced in v2.0.0 exposes the operational surface of the server. The most important command is `doctor`, which validates the runtime environment: ```bash ai-mind-map doctor ``` A healthy run reports Node.js version compatibility, an in-memory SQLite test, the presence of the built `dist/index.js` artifact, and the number of detected agents with valid configuration. This is the same diagnostic invoked automatically by `npx ai-mind-map install`, so post-install verification is a no-op for the user. Source: [README.md:31-60]() ### Context engine At runtime, three cooperating modules control how much of the codebase reaches the model: - **Content-Aware Compression** detects the kind of content it receives (source code, diff, stack trace, test output, JSON, markdown, config, build log, plain text) and applies one of three levels: `minimal` (whitespace and comment cleanup), `moderate` (signatures only, error lines only, etc.), and `aggressive` (signatures, errors, and structural markers only). The result always includes the original and compressed token counts so callers can reason about the ratio. Source: [src/context/compressor.ts:1-50]() - **Token Budget Manager** allocates explicit per-component budgets (`graphResults`, `changeSummary`, `memoryRetrieval`, `fileContent`), enforces them, truncates at logical boundaries, and reallocates when one component is under-budget. A formatted report exposes per-component usage and an estimated savings percentage. Source: [src/context/token-budget.ts:1-50]() - **Progressive Disclosure** loads context in three tiers: Tier 1 (always loaded, ≤ 500 tokens) for project identity and conventions, Tier 2 (searchable, ≤ 2000 tokens) for ranked graph results, recent changes, and memories, and Tier 3 (on-demand, variable budget) for compressed file contents. Tier 2 results are sorted by query relevance before the budget is enforced, so the most useful nodes are the last to be dropped. Source: [src/context/progressive-disclosure.ts:1-50]() ### Change tracking and diff engine The change subsystem is what makes the server's memory persistent across sessions. The diff engine combines `simple-git` output with filesystem timestamps so non-git projects still produce useful summaries, and exposes `since`/`until` time ranges plus include/exclude glob patterns. Source: [src/change-tracker/diff-engine.ts:1-40]() The change log persists every detected change to SQLite with FTS5 full-text search and BM25-ranked retrieval. Sessions group related changes, and the store supports symbol-scoped queries, time-range queries, pagination, pruning, and aggregate statistics such as most-changed files and most-active sessions. Source: [src/change-tracker/change-log.ts:1-50]() ## Operational Flow ```mermaid flowchart LR A[npx ai-mind-map install] --> B[Detect Agents] B --> C[Write MCP Config + Rules] C --> D[Run doctor] D --> E{Healthy?} E -- yes --> F[Agent launches npx -y ai-mind-map] E -- no --> D F --> G[MCP Server: index + memory + diff] G --> H[Context Engine: compress + budget + tiers] H --> I[41 MCP Tools to the agent] ``` ## Common Failure Modes - **Stale build artifact**: `doctor` reports `dist/index.js` missing — rerun `npm run build`. - **Agent not picked up**: the installer only writes config files it can locate; on a non-standard install path use the manual MCP snippet. - **Budget pressure**: if Tier 2 graph results are repeatedly truncated, raise `graphResults` in the token-budget configuration or narrow the query terms so relevance sorting can keep the most useful nodes within budget. Source: [src/context/progressive-disclosure.ts:1-50]() ## See Also - Architecture and tool reference: see the project README. - Compression internals: `src/context/compressor.ts`. - Budget enforcement and reports: `src/context/token-budget.ts`. - Change history and sessions: `src/change-tracker/change-log.ts`. --- --- ## Pitfall Log Project: shdra06/ai-mind-map Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification. ## 1. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/shdra06/ai-mind-map ## 2. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/shdra06/ai-mind-map ## 3. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map ## 4. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/shdra06/ai-mind-map ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/shdra06/ai-mind-map ## 6. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map ## 7. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map