GraphFlow

English | 中文

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

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:

• ~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. Third-party reproduction is actively welcomed — see ROADMAP.md for the open invitation.

Memory poisoning protection

…