(pronounced kon-TEX-tah)

One memory. One toolbox. One feedback loop. Any agent.

Kontexta is a local-first Model Context Protocol (MCP) server that gives your AI coding agents — Claude Code, Cursor, Cline, GitHub Copilot, Gemini, Antigravity — a persistent memory and a controlled command surface. Learn more at kontexta.dev

Instead of agents losing context between sessions or inventing their own shell commands, Kontexta provides:

• Brain: A git-backed markdown vault with FTS5 search and surgical section edits.
• Hands: A sandboxed command engine defined by you in kontexta.json.
• Eyes: A feedback loop that journals results back into the brain.

Most AI tools trap context inside their own chat window. Kontexta moves that context to your own SSD, providing six core advantages:

• Switch agents mid-project: Claude Code journals a decision; Cursor reads it 5 minutes later.
• Unified command surface: Author your kontexta.json once; every agent uses the same validated tools and approval gates.
• Multi-agent collaboration: Different agents working on different tasks contribute to the same indexed knowledge base.
• Zero-touch onboarding: projects.register + admin.onboard_agent injects a fenced, version-stamped workflow rules block into CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules / .continue/rules / .clinerules / .github/copilot-instructions.md so every new conversation — on any agent — wakes up already knowing how to use kontexta.

• Global reach: An agent working in Project A can instantly search and read the documentation, context, and states of Project B.
• Shared standards: Solve a problem once, document it, and let your agent apply that solution across all your other projects automatically.
• Heads-up on sensitivity: Because the vault is global, every registered project is readable by any agent session you start. If you mix client work with personal projects, keep sensitive material in a separate vault (KONTEXTA_DATA_DIR) rather than registering it alongside everything else.

• SQLite FTS5 Power: Instead of unpredictable vector-based RAG, Kontexta uses high-performance full-text indexing for deterministic, local-first context discovery.
• Reliable Discovery: Fast, exact keyword and regex-based search ensures you find what you're looking for without the "hallucination" risk of third-party embedding providers.

• Surgical fetching: Instead of indiscriminately dumping whole directories into the LLM's context window, Kontexta provides tools to fetch specific file outlines, sections, or targeted search excerpts.
• Budget awareness: Every tool response includes est_tokens so agents can smartly budget what they pull into memory.

• The "Context.md" Killer: Stop littering your source tree with CONTEXT.md or AI_NOTES.md files that clutter your PRs and get stale.
• Global Knowledge Vault: Keep your main codebase pristine. Architectural decisions, agent journals, and cross-project standards live in a separate, dedicated global vault accessible by any agent instance.

• Continuous learning: Through the "Eyes" and journaling system, your AI agents document their decisions, successes, and mistakes.
• Smarter next time: A problem solved today is saved in the Brain, meaning tomorrow's session starts with the benefit of yesterday's experience.

Kontexta builds a closed feedback loop that makes every turn smarter than the last.

A markdown knowledge vault optimized for context-window economy.

• FTS5 Search: Instant local keyword search.
• Surgical Edits: Tools for reading and updating specific markdown sections without pulling entire files.
• Token-Aware: Every response includes est_tokens and size_bytes so agents can budget their context.

A project-defined command surface that replaces "unrestricted shell access" with a sandboxed contract.

• Explicit boundaries: You declare exactly what an agent can do via kontexta.json. There is no unrestricted shell access.
• Sandboxed: Locked working directory, clean environment, and ring-buffered output.
• Human-in-the-loop: High-risk commands can require a cryptographic one-time token, pausing execution until you explicitly approve it.

Closes the loop by capturing Hands' output and journaling learnings back into the Brain.

• Live Observation: Tools like admin.overview({mode: "whats_new"}) and files.diff_against_disk let agents see what actually changed.
• Automatic journaling: Every MCP tool call is captured to a per-project, append-only event log (Layer 1). The journal.distill tool — or the lenient-mode auto-fallback — collapses raw events into per-topic markdown summaries (Layer 2) indexed alongside the rest of the knowledge base. journal.write (kind: "note" / "intent") lets agents enrich the log with decisions and topic pivots. Phase 2 also adds journal.housekeep (retention/archival), journal.commit_upgrades (closes the subagent dispatch loop), strict mode (configurable per project — blocks read tools when backlog exists), and an opt-in WebUI scheduler that runs mechanical distillation on a 15-minute clock when the dashboard is installed. Learn more about Journaling modes and configuration in docs/JOURNAL.md.

Imagine you are switching from Claude Code to Cursor mid-way through a feature.

• Claude Code knows why you chose that specific library.
• Cursor doesn't. You have to copy-paste or re-explain everything.
• CONTEXT.md files help, but they get stale, they clutter your PRs, and they don't capture live decisions.

1. Journaling: As Claude Code works, kontexta automatically captures every tool invocation and decision to a structured event log.
2. Persistence: Those logs are saved in your local Kontexta brain, not the chat window. The journal.distill tool consolidates raw events into per-topic markdown entries that are searchable alongside your knowledge base.
3. Seamless Handoff: When you open Cursor, it immediately sees the recent journal entries and architectural state via the Kontexta MCP.
4. Zero Re-explanation: Cursor "wakes up" with the exact same context Claude had.

Kontexta doesn't try to replace your favorite agent or memory library — it sits in a different spot. Here's an honest read of where it overlaps and where it doesn't:

Honest tradeoffs:

• If you only use one agent and one project, CLAUDE.md or vendor memory is simpler — reach for Kontexta when you're switching agents or coordinating across projects.
• mem0 and Zep do semantic recall that FTS5 doesn't; Kontexta trades fuzzy matching for determinism and local-only operation.
• Kontexta's Hands sandbox has no equivalent in the memory tools above — that's the unique surface, not the memory itself.

Requires Node 22.x LTS. That's it — no Docker, no pnpm, no build.

npx kontexta start

Boots the dashboard on http://localhost:23002 (opens in your browser) and starts the MCP server. First run walks you through master password, data location, and project registration in the browser.

If you only want the MCP server (no dashboard), point your AI client at:

{
  "mcpServers": {
    "kxta": {
      "command": "npx",
      "args": ["-y", "kontexta", "mcp"]
    }
  }
}

Or install automatically via Smithery:

npx -y @smithery/cli install safiyu/kontexta --client claude

For containerized deployments, see docs/INSTALL.md#docker-hub-compose.

Kontexta's dashboard is designed for local-first use — running on localhost or on a trusted machine you control. The threat model is:

• Default safe: A master password protects the UI. Sessions are HMAC-signed cookies, passwords are scrypt-hashed.
• IP bypass is opt-in per IP. During setup you can allowlist IPs (e.g. 127.0.0.1) to skip the login prompt from trusted addresses.
• Reverse-proxy mode is opt-in. If you put Kontexta behind nginx, Caddy, or Cloudflare Tunnel, enable "Trust X-Forwarded-For headers" during setup. Without this flag, those headers are ignored — so a LAN attacker cannot spoof an allowlisted IP.
• kontexta.json is your responsibility. The Hands engine executes shell commands you declare in this file. The sandbox limits where and how those commands run (path traversal blocked, ReDoS-proof regex, locked CWD, stripped PATH), but the what is whatever you wrote. Review any kontexta.json you didn't author yourself — same caution you'd apply to a Makefile, GitHub Actions workflow, or shell snippet from the internet.

In this demo:

• System audit and web clipping.
• Local RAG and context gathering.
• The Brain/Hands/Eyes loop in action.

No-install demo: Try the MCP endpoints interactively right from your browser on the Glama Kontexta page.

Why the high version number on a fresh repository? If you look at the commit history, you might wonder how a repository with so few commits reached its current major version.

Kontexta wasn't built over a weekend. It began over a year ago as a private, monolithic toolchain used to manage complex, multi-agent coding workflows. The versioning reflects its true architectural maturity.

Recently, I undertook a major effort to industrialize and modularize this engine, restructuring it into the three core pillars you see today: Brain, Hands, and Eyes. This process involved decoupling the core from private infrastructure and moving to a clean, open-source monorepo. The condensed git history is the result of this clean extraction—leaving behind internal legacy commits to publish only the battle-tested, production-ready framework available today.

What's deliberately deferred and what triggers will pull it forward lives in docs/ROADMAP.md. Notable open items: per-call project resolution in journaling, server-side LLM upgrade for the WebUI scheduler, and Layer 3 (embeddings + graph + semantic clustering).

• Global vault with two-way git sync.
• 58 MCP tools tuned for context economy.
• Batch operations (up to 500 files/call), grep, and regex support.
• Web clipping with auth-wall detection.
• Full git-backed versioning: files.get_history, files.get_diff, files.restore.
• Agent context rules onboarding: projects.register detects existing CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules/*.mdc / .continue/rules/*.md / .clinerules / .github/copilot-instructions.md and recommends a follow-up. The admin.onboard_agent tool injects an idempotent, version-fenced workflow rules block (or scaffolds one for the right agent) so every new conversation starts already aware of kontexta's conventions.

• Project-specific kontexta.json tools map.
• Strict sandbox: realpath-verified CWD, stripped PATH, and hard timeouts.
• ReDoS-proof parameter validation via re2.
• CSPRNG-bound confirmation tokens for high-risk commands.

• Built-in /docs page with a searchable catalogue of all 66 core tools.
• Form-based kontexta.json editor with live validation.
• Real-time status bar streaming git activity over WebSockets.

• Generic, dependency-aware calendar for tracking events across anything you name — a server, a delivery van, a store location, a piece of equipment, a room, or anything else you schedule against.
• Automatic conflict detection: overlapping windows on the same entity, overlapping windows on linked entities, and events scheduled too close together (configurable buffer).
• Month, week, and agenda views in the dashboard, matching the rest of the UI; click to add or edit events, manage entities and their dependency links.
• Export any date range as a standard .ics file for Outlook, Google Calendar, or Apple Calendar.
• 11 MCP tools so agents can schedule, link, and check conflicts straight from chat.

• CLI-driven documentation generation. Turn your knowledge base into polished documentation sites, API references, and LLM-readable docs.
• Render blocks. Composable output blocks for endpoints, glossary, mermaid diagrams, navigation, LLMs, markdown, and more.
• Seed templates. Pre-built templates for common documentation patterns — get started in minutes.
• Pipeline architecture. Pluggable pipeline with configurable sources, renderers, and output targets.

Kontexta is a project for developers, by developers. If you'd like to contribute new tools, improve the core engine, or refine the dashboard, please see our CONTRIBUTING.md for architecture guidelines and local setup instructions.

Built with care for the future of agentic coding. License: Apache-2.0