Documentation

Up and running in five minutes

Kodela installs alongside the AI tools you already use. Connect once, and context capture starts automatically.

Quick start

Install the CLI and connect Kodela to your AI tools. This detects Claude Code, Cursor, VS Code and more, and wires each one to capture context automatically.

$ npx -y @kodela/cli connect --apply --npx

Prefer to run the watcher without modifying tool configs? Start it standalone — it observes git and the filesystem as ground-truth capture.

$ npx -y @kodela/cli watch --auto-annotate --detach

Prefer to build from source? Clone the open-source Community Edition and build it locally:

$ git clone https://github.com/tkarlmarx/kodela-oss.git && cd kodela-oss && pnpm install && pnpm build

Requires Node 22+ and pnpm 11+. No account is needed for local single-developer use — nothing leaves your machine.

How capture works

Kodela uses two complementary paths that write to the same memory, so the why survives whether or not an agent annotated explicitly.

Fast path

MCP

MCP-capable agents call Kodela directly to author high-fidelity context in their own words.

Ground truth

Watcher

For every other tool, the watcher records what changed and attributes it — guaranteed coverage.

Sessions are enforced: a session can't close until every file it touched is explained, checked against a git-diff baseline captured at session start.

Memory Bank & pack

Two commands turn captured context into something your AI can read instantly — and neither needs a single flag to remember.

Automatic

Memory Bank

The six markdown files agents already read at the start of every task — project brief, product and active context, system patterns, tech context, progress. Generated on connect and kept current by the watcher. No command to remember.

One file

kodela pack

Your whole repo — its map, project DNA, and the captured why — packed into one AI-ready file you can paste into Claude, ChatGPT, or Cursor. Works on the first run, even before any context is captured.

$ npx -y @kodela/cli pack

Need to hand a teammate the reasoning behind a change? Turn any file's captured context into a clean snippet for a PR description or a handoff:

$ kodela explain src/auth/session.ts --share

Prefer to browse? kodela ui opens a free interactive local web app — search the why, filter by severity, drill into any file, and see whether your agent is getting smarter every session. Local-only, no account.

$ npx -y @kodela/cli ui

MCP tools

The MCP server exposes a small, composable tool surface.

kodela_session_startBegin a capture session (usually started by hooks) — auto-attaches recalled context for the task.

kodela_annotate_fileRecord the why for a changed file: actor, problem, reasoning, risk.

kodela_record_decisionAuthor a first-class, human-owned decision record.

kodela_get_contextAsk why a file is the way it is before editing it.

kodela_recallPull the most relevant prior why for the current task as an injectable block.

kodela_get_whyTrace a file back to the decisions that shaped it via an evidence-chain traversal.

kodela_session_endClose a session — enforced against the git-diff baseline.

annotate a changets

await kodela_annotate_file({
  session_id,
  file_path: "src/auth/session.ts",
  why_changed: "Rotation must persist the new token id so the " +
    "next refresh can verify the incoming token.",
  problem_solved: "Old token stayed valid after rotation.",
  risk: "medium",
});

Hosted MCP — read anywhere, one click

Team and Enterprise ship a hosted, multi-tenant MCP gateway. Point any MCP client at the URL and log in — no npx, no local process — and you get read tools scoped to only your org's projects: kodela_list_projects, get_context, recall, get_why, get_risks, list_decisions, and get_function_context. It's an OAuth 2.1 Resource Server (or a kdl_ API token), with per-user RBAC repo-narrowing and audit.

any MCP client — the whole team's memory, one URLjson

{ "mcpServers": { "kodela": { "url": "https://mcp.kodela.app/mcp" } } }

Once the gateway is published to the MCP Registry, connecting is one click:

Install in VS Code

Capture stays local and automatic; kodela sync pushes the entries, fused graph, and decisions to the org so the hosted tools answer with the full picture. Nobody has to run the CLI just to read.

CLI reference

The kodela command covers setup, capture, retrieval, and CI.

kodela connect --apply --npxWire Kodela into every detected AI tool — and generate the Memory Bank — in one line.

kodela uiOpen the free interactive local web app — search the why, filter by severity, drill into any file, explore the co-change graph, read decisions, and browse the timeline. Local-only, no account.

kodela packPack the repo and its captured why into one AI-ready file you can paste into any model.

kodela memory-bankGenerate the 6-file Memory Bank agents read at the start of every task.

kodela metricsSee whether your agent is getting smarter every session — memory size, per-session trend, and reuse.

kodela search <query> [--semantic]Search the why by keyword or meaning — reranked on-device so the best answer rises to the top.

kodela recall [topic]Return the most relevant prior why as a ready-to-paste block. No topic → auto-recall for the current task.

kodela capture-tierChoose how strictly context is captured before a session can close: enforced (default), assisted, or ambient (fill missing context asynchronously).

kodela watch --auto-annotate --detachRun the silent-capture watcher standalone — it keeps the Memory Bank fresh.

kodela context <file>Print the captured context and reasoning for a file.

kodela explain <file> --shareEmit a clean 'why this changed' markdown snippet to paste into a PR or handoff.

kodela detect-ai-change --exit-codeGate CI on AI-authored changes that lack context.

kodela check "<change>"Flag a change (or, with no argument, a proposed decision) that reverses an active recorded decision. --ci fails the build on a violation.

kodela governanceShow the governance scorecard: decisions honored vs violated, % of AI changes with captured intent, proposed conflicts, and a composite score.

CI enforcement

Gate pull requests on context coverage. The detector exits non-zero when an AI-authored change lacks an explanation, so missing context fails the build instead of merging silently.

$ kodela detect-ai-change --exit-code

Going further

The Community Edition repository holds the full documentation — architecture, the memory-graph data model, the MCP server, and the complete CLI. It's free and Apache-2.0 licensed.

Browse the repository Project roadmap Platform capabilities