kontext

kontext: declarative team knowledge for coding agents

English / Slovenčina

Docs · Quick start · Releases · Issues · Discussions

---

What is kontext

kontext is a declarative bridge between your coding agents and git. The decisions, conventions and pitfalls your agents follow are short Markdown files in the repository. Agents propose new ones while they work, people approve them in the pull request of the change, and every agent (Claude Code, Codex, Cursor, OpenCode, any MCP client) gets the result in a short brief for the paths it is about to touch.

It is one Rust binary with three faces: an MCP server (kontext mcp), a CLI and a set of git hooks.

          Claude Code · Codex · Cursor · OpenCode · any MCP client
                                 │  MCP (stdio) or CLI
                        ┌────────┴────────┐
                        │     kontext     │  ctx_brief · ctx_why · ctx_search · ctx_read
                        │  (Rust, 1 bin)  │  ctx_capture · ctx_prepare_commit · ctx_init …
                        └────────┬────────┘
                                 │  git hooks: validate + secret scan · Decision: trailers · index
                                 ▼
   TEAM KNOWLEDGE (git, reviewed)                   LOCAL (.git/kontext/)
   .ai/decisions/*.md   ◄── commit + pull request ── inbox: candidates agents captured
   .ai/conventions/ · learnings/ · incidents/       search index (Tantivy), caches
   .ai/architecture/                               workflow receipts; disposable search caches

Why kontext

• Declarative. What agents follow is declared in the repository: one Markdown file per decision says what holds, since when and for which paths, and .ai/kontext.toml says how it is served (brief budget, freshness threshold, trailers, secret scanning). Nothing lives in a service or a UI. → Knowledge store
• Reproducible. The same commit gives every teammate and every agent the same team knowledge. Search indexes and caches are derived and rebuilt on demand; retain local inbox/history and write receipts during pending work. Check out an older commit and agents see the decisions that held at that commit. → Architecture
• Reviewed and reversible. A capture waits in a local inbox until it is promoted into a commit and merged through a pull request, under the same CODEOWNERS and CI as the code. A reversed decision is superseded, not deleted; the commit that ships a decision carries a Decision: trailer. → Capture and review
• One brief, every agent. ctx_brief returns the decisions, conventions and pitfalls for the paths an agent is about to touch, in ~1–2k tokens, with details on demand. → Context layers
• Stale knowledge surfaces. An entry whose paths saw 20+ commits since someone last looked at it is flagged in the brief and in kontext status; kontext drift lists the entries a branch changed the code of without confirming them, under git and jj alike. → Freshness
• Step-by-step bootstrap. kontext init scans the repository and mines its history for decision-shaped commits in seconds; your agent then deepens it one small, resumable task at a time. → Init pipeline

Why not Claude Code's memory or CLAUDE.md?

	CLAUDE.md, AGENTS.md, .claude/rules	Claude Code auto memory	Memory services	kontext
Written by	people, as prose	the model, on its own	the model, from sessions	agents propose, people approve
Shared and reviewed	in pull requests	no: one user, one machine	per deployment, no review	in the pull request of the change
Reaches the agent	the root file every session; a nested CLAUDE.md when the agent reads files in its directory; a .claude/rules file with paths: when matching files are touched	the first 200 lines of its index, every session	by similarity to the query	ranked for the paths it names, within a budget; with hooks, the governing entries right before an edit
An entry records	paths at most (.claude/rules); no status, date or owner	when it was written	depends on the store	paths, status, date, author, how and when it was last verified
When it goes stale	stays until someone notices	the model may rewrite it	the model may overwrite it	flagged after N commits on its paths (20 by default)
Works with	Claude Code reads AGENTS.md natively, as do Codex, Cursor and OpenCode; .claude/rules is Claude Code only	Claude Code	their plugin, SDK or MCP server	every MCP client and the CLI

What still differs: rule files are loaded by path pattern and have no status, so a replaced rule stays until someone deletes it, nothing says which rule a change left behind, and only Claude Code reads .claude/rules. kontext adds supersession with history, a review step for what agents propose, drift and freshness on governed paths, and the same answer for every client.

kontext does not replace CLAUDE.md or AGENTS.md: keep the few instructions every session needs there. Decisions are too many to load whole and too important to leave unreviewed. → Why not something else?

Under your control

• Approval. Knowledge changes only through commits. With /.ai/ @acme/architects in CODEOWNERS and code-owner review required, no agent changes what every agent follows without that team's approval.
• Audit trail. git log -- .ai and kontext log --all show who decided what, when, and what replaced it. With kontext's hooks installed, git log --grep "Decision: <id>" finds the commit that shipped a decision.
• Policy in CI. kontext check fails a pull request on malformed entries, duplicate ids or high-confidence secrets. → Validate knowledge in CI
• Local and private. No account and no server; briefs in ~50 ms, hooks in ~0.1 s. Nothing leaves the machine unless you configure it. A cloned repository runs nothing until you trust it: shared adapters need kontext trust, and an entry's verify command runs only after kontext trust --verify pins its text. → Security
• No lock-in. The store is plain Markdown and stays readable without kontext.

Quick start

curl -fsSL https://raw.githubusercontent.com/SemanS/kontext/main/scripts/install.sh | sh   # → ~/.local/bin/kontext

cd your-repo
kontext init                          # scan → history → render → wire (git hooks) → deepen plan
git switch -c kontext/bootstrap && git add .ai && git commit -m "docs: bootstrap team knowledge"

kontext connect claude --write        # .mcp.json — or: claude mcp add --scope user kontext -- kontext mcp
kontext connect agents-md --write     # a short "how to use kontext" block in AGENTS.md

Then run /mcp__kontext__kontext-init in Claude Code (or ask any connected agent to continue the kontext bootstrap), or let an LLM do a first pass: kontext init --deepen --llm llm-claude.

Daily use:

kontext brief --focus src/billing       # what an agent sees first
kontext why src/billing/round.ts:40     # decisions, module, history, blame
kontext capture --kind decision --title "Prices are integer cents" --paths "src/billing/**" --body "…"
kontext prepare-commit --promote <id>   # ships the decision in the same commit
kontext log                             # the decision timeline

Full walkthrough: Quick start · build from source: Installation.

Use it with your agent

Agent	Connect	Guide
Claude Code	kontext connect claude --write (+ --hooks for the brief at session start and governing entries before an edit, opt-in)	Claude Code
Codex	kontext connect codex --write (+ agents-md: Codex follows AGENTS.md)	Codex
Cursor	kontext connect cursor --write	Other clients
OpenCode	kontext connect opencode --write	Other clients
Superset & orchestrators	nothing extra: worktrees share inbox and progress	Other clients
Any MCP client	command kontext, args ["mcp"]	MCP reference

Sixteen agent tools: ctx_brief · ctx_search · ctx_read · ctx_why · ctx_log · ctx_drift · ctx_threads · ctx_capture · ctx_challenge · ctx_confirm · ctx_verify · ctx_inbox · ctx_prepare_commit · ctx_init · ctx_init_submit · ctx_api, plus prompts kontext-init, kontext-commit, kontext-reflect, kontext-distill. ctx_verify runs a pinned shell command, so hosts ask before it.

Applications use the versioned application API: kontext api or structured MCP ctx_api for queries, extraction, safe retries, staging and reviewed Git exports. The application keeps its UI and collaboration workflow; kontext owns the knowledge rules and formats.

Optional adapters

kontext works without any. If you already run a semantic memory (OpenViking), a code graph (CodeGraph, Serena) or a session archive, an adapter connects it in a few lines of TOML, and claude -p, codex exec or a local Ollama model can draft the bootstrap. → Adapters

Performance

Release build on an Apple Silicon laptop (init with a warm file cache; the first cold run of the monorepo took 3.3 s):

Repository	init (scan + history + render)	first search (builds the index)	warm search	brief	pre-commit hook
TypeScript Nx monorepo (3.2k files, 1.5k commits)	1.1 s	0.47 s	0.14 s	0.04 s	0.13 s
Rust/Python/TS moon workspace (640 files)	1.1 s	0.25 s	0.11 s	0.04 s	0.11 s

Documentation

semans.github.io/kontext, in English and Slovak.

• Getting started: Introduction · Installation · Quick start · Set up your agents
• Concepts: Architecture · Knowledge store · Git integration
• Guides: Bootstrap an existing repository · Team workflow · OpenViking
• Reference: CLI · MCP · Configuration

The docs sources are in docs/. This repository records its own design decisions with kontext. See .ai/.

Community & Contributing

• Questions and ideas: Discussions
• Bugs and feature requests: Issues
• Contributing: bug fixes, presets, docs and translations are welcome. See CONTRIBUTING.md (SK) and the Code of Conduct
• Changelog: docs · Roadmap: docs

Security

Please report vulnerabilities privately. See SECURITY.md.

License

kontext is dual-licensed under either of

• Apache License, Version 2.0
• MIT license

at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in kontext by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.