Doramagic Project Pack · Human Manual

ai-mind-map

🧠 MCP Server that reduces AI coding agent token usage by 80-99%. Knowledge graph + persistent memory + smart compression for Claude, Cursor, Copilot, and any MCP-compatible agent.

Overview and System Architecture

Related topics: Core Engine: Knowledge Graph, Change Tracking, Memory, and Context, MCP Tools and CLI Reference, Installation, Configuration, and Operations

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Knowledge Graph

Continue reading this section for the full explanation and source context.

Section Change Tracker

Continue reading this section for the full explanation and source context.

Section Context Engine

Continue reading this section for the full explanation and source context.

Related topics: Core Engine: Knowledge Graph, Change Tracking, Memory, and Context, MCP Tools and CLI Reference, Installation, Configuration, and Operations

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.

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.

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.

flowchart TB
    subgraph Server["AI Mind Map MCP Server"]
        KG["Knowledge Graph<br/>tree-sitter AST · SQLite+FTS5 · PageRank"]
        CT["Change Tracker<br/>chokidar watcher · git diff · BM25"]
        MEM["Memory<br/>3-tier store · importance · decay"]
        CE["Context Engine<br/>Compressor · Progressive Disclosure · Token Budget"]
    end
    KG --> CE
    CT --> CE
    MEM --> CE
    CE -->|"41 MCP tools over stdio"| Agent["AI Agent<br/>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.

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.

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.

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.

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.

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, src/context/token-budget.ts, 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:

LayerContentsToken CostLifespan
WorkingCurrent task contextFull priceThis conversation
EpisodicSession summaries, recent decisionsOn-demand retrievalDays to weeks
SemanticCodebase graph, architecture, conventionsQueried, never dumpedPermanent (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.

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.

See Also

Source: https://github.com/shdra06/ai-mind-map / Human Manual

Core Engine: Knowledge Graph, Change Tracking, Memory, and Context

Related topics: Overview and System Architecture, MCP Tools and CLI Reference

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Diff Engine

Continue reading this section for the full explanation and source context.

Section Persistent Change Log

Continue reading this section for the full explanation and source context.

Section Content-Aware Compression

Continue reading this section for the full explanation and source context.

Related topics: Overview and System Architecture, MCP Tools and CLI Reference

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

flowchart TD
    A[AI Agent - Claude / Cursor / Copilot] -->|stdio / MCP| B[ai-mind-map Server]
    B --> C[Knowledge Graph<br/>tree-sitter + SQLite]
    B --> D[Change Tracking<br/>simple-git + FTS5]
    B --> E[Memory Layer<br/>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

TierBudgetContentWhen Loaded
Tier 1≤ 500 tokensProject identity, skeleton, conventions, taskAlways
Tier 2≤ 2,000 tokensGraph results, changes, memories, decisionsSearchable
Tier 3VariableFull files, test output, diffs, decisionsOn 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

  • Knowledge Graph — referenced throughout 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 projectsdiff-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 availablechange-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 queriesdetectContentType 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 — high-level overview and tool catalog
  • 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

Source: https://github.com/shdra06/ai-mind-map / Human Manual

MCP Tools and CLI Reference

Related topics: Overview and System Architecture, Core Engine: Knowledge Graph, Change Tracking, Memory, and Context, Installation, Configuration, and Operations

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Token Budget Manager

Continue reading this section for the full explanation and source context.

Section Content-Aware Compression

Continue reading this section for the full explanation and source context.

Section Progressive Disclosure

Continue reading this section for the full explanation and source context.

Related topics: Overview and System Architecture, Core Engine: Knowledge Graph, Change Tracking, Memory, and Context, Installation, Configuration, and Operations

MCP Tools and CLI Reference

Overview

AI Mind Map v2.0.0 ships as an Model Context Protocol 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.

FamilyCountRepresentative Tools
Code Memory Engine7mindmap_session_resume, mindmap_session_start, mindmap_session_end, mindmap_changelog, mindmap_hotspots, mindmap_digest, mindmap_file_digest, mindmap_verify
Knowledge Graph6mindmap_search, mindmap_get_structure, mindmap_trace_dependencies, mindmap_get_signature, mindmap_find_references, mindmap_get_file_map
Smart Tools (99% token savings)3mindmap_explain, mindmap_git_changes, mindmap_smart_search
Semantic Search3mindmap_semantic_search, mindmap_semantic_stats, mindmap_synonyms
Change Tracking3mindmap_what_changed, mindmap_session_diff, mindmap_impact_analysis
Memory5mindmap_recall, mindmap_remember, mindmap_get_decisions, mindmap_decide, mindmap_session_summary
Advanced Analysis7mindmap_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:

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:

flowchart LR
    A[AI Agent<br/>Claude / Cursor / Copilot] -->|JSON-RPC| B(MCP Server<br/>41 tools)
    B --> C[Knowledge Graph<br/>tree-sitter + SQLite FTS5]
    B --> D[Change Tracker<br/>chokidar + simple-git]
    B --> E[Memory<br/>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

Source: https://github.com/shdra06/ai-mind-map / Human Manual

Installation, Configuration, and Operations

Related topics: Overview and System Architecture, MCP Tools and CLI Reference

Section Related Pages

Continue reading this section for the full explanation and source context.

Section 1. Automatic (npx, recommended)

Continue reading this section for the full explanation and source context.

Section 2. Platform installers

Continue reading this section for the full explanation and source context.

Section 3. Manual / from source

Continue reading this section for the full explanation and source context.

Related topics: Overview and System Architecture, MCP Tools and CLI Reference

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.

The fastest path delegates both the fetch and the agent wiring to the installer:

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:

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:

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

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

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

Source: https://github.com/shdra06/ai-mind-map / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

medium Configuration risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Capability evidence risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Maintenance risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

Doramagic Pitfall Log

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
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.host_targets | https://github.com/shdra06/ai-mind-map

2. Capability evidence risk: Capability evidence risk requires verification

  • Severity: medium
  • Finding: README/documentation is current enough for a first validation pass.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.assumptions | https://github.com/shdra06/ai-mind-map

3. Maintenance risk: Maintenance risk requires verification

  • Severity: medium
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map

4. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • 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
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: risks.scoring_risks | https://github.com/shdra06/ai-mind-map

6. Maintenance risk: Maintenance risk requires verification

  • Severity: low
  • Finding: issue_or_pr_quality=unknown。
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map

7. Maintenance risk: Maintenance risk requires verification

  • Severity: low
  • Finding: release_recency=unknown。
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/shdra06/ai-mind-map

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 4

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ai-mind-map with real data or production workflows.

Source: Project Pack community evidence and pitfall evidence