语义代码搜索与上下文记忆 MCP 服务

Point each agent's stdio MCP entry at:

context-broker connect --project-root /absolute/path/to/project

The first connection auto-starts the shared service; every agent reuses one embedding model and cache pool. Manage it explicitly:

context-broker start
context-broker stop    # disconnects every shared client
context-broker update --check
context-broker update

The service uses an OS-assigned port on 127.0.0.1, an authenticated readiness check, and a startup lock, so concurrent agents never race. All clients must run as the same OS user; a private descriptor in ~/.cache/context-broker/service holds the random bearer token (CONTEXT_BROKER_SHARED_RUNTIME_DIR relocates it). Each connection binds one canonical project root — requests cannot override it, and chat/session identifiers stay scoped per project. In shared mode, global JSON storage names include a project-path digest so equally named folders cannot collide; legacy name-only global saves are not auto-migrated.

The service owns one lazy embedding model and a single LRU cache pool for indexes, query metadata, and token reports. CONTEXT_BROKER_MEMORY_POOL_MB (default 256) bounds estimated retained cache payloads — not total RSS, the model, or in-flight work. Queries keep at most CONTEXT_BROKER_QUERY_CACHE_MAX_ENTRIES entries per project (128), disk query-cache files are capped by CONTEXT_BROKER_QUERY_CACHE_MAX_FILE_BYTES (4,000,000), and disk embedding caches use read-only memory maps. get_memory_usage reports aggregate pool counts and the shared PID without exposing another project's content.

For foreground operation, serve still defaults to port 8771 (serve --port selects another). Disabling one agent's MCP connection ends only its proxy; other sessions continue. A Linux startup-only measurement with the same interpreter showed 846,224 KiB peak RSS for the old eager import vs 79,044 KiB for proxy construction, before model loading — a startup measurement, not a production benchmark.

The router ranks tool descriptors against the current task, applies a token budget, and returns only the tools that should be visible. Registry vectors live in .cache/token-slim-router-tools.json. Safety checks block prompt-injection text, path traversal, secret-like arguments, secret filenames, and dangerous shell commands; high-risk and shell-capable tools require explicit confirmation. Unknown tools are delegated back to the client runtime, never executed blindly.

Every save is dual-written to the chosen backend and a local-JSON ledger at <storage>/chats/<project_digest>/<session_id>.json — append-only, never overwritten. Saves invalidate then warm the default-params chat cache (CONTEXT_BROKER_AUTO_WARM_CACHE_ON_SAVE=1) so the next default load is an immediate hit. When REDIS_URL is set, full load_chat_context responses are cached with TTL CONTEXT_BROKER_CHAT_CACHE_TTL_SECONDS (default 300) for both backends.

Resources: codebase://auto-context (auto context per request) and codebase://token-counter (metrics for editor dashboards). Token counter reports persist under broker storage (.context-broker/_internal/token-counter-latest.json), which is excluded from semantic indexing.

By default, Context Broker uses half of available CPU cores for embedding/indexing. It exits when its launching host disappears and releases in-memory caches after prolonged idle periods, preventing orphaned MCP processes from consuming RAM.

At setup, call configure_history_indexing. It asks the user Index / No index through MCP elicitation and saves the choice per project. Indexing is off until an explicit choice enables it; No index still reads saved history directly, and disabling indexing removes only the derived SQLite index — never original chats or handoffs.

lookup_project_history(query) checks the project's local chat ledgers and model handoffs for the current issue. Question-bearing routing/search MCP calls also check history automatically and append at most three relevant excerpts. Initialization, tool discovery, and unrelated questions do not preload project memory.

Similarity uses conservative keyword overlap (≥2 meaningful terms, 60% query-term coverage) — it detects repeated and lexically similar issues; it is not universal semantic matching. No provider calls or embedding model loads are required. History stays excluded from the source-code index, and secret-bearing excerpts are excluded.

Both modes scan at most 128 recent candidate files, 1 MB per file, and 2000 records per lookup; each excerpt is ≤2000 characters. Oversized or unreadable history produces partial: true — never interpret it as exhaustive. Records from other projects are never retrieved. A standalone MCP server cannot intercept questions a host does not send to it.

save_model_handoff saves an immutable checkpoint; load_model_handoff restores it for any target model in the same project. Neither requires Redis, Honcho, or a provider API:

{
  "goal": "Original user request",
  "messages": [{"role": "user", "content": "Exact conversation text"}],
  "decisions": ["Keep the existing public API"],
  "constraints": ["Use the user-selected model and reasoning level"],
  "facts": [],
  "tasks": [{"task": "Native verification", "status": "failed", "failure_reason": "Host unavailable"}],
  "acceptance_criteria": ["Regression tests pass"],
  "open_questions": []
}

Pass the returned handoff_id to the next model — it must load that checkpoint before continuing. Exact supplied messages, decisions, failures, and file contents are retained; no automatic summary replaces them. Failed tasks require reasons; completed tasks require evidence. Changed files, corruption, missing checkpoints, or insufficient context budget return failed; saved memory stays intact for recovery.

Checkpoints live once under CONTEXT_BROKER_STORAGE_DIR/handoffs/<project-digest>/, independently of model, session, and storage mode. Identical saves reuse the same content-hash ID; updated checkpoints preserve previous versions. Atomic writes and file locks protect concurrent saves. Each checkpoint is limited to 256 KB (source files share the 64 KB snapshot limit); load defaults to a 32 KB byte budget. These tools cannot recover unsaved host history, transfer private model reasoning, or guarantee equal model quality.

delegate_large_task runs 2–4 independent proposal workers concurrently, then one integration reviewer, using the exact user-specified model ID for every call. The tool asks the user Split task / Keep one agent before any provider calls — decline, cancellation, timeout, or unavailable elicitation launches no workers, and there is no confirmation boolean that bypasses the prompt.

Configure CONTEXT_BROKER_LLM_BASE_URL (OpenAI-compatible, ending in /v1) and, if required, CONTEXT_BROKER_LLM_API_KEY on the broker service. Local HTTP is limited to loopback; remote endpoints require HTTPS. The provider must support /chat/completions JSON responses and return the requested exact model ID. Provider calls can incur charges; the confirmation states the assignments, selected model, context sharing, and maximum number of calls.

Workers have no command execution or file-writing tools — they return proposed changes, evidence, and risks. Passing review yields ready_for_integration, not completed work: the host must integrate proposals and run tests. Failed batches preserve successful proposal handoffs, cancel unfinished siblings, and never automatically retry paid calls. Files outside the project, secret files/content, oversized responses, incomplete provider responses, and model mismatches are rejected. Failures return status: "failed", failure_code, failure_reason, completed: false, with the MCP isError flag set; provider HTTP failures expose only the status code.

• Query cache → local JSON at .cache/context-broker.json
• Corpus embedding index → .cache/context-broker-index.json + .npy (invalidated by path set / mtime fingerprint / model name)
• Saved results / user memory / token history → local JSON under .context-broker/ or ~/.context-broker/
• Cross-chat context → optional Honcho or Redis backend
• Chat history → dual-written to the backend and <storage>/chats/<project_digest>/<session_id>.json

Three storage modes for saved JSON results:

1. Both (default) ⭐ — save to the project folder, load project-first with global fallback, list from both. Best for daily development.
2. Global — everything under ~/.context-broker/. Best for CI/CD and centralized management.
3. In-project — everything under the project's .context-broker/. Best for committing results to git and sharing with teammates.

CONTEXT_BROKER_CONTEXT_BACKEND=redis \
CONTEXT_BROKER_REDIS_URL=redis://localhost:6379/0 \
python -m context_broker dashboard

Binds 127.0.0.1:8770 by default; install extras with pip install "context-broker[dashboard]". The dashboard requires the Redis backend to enumerate projects, auto-loads the nearest .env (without overriding parent env), and re-running it when an instance is already serving is a clean no-op — safe to wire as an auto-launch step in every editor's MCP config. User identity is opt-in via CONTEXT_BROKER_USE_ACCOUNT_NAME=1 (defaults to the OS account name; CONTEXT_BROKER_ACCOUNT_NAME_OVERRIDE overrides; explicit user_peer_id args always win).

Prefer Honcho? CONTEXT_BROKER_CONTEXT_BACKEND=honcho — install with pip install "context-broker[integrations]". The same save_chat_context / load_chat_context tools then write to Honcho; context is session-limited by default to avoid mixing unrelated memory.

On Linux, closing the editor's stdio MCP connection terminates the broker even when the editor remains open or a synchronous operation is still running — the watchdog observes pipe hangup without reading protocol messages. Network transports remain available to other clients when one disconnects.

Editor plugin enable/disable settings belong to the editor; this repository contains no editor plugin or hook that synchronizes those settings, and stopping the broker process does not change an editor's plugin toggle.