# zavet — the knowledge layer for agent-built code > Agents forget why. Your repo shouldn't. zavet captures the reasoning behind your code as a byproduct of agent work — then stops agents from reverting it, answers `/zavet:why` in seconds, and ties every decision to the minutes it cost. - Canonical page: https://dirahq.sh/zavet - Source: https://github.com/dodi-smart/dirahq-zavet - Licence: Apache-2.0 - Price: free It lives in your repo: `.zavet/`, git trailers, Claude Code hooks, CI checks. Grep over markdown — no embeddings, no magic. Plain markdown and git, fully functional offline, sync off by default. ## Capture. Enforce. Recall. Documentation dies because it is a separate chore. zavet records decisions where the work already happens — in commits and sessions — and makes them mechanically load-bearing. ### Capture — byproduct, not chore Micro-decisions ride along as git trailers; structural ones become append-only 25-line records. Agents write them as they work, so there is zero separate documentation step. ### Enforce — mechanical, not vibes Decisions declare guarded paths. An agent touching them sees the decision first; an unreferenced commit is blocked — in the harness, in git hooks, and in CI. ### Recall — grep, not embeddings Index-first retrieval: one small file, grep, at most three documents. Answers in-session for agents and humans, or in the dira dashboard. No vector database. ## The join — only in dira Every decision has a cost. Every regression prevented has a value. Because zavet lives inside dira's session tracking, each decision is correlated with the sessions that produced it. Others have time *or* knowledge — the join is the part nobody else can fake. - **Cost of decision** — engaged, agent and compute time behind each record. - **Regression pressure** — which decisions agents keep colliding with. - **Knowledge coverage** — share of active code under a verified spec or guard. ## Backfill without lying On a 400k-LoC codebase, `/snapshot` reverse-engineers per-feature specs — permanently marked *unverified*, with open questions instead of invented rationale, until a human confirms them. A wrong "why" is worse than none. ## The European AI Act Enforceable since 2 Aug 2026. Annex IV §2(b), via Article 11, asks for *the key design choices including the rationale and assumptions made* — and the trade-offs behind the technical solutions adopted. That is not a document. That is a decision record with a `why`, a `rejected` and a date on it, which is precisely what zavet writes as a byproduct of the work. - **Annex IV §2(b)** — key design choices, their rationale, the assumptions, the trade-offs. A zavet decision record carries all four, dated at the moment it was made and attributed to a signed session. - **The guard matters more** — documentation an agent can silently contradict is not documentation. Guards force an agent that contradicts a recorded decision to surface it, which is what makes the record still true six months later. - **Art. 73 · 15 days** — a serious incident gives you a fortnight to explain a subsystem. `/zavet:why` answers with citations in seconds, offline. A wiki search does not answer at all. And the refusal that makes it worth anything: zavet will not invent a rationale. A decision reconstructed after the fact stays marked *unverified* until a human confirms it — because evidence manufactured in August about a choice made in March is not evidence, and an auditor who notices will trust nothing else you hand them. See also [/letopis.md](https://dirahq.sh/letopis.md) for the full article-by-article mapping. ## zavet vs. the wiki Confluence, Notion and AI knowledge tools like Lore live outside the repo. Agents never read them before editing, and nothing enforces what is written. zavet is code-coupled and mechanical. | Capability | Confluence | Notion | Lore | zavet | | --- | --- | --- | --- | --- | | Lives in the repo | Separate cloud | Separate cloud | Its own store | `.zavet/` + trailers | | Captured without a documentation chore | Pages you owe | Pages you owe | Ingests meetings & docs | Byproduct of agent work | | Agents see it before editing code | Unread by agents | Unread by agents | Only if you ask | Guard hooks, pre-edit | | Blocks reverts of recorded decisions | No | No | No | Guards block commits | | Staleness measured, not guessed | Page age only | Trust the author | Freshness signals | Against the diff | | Ties knowledge to time & cost | No | No | No | The dira join | | Works fully offline | No | No | No | Local-first | Confluence, Notion and Lore are strong general knowledge bases — for meetings, docs and team memory. zavet only does code-coupled decisions, and does them mechanically. ## Local-first Your repo is the source of truth; the cloud is a projection. Plain markdown in `.zavet/` plus git trailers. Wipe the cloud, re-sync, get the same bytes back. | Sync mode | What leaves the machine | | --- | --- | | Off (default) | Nothing. Guards enforce and `/zavet:why` answers in-session. | | Metadata only (recommended) | IDs, titles, status, guard events, coverage metrics. No wire field may carry content — a tested invariant. | | Metadata + content | Adds decision bodies and spec text, so full records work in the dashboard. Separate, explicit opt-in. | Self-hosting is first-class — the same `docker compose up` as dira. --- Ask your codebase why. zavet ships with dira — `dira onboard` sets up both, and it works fully offline. Every decision has a cost — zavet keeps the receipt. See also [/index.md](https://dirahq.sh/index.md), [/letopis.md](https://dirahq.sh/letopis.md), [/getting-started.md](https://dirahq.sh/getting-started.md).