REAgraph

A persistent, queryable knowledge graph for reverse engineering.

REAgraph turns one-shot reverse-engineering findings into a durable, structural graph of a program — so you (and your AI agent) never reverse the same thing twice, and so you can diff two builds by meaning instead of by byte offset.

It is the memory + structure layer that sits alongside a reverse-engineering engine. It is designed to complement REA (agent-driven reverse engineering, MIT) and graphify (source → knowledge graph, Apache-2.0). It is not affiliated with or endorsed by the REA project.

Status: early. The two core pieces below work and are tested. The live REA wiring and the MCP server are in progress (see docs/DESIGN.md).

Why

Reverse-engineering tools are brilliant sensors but they have three holes:

1. No memory. Findings live in a chat session and evaporate. Every session re-pays the full (slow, token-heavy) cost and rediscovers the same facts.

2. No reliable structure/diff. Version-diffing by byte location reports "everything changed" when code merely moved (REA #4520: a real app diff came back 0 unchanged because bytes shifted).

3. Unamortized cost. Every analysis pays full price; nothing compounds.

REAgraph plugs those three holes: persistent queryable memory, structural (byte-agnostic) identity & diff, and a store whose value compounds as findings accumulate.

Related MCP server: agent-memory-mcp

What works today

• reagraph add — merge a reverse-engineering finding (REA JAG JSON, or any node-link graph) into a persistent reagraph.json, with dedup and confidence upgrade (a later observed fact promotes an earlier inferred one instead of duplicating it).

• reagraph diff A B — a structural diff of two graphs by node/edge identity, immune to byte relocation. This is the fix for the #4520 class of bug: a module that only moved in the file reads as unchanged.

• reagraph summary — a bounded map of a graph of any size (god nodes + clusters), so a gigabyte-scale analysis becomes a short overview an agent can actually read.

• reagraph coverage — an honest verification report: what is observed vs only inferred vs unverified, with the frontier of "probe here next" and the explicit reminder that absence of a finding is not proof of absence.

• reagraph stats — totals and confidence breakdown of the accumulated graph.

• reagraph pull <target> — connect to REA (spawned via npx rea-agents, overridable with $REAGRAPH_REA_CMD), analyze a target, and fold each finding into the graph as it arrives. REAgraph is an MCP client of REA; it vendors no REA code. Degrades gracefully when REA or mcp is absent (use reagraph add). A content-addressed cache (keyed by the artifact's hash + analysis scope) serves a repeat analysis with no REA call (--no-cache / --refresh to override). The cache is local today and the backend is pluggable so a shared tier can drop in later.

• reagraph cache stats|clear — inspect or wipe the local analysis cache ($REAGRAPH_CACHE, default ~/.cache/reagraph).

• reagraph attest --source src.json --shipped shipped.json — does the shipped artifact match the source? Structurally aligns a graphify source graph with a REAgraph shipped-artifact graph (name match where symbols survive, Weisfeiler- Lehman fingerprints where they do not, carrying confidence and abstaining when unsure), then reports the shipped-but-unexplained residual (the supply-chain signal) and a confidence-weighted integrity score. High-signal triage, not an oracle: "unexplained" means "could not confidently match", not "malicious". Alignment uses seed-propagation to recover structure on stripped binaries, still abstaining on ties.

• reagraph doctor — preflight the live pull: checks mcp, node/npx, the resolved REA command, and graphify, with actionable fixes. A clean doctor means prerequisites are present, not that a real REA run was verified.

The analysis cache backend is pluggable: reagraph.remote_cache.RemoteCacheBackend is a shared-tier client (read-only by default so you benefit from others' public analyses without uploading; opt-in push is gated so private artifacts never leak; fail-open). The hosted server it talks to is the next step, not yet built (see docs/CACHE.md).

• reagraph serve — run the REAgraph MCP server (remember / recall / diff / stats) so any agent uses REAgraph as its reverse-engineering memory (needs the mcp package).

• reagraph.bridge — fold a live stream of findings in incrementally, saving after each one (crash-safe) and skipping a bad finding instead of aborting the run (so one malformed symbol never discards the whole analysis).

Quickstart

pip install -e .

# Fold a REA finding (or any node-link graph) into persistent memory
reagraph add finding.jag.json            # writes/updates ./reagraph.json
reagraph add more_findings.jag.json      # merges, dedups, upgrades confidence

reagraph stats                           # nodes/edges/confidence breakdown

# Structural version diff (byte-agnostic)
reagraph diff app-v1.json app-v2.json    # added / removed / rewired, not "0 unchanged"

Query/path/explain over the accumulated graph are delegated to graphify when it is installed (the graph is written in graphify's node-link format):

graphify query "where is the license checked" --graph reagraph.json

How it fits

  agent (Claude Code / Codex / opencode)
        |  asks REA to analyze a region
        v
      REA  --(finding: evidence + epistemic state)-->  reagraph add
        |                                                   |
        |                                           reagraph.json  (persistent memory)
        |                                                   |
        '---- query/path/explain  <----  graphify  <--------'

The agent probes with REA, folds each finding into REAgraph, and queries the accumulated graph before paying for another probe. Cost stops evaporating and starts compounding.

Benchmarks

Reproducible harnesses in bench/ (python bench/bench_*.py). Numbers below are from this machine; they are synthetic and machine-dependent, and the REA-call latency in the cache benchmark is modeled (real REA analyses take seconds to minutes), so treat them as orders of magnitude, not guarantees.

• Diff is byte-agnostic (the #4520 win). On a build where every symbol's location moved but the structure is identical: REAgraph reports 0% changed; a naive location-keyed diff reports 100% changed.

• Alignment abstains instead of mis-matching. Measured against generated ground truth: precision 1.00 both when symbols survive and when the binary is stripped; recall 1.00 with symbols, 0.95 stripped (structure-only). All injected nodes land in the residual (5/5 stripped, 6/6 tampered). Clean vs tampered integrity separation ~0.10 (0.99 vs 0.89).

• Summary stays bounded. A 100k-node graph summarizes to ~1.4 KB (god nodes capped, clusters capped) in ~0.2 s.

• Scale. merge ~2-4M nodes/s, diff ~1-3M nodes/s, summarize ~0.5-0.9M nodes/s; align ~0.1M nodes/s (heavier: Weisfeiler-Lehman + propagation).

• Cache. A repeat analysis is served with no REA call: a hit costs ~90µs vs re-running the analysis. At a modeled 30 s/analysis over 10 repeats that is ~270 s saved; the win compounds across sessions, teammates, and CI.

Roadmap

See docs/DESIGN.md. Near-term: incremental live-ingest from the REA MCP server, an MCP server exposing the memory to agents, demand-scoped re-analysis, and a shared analysis cache keyed by artifact hash.

License

MIT — see LICENSE. REAgraph is an independent project and is not affiliated with REA (morluto/rea) or its authors; see NOTICE.