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?
This is the beginning of the README. Read the rest at the original. Read the full README ↗
