Local-first memory & context harness for coding agents. Provides task planning, context compression, knowledge graph management, and episodic memory for Cursor, Claude Code, and other coding agents.
GraphFlow MCP exposes 11 tools with detailed descriptions and complex schemas. Naming follows verb_noun convention (graphflow_*). Most tools have comprehensive parameter documentation and structured outputs. However, several tools lack clear output schema documentation in the visible code, and some descriptions are overly technical/dense (>400 chars), reducing LLM clarity. Error handling guidance is minimal. Tool composition is sound but some tools combine multiple concerns (e.g., graphflow_context handles preview, expand, archive, and recall in one tool). No tool annotations (readOnlyHint/destructiveHint) visible despite clear read/write semantics.
[Core] Preview near-lossless context packaging OR expand a context anchor. Pass 'query' to preview; pass 'anchorId' (and no query) to expand. After you answer the user, call again with assistantReply (query optional) to write the original answer onto the pending turn/topic. The preview result includes dialogueHits: historical Q&A turns matching the query across sessions (superseded ones hidden; a correctionLine flags conclusions that were later revised). Titles on the workbench are display labels only — do not replace stored messages with an extracted abstract.
[Diagnostic] Return provider health, graph statistics, token savings, and optional workbench outline. Includes routing diagnostics (which LLM provider is active, fallback chain, latency/cost/quality metrics). Pass includeOutline=true to wake the collapsed workbench DAG (mainline + side branches).
[Export] Export graph nodes/edges or skill pack as JSON artifact. Returns artifact handle for large payloads.
[Knowledge Extraction] Extract structured knowledge (entities, relationships, lessons) from a dialogue turn or artifact. Returns extracted nodes ready to merge into the graph.
[Import] Import graph nodes/edges or skill pack from JSON artifact. Merges with existing graph.
graphflow_context combines 5+ distinct operations (preview, expand, archive, recall, reduce) in one tool with overlapping optional parameters. This violates single-responsibility principle and forces LLMs to reason about complex conditional logic.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) visible in definitions despite clear semantic differences (graphflow_run/graphflow_report_outcome are write operations; graphflow_diagnose/graphflow_export are read-only). MCP spec 2026-07-28 recommends these for agent planning.
Output schemas not documented in visible code. Tool descriptions mention return types (e.g., 'returns artifact handle', 'returns node count') but formal JSON Schema output definitions are absent, forcing LLMs to infer structure.
Inferred effective spec: 2026-07-28+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 64 | 2026-07-28+ | v2 |
[Indexing] Index a file or directory into the knowledge graph. Supports code, markdown, PDF, Office docs (with @firecrawl/anydoc). Returns node count and anchors created.
[Core] Submit or merge agent-delegated work-item answers (Six Hats, 5-Why, intent/requirement analysis). Call submit { task, workItemId, response } for each required work item; then call merge { task } to finalize and return the merged plan + insight.
[Core] Generate a DAG-style task plan and seed a workbench of function-topic nodes (workbench.topics + workbench.outline). Click a topic and pass topicId to graphflow_context to refine or return to the mainline. Wake the collapsed outline later via graphflow_diagnose with includeOutline=true (graph.workbenchOutline) or CLI `graphflow workbench tree`. mode='simple' (default) for planning; mode='insight' for Six Hats + 5-Why. Without a GraphFlow LLM API key, BOTH modes bridge to you (the coding agent): simple returns mode='agent-delegated' with lightweight simple-plan-* work items plus optional suggestedNodes (heuristic, non-final); insight returns the full Six Hats work-item set. MUST answer via graphflow_insight (submit then merge).
[Maintenance] Rebuild the knowledge graph from scratch (re-index all source files). Use after major config changes or to recover from corruption.
[Core] Report the real execution outcome of a bridge-mode task back to GraphFlow. After an external coding agent executes the executionDescriptor returned by graphflow_run, it calls this tool to close the learning loop: updates the episode record (pass/fail). Skill score updates require quality lessons; a pass without lessons records the episode but does not apply skill learning. SessionEnd auto-capture does not call this unless success is an explicit argument (pending stays pending).
[Core] Plan and package a task with compressed context, returning a structured execution descriptor for external coding agents (Cursor, Claude Code) to execute. Bridge mode by default. CALL graphflow_report_outcome AFTER executing the plan to close the learning loop.
graphflow_context description is 412 characters (exceeds 200-char LLM-optimized baseline). Dense technical language ('near-lossless context packaging', 'dialogueHits', 'correctionLine') reduces clarity for agent selection.
Error handling guidance absent. No tool description explains what to do on failure (e.g., 'If indexing fails, check file permissions' or 'Retry with a smaller batch'). Agents receive no recovery path.