From 6252d681f3e8ffabb904d6dfcd92cb584c36a20b Mon Sep 17 00:00:00 2001 From: rajkumarsakthivel Date: Sat, 1 Aug 2026 13:58:05 +0100 Subject: [PATCH] docs: update README and wiki for recent features - Add Django and Express to multi-language benchmark table - Update MCP tools count from 9 to 11 (session_timeline, session_event) - Add Resource Governor, Memory Nudges, and HTTP Search Endpoint sections - Update roadmap with completed items and mcp 2.x port - Configuration.md: add serve.*, retrieval.marginal_ratio, multi-provider pricing - CLI-Reference.md: update version to 0.4.25, add cce serve --http - Fix dash-as-punctuation across all doc files --- README.md | 35 ++++++++++++++++++++++++----- docs/wiki/CLI-Reference.md | 25 ++++++++++++--------- docs/wiki/Configuration.md | 46 +++++++++++++++++++++++++++++++------- 3 files changed, 82 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 66b1769..1e60db6 100644 --- a/README.md +++ b/README.md @@ -132,8 +132,8 @@ the section for the current project. **Pi note:** Pi does not support MCP natively. To use CCE with Pi, you need a pi MCP adapter extension (e.g. [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter)) that consumes the `.mcp.json` config and exposes CCE's tools to the Pi agent. -`cce init` sets up both `.mcp.json` and `AGENTS.md` — Pi loads the latter -automatically for startup instructions. +`cce init` sets up both `.mcp.json` and `AGENTS.md` (Pi loads the latter +automatically for startup instructions). ``` my-project · 38 queries · last query 5m ago @@ -206,10 +206,12 @@ Output compression (reducing Claude's reply length) provides additional savings | Repo | Language | Files | Retrieval savings | Recall@10 | |------|----------|-------|-------------------|-----------| | [FastAPI](benchmarks/results/fastapi.md) | Python | 53 | **94%** | 0.90 | +| [Django](benchmarks/results/django.md) | Python (large) | 2,347 | **93%** | 0.95 | +| [Express](benchmarks/results/express.md) | JavaScript | 6 | **94%** | 1.00 | | [chi](benchmarks/results/chi.md) | Go | 94 | **76%** | 0.67 | | [fiber](benchmarks/results/fiber.md) | Go (monorepo) | 396 | **93%** | 0.07 | -Go's shorter files reduce the retrieval headroom (smaller baseline). Monorepos dilute recall at top-10 (fiber). Middleware queries with one-feature-per-file hit R=1.00 consistently. +Django (2,347 files, 5.4M tokens) shows CCE scales to large codebases with 0.95 recall. Go's shorter files reduce the retrieval headroom (smaller baseline). Monorepos dilute recall at top-10 (fiber). Middleware queries with one-feature-per-file hit R=1.00 consistently. **Reproduce it yourself:** @@ -225,7 +227,7 @@ Full results in [`benchmarks/results/`](benchmarks/results/). Queries and method ## What you get -**9 MCP tools** that Claude uses automatically: +**11 MCP tools** that Claude uses automatically: | Tool | What it does | |------|-------------| @@ -233,6 +235,8 @@ Full results in [`benchmarks/results/`](benchmarks/results/). Queries and method | `expand_chunk` | Full source for a compressed result | | `related_context` | Find code via graph edges (calls, imports) | | `session_recall` | Recall decisions from past sessions | +| `session_timeline` | Walk turn summaries for a session (drill into recall hits) | +| `session_event` | Inspect raw tool input/output for a specific event | | `record_decision` | Save a decision for future sessions | | `record_code_area` | Record which files were worked in | | `index_status` | Check index freshness | @@ -325,6 +329,24 @@ Memory entries compressed without LLM calls. Drops articles, fillers, pronouns. Dollar estimates in `cce savings` support 15+ models across Anthropic, OpenAI, and Google. Static pricing ships with CCE, live Anthropic pricing is fetched and cached 7 days. Configure `pricing.model` (e.g. `gpt-4o`, `gemini-2.5-pro`, `sonnet`) or override with `pricing.input` / `pricing.output` for custom rates. +
+Resource Governor (Multi-Instance Safety) + +Running dozens of `cce serve` processes (one per project per AI session) can exhaust system memory. The resource governor caps ONNX Runtime threads per process, uses advisory file locks so only one process indexes a given project at a time, backs off under Linux memory pressure (PSI), and auto-shuts down idle servers after 30 minutes. Configure via `serve.idle_timeout_minutes` and `serve.max_ort_threads`. +
+ +
+Memory Nudges + +CCE's cross-session memory depends on the agent calling `record_decision` and `record_code_area`. Memory nudges make recording ambient: after N searches without a recording, `context_search` results include a short reminder. At session end, the Stop hook summarizes unrecorded activity. Nudges re-arm after the first recording so they stay useful without being noisy. +
+ +
+HTTP Search Endpoint + +`cce serve --http` exposes a `POST /search` endpoint for custom agent integrations that speak HTTP instead of MCP stdio. Same hybrid retrieval pipeline, structured JSON response with confidence scores. Input validation clamps `top_k` (1..100) and `confidence_threshold` (0.0..1.0). +
+
Append-Only Savings Ledger @@ -372,7 +394,7 @@ pricing: # output: 75.0 # override $/1M output tokens ``` -**Remote Ollama:** If you run Ollama on another machine in your network, set `compression.ollama_url` (e.g. `http://nas.local:11434`) or export `CCE_OLLAMA_URL` — the env var wins. CCE probes the endpoint and falls back to truncation-only compression when it's unreachable, so a flaky link won't break indexing. +**Remote Ollama:** If you run Ollama on another machine in your network, set `compression.ollama_url` (e.g. `http://nas.local:11434`) or export `CCE_OLLAMA_URL` (the env var wins). CCE probes the endpoint and falls back to truncation-only compression when it's unreachable, so a flaky link won't break indexing. --- @@ -506,9 +528,10 @@ Output tokens cost 5x more per token (e.g. Opus: $15/1M input vs $75/1M output), ## Roadmap - [x] Multi-repo benchmarks (FastAPI, chi, fiber) -- [ ] More benchmarks (Django, Express) +- [x] More benchmarks (Django, Express) - [ ] Tree-sitter support for C, C++, Ruby, Swift, Kotlin - [ ] Docker support for remote mode +- [ ] Port to mcp 2.x API See [CHANGELOG.md](CHANGELOG.md) for shipped features. diff --git a/docs/wiki/CLI-Reference.md b/docs/wiki/CLI-Reference.md index ec20b36..94e9912 100644 --- a/docs/wiki/CLI-Reference.md +++ b/docs/wiki/CLI-Reference.md @@ -18,7 +18,7 @@ All commands use colorful, structured output with line-by-line animation on TTY: Running `cce` with no subcommand shows a welcome banner with project status at a glance: ``` -╭─────────────────────────── Code Context Engine v0.4.4 ────────────────────────────╮ +╭─────────────────────────── Code Context Engine v0.4.25 ────────────────────────────╮ │ │ │ ⬡ C C E ⬡ │ │ │ @@ -264,7 +264,7 @@ cce status -v **Oneline output example** (shown at the top of each Claude Code session): ``` -CCE v0.4.4 · my-project · 1247 chunks indexed · 68% saved over 42 queries +CCE v0.4.25 · my-project · 1247 chunks indexed · 68% saved over 42 queries USE context_search MCP tool for all code questions. Do NOT use Read/Grep to explore code. ``` @@ -449,10 +449,10 @@ cce dashboard The dashboard provides four views: -- **Overview** — chunks indexed, files indexed, queries run, tokens saved, live charts -- **Files** — full file list with staleness detection (`ok`, `stale`, `missing`) -- **Sessions** — architectural decisions and code areas from past Claude sessions -- **Savings** — token usage breakdown with compression controls +- **Overview**: chunks indexed, files indexed, queries run, tokens saved, live charts +- **Files**: full file list with staleness detection (`ok`, `stale`, `missing`) +- **Sessions**: architectural decisions and code areas from past Claude sessions +- **Savings**: token usage breakdown with compression controls **Variants:** @@ -648,7 +648,7 @@ cce upgrade Install method: uv Running: uv tool upgrade code-context-engine - ✓ Upgraded 0.4.3 → 0.4.4 + ✓ Upgraded 0.4.3 → 0.4.25 Refreshing project config... ✓ MCP server config is current @@ -661,7 +661,7 @@ cce upgrade **When already on the latest version:** ``` - ✓ Already on latest version (0.4.4) + ✓ Already on latest version (0.4.25) ``` **Check without upgrading:** @@ -672,7 +672,7 @@ cce upgrade --check ``` ── Upgrade ─────────────────────────────────────── - Current version: 0.4.4 + Current version: 0.4.25 Install method: uv To upgrade: uv tool upgrade code-context-engine @@ -737,11 +737,16 @@ These behave identically to the `cce services start` and `cce services stop` com ## cce serve -Start the MCP server. Claude Code calls this automatically via `.mcp.json` — you do not need to run this manually. +Start the MCP server. Claude Code calls this automatically via `.mcp.json`. You do not need to run this manually. ```bash cce serve # Point at a specific project directory (useful for debugging) cce serve --project-dir /path/to/your/project + +# Start with an HTTP search endpoint (POST /search) for custom integrations +cce serve --http ``` + +When `--http` is passed, the server also listens on an HTTP port and exposes a `POST /search` endpoint. This is useful for custom agent integrations that speak HTTP instead of MCP stdio. The endpoint accepts JSON with `query`, `top_k` (1..100), and `confidence_threshold` (0.0..1.0), and returns ranked results with confidence scores. diff --git a/docs/wiki/Configuration.md b/docs/wiki/Configuration.md index fa83db1..1c9d4e7 100644 --- a/docs/wiki/Configuration.md +++ b/docs/wiki/Configuration.md @@ -32,14 +32,26 @@ indexer: retrieval: top_k: 20 # Maximum number of chunks to return per query confidence_threshold: 0.2 # Minimum confidence score to include a result (0.0–1.0) + marginal_ratio: 0.75 # Stop adding results once score drops below this fraction of the + # top score. 0 disables (always fill to top_k). Default 0.75. embedding: model: BAAI/bge-small-en-v1.5 # Embedding model (fastembed-compatible) pricing: - model: opus # Which Claude model to use for cost estimates in `cce savings` - # Options: opus | sonnet | haiku - # Prices are fetched from Anthropic's docs and cached for 7 days + model: opus # Which model to use for cost estimates in `cce savings` + # Anthropic: opus | sonnet | haiku + # OpenAI: gpt-4o | gpt-4o-mini | gpt-4.1 | gpt-4.1-mini | + # gpt-4.1-nano | o3 | o3-mini | o4-mini | codex-mini + # Google: gemini-2.5-pro | gemini-2.5-flash | gemini-2.0-flash + # Anthropic prices are fetched live and cached 7 days. + # Other providers use static pricing updated with each release. + # input: 15.0 # override $/1M input tokens (any model) + # output: 75.0 # override $/1M output tokens (any model) + +serve: + idle_timeout_minutes: 30 # Auto-shutdown `cce serve` after N minutes of inactivity (0 = disabled) + max_ort_threads: 2 # Max ONNX Runtime threads per `cce serve` process (0 = ORT default) ``` --- @@ -73,7 +85,7 @@ Controls how much CCE compresses code chunks before including them in Claude's c | Level | Behavior | |-------|----------| -| `minimal` | Truncation only — keeps signature + docstring, drops body | +| `minimal` | Truncation only. Keeps signature + docstring, drops body | | `standard` | Truncation + light summarization if Ollama is available | | `full` | Full LLM summarization via Ollama (requires Ollama running) | @@ -108,15 +120,17 @@ CCE auto-detects available RAM and adjusts its behavior: | 12 to 32 GB | `standard` | Full pipeline, standard batch sizes | | More than 32 GB | `full` | Larger Ollama models, larger batches | -You do not need to set this manually — it is detected at startup. +You do not need to set this manually. It is detected at startup. --- ## Retrieval Tuning -**`top_k`** — how many chunks the retriever returns per query. Higher values surface more context but cost more tokens. Default: 20. +**`top_k`**: how many chunks the retriever returns per query. Higher values surface more context but cost more tokens. Default: 20. -**`confidence_threshold`** — minimum score to include a result. Range 0.0 to 1.0. Lower values return more results; higher values return only strong matches. Default: 0.2. +**`confidence_threshold`**: minimum score to include a result. Range 0.0 to 1.0. Lower values return more results; higher values return only strong matches. Default: 0.2. + +**`marginal_ratio`**: once results are ranked, any chunk whose score is below this fraction of the top score is dropped. This prunes low-value tail results and reduces tokens served. Range 0.0 to 1.0; 0 disables the cutoff. Default: 0.75. At runtime, Claude can pass `top_k` and `max_tokens` directly to `context_search`: ``` @@ -150,7 +164,7 @@ Any model available in fastembed works. Changing the model requires a full re-in cce clear --yes && cce index --full ``` -**Note:** The default `BAAI/bge-small-en-v1.5` is recommended for most use cases — it balances quality, speed, and size well. Larger models improve retrieval quality but are slower to embed. +**Note:** The default `BAAI/bge-small-en-v1.5` is recommended for most use cases. It balances quality, speed, and size well. Larger models improve retrieval quality but are slower to embed. --- @@ -167,3 +181,19 @@ cce dashboard --port 9090 ``` PID and port files are stored in `~/.cce/pids/`. + +--- + +## Resource Governor (`serve.*`) + +When multiple `cce serve` processes run simultaneously (one per project per AI session), they can exhaust system resources. Two config keys control this: + +**`serve.idle_timeout_minutes`**: auto-shutdown the MCP server after N minutes of inactivity. Prevents zombie processes from accumulating. Set to 0 to disable. Default: 30. Can also be set via the `CCE_IDLE_TIMEOUT_MINUTES` environment variable. + +**`serve.max_ort_threads`**: cap the number of ONNX Runtime threads per `cce serve` process. With many processes, uncapped threads (default = CPU count) create thousands of OS threads competing for cores. Set to 0 to use the ORT default. Default: 2. Can also be set via the `CCE_ORT_THREADS` environment variable. + +```yaml +serve: + idle_timeout_minutes: 30 + max_ort_threads: 2 +```