safiyu/kontexta repository overview

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

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.

⁠The Unique Value

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

⁠1. Cross-Agent Handoff

• 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: register_project + onboard_agent injects a fenced, version-stamped workflow rules block into CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules / .continue/rules / .clinerules so every new conversation — on any agent — wakes up already knowing how to use kontexta.

⁠2. Cross-Project Awareness

• 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.

⁠3. Deterministic Context Retrieval

• 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.

⁠4. Token-Optimized Context Economy

• 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.

⁠5. Separation of Code and Context

• 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.

⁠6. Compounding Intelligence

• 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.

⁠Docker Hub compose

Requires Docker 24+ with the compose plugin.

Pull and run the pre-built image from Docker Hub⁠ in a single command:

curl -fsSL https://raw.githubusercontent.com/safiyu/kontexta/main/docker-compose.hub.yml \
  | docker compose -f - up -d

Or download the compose file first and run it directly:

curl -fsSL https://raw.githubusercontent.com/safiyu/kontexta/main/docker-compose.hub.yml \
  -o docker-compose.hub.yml

docker compose -f docker-compose.hub.yml up -d

Env: Kontexta data directory and Projects root path to be added before deploy to the file.