Temporal knowledge graph - remember WHEN facts were true, not just the current snapshot

[abeo]

Idea: a temporal knowledge graph — remember when facts were true, not just the current snapshot

Category: Ideas

TL;DR

graphify currently models a codebase as it is right now. I'd love to see it also model when things were true — node and edge lifetimes across commits. The graph would stop being a HEAD snapshot and become a history you can query: "when did this symbol disappear, and in which commit?", "what did the call graph look like at v1.0?", "which functions have been caller-less for the last N commits?". Git already stores the time axis; graphify currently collapses it. The payoff is large, and there's a cheap on-ramp that reuses what graphify already produces.

What prompted this

I hit a subtle staleness bug that I think is actually a temporal problem in disguise.

As I understand the current incremental model (graphify update driven by git hooks), an incremental pass prunes nodes for deleted files, but a symbol removed from a surviving file is never pruned — the node lingers and the graph quietly contradicts source. In my case a function was deleted from a file that lived on (a subsystem cutover), and its node + its inbound calls edge survived every incremental rebuild for weeks. Only a full clean rebuild (clearing graph.json + manifest) removed it.

The deeper issue: the graph asserts "symbol X exists" as a timeless fact, when the truth is "X existed until commit abc123." A model that records when a fact was true can't have this bug — removal is a recorded event (you close the symbol's interval), not a deletion you can forget to apply.

The model

The clean insight is that git is already a temporal store of the code; graphify just throws the time axis away at extraction. Two ways to keep it:

A — Interval-stamped (the "real" version). Every node and edge carries valid_from_commit → valid_to_commit. A live symbol has an open interval; a removed one gets its interval closed at the commit that removed it. All queries are "as of commit X" (default = HEAD). Staleness becomes structurally impossible — you never leave a dangling node, you close an interval.

B — Snapshot + diff (the pragmatic on-ramp). Retain graph.json keyed by commit SHA and diff on demand (or emit an append-only node_added / node_removed / edge_added / edge_removed event stream). Current state is a fold up to T; history is a fold up to any earlier T. This is easy to bolt on, because anyone running the git-hook integration already regenerates graph.json every commit — the raw material is being produced and discarded today.

Why it's worth it — use cases

Several of these are things people currently do by hand:

• Graph-level blame — "when did someSymbol disappear, and in which PR?" One query instead of an archaeology session.
• Dead-code aging — "which symbols lost their last inbound edge N commits ago and never regained one?" Surfaces vestigial code automatically. (I found a dead, caller-less function by hand this week that this would have flagged the moment it lost its last caller.)
• Doc/comment drift detection — temporal join: compare a comment's last-edited commit against the last-changed commit of the symbol it references. Symbol changed after the comment → likely stale doc. An automated version of "grep the old name after a rename."
• Real refactor impact — diff the graph before/after a PR. get_pr_impact already gestures at this; a temporal store makes it concrete and historical (any two points, not just HEAD).
• Architecture over time — watch a module's fan-in triple across a month, or god-nodes emerge. Coupling trends are invisible in a single snapshot.
• Archaeology / onboarding — "show me the call graph as it was at the v1.0 release."

On the API side this is mostly additive: the existing MCP tools (get_node, get_neighbors, god_nodes, shortest_path, …) would gain an optional as_of=<commit> parameter; new tools like timeline(symbol) and diff(commitA, commitB) fall out naturally.

The genuinely hard part (worth naming)

Node identity across time. If a function is renamed or moved between files, is that one node with a continuous interval or a death + a birth? Get it wrong and every rename reads as delete-then-add, which poisons "when did X change." This needs rename/move detection — git similarity scoring, or identity by signature/body-hash rather than a path-derived id. Everything else (storage — graphs are a few MB; query filtering) is comparatively mechanical. This is the part that separates a trustworthy temporal graph from a noisy one, and it's where the design effort really goes.

A pragmatic ladder (cheap → rich)

1. Archive snapshots — on each rebuild, drop a copy of graph.json keyed by commit SHA + timestamp. Nearly free; it's already regenerated per commit.
2. graphify diff <A> <B> — added/removed nodes + edges between two points. Built on (1); covers most "what changed when" needs with no temporal store at all.
3. Interval-stamped store (Model A) — as-of / between / timeline queries; structurally cures the staleness class above.
4. Derived insights — dead-code aging, doc-drift alerts, coupling trends, all built on (3).

Rungs 1–2 are valuable standalone and a low-risk way to validate demand before committing to the identity-tracking work in 3–4.

Question for the maintainer / community

• Is any of this already on the roadmap, or partially achievable today (e.g., is get_pr_impact already diffing two graph states under the hood)?
• Would a lightweight snapshot-archive + diff rung be a welcome contribution as a first step?
• For identity-across-renames, is there appetite for signature/body-hash node ids, or is the path-derived id load-bearing elsewhere?

Happy to help prototype the snapshot/diff rung if there's interest. Thanks for graphify — it's become a daily-driver navigation tool for a large multi-app monorepo here.

[safishamsi]

Really thoughtful writeup, thanks @abeo — and the bug you spotted is the more urgent half, so let me split the two:

The staleness bug is real — confirmed it. graphify update (and the post-checkout hook) take the full-re-extraction path, which only evicts nodes for files deleted from disk, never a symbol removed from a file that still exists. So the dead function's AST node + its inbound calls edge leak until a clean rebuild. (The post-commit hook path is fine — it evicts by changed-file.) We'll fix it; tracking it as its own issue (#1116) since it's independent of the temporal idea. The one subtlety for anyone who picks it up: the update pass is AST-only, so the fix has to evict by AST-node identity, not blanket-by-source-file, or it'd silently drop the cached semantic nodes that share a file.

On the temporal feature — yes, the snapshot + diff rung is welcome, and it's lighter than it looks:

• The diff primitive already exists: analyze.graph_diff(G_old, G_new) returns added/removed nodes+edges. graphify diff <A> <B> is mostly CLI wiring over two archived snapshots.
• The git hook already regenerates graph.json every commit, so archiving one keyed by SHA is a thin sidecar write — no core changes.
• get_pr_impact is not a snapshot diff (it's forward file→impact), so it complements rather than overlaps.

On rungs 3-4 (interval store + rename-stable identity): let's defer. The path-derived node ID is load-bearing (it has to match what semantic extraction emits, see #1033) — moving to signature/body-hash identity touches AST extraction, the semantic prompt, dedup, and cross-file resolution, so it's a big cross-cutting change. Fine for an early diff to read a rename as delete+add; we can revisit identity once there's demand.

If you want to take the snapshot-archive + graphify diff rung, go for it — happy to review. Thanks again, genuinely useful.

[abeo]

Thanks for the quick confirmation and for splitting out #1116 — glad the repro was useful. For what it's worth we'd traced the same root cause independently: incremental update prunes nodes only for deleted files (via merge_into_graph), so a symbol removed from a surviving file lingers until a clean rebuild.

Agreed on deferring interval-store and rename-stable identity. Path-derived IDs being load-bearing across AST extraction + semantic analysis makes retrofitting interval semantics underneath them real surgery — and snapshot+diff captures most of the practical value (graph-blame, dead-code aging, refactor-impact) without touching that foundation.

The snapshot-archive + graphify diff <A> <B> rung would genuinely be useful for us, so it's going in our backlog — I'd like to pick it up when we have a window. A couple of things I noticed while poking at the code, in case they're useful for whoever gets to it first:

• Snapshot store — there's no commit-SHA stamping anywhere today (the detect manifest is content-hash keyed), so archiving means capturing git rev-parse HEAD at archive time. The global-manifest.json pattern in global_graph.py looks like a clean precedent — a graphify-out/snapshots/<sha>.json.gz store plus a manifest mapping SHA → {archived_at, parent, node_count}.
• Async hook — the post-commit hook runs the rebuild detached (nohup … &), so the fresh graph doesn't exist at hook-fire time; the archive step probably wants to hang off _rebuild_code() completion in watch.py rather than the hook itself, likely opt-in with a retention cap.
• diff — analyze.graph_diff() already returns exactly the right shape; the diff command looks like a thin wrapper (human + --json). Worth noting it's add/removed-only today — no "changed edge" detection for, say, a confidence delta on a surviving edge.

When I do pick it up I'll keep the first PR tight — archive + diff + tests, derived analytics as a follow-on — and check in on store layout/keying before writing much. Thanks for the offer to review.