yigraf

"Why I Graph?" — 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 to do, and why it ended up this way. yigraf holds those beliefs in one connected graph — each one justified, pinned to the code it's about, and checked against that code as it changes — and hands the agent the relevant slice at the moment it acts.

It's a tool for the agent, not another dashboard for you. You're the principal: you set the direction and answer the judgment calls yigraf refuses to make on its own. The agent does the work — and now it does it on knowledge that is still true.

Why

Every /clear wipes what your agent knew. What survives — a doc, a comment, a note in a backlog — is the more dangerous half: it was true once. Source code records what runs, never what it's supposed to guarantee or why it's shaped that way, and nothing in it announces that a decision you settled weeks ago no longer holds.

So your agent has two failure modes, not one. It relearns the repo from scratch every session — or, worse, it acts with full confidence on something that stopped being true three commits ago, and re-litigates decisions you already made because nothing told it they were still standing.

Storing knowledge only fixes the first. yigraf is built for the second: justify, detect, revise.

• Justify. No free-floating facts. Every belief carries its reasoning, the alternatives that were ruled out, and an anchor to the exact code it's about — so it can later be checked rather than merely trusted. Beliefs also carry a grounding tier, so "we measured this" and "we assumed this" never read as the same claim.
• Detect. When anchored code changes, the belief that depended on it is flagged as drifted. Anything yigraf infers arrives tagged inferred and never outranks the evidence behind it.
• Revise. A flag is settled explicitly — reaffirm the belief, supersede it with what's true now, or record the dispute when two live beliefs collide. yigraf never silently picks a winner, and the superseded reasoning is kept as an edge rather than deleted, so your agent can see what the repo used to believe and why it changed its mind.

That loop is what makes retrieval worth trusting: the slice your agent gets back is knowledge that has survived contact with the current code, and says so when it hasn't.

What yigraf gives your agent

Four questions an agent can't answer from source alone — and loses on every reset:

The magic is in the links between them. A task points at the symbols that implement it. A decision is pinned to the code it concerns. A spec governs a region of the repo. So when your agent asks "what governs this file?", yigraf can answer — and when code drifts away from the thing that was supposed to hold, yigraf notices and says so.

Does it actually work?

Measured, not asserted — on 10 of the top popular open source repos in Github (not yigraf's own repo, which would rig the result), 960 runs, floor model (Sonnet), three arms: yigraf installed, yigraf's instructions only, and no yigraf at all.

Asked why the code is shaped the way it is, the agent with yigraf answered from context — the no-yigraf agent went looking:

Told to edit a governed symbol, the agent's own edit drifts the anchor and yigraf says so. It stopped and re-verified against the decision 6 times out of 8. Without yigraf: 0 out of 8.

And the part that didn't work. A single line in CLAUDE.md — "run yigraf context before changing code" — scored the same 6/8. The edit-time hook, yigraf's most distinctive mechanism, bought nothing measurable over simply telling the agent to ask. One case, one model, n = 8 — but it's an open question now, not a claim.

Get started — just tell your agent

yigraf is a tool for agents, so setting it up is a job for your agent. In any repo, say:

"Install github.com/mansilla/yigraf and wire it into this project."

A capable agent installs the CLI, indexes your code, and connects yigraf to your host — Claude Code, Codex, Cursor, and friends are auto-detected; anything else gets the universal MCP server. It won't touch your requirements.txt (yigraf is a dev tool, not a runtime dependency).

If you are that agent: the CLI comes from PyPI — uv tool install yigraf (or pipx install yigraf). This GitHub URL is the documentation, not the install source; do not clone the repo into the project. Then yigraf init, yigraf build, yigraf install, in the project root.

Rather do it yourself? Three lines:

pipx install yigraf     # isolated CLI (or: pip install yigraf / uv tool install yigraf)
yigraf init && yigraf build     # create the workspace + index your code
yigraf install                  # wire your agent host (auto-detects; falls back to MCP)

Full install options (per-OS, from source, MCP config, semantic-recall tuning) live in the guide.

Using it — just talk to your agent

You don't run yigraf; you tell your agent to. It listens on your repo and speaks up at the right moments — but you can always prompt it directly:

• Starting something? "Before you change the auth flow, ask yigraf what governs it." Your agent pulls the intent, the plan, and the past decisions that touch that code — so it works with the grain instead of relearning from scratch.
• Saw a drift warning? "Check what yigraf's drifts are about." Each one means code moved away from something that was supposed to hold. Your agent walks them and either confirms it still holds or flags what changed.
• yigraf flagged a conflict? "Let's go through the conflicts one by one." Two live beliefs disagree about the same code. You decide which wins — yigraf never silently picks.
• Made a real decision? "Remember why we did this, and what we ruled out." It's saved as a memory and resurfaces the next time someone touches that code.
• Coming back to a project? "Ask yigraf what's in flight." The active plan and open tasks come back, so a thread dropped last week picks up where it left off.
• A rule that always applies? "Pin that." Most knowledge surfaces because it's relevant to what you're doing — but "never write this vendor's APIs from memory" is relevant to everything, which means it ranks nowhere. Pinned rules are injected at the start of every session instead.
• Agent says it's done? "Have yigraf confirm." yigraf status is the one surface that reports everything outstanding at once; "no open tasks" is not the same as "nothing left to re-verify".

That's the whole loop. Your agent handles the mechanics (context, link, drift, remember); you stay in plain language. The deeper mechanics — how drift is detected, how conflicts resolve, how a memory earns trust — are in the guide.

The house rules your agent reads first

Every session starts with a short block of standing instructions, before anything relevance-ranked: read the skill, capture as the work lands, check status before claiming done. yigraf ships the text and upgrading the CLI updates it, so you get the current rules for free. It is yours to rewrite: uncomment session_start.preamble in yigraf/config.yaml and the rules become the repo's — the file is committed, so a team's conventions live with the repo rather than in each agent's private memory, and from that point yigraf never touches them.

It exists because ranking has a blind spot that better ranking cannot fix. A rule about how to work here resembles no particular topic, so it never wins a relevance cut; and an agent cannot ask for knowledge it doesn't know exists — a fresh session, by construction, knows none of it exists. So session start also lists the titles of what it didn't have room to show, for about 30 tokens each. Knowing something is there is the whole precondition for asking about it.

Works with your host

yigraf reaches your agent two ways: pull (the agent asks yigraf for context over MCP — works everywhere) and push (yigraf injects the governing slice the moment the agent edits a file — where the host has the hooks for it). You always get pull; you get push at the best fidelity your host allows.

Details and the full per-host matrix: docs/hosts.md.

The graph algebra

yigraf's edges aren't labels on a filing cabinet — they're typed arrows with an algebra, and that algebra is what lets the graph answer things nobody wrote down:

• Edges are typed. implements, serves, concerns, calls, supersedes each only connect certain families, so a malformed claim can't enter the graph.
• They compose — partially. A task that implements a function that calls another is understood to depend on the second. Composition is deliberately not associative: the paths that shouldn't chain, don't.
• Confidence is a semiring, not a percentage. Trust lives on a three-element lattice and combines by bottleneck: a derived edge is never stronger than the weakest link behind it. That's why everything yigraf infers arrives tagged inferred and asks to be confirmed instead of posing as fact.
• Merging converges. Folding two versions of the graph is a theorem, not a hope — which is what makes the graph safe to rebuild and safe to share.

The full development — the type discipline, the semiring, the algebraic path problem as a query engine, and why the typed λ-calculus lends its types here but not its reductions — is written up in Typed arrows for AI agent memory.

Learn more

• Typed arrows for AI agent memory — the algebra yigraf stands on, with the proofs.
• Guide — install in depth, the full workflow, and how drift, conflicts, and memory maturity actually work.
• Hosts · MCP setup · Statusline — wiring yigraf into your tools.
• Language support — the tested capability matrix across 16 languages.

Status

yigraf 1.x is local by default — the engine is self-contained inside a single repo/folder. No account, no service, no code or reasoning leaving your machine; yigraf status checks PyPI once a day so it can tell you an update exists, and that is the only socket it opens.

Since 1.2.0 a workspace can opt into a shared log — yigraf sync against a yigraf-server, off unless you bind it (yigraf online <link-url>, 1.3.0) — which is what lets a team resolve each other's conflicts and see each other's beliefs drift against their own code. Reads still run against a local replica, so being offline costs you nothing. The hosted, multi-user, real-time product line is still the 2.0 roadmap. MIT licensed.