kontext MCP server
Commit Nov 2, 2026Provides coding agents with declarative team knowledge by serving decisions, conventions, and pitfalls stored as Markdown files in git.
Also known as SemanS/kontext
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 2, 2026
- License
- Apache-2.0
What is kontext MCP?
kontext provides coding agents with declarative team knowledge by serving decisions, conventions, and pitfalls stored as Markdown files in git.
Summary generated from the project's README
About kontext MCP server
Providing coding agents with declarative team knowledge is what kontext enables by serving decisions, conventions, and pitfalls stored as Markdown files within a git repository. It acts as a bridge between AI agents and your codebase, ensuring that tools like Claude Code, Codex, Cursor, and OpenCode receive the same context regarding architectural choices and project rules. The system operates locally using a single Rust binary that functions as an MCP server, a CLI, and a set of git hooks.
Developers use this server to manage knowledge through a reviewed and reversible workflow. Instead of relying on unverified model memory, agents propose new knowledge that humans approve via standard pull requests. The server provides specific tools such as ctx_brief to deliver relevant context for specific file paths, ctx_why to explain the history behind a decision, and ctx_search for finding specific documentation. It also tracks knowledge freshness, flagging entries that have not been verified after a certain number of commits to prevent stale information from guiding AI development.
What you can do with it
- 1Briefing agents on local contextAsk an AI client to retrieve the specific decisions and conventions relevant to the files it is about to modify.
- 2Capturing new team knowledgeHave an agent propose a new coding convention or decision based on its recent work.
- 3Detecting outdated documentationIdentify knowledge entries that may no longer be accurate because the underlying code has changed significantly.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesemans/kontext is public and reachablegithub.com/semans/kontext ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/semans/kontext ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubkontext: 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.tomlsays 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_briefreturns 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 driftlists the entries a branch changed the code of without confirming them, under git and jj alike. → Freshness - Step-by-step bootstrap.
kontext initscans 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/architectsin CODEOWNERS and code-owner review required, no agent changes what every agent follows without that team's approval. - Audit trail.
git log -- .aiandkontext log --allshow 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 checkfails 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'sverifycommand runs only afterkontext trust --verifypins 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
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.
kontext MCP questions
How does kontext store knowledge?
Knowledge is stored as short Markdown files directly in your repository under directories like .ai/decisions/, .ai/conventions/, and .ai/architecture/.
Can I use kontext with Claude Code or Cursor?
Yes, kontext supports Claude Code, Codex, Cursor, OpenCode, and any other MCP client.
Is my data private?
Yes, kontext is local and private; nothing leaves your machine unless you configure it, and there is no account or central server required.
How do I prevent agents from making unauthorized changes to team knowledge?
You can control knowledge changes through git, using CODEOWNERS to require human approval for pull requests that modify the .ai directory.