ctxkit

ctxl

Local-first context memory for AI coding agents

---

Overview

ctxl (pronounced "contextual") gives AI coding agents -- Claude, Copilot, Cursor, and others -- persistent, structured project memory. Instead of re-reading your entire codebase on every request, agents receive a curated Context Pack containing exactly the knowledge they need.

Memory lives in .ctx YAML files alongside your code. They are tracked in git, reviewable in pull requests, and owned by your team -- not a third-party service.

v2 introduces the .ctxl index system for budget-constrained context selection, version tracking with automatic history entries, multi-agent conflict resolution, auto-update during coding sessions, project bootstrap, spec-kit bidirectional sync, and session-aware PR context generation.

Core principles:

• Local-first, private-by-default. No data leaves your machine. Ever.
• Deterministic. Same inputs always produce the same Context Pack, in the same order.
• Budget-aware. Respects token limits with index-based scoring and category budgets.
• Transparent. Every included and excluded item is attributed with reason codes.
• Version-tracked. Every .ctx change is recorded with full history and conflict resolution.

---

Key Features

• Hierarchical .ctx memory files -- per-directory context that merges upward, child overrides parent
• .ctxl index system -- scored, categorized, budget-constrained context selection with dependency graph
• Version tracking -- automatic history entries and archival for every .ctx change
• Multi-agent conflict resolution -- three-way merge with lock manager for concurrent agent sessions
• Auto-update -- staleness tracking and proposal generation during coding sessions
• Project bootstrap -- analyze directory structure and generate .ctx files automatically with ctxkit bootstrap
• Spec-kit bridge -- import constitution and specs as locked decisions and contracts, bidirectional sync
• PR context generation -- session-aware PR descriptions with prompt chains and agent decisions
• Smart context pack assembly with index-based selection, locality, recency, and tag-based scoring
• Contract enforcement with scope matching across paths and tags
• Token budget management with category budgets and guaranteed deterministic output
• Drift detection -- flags when referenced files are moved, renamed, or deleted
• Proposal workflow -- diffs are shown before any .ctx modification is written
• Session tracking with full audit trail of every context injection
• MCP server -- 16 structured JSON-RPC tools usable by any MCP-compatible agent
• Claude Code plugin -- automatic context injection via 8 hooks, interactive /ctxkit and /ctx skills
• Codex integration -- MCP registration, AGENTS.md generation, and CLI fallback
• Agent wrapper for transparent context injection via ctxkit run
• React inspection dashboard with 5 new pages: timeline, context map, conflicts, activity feed, PR context
• Secret detection and automatic redaction of credentials in diffs and logs
• V1-to-V2 migration with ctxkit migrate

---

Architecture

ctxl is a TypeScript monorepo with seven packages: