KAUT — Knowledge Actualization Under Trust

Makes legacy codebases AI-native. KAUT is self-maintaining, AI-first documentation for your project — a knowledge layer that makes undocumented, weak-context code legible to AI agents. Not a memory of conversations — a knowledge base about the system itself: what it does, how it is structured, and why. It turns what agents learn while working into living documentation — so no session starts from zero.

Zero-dependency Node.js (≥ 20, developed on 24), Apache-2.0. Developed and tested on macOS and Linux (CI runs Linux, Node 20 and 24); Windows is not supported.

A complete, standalone product. One git clone is the whole install; point your harness at the bundled MCP server (or call the CLI from any skill/prompt) and it works — no orchestrator, no framework, no services, no accounts, nothing else to deploy. It composes with the sibling TAUT orchestration framework (TAUT drives agents, KAUT is what they know) — but that integration is optional, not a dependency.

Status: v0.8.1 — the full loop is live. Reading: lookup (one-call ready answer) with freshness verdicts (merge-base-anchored, never crying "fresh" when unsure), trust tiers, and the altitude coverage band; tamper containment withholds anything edited outside the pipeline. Multi-repo: workspace registry, per-member stores, one system store anchored to a launcher repo. Writing: the layered write gate (agent-tier updates land directly; owner-gated layers and novel docs queue as drafts for asynchronous review). Maintenance: refresh (re-derivation delta bundles), touched (change-site sensor), digest/note (usage and outcome telemetry). Interop: stores meet the OKF v0.2 conformance bar and kaut okf export produces idiomatic OKF bundles. Any MCP-capable harness plugs in via the bundled MCP server. What is live in detail: docs/HANDBOOK.md §16.

The problem it solves

Every new AI session starts with amnesia: the agent re-explores your project, asks the same questions again, and — worst of all — keeps making the most expensive kind of mistake: code that compiles and passes tests, but quietly breaks a business rule it had no way of knowing about.

The "why" of a project is usually written nowhere. KAUT gives it a place to live — and keeps it alive.

This hurts most on legacy code: years of undocumented decisions, no original authors around, business rules visible only as side effects. That is precisely where AI coding tools underperform today — and precisely the codebase KAUT is built for. KAUT is the first step of a larger goal: making legacy codebases AI-native — structured so that agents can work on them safely and cheaply.

Related MCP server: 50 First Tapes MCP Server

What KAUT is — and is not

Three familiar categories look similar from a distance. KAUT is none of them — and the differences are exactly where the value is.

Not another memory system. Memory answers "what did we talk about, what does this user prefer?" — personal, episodic, unverifiable. KAUT answers "how does this project work, and why?" — documentation: organized by domain, source-bound, freshness-checked, trust-labeled, and readable by any agent and by humans. Personal notes never enter KAUT; project knowledge never stays trapped in one agent's memory. That boundary is built into the write path.

Not RAG. Retrieval-augmented generation indexes whatever text happens to exist and serves the best-matching chunks — with no idea whether they are still true. KAUT stores the opposite selection: only knowledge that is expensive to re-derive and not cheaply visible in the code (the storage litmus), distilled into short docs a model reads whole — no embeddings, no ranking, no chunk soup. And every doc carries a machine-checked freshness verdict: anchored to the commit it was derived from, diffed against the tracked main branch on every read, erring toward stale when git cannot prove otherwise. Run RAG over your code if you like — KAUT is for what the code does not say: the why, the cross-cutting invariants, the tribal knowledge.

Not an LLM wiki. Auto-generated documentation is plausible text, unverified at birth and abandoned at first commit. A KAUT doc cannot exist without typed source bindings and an anchor commit — and cannot stay wrong silently, because the sources are diffed on every read. The write path is the other half: mechanical layers regenerate automatically, agents may land operational facts they verified in-session, but judgment-tier knowledge (decisions, domain semantics, contracts) only enters through a human-approved gate — updates queue as drafts you review in batch. A wiki decays by default; KAUT's default is to confess.

And it is not a proprietary silo. KAUT is an implementation of the vendor-neutral Open Knowledge Format (OKF) v0.2 — stores are typed-markdown concept documents that satisfy OKF's conformance bar in place, and kaut okf export projects any store into a fully idiomatic OKF v0.2 bundle (provenance, trust and lifecycle families included), readable by any OKF consumer. KAUT's freshness/trust machinery rides on top as OKF-protected extension keys: the format records knowledge — the engine is what keeps it true. The normative mapping lives in SCHEMA.md.

Principles

1. Source-bound, commit-anchored. Every fact names the files it came from and the commit it was derived at. No source, no doc — the contract is validated at the door.

2. Err toward stale. Freshness is a pure git computation (merge-base against the tracked main branch). When git cannot prove a doc is current, the verdict says so. KAUT never cries "fresh" when unsure — a false "stale" costs a re-check; a false "fresh" ships a bug.

3. Knowledge informs; it never authorizes. A healthy verdict is permission to skip re-derivation, not permission to act. Verdicts route trust: healthy + precise = usable as-is; stale / broken / coarse-altitude = confirm in code first.

4. Serve nothing you can't vouch for. The store is read by AI agents, so an out-of-pipeline edit is an injection channel, not a convenience. Anything not byte-identical to the last pipeline commit is withheld entirely (tampered) until restored or legitimately landed.

5. Humans own judgment; agents own mechanics. The layered write gate: maps regenerate freely, verified operational facts land at agent tier, and decision/domain/contract knowledge waits in a draft queue for the owner's one-keystroke review.

6. Repair where it's cheapest. Freshness decay is fought structurally, not heroically: the change site (touched names the docs a code change owes), the read site (a stale verdict arrives with a refresh delta bundle — exactly what changed, against what to re-derive), and honest telemetry (digest) to see whether upkeep keeps pace.

7. Local-first, zero-dependency, repo-untouched. One clone, no install step, no daemon, no cloud; the knowledge store lives outside your repository, and freshness checks cost git comparisons — not model calls.

What KAUT does

• One known place to look. The agent checks KAUT before re-exploring your code. Either the answer is there, or KAUT notes the gap so it gets filled later.

• Knowledge collects itself. After a task is done, the useful things the agent just learned are condensed into the base — a byproduct of work already paid for, not a separate documentation project.

• It never lies confidently. Every stored fact stays tied to the code it came from. When that code changes, the fact is automatically flagged as possibly outdated. When in doubt, KAUT says "re-check this" instead of pretending everything is fresh.

• It refuses to serve what it can't vouch for. The knowledge base is read by AI agents, so a file edited behind KAUT's back (outside its own version control) is a potential injection channel. Such content is withheld entirely until it is restored or properly re-committed — every answer the agent sees comes from a provenance-tracked commit.

• You stay the judge. Owner-gated layers and novel docs never land without your approval: updates queue as drafts (kaut draft), and you land or drop the whole batch in one sitting (kaut review). You don't have to be present when the agent finishes.

• Your repository is never touched. All knowledge lives in a separate folder outside the project. Your git history, branches, and teammates never see it.

• Any agent can plug in. Besides the CLI, KAUT ships an MCP server (node <engine>/mcp.mjs, zero dependencies) — the same lookups, freshness verdicts, and gated writes as MCP tools, for any MCP-capable harness or orchestrator. One server handles a whole multi-repo workspace (each call names its repo).

Architecture

flowchart LR
    subgraph clients["Clients"]
        direction TB
        HARNESS["AI agents\nany MCP-capable harness"]
        HUMAN["Humans and CI\nshell, scripts"]
        ORCH["Orchestrator, e.g. TAUT\n(optional)"]
    end

    subgraph engine["KAUT engine - stateless, zero-dep Node, no daemon"]
        direction TB
        SURF["Two surfaces\nmcp.mjs - 7 MCP tools\nkaut.mjs - CLI"]
        READP["READ path (lock-free)\nlookup / stale / digest\nfreshness verdict = pure git computation\n+ trust tier + altitude on every answer"]
        WRITEP["WRITE path (one chokepoint)\nlayered write gate + draft queue\nagent tier lands, judgment tier\nwaits for owner review"]
        MAINTP["Maintenance loop\nrefresh / touched / note\nmap collectors (stack adapters)"]
    end

    subgraph home["Knowledge data home - set once with kaut home"]
        direction TB
        STORES["One store per repo\ntyped markdown + frontmatter\nown private git = audit + rollback\njournal telemetry"]
        REG["workspaces registry\nmember stores + one system store"]
        BACK["backups/\nkaut backup / restore"]
    end

    REPOS["Your repositories\nREAD-ONLY sources\n(at most one git-ignored pointer file)"]
    OKFB["OKF v0.2 bundle\nkaut okf export"]

    HARNESS --> SURF
    HUMAN --> SURF
    ORCH --> SURF
    SURF --> READP
    SURF --> WRITEP
    SURF --> MAINTP
    READP -- "diff sources against\nthe anchor commit" --> REPOS
    MAINTP -- "derive maps from code" --> REPOS
    READP <--> STORES
    WRITEP --> STORES
    STORES --> OKFB

The shape in four sentences. The engine is stateless — every command (CLI or MCP tool) computes its answer from two git histories and exits; there is nothing resident to run, sync, or corrupt. Knowledge lives outside your repositories, one store per repo in the data home, and each store is its own private git repository — which is what makes the write gate, tamper containment, audit, and rollback possible. The read path never blocks and never guesses: a verdict is derived by diffing a doc's typed sources against its anchor commit at the moment you ask. The write path has exactly one chokepoint, so policy (agent tier vs owner review) cannot be bypassed by choosing a different command.

Quickstart

1. Clone the engine next to the repositories it will serve (a sibling folder — setup scans its neighbors; there is no npm install, the engine has zero dependencies):

cd ~/projects && git clone https://github.com/yurgeno/kaut.git

2. Run setup — three questions, and every answer has a flag for scripted installs:

node kaut/kaut.mjs setup

• Knowledge data folder — where the stores live (default: <siblings>/kaut-data). Persisted once (the kaut home redirect): every later command and the MCP server resolve it themselves — nothing to export, nothing to pass. This folder is live data: the engine only ever adds to it; nothing existing is wiped or rewritten.

• Which repositories — setup lists every sibling git repository; answer all, numbers, or names.

• Bootstrap now? — yes creates/actualizes a store per selected repo on the spot (idempotent: existing stores are actualized, never re-seeded); no just records the configuration and prints the per-repo commands for later.

Non-interactive: node kaut/kaut.mjs setup --data <dir> --repos all --bootstrap --yes (--no-bootstrap, --scan <dir> to scan elsewhere).

3. Follow the printed next steps — setup ends with exactly two: connect the MCP server to your harness, and paste the knowledge contract into your agent instructions (both below). Optionally generate the mechanical map per repo:

node kaut/kaut.mjs map

(bootstrap already detected your stack and seeded the right collectors — see Supported stacks below; a collector whose input is absent skips itself with a note, and map.collectors: [] means the map layer simply stays empty).

Supported stacks

Bootstrap, the knowledge loop, freshness verdicts, the write gate — all of it is stack-agnostic: any git repository works. Only the mechanical map/ layer is stack-specific, and bootstrap auto-detects the stack and seeds map.collectors accordingly (existing configs are never touched; every knob stays overridable):

A repo with no recognizable stack gets an empty map layer and everything else works the same. The lexical collectors are honest best-effort scans, marked as such in the generated doc. Adapters for further stacks are deliberately small modules — see CONTRIBUTING.md if yours is missing.

Wiring your agents — the step that makes it real

A store alone changes nothing: your agent has to know it exists and when to consult it. Two moves (full guide with paste-ready blocks and a worked session: docs/AGENT-INTEGRATION.md):

1. Connect the MCP server to your harness (.mcp.json for Claude Code, config.toml for Codex — snippets in the guide). The seven kaut_* tools appear in every session, and their descriptions already teach the model the discipline: look up before re-exploring, route trust by the verdict, write back through the gate.

2. Paste the knowledge contract into whatever your agent loads every session (CLAUDE.md / AGENTS.md / system prompt) — a ~15-line block from the guide that makes the behavior reliable rather than occasional: read before re-deriving; healthy + precise = use as-is, stale/coarse = confirm in code; tag outcomes with kaut_note; after editing files run kaut_touched and repair or queue what the change owes.

Optionally wrap the contract as a harness skill (template in the guide), or let an orchestration framework compile the wiring for you — TAUT does it from one setup answer. Then: work as usual. If you ever want to browse yourself, node <engine>/kaut.mjs lookup prints the catalog of topics.

Daily use — there is none

KAUT is designed to be invisible. You will notice it in exactly three moments:

• On your command — tell the agent to save what it just learned ("persist this to KAUT"): it filters the session's findings through the litmus test, writes them with proper source bindings, and commits to the store's git. Owner-gated knowledge still stops at the draft queue for your review.

• When drafts pile up — kaut review lists what awaits you; approve or reject the batch in one sitting (doctor also warns while a queue is pending).

• Occasionally the agent asks a question only a human can answer ("is this rule intentional, or an accident?"). Your answer becomes the most valuable kind of knowledge in the base.

Everything else — looking things up, checking freshness, rebuilding the map — happens automatically and silently.

Commands

Run from anywhere inside a project git repository:

node <engine>/kaut.mjs setup         # guided install: data home, sibling-repo scan, bootstrap (run once, from anywhere)
node <engine>/kaut.mjs bootstrap     # create/repair the project's knowledge store (idempotent)
node <engine>/kaut.mjs index         # regenerate INDEX.md (under lock; auto-commits changes)
node <engine>/kaut.mjs doctor        # integrity checks; exit 0 = healthy
node <engine>/kaut.mjs home [<dir>]  # show or set the knowledge-data home (redirect at ~/.kaut/config.json)
node <engine>/kaut.mjs paths         # print resolved {projectId, root, engine, repo, mainBranch, source}
# reading core:
node <engine>/kaut.mjs lookup [<id>] # one-call ready block; no id = catalog; unknown id = miss (exit 0)
node <engine>/kaut.mjs stale [<id>…] # freshness verdicts for all/selected docs (read-path, no lock)
node <engine>/kaut.mjs map           # regenerate L0 maps per config map.collectors + commit
# maintenance loop:
node <engine>/kaut.mjs refresh [<id>…]        # per-doc re-derivation delta bundles (read-only)
node <engine>/kaut.mjs draft <id>             # queue a finished doc update for async owner review
node <engine>/kaut.mjs review [<id>…]         # owner side: list / diff / --approve / --reject
node <engine>/kaut.mjs touched <file>…        # which docs bind the given changed files
# telemetry:
node <engine>/kaut.mjs note <topic> <result>  # record an in-session outcome (trusted|confirmed|insufficient|stale-misled)
node <engine>/kaut.mjs digest [--since <ISO>] # aggregate journal telemetry across workspace stores
# backup / restore (the whole data home — stores, registry, setup record):
node <engine>/kaut.mjs backup                 # dated, versioned .tar.gz under <data>/backups/
node <engine>/kaut.mjs restore [latest|<file>] [--force]   # no arg = list; never overwrites without --force
# open format (OKF v0.2):
node <engine>/kaut.mjs okf check              # store-as-OKF-bundle conformance report (exit 0 = conformant)
node <engine>/kaut.mjs okf stamp              # backfill `type:` on legacy docs (through the write gate)
node <engine>/kaut.mjs okf export --out <dir> # project committed HEAD into an idiomatic OKF v0.2 bundle
# workspace (multi-repo):
node <engine>/kaut.mjs workspace init --manifest <conductor>/manifest.json
                                     # registry + member stores + ONE system store anchored to the launcher
node <engine>/kaut.mjs workspace list

MCP server: node <engine>/mcp.mjs — a zero-dependency stdio JSON-RPC server exposing the session verbs as MCP tools (kaut_lookup, kaut_note, kaut_refresh, kaut_touched, kaut_write, kaut_draft, kaut_status). Every tool takes an optional repo argument, so one server serves a whole multi-repo workspace. The owner-run escapes (review --approve, index --approve) are deliberately not exposed over MCP.

Flags: --dry-run (print actions without acting) · --json (machine output for stale|lookup|refresh|review|touched|digest) · --quiet · --approve / --reject (owner-run) · --force (restore: overwrite existing data; okf export: write into a non-empty dir) · --out <dir> (okf export) · --note <text> (note, review --reject) · --manifest <path> (workspace init) · --workspace <name> (doctor/stale/digest across a workspace) · --since <ISO-date> (digest) · --help/-h (usage, exit 0).

Exit codes: 0 ok · 1 validation/doctor failure · 2 store busy (lock held) · 3 environment missing (not a git repo / store not bootstrapped).

lookup and stale are read-path — they take no lock and only append a line to journal.jsonl (usage telemetry, untracked). A freshness verdict is data, not an error: stale exits 0 even when docs are stale. Verdict line, at most one, by priority tampered > disputed > broken > stale > branch-advisory; a healthy doc renders clean.

Operational depth — store layout on disk, resolution order, tamper containment and the write gate in detail, uninstall, engine internals: docs/OPERATIONS.md.

Configuration

One file: kaut.config.json in the store (created by bootstrap, sensible defaults). Most people only ever touch the map block (collector list and file locations — see the quickstart note above). The full reference of what the engine actually reads: docs/HANDBOOK.md §15.

Is it actually helping?

KAUT is built to keep itself honest:

• It maintains a usage journal per store (journal.jsonl): every lookup with its verdict, every gated write, every recorded outcome. kaut digest aggregates it across a workspace into reach / self-maintenance / value-signal numbers.

• Sessions record how a doc actually fared (kaut note <topic> trusted|confirmed|insufficient|stale-misled) — the honor-system value signal that shows where knowledge saved work and where it misled.

• Benchmarking is done externally (run the same task with and without KAUT and compare); the engine deliberately ships no benchmark harness.

The journal is append-only untracked telemetry and grows without bound; it is safe to truncate old lines manually (it is never knowledge, and digest simply sees a shorter history).

Backup

The data folder is the whole database — treat it accordingly. kaut backup packs the entire data home (every store with its git history, the workspace registry, the setup record) into a dated, versioned archive under <data>/backups/ — a plain .tar.gz (hand-rolled ustar + node:zlib, zero dependencies) that any standard tar tool can also read. kaut restore latest (or a file name) brings it back; nothing existing is ever overwritten without --force — a refused restore lists the conflicts and touches nothing.

Tests

cd <engine> && node --test          # 213 tests, zero deps (node:test)

Run the bare node --test — do not pass the test directory as an argument (on Node ≥ 24 that form fails to resolve the suite).

Uninstall

Delete the store directory (~/.kaut/<project-id>) and the pointer file (<repo>/.kaut.json), and remove the .kaut.json line from <repo>/.git/info/exclude. Your repository was never modified to begin with — there is nothing else to clean up.

FAQ

Is this just another agent memory system? No. Agent memory remembers conversations and preferences; KAUT is the project's documentation — AI-first, source-bound, freshness-checked. The write path enforces the boundary: project knowledge goes to KAUT, personal preferences go to the agent's own memory.

Is this RAG? No. There are no embeddings, no chunking, no retrieval ranking. KAUT stores a small set of distilled docs an agent reads whole, each with provenance and a git-computed freshness verdict — and deliberately stores only what is not cheaply derivable from the code. RAG over your codebase and KAUT answer different questions and coexist fine.

Is this an auto-generated wiki? No. Nothing enters the store as unverified generated prose: every doc must carry typed source bindings and a commit anchor, mechanical layers are regenerated (not hallucinated), and judgment-tier knowledge passes a human-approved gate. And unlike a wiki, a KAUT doc cannot rot silently — its sources are diffed on every read.

Is the store format proprietary? No — the opposite. KAUT implements the vendor-neutral Open Knowledge Format (OKF) v0.2: plain typed-markdown concept documents. Any OKF consumer can read a store, and kaut okf export produces a fully idiomatic OKF bundle. No lock-in: your knowledge is portable markdown in a git repo either way.

Will it commit anything into my repository? No. At most one ignored pointer file. The knowledge store lives outside the repo.

Does my team have to adopt it? No. KAUT is local-first: one developer installs it and benefits; nobody else is involved or affected.

What if a stored fact is wrong? Every fact carries its origin and a trust label; the agent treats low-trust facts skeptically and verifies them against code. The store keeps full history, so bad entries can be traced and rolled back.

What does it cost to run? The first map build is the expensive part (minutes). Day-to-day upkeep is designed to cost near-nothing: freshness checks are pure git comparisons — no AI calls involved.

Learn more

• The project wiki — Getting Started, Connecting Your Project, Core Concepts, the Maintenance Loop, FAQ and Troubleshooting in guided form

• docs/HANDBOOK.md — how it all works, in human language but in full detail

• docs/OPERATIONS.md — operator reference: on-disk layout, resolution, tamper containment, write gate, engine internals

• docs/AGENT-INTEGRATION.md — wiring agents to the store: the knowledge contract, per-harness snippets, a skill template, a worked session

• docs/MCP.md — the MCP server reference: registration, all 7 tools, protocol

• SCHEMA.md — the normative data contract this engine implements (incl. the OKF v0.2 conformance mapping)

• CHANGELOG.md — release history

• CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md

License & citation

Apache-2.0 — see LICENSE and NOTICE. If you use KAUT or build on the concepts it implements, please cite it via CITATION.cff.

Contact: Yuriy Orlov yuriy.orlov@undertrust.dev