A truth maintenance system for AI coding agents.

Your agent acts on beliefs about your repo — what the code is for, what must hold, what's left, and why it ended up this way. yigraf holds those beliefs in one connected graph, each one justified and pinned to the code it's about, and tells your agent the moment one stops being true.

❯ pipx install yigraf

v1.x·local, no network·MIT

Why

A stale belief is worse than no belief.

Every /clear wipes what your agent knew. What does survive — a doc, a comment, a note in a backlog — is the more dangerous half: it was true once. Source records what runs, never what it must guarantee or why it's shaped that way, and it never announces that a decision you settled weeks ago no longer holds. So your agent either relearns the repo from scratch or acts with confidence on something that stopped being true three commits ago. Nothing in your stack was maintaining the difference. yigraf does.

How it maintains truth

Justify, detect, revise.

Storing knowledge is the easy half. A truth maintenance system is judged on what it does when the world moves underneath it.

Justify

No free-floating facts. Every belief carries its reasoning, the alternatives ruled out, and an anchor to the exact code it's about — so it can later be checked instead of merely trusted.

Detect

When anchored code changes, the belief that depended on it is flagged as drifted. Inferences arrive tagged and never outrank the evidence behind them.

Revise

A flag is settled explicitly: reaffirm it, supersede it with what's true now, or record the dispute when two live beliefs collide. yigraf never silently picks a winner.

The retracted reasoning is kept, not deleted — supersedes is an edge, so your agent can see what the repo used to believe and why it changed its mind.

What it holds

Four questions source code can't answer.

The ones an agent loses on every reset — kept as a living graph beside your code, with the links between them doing the real work.

structureWhat is this?Your code — files, symbols, calls. Parsed across 16 languages, hashed so reformatting isn't "change."

intentWhat is it for?The specs and guarantees the code has to uphold — the SHALL/MUST contracts it serves.

planWhat am I doing?Goals and tasks, and exactly which symbols implement each one.

memoryWhy is it this way?The decisions, the reasoning, and the roads you deliberately didn't take.

A task points at the code that implements it. A decision is pinned to the code it concerns. So when the code drifts away from what was supposed to hold, yigraf notices — ask it what governs this file? and it can answer.

Using it

You don't run yigraf. You talk to your agent.

It listens on your repo and speaks up at the right moments — but you can always prompt it in plain language.

[Y𝚒𝚐𝚛𝚊𝚏] — your-repo — agent session

❯Before you change the auth flow, ask yigraf what governs it.

yigraf context "auth flow"

intent session-expiry — SHALL expire a session after 30m idle

memory chose a monotonic clock — wall-clock skews under NTP

plan task auth/1 — add idle-timeout · implements session.refresh

Got it — I'll keep the 30-minute idle contract and stay on the monotonic clock.

❯Check what yigraf's drifts are about.

yigraf drift

⚠ soft session.refresh changed since task auth/1 was anchored

The refactor kept the idle-timeout behavior — the contract still holds. Re-anchoring the link.

❯Remember why we did this, and what we ruled out.

Saved. It'll resurface the next time someone touches session.refresh.

Reaches your agent

Two channels, every host.

Pull

Your agent asks yigraf for the governing slice over MCP. Works with every MCP-capable host — the universal floor.

Push

yigraf injects the slice the moment your agent edits a file, at the best fidelity your host's hooks allow.

Claude Code · edit hooks Codex · edit hooks Cursor · rule Windsurf · rule Kilo · rule Antigravity · rule any MCP host · pull