GitHub - Roarpeng/GraphFlow: Local-first code knowledge graph and context harness for coding agents. MCP + DeepSeek Harness (dsh) plugin. · GitHub
Skip to content

Latest commit

 

History

356 Commits

Folders and files

Repository files navigation

GraphFlow

English | 中文

npm version

The memory & context harness for coding agents. Local-first code knowledge graph · bounded context compression (~98% token savings) · cross-session learning flywheel.

The community is converging on an "agent harness" vocabulary: memory + hooks + skills are the harness primitives that turn a stateless model into a reliable long-running agent. GraphFlow implements all three for coding agents and ships them through a portable MCP surface (Cursor, Claude Code, 15+ agents):

Harness primitive GraphFlow implementation
Memory 12-language AST code graph + Episodic / Skill / Decision nodes �project knowledge and project experience persist across sessions
Hooks Outcome auto-capture (on by default) + Claude Code SessionEnd / Stop and DeepSeek Harness agent/disposed glue close the learning loop automatically �no manual outcome reporting required
Skills A four-class flywheel (proven / correctable / anti-pattern / noise) with canary validation �skills are promoted by evidence, not by assertion

Pure TypeScript/Node. CLI + MCP + VS Code extension. Fully offline, no API key required.

Why a harness, not another RAG

Most "memory" products are either static injection (load CLAUDE.md / rules files in full on every session) or plain RAG (retrieve chunks, no learning). Both fail in long-lived projects:

  • Static injection pays the same token cost every session regardless of the task, and grows until it is truncated or ignored.
  • Plain RAG retrieves text but never accumulates experience â€?the thousandth task pays the same cost as the first.

GraphFlow is a harness: memory is dynamic and typed. Each request retrieves only what the current decision needs �graph anchors, compressed summaries, similar past episodes, applicable skills �under an explicit token budget (L0–L3 layered compression, ~98% savings measured). What the agent learns (outcomes, lessons, skills) is written back through hooks, so the harness gets better with use.

It is also local-first and portable: everything runs offline with no API key, and the whole surface is exposed over MCP, so the same memory travels across agents instead of being locked into one vendor's format.

Proof, not promises

Third-party reproduction entry: npm run proof:flywheel �one command, offline, no API key. Guide: docs/flywheel-reproduction.md. Independent runs are welcome; open a GitHub issue titled [benchmark] Independent reproduction �<commit>.

All headline numbers come from a public, reproducible benchmark suite (benchmarks/README.md) with published methodology (docs/benchmark-standards.md) and machine-readable JSON dumps pinned to commits. Authoritative percentages live in the tracked RESULTS markdown; this package does not invent new scores.

  • ~98% token savings (8-query suite, 262,926 â†?2,843 tokens; independently re-counted with gpt-tokenizer)
  • 132-query golden retrieval set in CI (Hit@5 = 100%, MRR = 0.836, NDCG@5 = 0.601); downloadable open dataset: benchmarks/datasets/retrieval-golden-v1.json â€?run npm run bench:retrieval
  • Skill A/B: 100% vs 61.5% task success with the flywheel on vs off (26 tasks)
  • Memory ROI: 100% vs 56.5% with episodic memory on vs off (62 tasks, with attribution chains)

Results are commit-anchored so any number above can be checked out and re-run. See ROADMAP.md for the open invitation.

Memory poisoning protection

Shared and synced memory is only useful if it cannot be silently corrupted. Skills merged from external sources (e.g. skill sync imports) are treated as unproven until validated locally: imported skills carry provenance markers, never enter the proven class directly, must pass canary validation on real tasks before promotion, and anti-pattern skills are isolated rather than deleted so they can be audited. Promotion is gated by the four-class lifecycle, not by trust in the source. See docs/team-memory-security.md.

Quick start

No API key needed (offline AST indexing + graph compression):

# 1. Build the graph offline (AST indexing, no LLM)
npx @roarpeng/graphflow graph index .

# 2. Preview compressed context (anchors + summaries, 90%+ token savings)
npx @roarpeng/graphflow context preview "orchestrator" --json

Connect via MCP (Cursor / Claude Code / �:

{
  "mcpServers": {
    "graphflow": {
      "command": "npx",
      "args": ["-y", "--package=@roarpeng/graphflow", "graphflow-mcp"]
    }
  }
}

The agent calls graphflow_context for compressed context, then graphflow_plan to plan; without a provider API key GraphFlow automatically bridges the ATP thinking protocol to the host agent (agent-delegated mode). For symbol-precise edits, compose Serena as a second MCP server �GraphFlow + Serena (examples/graphflow-serena.mcp.json).

Why GraphFlow

Single-purpose tools each do one thing well; GraphFlow combines graph + compression + planning protocol + learning memory in one place:

Capability GraphFlow CodeGraph Serena Repomix
Code graph 12-language AST index more mature LSP symbols �
Context compression layered + graph compression + vector recall partial partial whole-repo dump
Planning protocol ATP IR + DAG + agent bridge � � �
Learning memory Episodic / Skill / Decision flywheel � � �
Local-first � � � �
Open protocol ATP/IR public spec � � �

The differentiator is the learning flywheel: graph indexing and token compression are replicable; project-private experience (skills, lessons, decisions) accumulated across sessions is not �it compounds with use. Serena is a complement, not a competitor �see GraphFlow + Serena: better together (中文; comparison).

Core capabilities (v1.15+)

Module Capability
Planning protocol ATP v1.1 (Intent / Requirement / Six Hats / 5-Why / First Principles / Decision Matrix / Planning / Reflection); simple / complex / insight modes; agent-delegated bridge without an LLM; skill-conditioned DAG (skillRefs / avoidPatterns on plan nodes); ATP/IR public spec v1.1
Goal alignment Goal anchor nodes (intent five-tuple as first-class citizen, original requirement auto-injected); low-confidence clarification gate (no plan below 0.6); runtime alignment-check; deviation classification (misread-requirement / scope-creep / tech-drift); goal version chain + diffs
Knowledge graph 12-language AST indexing; File / Module / Symbol + Concept / Requirement; cross-layer edges documents / implements / derived_from; Office/PDF �Markdown via optional @firecrawl/anydoc (MIT). CLI/npm: optionalDependency. VSIX: not bundled; on activate the extension auto-downloads the current-OS binary into ~/.graphflow/optional-deps when graphflow.downloadAnydoc is true (default). Disable the setting to skip network; source indexing still works.
Context compression L1/L2/L3 layered anchors; graph compression (edge weights + PageRank, LRU cache); stem-matching recall (orchestrate �orchestration); vector recall + RRF; RepoMap overview; adaptive budget
Retrieval & fidelity Golden-set regression gate (132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601); separate anchor-recall and normalized body-coverage metrics persisted beside token savings
Vector index In-process memoization + disk persistence (fingerprint-checked, seconds to restore after MCP restart)
Storage backends file / memory / sqlite (FTS5, tokenizer-enhanced searchtext, camelCase searchable) / auto (sqlite-first with fallback) / mcp-http
Learning flywheel Episodic memory, reflection, skill nodes (score ±1, bounded [-20,20]), nightly training, adaptive evidence-aware forgetting, auto-capture + Claude Code hooks (on by default), SkillOpt-lite bounded guidance edits, four-class lifecycle + canary gate for synced skills, portable SKILL.md import/export, npm run backfill:episodes, contribution reports (skill report / graphflow_diagnose / route diagnose)
Team sharing graphflow team serve (tenant + RBAC) + skill sync export/import/push/pull; imports/pulls are a bidirectional MERGE; golden queries via .graphflow/team-golden.json; security model + ops runbook
Benchmarks Comprehensive 92.9% · Independent-style 96.2% · context-readiness eval · 98.2% token savings
Model routing Smart / Economy tiers; multi-provider health probes and fallback (DeepSeek, OpenAI, Anthropic, Bailian, Doubao)
Workbench Plan DAG seeds function-topic containers; collapsed outline; click topicId to resume; drift forks a side branch; original Q/A stored via assistantReply
Observability graphflow_diagnose / route diagnose: provider health + graph stats + token savings + flywheel health (auto-capture, episodes, skills by class, session journal) + workbench outline
Agent surfaces CLI --json; MCP stdio and Streamable HTTP (stateless JSON or stateful SSE, 10 tools); auto-install into 15+ agents (incl. Codex Windows NODE/NPX_CLI short-path MCP). HostAdapter registry owns Cursor / Claude Code / DeepSeek Harness install · uninstall · doctor; other hosts still use the legacy installers
Evidence & governance Outcome evidence packages (commit/diff/tests), evidence backfill, tamper-evident audit chains, ADR/Invariant/APIContract/Test review states, artifact three-way merge/signing/encryption, retention/quarantine, release gates
Engineering quality TypeScript strict; vitest suite; npm run ci includes extension packaging and smoke tests

Positioning

GraphFlow is not an orchestrating executor �it is the memory & context harness for coding agents. Task execution is delegated to the host coding agent via bridge mode (honest semantics, no faked COMPLETED); GraphFlow's job is to make the agent see clearly and remember.

MCP tools (10)

Tool Function
graphflow_context Compressed context package (query �anchors + summaries; topicId / assistantReply to resume a workbench node or fill the pending answer; anchorId �expand)
graphflow_plan Task planning (mode='simple' or 'insight'; seeds workbench.topics + workbench.outline; agent-delegated without an LLM)
graphflow_run Orchestration + bridge execution descriptor
graphflow_report_outcome Outcome backfill (incl. deviation classification), closes the learning flywheel
graphflow_insight ATP insight submit / merge (agent bridge protocol)
graphflow_index Incremental / full indexing; optional knowledgeExtract: true distills dialogue turns into Concept / Requirement nodes with provenance edges
graphflow_skill_insights Skill insights
graphflow_diagnose Diagnostics (provider + graph + token savings + flywheel + graph.workbenchOutline)
graphflow_artifact Graph artifact import / export
graphflow_skill_guide GraphFlow skill usage guide

MCP workspace resolution: the workspace is discovered automatically from the MCP client cwd; override with GRAPHFLOW_WORKSPACE_ROOT.

Workbench navigation (v1.9.14)

Everyday chat stays a single thread. Complex work seeds a workbench of function-topic containers from graphflow_plan �one canvas node per plan step, not one node per turn. Click a node and pass topicId to graphflow_context to refine that function or return to the mainline. Drift auto-forks an isolated side branch (co_occurs); the trunk is not overwritten. After answering, call graphflow_context({ assistantReply }) so the original reply is stored. Outline titles are display labels only; next-turn context is Goal + ancestor titles + the node's original Q/A.

Wake the collapsed outline when you need it (still 10 MCP tools):

graphflow workbench tree --json            # CLI
# VS Code / Cursor: GraphFlow: Workbench Tree (Activity Bar, default collapsed) or chat /tree
# MCP: graphflow_diagnose �graph.workbenchOutline
graphflow context preview --topic-id "<topic:...>" "continue from this node"
graphflow context preview --reply "original assistant answer"

CLI quick reference

graphflow graph index .                    # build the graph
graphflow context preview "orchestrator"   # preview compressed context
graphflow plan "refactor planner" --json   # plan (also seeds workbench topics)
graphflow workbench tree --json            # on-demand function DAG + side branches
graphflow run "update readme"              # orchestrate (bridge)
graphflow skill insights                   # skill insights
graphflow skill report                     # flywheel contribution report
graphflow mcp serve --http                 # stateless MCP Streamable HTTP (add --stateful for SSE sessions)
graphflow team serve                       # team graph JSON-RPC (tenant + RBAC; non-loopback requires auth)
graphflow outcome backfill --evidence evidence.jsonl  # close pending episodes with evidence packages
graphflow governance release-gate         # enforce proven-skill/fidelity/pending gates
graphflow skill sync export                # export team skill pack + golden queries (share via git)
graphflow skill sync import                # import team skill pack (MERGE; --force to overwrite) + golden merge into .graphflow/team-golden.json
graphflow route diagnose                   # routing diagnostics
graphflow learn nightly                    # nightly learning
graphflow doctor                           # install self-check

Configuration

Three-layer merge: global ~/.graphflow.config.json �project graphflow.config.json �project .graphflow/config.json. Copy graphflow.config.example.json to get started.

Key options:

Option Description
graphPolicy.transport file / memory / sqlite / auto (recommended: sqlite-first, falls back to file) / mcp-http
graphPolicy.maxContextTokens Context budget (default 1500)
graphPolicy.autoIndexOnSave Auto incremental index on save (default true)
embeddingPolicy.provider transformers (local default) / openai / hash
embeddingPolicy.vectorStorePath Vector index persistence path (.hnsw derived automatically)
skillPolicy.enableSkillFlywheel Learning flywheel switch

Team backend pilot

Set graphPolicy.transport to mcp-http to host the graph on a remote Graphify service (shared by the team); requires graphPolicy.mcpEndpoint (http(s) URL, optional mcpApiKey bearer token):

{ "graphPolicy": { "transport": "mcp-http", "mcpEndpoint": "http://graphify.team.internal:8080" } }

A missing/malformed endpoint fails at config validation; connection or runtime request failures degrade transparently to local JSON storage (graphPolicy.graphStorePath, default graphflow-out/graphflow-graph.json) with a logger.warn, consistent with the sqlite→file fallback, never interrupting the agent. HTTP 401/403 (auth / RBAC deny) do not degrade �they throw. graphflow team serve implements graph.read_snapshot and team.health; third-party Graphify servers without those methods still fall back to the local mirror. See docs/team-memory-security.md.

Benchmarks

  • Comprehensive: COMPREHENSIVE-RESULTS.md â€?P1–P6 six-dimension evaluation, overall 92.9% (indexing 100% / compression 64.9% / planning 100% / learning 100% / bridge 100% / performance 99.7%)
  • Independent-style: INDEPENDENT-RESULTS.md â€?CodeGraph-style 5-domain evaluation, Hit@5 96%, token savings 96.6%, overall 96.2%
  • SWE-bench-style: SWE-BENCH-RESULTS.md â€?self-built 12-instance context-readiness eval; SWE-BENCH-REAL-RESULTS.md â€?Flask real-project 10-instance file-recall eval (48.3%)
  • Token savings: RESULTS.md â€?8 representative queries, 98.2% savings, re-counted with independent gpt-tokenizer
  • Retrieval quality: RETRIEVAL-EVAL-RESULTS.md â€?132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601
  • Skill flywheel A/B: SKILL-AB-RESULTS.md â€?injection rate 100%, recall 100%, overhead 25.6 tok/task

VS Code / Cursor extension

Download graphflow-<version>.vsix from GitHub Releases (or Open VSX: roarpeng.graphflow).

Commands: Settings / Show Graph (graph visualization) / Preview Context / Plan & Brainstorm / Run Task / Skill Insights / Install MCP; chat agent @graphflow (/run /plan /graph /skills /diagnose /learn /history).

Agent Plugins 1.0

Primary install path for hosts that support Agent Plugins. GraphFlow ships as a portable package at the repository root:

plugin.json              # Agent Plugins 1.0 manifest
mcp.json                 # stdio MCP (type required by the spec)
skills/graphflow/SKILL.md

Install in Cursor (local):

mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/GraphFlow ~/.cursor/plugins/local/graphflow
# then Restart Cursor / Developer: Reload Window

Install via Team Marketplace / Git: import this repository; clients discover plugin.json, then load skills/ and mcp.json.

Docs: Context Engineering contract · Experience memory

Uninstall: Removing the Agent Plugin in Cursor only drops the plugin package. Skills/Rules/MCP written by graphflow install remain and will keep steering the agent �run:

npx @roarpeng/graphflow uninstall

That removes user + workspace MCP entries, skills/graphflow folders, GraphFlow rules/instruction blocks, Claude Code hooks, and the DeepSeek Harness cordis.patch.yml overlay. Also delete any local symlink under ~/.cursor/plugins/local/graphflow if you used one.

DeepSeek Harness �件(用法与能力�

GraphFlow �DeepSeek Harness �dsh-plugin。包�dsh.bundle + cordis.patch.yml 会把 GraphFlow MCP 挂到内置 @deepseek-ai/dsh-mcp-client,并�@roarpeng/graphflow/dsh glue �入�件树。模型看到的工具�是 mcp__graphflow__graphflow_*。中文说明� README.zh.md�

*�dsh 上能工作 vs �能工作�

能力 dsh
10 �MCP 工具(mcp__graphflow__graphflow_*),stdio cwd = 会�工作� �
Skill(on-demand skill({name:"graphflow"});bundle glue 注册,�必先 graphflow install� �
会�结�飞轮:仅 agent/disposed 关闭 pending episode(��live session/flush;GRAPHFLOW_AUTO_CAPTURE=0 �关� �
首轮�hint:先�graphflow_context(rootDir = cwd� �
Workbench 数�(topicId / outline)� MCP graphflow_context / graphflow_diagnose �
VS Code/Cursor 图谱���Settings webview�Workbench Tree�@graphflow chat **�*(宿�UI,�移��
Cursor Agent Plugins 1.0 �现 **�*(dsh �dsh.bundle�
Claude Code SessionStart/End/Stop 文件 hooks **�*(dsh analog 是上�的 glue�

*装进�个 profile(推�)�

dsh plugin --profile web add @roarpeng/graphflow
npx @deepseek-ai/dsh web

或在已有 ~/.dsh 时写 home �overlay(对所�profile 生效):

npx @roarpeng/graphflow install

会写�$DSH_HOME/cordis.patch.yml(MCP + glue)与 $DSH_HOME/skills/graphflow/SKILL.md。�载:npx @roarpeng/graphflow uninstall,或 dsh plugin --profile web remove @roarpeng/graphflow。graphflow doctor 会检�overlay�glue�skill�

*用法� 第一轮先 mcp__graphflow__graphflow_context(传�rootDir = 仓库�对路径),��任务�graphflow_plan;改完代�� graphflow_index;若走了 graphflow_run,结��必须 graphflow_report_outcome。��在 patch 里写�GRAPHFLOW_WORKSPACE_ROOT�

Agent integrations

Use npx @roarpeng/graphflow install as the fallback when you need Rules, multi-agent wiring, or a host that does not load Agent Plugins:

npx @roarpeng/graphflow doctor     # detect installed agents
npx @roarpeng/graphflow install    # auto-install MCP + Skill + Rules
npx @roarpeng/graphflow uninstall  # remove MCP + Skill + Rules + hooks
npx @roarpeng/graphflow init       # write a minimal project config

Supported: Cursor, VS Code, Trae (incl. CN), Claude Code, Windsurf, Cline, Roo Code, Kilo Code, Gemini CLI, Codex, Antigravity, Opencode, Qoder, Amazon Q, Zed, Continue, DeepSeek Harness (dsh), and more (15+). Cursor, Claude Code, and DeepSeek Harness go through the HostAdapter registry (installViaHostAdapter); remaining hosts still use the legacy installers.

Path When to use
Agent Plugins Preferred single-host Skill + MCP discovery
graphflow install Rules / multi-agent / non-plugin hosts
graphflow uninstall After removing a plugin (or anytime) �clears leftover Skill/MCP/Rules

Protocol

ATP/IR �Agent Thinking Protocol public specification v1.0: work-item registry, submit/merge contract, compatibility rules. Third-party tools can implement compatible producers / consumers. Minimal Producer example: examples/atp-minimal-producer/. Dual-MCP compose snippet (GraphFlow + Serena, config only): examples/graphflow-serena.mcp.json.

Community

GraphFlow is a single-maintainer project (bus factor = 1); community collaboration is the key to reducing single-point risk. Contributions welcome:

  • Contributing guide: dev environment, code style, test requirements and PR checklist
  • Roadmap: completed milestones and next steps (P0–P2)
  • Issues: bug reports and feature requests (please use the built-in templates)
  • Discussions: questions and ideas

Development

npm install
npm run ci        # lint + build + tests + extension packaging + smoke

Requires Node.js �20, npm �10. Expected: lint clean, build succeeds, 961 tests pass.

Project structure

GraphFlow/
├── plugin.json         # Agent Plugins 1.0 manifest
├── mcp.json            # Agent Plugins MCP (stdio)
├── cordis.patch.yml    # DeepSeek Harness (dsh) bundle layer (MCP + glue)
├── dsh/plugin.mjs      # dsh ESM glue: skill register + session-end capture
├── skills/graphflow/   # portable Agent Skill (canonical SKILL.md)
├── src/
�  ├── core/           # orchestration core: orchestrator, triage, dag-engine, agent-delegation
�  ├── graph/          # indexing, context slicing, graph compression, sqlite/auto storage, snapshot
�  ├── routing/        # model routing and health probes (5 providers)
�  ├── learning/       # embeddings, episodic, skill-flywheel, hnsw, nightly
�  ├── agents/         # ATP schema, planner, insight, brainstormer
�  └── surfaces/
�      ├── cli/        # CLI + runtime
�      └── mcp/        # MCP server (10 tools)
├── tests/              # 142 files / 961 tests (incl. governance foundation and MCP HTTP/stdio matrix)
├── benchmarks/         # comprehensive + independent + SWE-bench + token savings + skill A/B (reproducible)
├── docs/               # ATP spec + context contract + experience memory + flywheel reproduction + GraphFlow/Serena
├── examples/           # ATP producer + team-memory config + GraphFlow/Serena dual-MCP snippet
├── vscode-extension/   # VS Code panel and commands
└── CHANGELOG.md

Changelog

Full history in CHANGELOG.md. License: Apache-2.0.

About

Local-first code knowledge graph and context harness for coding agents. MCP + DeepSeek Harness (dsh) plugin.

Topics

Resources

Contributing

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages