Skip to content

Getting Started

Jump to bottom
Yuriy Orlov edited this page Aug 27, 2026 · 2 revisions

Getting Started

KAUT installs as a git clone, needs no dependencies, and sets up one project in two commands. This page walks through the install, the first knowledge store, and what actually lands on disk. For the product narrative see the repo README.md; for operator depth (resolution order, on-disk layout, uninstall) see docs/OPERATIONS.md.

Prerequisites

  • Node.js ≥ 20 (the engine is developed on 24)
  • git — the project you connect must be a git repository, and each knowledge store keeps its own private git history
  • macOS or Linux

Install — clone, setup, done

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

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

2. Run the guided setup:

node kaut/kaut.mjs setup

Three questions:

  1. Knowledge data folder (default ~/projects/kaut-data) — where every store lives. Persisted once via the kaut home redirect: every later command and the MCP server resolve it themselves. This folder is live data — the engine only ever adds to it; nothing existing is wiped or rewritten.
  2. Which repositories — setup lists every sibling git repository; answer all, numbers, or names.
  3. Bootstrap now? — yes creates/actualizes a store per selected repo on the spot; no records the configuration and prints the per-repo commands for later. Bootstrap is idempotent either way: re-running setup on a populated data folder actualizes, never re-seeds.

Setup ends by printing the two wiring steps — register the MCP server with your harness and paste the agent knowledge contract (Using With Agents).

Scripted installs: setup --data <dir> --repos all --bootstrap --yes (plus --no-bootstrap, --scan <dir> to scan a different folder).

After setup: the map, verification, browsing

Setup's bootstrap already created the store skeleton per selected repo (idempotent — create-only-if-absent; a repo added later gets its store with cd <repo> && node <engine>/kaut.mjs bootstrap). Next, generate the L0 project map per repo:

cd <repo> && node <engine>/kaut.mjs map

Non-default stacks: the default map collectors are Vue/monorepo-conventional (src/router/routes.ts, packages/*). On other stacks the route collector is skipped with a "routes file not found" note and the rest still run. Point map.routesFile / map.packagesDir at your stack's files in the store's kaut.config.json, trim map.collectors, or skip map entirely — see Connecting Your Project.

Verify and browse:

node <engine>/kaut.mjs doctor    # integrity checks; exit 0 = healthy
node <engine>/kaut.mjs lookup    # no id = the catalog of topics
node <engine>/kaut.mjs lookup map/routes

From here, agents do the rest — looking things up (kaut lookup, or the kaut_* MCP tools: see MCP Server) and landing knowledge through the write gate as they work.

What you get on disk

  • The store, outside your repo — your data folder, <data>/<project-id>: its own private git, kaut.config.json, INDEX.md, and the layer directories. Your repository's history, branches, and teammates never see it.
  • One pointer file — <repo>/.kaut.json, ignored via .git/info/exclude (not via the committed .gitignore), so the team repository stays byte-identical. Losing the pointer is harmless: derivation resolves the same store.
  • Nothing else. The project repository is never modified. Uninstall = delete the store and the pointer (docs/OPERATIONS.md has the exact steps).

Next steps

  • Connecting Your Project — how knowledge binds to your code: sources, layers, anchoring, workspaces
  • MCP Server — plug any MCP-capable agent harness in
  • Maintenance Loop — how knowledge stays fresh
  • docs/HANDBOOK.md — the full technical guide, in human language

Clone this wiki locally