# GraphFlow

English | [中文](README.zh.md)

[![npm version](https://img.shields.io/badge/npm-1.17.1-blue)](https://www.npmjs.com/package/@roarpeng/graphflow)

> **The memory & context harness for coding agents.** Local-first code knowledge graph · bounded context compression (95.6% vs a realistic top-K-files read; see [both baseline arms](benchmarks/RESULTS.md)) · 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; measured against a realistic top-K-files read, see [benchmarks/RESULTS.md](benchmarks/RESULTS.md)). 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](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](benchmarks/README.md)) with published methodology ([docs/benchmark-standards.md](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.

- **Token savings, two arms — quote them separately** (8-query suite, independently re-counted with `gpt-tokenizer`): **95.6%** against the fair counterfactual (the same ranker's top-10 anchors resolved to real files and read in full: 136,265 → 6,044 tokens) and **98.5%** against a naive term-frequency grep baseline (410,725 → 6,044), whose denominator is an upper bound by construction. The realistic arm cannot inflate itself: anchors pointing at fewer or smaller files make its savings *smaller*. Details: [benchmarks/RESULTS.md](benchmarks/RESULTS.md)
- **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`](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](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](docs/team-memory-security.md).

## Quick start

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

```bash
# 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 / …):

```json
{
  "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](docs/graphflow-serena.md) (`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](docs/atp-ir-spec-v1.md) | — | — | — |

> 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](docs/graphflow-serena.md) ([中文](docs/graphflow-serena.zh.md); [comparison](docs/comparison.md)).

## Core capabilities (v1.17+)

| 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](docs/atp-ir-spec-v1.md) |
| **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; **post-packaging accounting** (dialogue recall lines and workbench prompt lines count against the reported budget; `dialogueHits` reported separately as `unbudgetedTokens` so savings are computed on the true total) |
| **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](docs/team-memory-security.md) |
| **Benchmarks** | [Comprehensive 92.9%](benchmarks/COMPREHENSIVE-RESULTS.md) · [Independent-style 96.2%](benchmarks/INDEPENDENT-RESULTS.md) · [context-readiness eval](benchmarks/SWE-BENCH-RESULTS.md) · token savings with **two baseline arms** — [95.6% realistic / 98.5% naive grep](benchmarks/RESULTS.md) |
| **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 install · uninstall · doctor for **every** registered host: 4 hand-written slices (Cursor / Claude Code / DeepSeek Harness / Kimi Code) + a generic profile-backed slice for the rest |
| **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):

```bash
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

```bash
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](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):

```json
{ "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](docs/team-memory-security.md).

## Benchmarks

- **Comprehensive**: [COMPREHENSIVE-RESULTS.md](benchmarks/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](benchmarks/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](benchmarks/SWE-BENCH-RESULTS.md) — self-built 12-instance context-readiness eval; [SWE-BENCH-REAL-RESULTS.md](benchmarks/SWE-BENCH-REAL-RESULTS.md) — Flask real-project 10-instance file-recall eval (48.3%)
- **Token savings**: [RESULTS.md](benchmarks/RESULTS.md) — 8 representative queries, **98.2%** savings, re-counted with independent gpt-tokenizer
- **Retrieval quality**: [RETRIEVAL-EVAL-RESULTS.md](benchmarks/RETRIEVAL-EVAL-RESULTS.md) — 132 queries, Hit@5=100%, MRR=0.836, NDCG@5=0.601
- **Skill flywheel A/B**: [SKILL-AB-RESULTS.md](benchmarks/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](https://github.com/Roarpeng/GraphFlow/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](https://agent-plugins.org). GraphFlow ships as a portable package at the repository root:

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

**Install in Cursor (local):**

```bash
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](docs/context-contract.md) · [Experience memory](docs/experience-memory.md)

**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:

```bash
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](https://www.deepseek.com/harness/en/) 的 [`dsh-plugin`](https://github.com/topics/dsh-plugin)。包内 `dsh.bundle` + `cordis.patch.yml` 会把 GraphFlow MCP 挂到内置 `@deepseek-ai/dsh-mcp-client`，并把 `@roarpeng/graphflow/dsh` glue 插入插件树。模型看到的工具名是 `mcp__graphflow__graphflow_*`。中文说明见 [README.zh.md](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（推荐）：**

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

**或在已有 `~/.dsh` 时写 home 级 overlay（对所有 profile 生效）：**

```bash
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:

```bash
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`), Kimi Code CLI, and more (15+). **Every** registered host goes through the HostAdapter registry (`installViaHostAdapter`); the legacy installers now only cover host-scoped extras (Trae user Skills, project-level rules).

| 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](docs/atp-ir-spec-v1.md): work-item registry, submit/merge contract, compatibility rules. Third-party tools can implement compatible producers / consumers. Minimal Producer example: [`examples/atp-minimal-producer/`](examples/atp-minimal-producer/). Dual-MCP compose snippet (GraphFlow + Serena, config only): [`examples/graphflow-serena.mcp.json`](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](CONTRIBUTING.md): dev environment, code style, test requirements and PR checklist
- [Roadmap](ROADMAP.md): completed milestones and next steps (P0–P2)
- [Issues](https://github.com/Roarpeng/GraphFlow/issues): bug reports and feature requests (please use the built-in templates)
- [Discussions](https://github.com/Roarpeng/GraphFlow/discussions): questions and ideas

## Development

```bash
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

```text
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](CHANGELOG.md). License: Apache-2.0.