Decision Graph

decision-graph

**English** · [Tiếng Việt](README.vi.md)

[](https://github.com/vietqtran/decision-graph/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/)

**Decision memory for codebases worked on by AI agents.**

A code graph tells you *what* the code does. `decision-graph` tells you *why it is that way* — when a business rule appeared, who decided it, what alternatives were rejected, and whether the decision still holds.

`git blame` gives you a commit message. It does not tell you that a customer's CTO asked for a second approval tier in a meeting, that a separate module was considered and rejected as unmergeable, or that the threshold was lowered six months later by someone else.

Language- and framework-agnostic. Works in any repo.

Why

The pain is sharpest when one base product is extended per customer — but it shows up anywhere business logic accumulates:

• An agent "improves" a rule that was deliberately written that way for one tenant.
• Nobody remembers whether an odd-looking branch is a bug or a requirement.
• The same rejected approach gets proposed again every few months.
• Decisions live in Slack threads, ticket comments, and people's heads.

AI agents make this worse, because they have no implicit memory of the last six months of meetings — but they *will* follow a written record if one exists.

Design principles

• Markdown is the source of truth. One .md file per decision, in git, reviewable in a PR.
• SQLite is only an index. Delete decisions/_index/ and rebuild any time.
• Agents may not invent decided_by. An agent can only create a draft; promoting it to active requires a human.
• Recording is a side effect of coding, not a chore to remember — hooks prompt at the r