Context DAG: Version-Controlled Reasoning for AI Agents

Every AI coding session throws away its most useful artifact. The diff survives; the path to it does not. Which files did the agent read before it edited? Which assumption did it test and reject? What did it leave as a TODO, and why did it pick this design over the obvious alternative? Those answers live in a chat window that closes — so the next session re-discovers the project from scratch, and the reviewer is left reading a diff with no idea how it was reached. The usual patch is a markdown memory file (CLAUDE.md, AGENTS.md, a notes doc). It helps, and it also rots: one mutable blob, no ancestry, no way to branch an experiment, no link from a note to the commit it describes.

h5i treats reasoning as versionable project state instead. It records a context DAG under the Git ref refs/h5i/context — the reasoning layer of an auditable workspace, separate from your working tree but shareable through Git. Each unit of work becomes a typed node with ancestry; reasoning can branch and merge like code; and snapshots pin to the commit SHAs they produced, so the next agent (or the next reviewer) can recall the goal, the milestones, the decisions, the open risks, and the file-specific prior reasoning before touching a line.

What goes into the DAG

h5i's context entries use a small vocabulary that maps cleanly to agent work:

This is intentionally simpler than a full transcript. h5i is not trying to preserve every token. It preserves the shape of the work: what was known, what was decided, what changed, and what still matters.

Daily workflow

The honest daily workflow is: you just work. A human wires the hooks once per runtime, and from then on capture is automatic — nobody types h5i hook … by hand:

$ h5i hook setup --write --target claude  # wires SessionStart · UserPromptSubmit · PostToolUse · Stop
$ h5i hook setup --write --target codex   # wires SessionStart · Stop

With Claude Code all four handlers fire on their own: h5i hook session-start injects prior context, h5i hook claude prompt records the verbatim prompt, h5i hook claude sync writes OBSERVE and ACT as files are read and edited, and h5i hook claude finish mines THINK and NOTE and checkpoints the milestone when the turn ends. Codex has no per-prompt or per-edit hook, so it wires just two (h5i hook session-start and h5i hook codex finish --quiet); the finish step parses Codex's own session JSONL via h5i hook codex prelude/sync/finish to reconstruct the prompts and OBSERVE/ACT entries it had no event hook for. Either way, both agents write to the same shared context workspace.

The only entries emitted explicitly — by the agent at a task boundary, not typed by you each day — are the goal at the start of a task and the occasional flag left for a future reviewer:

$ h5i recall context init --goal "ship OAuth login safely"
$ h5i recall context trace --kind NOTE \
  "RISK: refresh-token rotation untested across deploys"

Branching reasoning, not just code

Agent work often includes experiments: try a lock-free design, compare two caching strategies, inspect whether a bug is in the parser or the caller. Those investigations are valuable even when you abandon them. h5i lets you branch context to isolate the experiment, then merge the useful conclusion back.

$ h5i recall context branch experiment/cache-layer \
  --purpose "compare Redis cache against local LRU"
# inspect, test, decide — OBSERVE/THINK/ACT land on the branch, not on main
$ h5i recall context checkout main
$ h5i recall context merge experiment/cache-layer

The merge is what makes this a graph and not a list. It writes a MERGE node that records both parent IDs — the tip of main and the tip of the experiment — so the conclusion ("LRU won; Redis added a network hop we did not need") arrives on main carrying a pointer back to the investigation that produced it. A teammate who later asks "did anyone try Redis here?" follows that edge instead of guessing. You can render the whole shape, parents and all, in the terminal:

$ h5i recall context dag      # coloured DAG: kind, 8-hex id, time; MERGE shows both parents
$ h5i recall context relevant src/cache.rs  # prior reasoning for one file
$ h5i recall context knowledge  # every THINK across all branches — the decision log
$ h5i recall context todo       # open NOTE/THINK items: TODO / FIXME / BLOCKED

A flat file cannot answer those questions because it has no edges to follow and no per-entry type to filter on. The DAG is queryable precisely because the structure is in the data, not in prose you have to skim.

Snapshots pinned to commit SHAs

Reasoning is most useful when it is anchored to the code it explains. Every h5i capture commit automatically snapshots the context workspace and links it to the resulting Git commit SHA. That gives you two operations a plain memory file can never offer:

$ h5i recall context restore a1b2c3d     # reasoning state as of that commit
$ h5i recall context diff a1b2c3d HEAD   # how the reasoning evolved since

restore answers "what did we know when we shipped this?" — useful when a commit from three weeks ago turns out to be wrong and you need the assumptions behind it. diff answers "what changed in our thinking between these two points?" — the reasoning counterpart of git diff. Because the snapshot is keyed by SHA, the reasoning and the code can never drift apart: checking out an old commit and restoring its context gives you a coherent picture of that moment, not today's notes pasted over yesterday's code.

How it compares to memory files and vendor memory

A flat memory file is easy to append and hard to trust. It has no ancestry, no branch boundary, no commit linkage, and no clear line between durable knowledge and scratch notes. A DAG gives context a structure close to the work itself. The alternatives each get something right — here is the honest tradeoff:

The point is not that markdown memory is useless — it is a fine place for stable, hand-curated project rules. The point is that a single file is the wrong shape for the volatile, branching, per-commit reasoning of an active session, and that is exactly where a DAG earns its keep.

What this changes for review

A context DAG gives reviewers a way to audit the path to the diff, not only the diff itself. If an agent changed authentication code, the reviewer can ask whether it observed the login tests, whether it recorded a risky assumption, and whether another context branch already investigated the same failure. That turns review from transcript archaeology into targeted verification.

The DAG also makes handoff cleaner. A second agent can inherit the current goal, relevant observations and unresolved notes without rereading the whole repository. Humans get the same benefit when a branch sits for a week and the original conversation is gone.

The bottom line

Agent reasoning is project state, and like any state worth keeping it wants the affordances Git already gives code: history, branches, merges, and a way to look at any past moment. A flat memory file gives you none of those; it gives you an append-only blob that drifts from the code and loses the structure of the work. A context DAG keeps the in-repo, version-controlled virtues of that file and adds the parts that make it trustworthy — typed nodes, ancestry, merges that record both parents, and snapshots pinned to the commit SHAs they explain.

The practical test is simple: when a branch sits untouched for a week, can the next session — or the next reviewer — recover not just what changed but how it was reached? With a chat window, no. With a DAG you can restore, diff, and follow the merge edges, the answer is yes, and review stops being archaeology.

FAQ

What to read next

Use the workflow guide for day-to-day commands, or read how h5i renders the same context into a PR body when a branch is ready for review.