elara-labs · rajkumarsakthivel · Aug 1, 2026 · Aug 1, 2026
@@ -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,14 +227,16 @@ 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 |
 |------|-------------|
 | `context_search` | Hybrid vector + BM25 search with graph expansion |
 | `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.
 </details>
 
+<details>
+<summary><strong>Resource Governor (Multi-Instance Safety)</strong></summary>
+
+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`.
+</details>
+
+<details>
+<summary><strong>Memory Nudges</strong></summary>
+
+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.
+</details>
+
+<details>
+<summary><strong>HTTP Search Endpoint</strong></summary>
+
+`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).
+</details>
+
 <details>
 <summary><strong>Append-Only Savings Ledger</strong></summary>
 
@@ -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.
 

@@ -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.
@@ -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
+```