Content
# context-router
[](https://pypi.org/project/context-router-cli/)
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://github.com/mohankrishnaalavala/context-router/actions)
> **Memory-aware context engine for AI coding agents.**
> Persistent project memory · multi-repo workspaces · **96% fewer end-to-end tokens** than comparable tooling (21 tasks, 7 OSS projects, 21/21 rank-1) · MCP-native, local-first.
context-router is **more than a context picker**. It indexes your code,
**remembers what your team learned** (observations + decisions, shared
via git), and gives every coding agent the *minimum useful* slice of
both — so each session compounds on the last instead of starting from
zero.
```text
┌─ your repo ──────────────────────┐ ┌─ pack (~159 tokens) ────────┐
│ 50,000 LOC, 12,000 symbols │ → │ • src/auth/cache.py │
│ + .context-router/memory/*.md │ │ • tests/test_auth_cache.py │
│ + workspace.yaml (multi-repo) │ │ • ADR-0014: TTL grace policy│
└──────────────────────────────────┘ └─────────────────────────────┘
↑ ranker uses code structure, query, freshness, memory
```
---
## Three things that make it different
### 🧠 Memory that compounds
Every fix, decision, and hard-won lesson becomes a **markdown observation**
in `.context-router/memory/`. Commit it to git — your whole team shares
it. Future agents call `search_memory` and get the answer in one MCP call
instead of re-deriving it from the diff history. **No SaaS, no lock-in,
no separate backend** — memory is shipped via your existing git flow.
Two kinds of memory, both first-class:
| Type | Captures | Used by |
|---|---|---|
| **Observations** | Bug fixes, perf wins, gotchas, "why this looks weird" | Future debug/implement packs auto-recall related entries |
| **Decisions (ADRs)** | Library picks, pattern choices, schema changes — with rationale | Surfaced in handover packs and during implement queries that touch the area; supersession lifecycle preserved |
Two more multipliers:
- **Auto-capture hooks** (`setup --with-hooks`): a git post-commit hook saves an observation per commit; a Claude Code PostToolUse hook saves on every Edit/Write. Memory builds up silently while you work.
- **Feedback learning** (`record_feedback`): each pack's useful/missing/noisy reports tune per-file confidence after ≥3 reports — query-similarity-weighted since v4.4.2 so feedback for one query doesn't poison unrelated ones.
### 🔗 Multi-repo workspaces, not just monorepos
Most context tools assume one repo. context-router treats a workspace
of N repos as one searchable graph: `workspace detect-links` infers
cross-repo edges from Python imports + OpenAPI / protobuf / GraphQL
contracts; `workspace pack` returns a unified ranked pack with
`[repo]` labels and warns when edges cross community boundaries.
### ⚡ 96% fewer end-to-end tokens without losing recall
v4.5 measures what agents actually pay: **pack tokens + downstream read
tokens** (symbol-body items cost only their line span). Workload-matched
holdout vs `code-review-graph`, 21 tasks across 7 OSS projects
(Go · Rust · Python · Java · TypeScript · k8s-scale):
| Metric (21 tasks) | context-router | code-review-graph |
|---|---:|---:|
| Rank-1 hit | **21/21** | 16/21 |
| **End-to-end tokens** | **15,325 (~730/task)** | 380,260 |
| Reduction | **−96.0%** | — |
Full methodology, per-task breakdown, caveats and reproduction in
[`BENCHMARKS.md`](BENCHMARKS.md).
---
## 60-second quickstart
```bash
# Install (uv recommended; pipx / pip / brew also work — see AGENT_GUIDE.md)
# Default — Python · TypeScript / JavaScript · Java · C# · YAML · SQL
uv tool install context-router-cli
# OR for polyglot / monorepo users — adds Go · Rust · Ruby · PHP parsers
uv tool install 'context-router-cli[all-languages]'
# In your repo:
context-router init # creates .context-router/
context-router setup --with-hooks # configure agent + auto-capture
context-router index # scan symbols/edges (<30s typical)
# Use it
context-router pack --mode review # for a PR
context-router pack --mode implement --query "add rate limiting" # for a feature
context-router pack --mode debug --error-file pytest.xml # for a failure
```
For the full setup walkthrough — including MCP server registration for
Claude Code, Cursor, Copilot, Gemini, Windsurf, and Codex — see
[`AGENT_GUIDE.md`](AGENT_GUIDE.md). **Hand `AGENT_GUIDE.md` to a local
agent and it can install, configure, and start using context-router on
its own.**
---
## Pack modes at a glance
| Mode | Use when | Default budget |
|---|---|---:|
| `review` | Reading a diff / PR | 1,500 tok |
| `implement` | Writing new code per a query | 1,500 tok |
| `debug` | Tracing a failure | 2,500 tok |
| `handover` | Onboarding / sprint summary (or `--wiki` for deterministic markdown) | 4,000 tok |
| `minimal` | Quick triage — ≤5 items + `next_tool_suggestion` | 800 tok |
Optional flags: `--with-rerank` (cross-encoder, +0.10–0.20 precision),
`--with-semantic` (bi-encoder cosine), `--max-tokens N`,
`--inline-bodies {top1|all|none}`, `--json`. Pack metadata exposes
`depth` (`narrow`/`standard`/`broad`) and `feedback_applied` so you
can see which historical signals shaped the result.
> `--with-rerank` and `--with-semantic` need the optional `[semantic]`
> extra (~22 MB cross-encoder + bi-encoder weights, downloaded once):
> `uv tool install 'context-router-cli[semantic]'` (or `pipx install
> 'context-router-cli[semantic]'`). Without it, both flags log a warning
> and silently fall through to the structural ranker.
---
## MCP integration
context-router exposes **17 MCP tools** over stdio JSON-RPC 2.0.
Compatible with Claude Code, Cursor, Copilot, Gemini CLI, Windsurf,
and any other MCP-aware agent.
<details>
<summary><strong>Claude Code — <code>.mcp.json</code></strong></summary>
```json
{
"mcpServers": {
"context-router": { "command": "context-router", "args": ["mcp"], "type": "stdio" }
}
}
```
</details>
<details>
<summary><strong>Cursor — <code>.cursor/mcp.json</code></strong></summary>
```json
{
"mcpServers": {
"context-router": { "command": "context-router", "args": ["mcp"], "cwd": "${workspaceFolder}" }
}
}
```
</details>
<details>
<summary><strong>Windsurf — <code>.windsurf/mcp_config.json</code></strong></summary>
```json
{
"servers": {
"context-router": { "command": "context-router mcp", "transport": "stdio" }
}
}
```
</details>
<details>
<summary><strong>Gemini CLI — <code>~/.gemini/settings.json</code></strong></summary>
```json
{
"mcpServers": {
"context-router": { "command": "context-router", "args": ["mcp"] }
}
}
```
</details>
`context-router setup --agent <name>` writes the right config for you.
Run `context-router doctor` to verify the agent can reach the server.
**Tool surface:** `get_context_pack` · `get_debug_pack` ·
`get_minimal_context` · `generate_handover` · `explain_selection` ·
`build_index` · `update_index` · `get_call_chain` · `suggest_next_files` ·
`save_observation` · `search_memory` · `list_memory` ·
`save_decision` · `get_decisions` · `mark_decision_superseded` ·
`record_feedback` · `get_context_summary`.
Full tool reference and the **agent-contract section** every coding
agent should follow live in [`AGENT_GUIDE.md`](AGENT_GUIDE.md).
---
## Language support
**Default install** (`uv tool install context-router-cli`):
Python · TypeScript / JavaScript (`.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`)
· Java (full, with `enum`) · .NET / C# (full, with `record` / `enum`) ·
YAML (`.yaml`/`.yml` — k8s / Helm / GitHub Actions) · SQL DDL
(`CREATE TABLE / VIEW / FUNCTION / PROCEDURE` via regex).
**`[all-languages]` extra** (`uv tool install 'context-router-cli[all-languages]'`):
adds Go · Rust · Ruby · PHP via tree-sitter. The analyzer source ships in
every wheel; the extra only adds the optional tree-sitter parser deps.
Without the parsers, the entry points still register and `context-router
doctor` reports a stderr warning per missing parser — silent skipping is
forbidden by the no-silent-failure policy.
Add another language by implementing the `LanguageAnalyzer` protocol
and registering via the `context_router.language_analyzers` entry
point — `context-router index` picks it up automatically.
---
## Architecture (one screen)
```
packages/
contracts/ # Pydantic models + plugin protocols (no internal deps)
storage-sqlite/ # SQLite + FTS5, migrations, repositories
graph-index/ # File scanner, language dispatch, git diff, communities
ranking/ # BM25 + freshness + semantic + cross-encoder + score floor
core/ # Orchestrator — wires storage + graph + ranking
language-{python,typescript,java,dotnet,yaml}/ # tree-sitter analyzers
memory/ # Observations + FTS + freshness + export
runtime/ # Stack trace + JUnit/pytest XML parsers
workspace/ # Multi-repo workspace support
benchmark/ # 20-task suite + holdout runner
apps/
cli/ # Typer CLI
mcp-server/ # MCP server entry point
```
Strict module boundaries (CI-enforced): `contracts` has zero internal
deps; only `storage-sqlite` touches SQLite; only `core` imports from
`storage-sqlite`/`graph-index`/`ranking`; CLI/MCP only import `core`
and `benchmark`.
---
## Documentation
| Doc | For |
|---|---|
| [`AGENT_GUIDE.md`](AGENT_GUIDE.md) | **Hand to your AI agent** — install, setup, every feature, the agent contract, troubleshooting, examples |
| [`BENCHMARKS.md`](BENCHMARKS.md) | Full holdout results across 6 OSS projects, reproduction commands, fixture provenance |
| [`CHANGELOG.md`](CHANGELOG.md) | Per-release detail (current: v4.5.0) |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, coding standards, PR process |
---
## Development
```bash
git clone https://github.com/mohankrishnaalavala/context-router
cd context-router
uv sync --all-packages --extra dev
uv run pytest --tb=short -q # 476 tests, ~60s
uv run ruff check .
```
---
## Reporting issues & support
Found a bug or have an idea? We'd love to hear it.
- **🐞 Bug reports** (install failures, crashes, wrong output, silent no-ops):
[open a bug report](https://github.com/mohankrishnaalavala/context-router/issues/new?template=bug_report.yml).
Please include `context-router --version`, how you installed it, and your OS.
- **✨ Feature requests**:
[open a feature request](https://github.com/mohankrishnaalavala/context-router/issues/new?template=feature_request.yml).
- **❓ Questions & setup help**: ask in
[Discussions](https://github.com/mohankrishnaalavala/context-router/discussions),
and check [`AGENT_GUIDE.md`](AGENT_GUIDE.md) for setup and troubleshooting.
- **🔒 Security vulnerabilities**: please **don't** open a public issue — use
[private vulnerability reporting](https://github.com/mohankrishnaalavala/context-router/security/advisories/new)
(see [`SECURITY.md`](SECURITY.md)).
Contributing a fix or feature? See [`CONTRIBUTING.md`](CONTRIBUTING.md).
## License
Apache 2.0 — see [LICENSE](LICENSE).
