claude-code-infinite 1.0.11 → 1.0.14

package/README.md

@@ -4,74 +4,234 @@
 
 # Claude Code Infinite
 
-* Maximize Claude's intelligence with context-management from [MemTree.dev](https://memtree.dev)
-* Supports unlimited-length coding sessions
-* Feels fast and fresh with every message
-* Automatically recalls only the relevant past information
-* Allows you to continue your session without summarizing or compacting
- 
+Memory for long-running agents. Claude Code Infinite indexes your Claude Code sessions with
+[MemTree](https://memtree.dev) so their history can be easily searched, navigated, and understood,
+by you and by Claude, within a session and across all of them.
+
+While Claude works, MemTree summarizes each new batch of messages in the background and files it
+under a topic. Each topic gets its own summary, and the whole session gets one at the top. When a
+session outgrows the context window, Claude works from these summaries plus your most recent
+messages, so the session can keep going indefinitely. When it needs a detail, it opens a branch and
+follows it down to the original messages.
+
+* **Search across every session.** Claude can find what was decided, tried or ruled out in any of
+  your past sessions, by exact words or by meaning, filtered by project and date
+* **Browse each session's MemTree** in your browser, from the link `ccc` prints in the terminal
+* **Replaces `/compact` without losing the thread.** In a blind-graded benchmark, MemTree matched
+  full-context Claude Code and beat Claude Code's built-in `/compact` by 20 points
+  ([details](#long-session-benchmark))
+* **Unlimited-length sessions**, with relevant past information recalled automatically
+
+## Search across sessions
+
+Every `ccc` session is indexed as it runs, and Claude gets read-only `memtree` tools over all of
+your indexed sessions, so you can just ask:
+
+* "What did we decide about the retry limit last week?"
+* "Find the session where we fixed the token-count bug, and show me the fix."
+* "We tried this before. What went wrong last time?"
+
+| Tool | What it does |
+| --- | --- |
+| `search` | Searches this session's tree or all of your sessions. Text mode (default, free) matches exact words, ids, paths and errors; vector mode matches meaning. Filter by project, `since` and `until`. |
+| `list` | Lists your sessions, most recently active first, with title, first message, project (directory, repo, branch), models and times. Filter by time, project or words. |
+| `read_node` | Opens a node: its summary, its path from the root, and its children. |
+| `read_lines` | Reads the exact original transcript lines under a leaf. |
+
+Hits name their node, so Claude goes from a search hit to the summary around it and then to the
+exact lines. Type `/memtree-view` for the link to this session's tree. Details are under
+[Memory tools](#memory-tools).
+
+## Long-session benchmark
+
+In a blind-graded benchmark on a 775k-token Claude Code session, MemTree matched full-context
+Claude Code and beat Claude Code's built-in `/compact` by 20 points, finishing in about half the
+time. That is the same score as full context with a third of the tokens.
+
+| Setup | Score | Input tokens / run | Wall time | How it handles the history |
+| --- | --- | --- | --- | --- |
+| **Claude Code Infinite** | **69** | **39M** | **11–22 min** | Sent whole until the 800k budget, then compressed once to ~420k; never compacted |
+| Full context | 69 | 113M | 24–54 min | Grew to ~970k and hit Claude Code's auto-compaction mid-task every round |
+| `/compact` | 49 | 17M | 29–40 min | Claude Code's `/compact` before the task, 789k → 13k |
+
+Every setup resumes the same ~775k-token history and is given one task: fix the security issues
+found earlier in the session, which are listed only in the conversation. Claude Opus 5.5, 3
+rounds, graded blind against a fixed answer key by an independent grader. Scores are 0–100 means
+(68.7 / 69.3 / 48.7 in table order); the noise floor is 10 points, so MemTree vs full context is parity, not a
+win, while MemTree was ahead of `/compact` in every round. Average wall time was 16 min
+for MemTree and 38 min for full context. Input tokens count uncached, cache-read and cache-write
+tokens; `/compact`'s exclude the one-time `/compact` step. This is one task family, one model and
+3 rounds, not a general benchmark.
+
 ## Requirements
 
-* [node.js 18 or newer](https://nodejs.org/en/download/)
+* [node.js 20.3 or newer](https://nodejs.org/en/download/)
 * [Claude Code (the terminal version)](https://code.claude.com/docs/en/quickstart)
 * **Claude Subscription** - optional but highly recommended as this offers up to 1000x cost savings vs Anthropic's API pricing
 
-> [!NOTE]
-> #### No Anthropic Subscription
-> If you do not want to buy Anthropic subscription, choose option 2. "Anthropic Console account", during the Claude Code setup.
->
-> You don't need to buy API credits, just login and Claude Code will let you complete setup. Anthropic API usage will be billed through https://polychat.co.
->
-> Finally run `/logout` within Claude Code and rerun with `ccc`
-
 ## Setup
 
-1. Install with npm
+> [!TIP]
+> No Claude subscription? Use an Anthropic API key exactly as with vanilla Claude Code
+> (`ANTHROPIC_API_KEY` or a Console login). `ccc` forwards it unchanged to api.anthropic.com, and
+> you pay Anthropic per token.
+
+1. Install (Node ≥ 20.3; no git needed)
   ```bash
-npm install -g claude-code-infinite
+  npm install -g claude-code-infinite
   ```
 2. Run Claude Code Infinite with
   ```bash
   ccc
   ```
 
-## How it works
+This will guide you through setting up your PolyChat key which you can also get [here](https://polychat.co/auth?memtree=true).
 
-<table><tr><td>
-<img width="1050" height="445" alt="image" src="https://github.com/user-attachments/assets/d1ab2456-9a64-4118-a72a-b9d133c7c8bd" />
-</td></tr></table>
+## Environments
 
+The tool supports multiple environments (this selects the MemTree compression API only — Anthropic traffic always goes directly from your machine to api.anthropic.com):
 
-When you send a message, we retrieve relevant details and summaries from the prior messages in your thread. These details and summaries populate a **memory message**. Following the memory message, we append a compressed version of your recent message history. The resulting context-window is dramatically smaller, allowing Claude to process your request with much greater efficacy, lower latency, and reduced cost.
+- **Production** (default): `ccc` - Uses https://api.polychat.co
+- **Local**: `ccc local` - Uses http://localhost:8080 for local development
+
+Each environment maintains its own separate API key.
+
+## Claude Code auto-compaction
+
+`ccc` disables Claude Code's automatic conversation compaction for the Claude process it launches. MemTree manages the context sent to the model, so letting Claude Code independently summarize the full local transcript can compact a conversation MemTree already reduced. Manual `/compact` remains available.
+
+Claude Code 2.1.219 also recommends “Resume from summary” for any old session
+above a fixed 100k-token threshold, even when the active model has a 1M window
+and auto-compaction is disabled. `ccc` suppresses that resume-time
+recommendation as well; it does not disable the manual `/compact` command.
+
+A session whose last response reached the verified local refusal threshold
+(for example one sent whole while MemTree was unavailable) would otherwise be
+refused locally with "Context limit reached" on every prompt after a resume.
+On `ccc --resume <id>`, `ccc` backs the transcript up to
+`~/.claude-code-infinite/transcript-backups/` and lowers that last response's
+recorded usage to half the window, so the next message is sent and MemTree
+compresses it.
+
+To restore Claude Code's native auto-compaction setting for one invocation, use:
+
+```bash
+CCC_AUTO_COMPACT=1 ccc
+```
 
-## What this is NOT
+Claude Code normally treats any custom `ANTHROPIC_BASE_URL` as an unverifiable
+gateway and can therefore account for a resumed native-1M model as if it had a
+200k window. `ccc` identifies its transparent localhost relay as trusted, so
+current native-1M models retain the same context window they have when Claude
+Code connects directly to Anthropic. The official
+`CLAUDE_CODE_DISABLE_1M_CONTEXT=1` switch still forces the legacy 200k behavior.
 
-This is not a MPC or tool for simply retrieving memories. While we are compatible with all MPC's, tools, and other Anthropic features, these do not prevent your context window from becoming detrimentally large. MCP's and tools are some of the biggest token bloaters and it's exactly these types of messages that we heavily reduce during our compression phase.
+## Privacy & architecture: your Anthropic credentials never leave your machine
 
-## Why it works
+`ccc` runs a small proxy on `127.0.0.1` and launches Claude Code with `ANTHROPIC_BASE_URL` pointed at it and automatic compaction disabled. Claude Code keeps its **native login** — token refresh, plan-default model selection, and rate-limit handling behave exactly like vanilla Claude Code, and your OAuth token is sent only to `api.anthropic.com` from your own machine.
 
-LLMs get exponentially less intelligent as their input grows. 
+```
+Claude Code ──▶ localhost proxy (ccc)
+                  ├──(messages only, MemTree API key)──▶ api.polychat.co /v1/context_memory
+                  │◀──(compressed messages)─────────────┘
+                  └──(compressed request + your local OAuth)──▶ api.anthropic.com
+```
 
-References:
-- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172) (2023)
-- [RULER: What's the Real Context Size of Your Long-Context Language Models?](https://arxiv.org/abs/2404.06654) (2024)
-- <a href="https://research.trychroma.com/context-rot" target="_blank" rel="noopener noreferrer">Context Rot from Chroma</a> (2025)
- 
-<a href="https://www.youtube.com/watch?v=TUjQuC4ugak" target="_blank" rel="noopener noreferrer">
-  <img src="https://img.youtube.com/vi/TUjQuC4ugak/0.jpg" alt="Context Rot Video">
-</a>
+- Only message content is sent to MemTree for indexing/compression — never credentials.
+- Anthropic requests go directly from the local proxy to api.anthropic.com using the authentication Claude Code supplied. PolyChat never sees that credential or Anthropic traffic.
+- If MemTree is unreachable, slow, or your MemTree plan needs payment, `ccc` degrades to a transparent passthrough so your session is never interrupted.
 
+### Inline notices
 
-Furthermore, the above research primarily tests on needle-in-a-haystack tasks, which underestimates the effect for more difficult tasks encountered in coding.
+In interactive sessions, `ccc` reports these MemTree states as display-only lines in Claude Code:
 
-This is why starting sessions from scratch provides such a significant uplift in ability. What we're essentially doing is keeping each session as close to from-scratch as possible by limiting the tokens in Claude's context window to around 30k, or 15% of the standard 200k context-limit, filled precisely with the information relevant to your **last** message. Read more about how MemTree works [here](https://api.polychat.co/context-memory).
+- `✓ MemTree · conversation optimized · ~813k → 408k tokens`, with the session's newest completed MemTree page on its own line below it and a blank line before the answer, when a compressed turn reflects new indexing (MemTree's index covers more of the conversation than before) or a newly finished MemTree page. The before-count is `ccc`'s size estimate for the request that would otherwise have been sent (MemTree's `usage.raw_prompt_tokens` when `ccc` has none); the after-count is Anthropic's reported compressed input, estimated from bytes until usage arrives. Counts under a million are whole thousands, larger ones one decimal (`1.3m`). Without both counts, or when the result is not smaller, the line reads just `✓ MemTree · conversation optimized`. The line is green when terminal color is available, and plain when `NO_COLOR` or a monochrome terminal is configured. `ccc` uses the standard ANSI green foreground sequence and Node's capability detection, so the same path works in ANSI terminals on macOS/Linux and supported Windows consoles.
+- `⚠ MemTree degraded — this turn ran uncompressed` when a blocking compression call fails or times out.
+- `⚠ MemTree is off — payment required…` once when compression and indexing are disabled for payment.
+- `• MemTree` with the page on its own line below it, once at the end of a user turn, when the turn used a MemTree index whose link has not been shown yet (the first one of the session, then each newly finished index), unless the turn's success line already showed it. The line comes from the `Stop` hook, so it lands after the turn's last message. When MemTree passed the conversation through whole because it already fits the model's budget, the label line reads `• MemTree · /memtree-compact to compact session`. The URL always gets a line to itself, so a long link does not wrap the label or note. The displayed link follows the server's newest completed tree for this session, preserving its pinned namespace and own/served selection. If that lookup is unavailable, it falls back to the compression page; that page can show a completed prefix while its own tree builds. Open it in a browser, read it as JSON with `ccc fetch <url>`, or, from an agent inside the session, `GET $ANTHROPIC_BASE_URL/memtree/<short id>.json` on the loopback proxy without handling the key. Every MemTree call carries Claude Code's session id, so `GET $ANTHROPIC_BASE_URL/memtree/sessions/<session id>.json` lists every page from one session, newest first (the session id is the `--resume` id and the name of the transcript under `~/.claude/projects/`). `/memtree` lists the MemTree commands. Type `/memtree-view` at any time to print the session's latest link. `/memtree-compact` is MemTree's replacement for Claude Code's `/compact`: your next message is sent compressed to half the budget (or `/memtree-compact 400k` for another target), and from then on the session follows the compaction rules under [How it works](#how-it-works) with that target. `/memtree-compact off` goes back to sending the conversation whole. `CCC_COMPACT_TARGET=500k` sets the target of every compaction for every session from launch, for benchmarks and headless (`-p`) runs, where the slash command is unavailable; it does not compact by itself, the budget still decides when, and `/memtree-compact off` still turns compaction off for one session. `CCC_COMPACT_TARGET=off` starts every session in the `/memtree-compact off` state instead (`/memtree-compact [N]` still turns it back on). `ccc` answers these commands locally, so they cost no model turn and nothing is added to the conversation; the compaction setting lasts for the life of the `ccc` process. When a session starts and already has a page, which in practice means a resumed one (`ccc --resume`, or `/resume` inside a running session), its latest link is shown right away: `ccc` remembers the newest page per session in `~/.claude-code-infinite/memtree-links.json` (most recent 200 sessions) and a `SessionStart` hook prints it. `CCC_MEMTREE_LINK` changes where the link appears: `turn` (default), `message` (under every finished assistant message, green when the index is new, dim otherwise), `stop` (every turn, on `Stop`), `success` (only on the line below `✓ MemTree · conversation optimized`), or `off`.
 
-### Operating System Analogy
+The newest-tree lookup runs in the background with a 60-second cache, at most eight outstanding fetches, and one 10-second deadline across at most 32 finder pages. `/memtree-view` and resume hooks wait at most 2.5 seconds. Servers with the finder session-ID search (polychat `0202eaa` and later, including reviewed `c67cadb`) use `/v1/memtree/sessions?q=<id>`, following cursors and accepting only the exact session ID. A missing endpoint falls back to the compression page and is not retried for 30 minutes. The older exact route `/usage/memtree/sessions/<id>.json` accepts the bearer key, but excludes index-only calls and does not report completed trees, so it cannot supply this link. No verified server version provides a suitable exact newest-completed-tree lookup yet.
 
-It may seem strange that we are advocating for small context windows in a product called Claude Code Infinite. But Infinite is referring to the size of a new memory layer, the MemTree, which is a layer above the context window. This layer is larger and updated more slowly than the LLMs main input, just as disk is larger + slower than RAM.
+`/memtree-view` emits OSC 8 hyperlinks only when the ccc proxy has a TTY and detects iTerm2 3.1+ (`TERM_PROGRAM=iTerm.app` plus its version), JetBrains (`TERMINAL_EMULATOR=JetBrains-JediTerm`), Ghostty, WezTerm, VS Code, kitty, or Windows Terminal (`WT_SESSION`). Detection happens in the proxy, before hook output is relayed through pipes. `NO_COLOR`, dumb/unknown terminals, tmux/screen, and non-TTY output get a plain URL. Apple Terminal also gets the full visible URL for its normal URL handling. The success and Stop notices retain their visible URLs, and a late lookup cannot repeat the same page already linked by that turn's success notice.
 
-So you can think of MemTree as an operating system's virtual memory manager. Just as an OS manages RAM by swapping less-used data to disk, MemTree manages the model's context window by intelligently recalling only the most relevant information from past interactions. This ensures that the model always has access to the most pertinent data without being overwhelmed by the entire history of the conversation.
+**The end of a session.** MemTree indexes once about 10k new tokens build up, and each index call carries a request's messages, so a session's last turns, including the reply it ended with (often where a PR was opened), would never be indexed. `ccc` therefore sends one final index call per session: the main conversation plus that last reply, read from Claude Code's transcript, flagged so MemTree indexes the tail even below its minimum (at most once per conversation per 30 minutes; two conversations with an identical first message share that allowance). It goes out 10 minutes after a turn ends with no new request, or at exit for the 3 most recent sessions, inside the 2-second background drain; `-p` and non-TTY runs, which have no `Stop` hook, get it at exit. A failure is logged and never changes `ccc`'s exit code. Until then, `read_lines` with `"tail": true` reads the messages after the tree verbatim. When `ccc` runs inside another Claude Code session, the inner Claude Code writes no transcript unless `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` is set; without it the final index still covers everything through the last request, just not the final reply.
 
+`ccc` installs a minimal session-only Claude Code plugin using the repeatable `--plugin-dir` option. Its `MessageDisplay` hook changes only what the terminal renders and never alters stored assistant content; a `Stop` hook supplies a fallback for tool-only responses. That fallback may be saved by Claude Code as non-model hook UI metadata, but it is excluded from resumed model and recap requests. Notices are never added to model context, and Anthropic responses are left untouched with one exception: the hidden recap request Claude Code sends when you come back to an idle session gets a final `• MemTree` / `<url>` text block, so the recap ends with the link (not added when `CCC_MEMTREE_LINK=off`). Claude Code keeps that recap as a UI-only system entry, never as conversation content, and the block is skipped when it would push the recap past Claude Code's 400-character cap, and `-p`/non-TTY output is left unchanged. Legacy marker cleanup remains for transcripts created by older `ccc` releases. The payment state can also produce a separate terminal warning at startup.
+
+Claude Code currently displays the original assistant text instead of `MessageDisplay` replacements while verbose mode is enabled. Turn verbose mode off to see the inline MemTree line.
+
+### Memory tools
+
+Interactive `ccc` sessions also get a small MCP server, `memtree`, with four read-only tools (see [Search across sessions](#search-across-sessions)): `mcp__memtree__search` (`query`; optional `tree`, `"current"` for this session or omitted for all of your sessions; `mode` `text` (default, free) or `vector` (meaning, first page charged); `project`, `since`, `until`, `cursor`, `limit` (default 10, at most 50)), `mcp__memtree__read_node` (`node`, an address `<tree>#<id>` from search, or `id` with optional `tree`: summary, path from the root, children, leaf line range), `mcp__memtree__read_lines` (a leaf's `node`, or `block`, `start`, `end` with optional `tree`: exact transcript lines, at most 400 lines / 40k characters per call) (with `tail: true` instead, the newest messages after the tree that are not indexed yet) and `mcp__memtree__list` (your sessions, most recently active first; `since`, `until`, `project`, `q`, `cursor`, `limit`). Other sessions' trees are named explicitly by reference and authorized by your MemTree key. This session's tree (`tree: "current"`, or no `tree` on `read_node`/`read_lines`) is the one the current request was served from: the server asks the `ccc` proxy for `GET $ANTHROPIC_BASE_URL/memtree/current?session=<id>` (only that session's compression source page, or its stored source page on resume; `current.json?session=<id>` returns the page itself). Completed pages are cached. If the proxy temporarily serves an older prefix while a newer tree is indexing, the tools reuse that prefix during a 45-second cooldown, then check the page again. `ccc` registers it with `--mcp-config=<temp file>`, which keeps working under `--strict-mcp-config`, and pre-allows the four read-only tools; `CCC_MEMTREE_MCP=0` turns it off. The MCP process requires `CLAUDE_CODE_SESSION_ID` and checks that both the pointer and page belong to it. If Claude Code retains an MCP process with an old session ID after `/clear` or a session switch, reconnect the MCP server with the current session ID; it cannot infer a new identity from another session using the proxy. Print (`-p`) and non-TTY runs get it only when their own `--mcp-config` names a server `memtree` run by `ccc memtree-mcp` (add `--allowedTools mcp__memtree__search,mcp__memtree__read_node,mcp__memtree__read_lines,mcp__memtree__list`). Whenever the tools are configured, compress calls carry `x-memtree-tools: search,read_node,read_lines,list` so MemTree tells the model how to use them.
+
+## How it works
+
+<table><tr><td>
+<img width="1050" height="445" alt="image" src="https://github.com/user-attachments/assets/d1ab2456-9a64-4118-a72a-b9d133c7c8bd" />
+</td></tr></table>
+
+
+When you send a message, we retrieve relevant details and summaries from the prior messages in your thread. These details and summaries populate a **memory message**. Following the memory message, we append a compressed version of your recent message history. The resulting context-window is dramatically smaller, allowing Claude to process your request with much greater efficacy, lower latency, and reduced cost.
+
+**Compaction keeps a stable prefix.** While a conversation fits the model's budget (800k tokens for Opus 5.5), it is sent whole. When a request reaches the budget, `ccc` compresses it once, to half the budget (or your `/memtree-compact N`), and keeps those compressed bytes as the session's prefix. Every later request, human turns included, is that same prefix followed by the messages that came after it, verbatim, with no compression call (MemTree still indexes in the background). Because the prefix does not change, Anthropic reads it from the prompt cache on every turn after the one that compacted, instead of writing the whole compressed context again. `ccc` compresses again only when prefix plus newer turns reach the budget (measured from the size Anthropic reported for the previous request, plus an estimate for what was added), or when the messages the prefix stands for change (rewind, edit, fork, `/clear`). If that recompression fails, the turn is sent on the old prefix rather than the whole history. The budget is the one MemTree reports for the model; until the server reports one, `ccc` uses 80% of the model's context window. `CCC_BUDGET_TOKENS=60k` overrides it for testing. Every `requests.jsonl` line carries the `pid` of the `ccc` process that wrote it, which tells apart concurrent sessions sharing the log. The same rule holds inside a tool loop, so a long single turn (a headless `-p` run, or a long agentic loop) is compacted as it grows rather than only when you next type: each tool request under the budget goes out with no compression call, the one that reaches it is compressed once and becomes the stable prefix, and later tool requests and your next message ride that prefix until it reaches the budget again. `requests.jsonl` shows the `compaction` of each main-thread human turn and of every tool turn (budget, its source, the size estimate, and the reason for a compaction: `budget`, `prefix-mismatch`, `manual` or `target-change`); a human turn sent on the stable prefix is `turnType: "followup-prefix"`, a tool turn `tool-memory` (on its route) or `tool-prefix` (on the prefix directly), and a tool turn that compacted `tool-recompressed`.
+
+That compressed context stays in force for the rest of the turn: the tool loop it kicks off, and the matching Count Tokens calls, are routed through the same compressed prefix. The Count Tokens part matters — Claude Code sizes its context from those replies, so counting the uncompressed history would make it auto-compact a conversation memory had already shrunk. A mismatched or resumed conversation shape drops the route rather than grafting one session's prefix onto another.
+
+Compressed prefixes are stored per *lane*, not in a single slot: the main thread, each subagent, and the away-summary side channel each key their own route by session and identity. Every lane gets the same deal — it installs its own prefix and rides it — and lanes cannot evict one another, so a subagent or a background side request can no longer strand the main conversation on full history.
+
+Programs you run from inside a `ccc` session (scripts, test suites, SDK apps) inherit its `ANTHROPIC_BASE_URL`, so their Anthropic calls reach `ccc` too. `ccc` handles only Claude Code's own requests, which always carry an `X-Claude-Code-Session-Id` header. Anything else is forwarded to Anthropic unchanged: it is never compressed or indexed on MemTree, and it cannot disturb the session's compressed history. These requests are logged in `requests.jsonl` as `turnType: "foreign"` with the start of their `User-Agent`. `CCC_CLAUDE_CODE_ONLY=0` turns the filter off.
+
+Subagents follow the same budget rule in their own tool loops: under the budget a subagent's tool request goes out as it is, and the one that reaches it is compressed once and becomes that subagent's route, which its later tool requests ride. A tool-turn compression is a blocking MemTree call and a soft fuse, not a hard cap: if MemTree is unavailable or returns nothing usable within its normal compression budget, the request goes out on the old prefix, or whole when there is none; a failed call puts compression on a brief cooldown, so an outage costs one stall rather than one per tool call, and a lane whose attempt produced nothing waits until its history has grown by a twentieth of the budget before trying again. An attempt that finds nothing indexed yet (a no-op with no tree) makes the lane skip compression calls until MemTree reports that tree built; a request that would overflow the context window still tries. A request with no session id is compressed without installing, since a route that cannot be matched later must not be stored. `/memtree-compact off` and `CCC_COMPACT_TARGET=off` pass tool requests through with no compression call. `CCC_TOOL_ROUTE_RECOVERY=0` turns off tool-turn compression for one invocation (tool requests make no size check and no compression call; human turns still compact); outcomes are recorded in `~/.claude-code-infinite/logs/requests.jsonl` under `routeLane`/`routeMiss`/`routeRecovery` (`compressed`, `noop`, `failed`, `no-gain`, `cooldown`, `in-flight`, `backoff`, `awaiting-index`, `disabled`, ...).
+
+Routing decisions, per-turn timings and usage, recovery outcomes, and delivery status are recorded in `~/.claude-code-infinite/logs/requests.jsonl`.
+
+The compression budget is a trigger to try MemTree, not a hard forwarding limit.
+If compression is unavailable, `ccc` sends the available request when its input
+plus output reservation fits the model's native window. If Count Tokens fails or
+is disabled, a learned estimate alone cannot block the turn: the final check uses
+the plain bytes-based estimate. Such a fallback can still be rejected by the
+upstream API, which makes the final tokenization decision. An `overBudgetForward`
+field in the request log marks requests forwarded above the compression budget.
+
+Sizing belongs to the individual request. Original bodies, validated compressed
+prefixes, and replacement bodies each retain their own estimate and count result;
+the compression planner, `client_input_tokens`, and final selection consult that
+shared record. A fitting compressed candidate is preferred, with the original as
+a fallback. If counting is unavailable, candidate selection uses the conservative
+bytes-based input estimate plus the requested output reservation against the
+model's native window. Refusal requires that no eligible candidate fits; a failed
+replacement cannot discard an original or prefix that still fits.
+
+`ccc` uses Anthropic Count Tokens selectively to check uncertain sizes and before
+refusing an estimated overflow. Counts describe the particular body being sent,
+including a compressed body when applicable. A request shares a three-second
+counting allowance across its checks; authentication failures and rate limits
+put counting on a bounded cooldown. `CCC_COUNT_TOKENS=0` disables these checks.
+The `countTokens` array in each request-log record lists the status class and
+elapsed milliseconds of each actual attempt, without bodies or credentials.
+If counting an assembled compressed prefix discovers that it is over budget,
+`ccc` makes at most one bounded recovery compression attempt before deciding
+whether to forward or refuse it. The request log records that decision under
+`lateCountRecovery.outcome` as `compressed`, `forwarded`, or `refused`.
+
+Before publishing a release, verify Claude subscription OAuth counting in a live
+session: launch this checkout's `node dist/cli.js --resume` with the normal Claude
+subscription login and resume a large conversation. After sending a turn, inspect
+the new `countTokens` entries in the request log for that process's `pid`. A
+successful count confirms acceptance; an authentication failure should leave the
+turn on the bytes-based fallback and suppress further counts during cooldown.
+An absent entry means no count was needed, so that turn does not verify OAuth
+acceptance. Mock tests verify header forwarding and failure behavior; they do not
+establish that Anthropic accepts subscription OAuth for this endpoint.
+
+Memory quality is evaluated offline: the weekly `memtree-bench` harness replays a fixed scenario through a ccc-wrapped arm and a vanilla Claude Code arm and grades complete outcomes blind against an answer key. (An earlier in-request memory-vs-full A/B comparison with a live grader was removed in 2026-08; it was off by default, and the offline benchmark measures the same question with a stronger instrument.)
+
+## More than a memory-retrieval tool
+
+Search tools alone don't keep a long session's context from growing until the model degrades.
+Claude Code Infinite does both: it indexes and searches your history, and it manages what the model
+sees, keeping it within budget. It works alongside your MCP servers, tools and other Claude Code
+features, and their output, often the biggest source of tokens, is exactly what MemTree reduces most.
 
 ## Usage Tips
 
@@ -85,20 +245,27 @@ So you can think of MemTree as an operating system's virtual memory manager. Jus
 
 * You can resume previous threads with `/resume`
 
+For `ccc --resume <id>`, an automatic, best-effort repair can unblock a transcript whose last response already exceeds Claude Code’s local refusal limit. It changes only that response’s usage totals and the iteration Claude Code counts, after writing an exclusive, uniquely named backup under `~/.claude-code-infinite/transcript-backups`. Earlier iterations and conversation content stay intact. The installed Claude Code 2.1.288 computes its blocking limit as the context window minus the output allowance (capped at 20,000) minus 3,000 tokens: 977,000 for the supported 1M models. Other versions use the conservative full-window threshold. The window comes from ccc’s model table, explicit `[1m]` transcript model signals, and any `--model` or `ANTHROPIC_MODEL` override, conservatively keeping the largest supported window. A successful response with input already beyond that inferred window disproves the inference and is never repaired. Unknown model overrides (including unresolved aliases), models or usage shapes, threshold overrides, possible running writers, changed snapshots, backup collisions, and filesystem errors all skip repair and continue the original resume. Process and file checks are bounded; other running JavaScript runtimes may conservatively prevent repair.
+
 
 ## Troubleshooting
 
-### 401 {"detail":"Your session has expired or the token is invalid. Please sign in again."}
+### Anthropic auth errors (401s, login prompts)
 
-This happens if you chose "Anthropic Console account" during setup instead of using an Anthropic subscription.
+`ccc` never touches your Anthropic credentials — Claude Code manages its own login exactly as it does without `ccc`. If you see auth errors, fix them the vanilla way: run `/login` inside Claude Code (or `claude` directly) and re-authenticate.
 
-Fix:
+### MemTree degraded / passthrough mode
 
-1. Run: `/logout`
-2. Re-run `ccc`
+If you see an inline "⚠ MemTree degraded — this turn ran uncompressed" notice, the compression API is unreachable or your MemTree key is invalid/expired. Your session keeps working uncompressed. Check your key at [polychat.co](https://polychat.co/auth?memtree=true), or delete it from `~/.claude-code-infinite/config.json` and re-run `ccc` to re-enter it.
 
-This logs you out of your Anthropic Console account and keeps you in `ccc` which uses PolyChat. If you'd like to use your own API key with PolyChat, login to polychat.co and head over to our [BYOK settings](https://app.polychat.co/api-keys).
+## Upgrading
 
-## API Rate limit errors
+`ccc` checks npm at startup (bounded to two seconds, silent if offline) and, when a
+newer release exists, shows one line under the MemTree banner inside Claude Code with
+the upgrade command. Upgrading is never automatic:
+
+```bash
+npm install -g claude-code-infinite
+```
 
-If you hit your Anthropic subscription's rate limits, you can still continue by running `/logout` and restarting `ccc`. This will bill tokens through your PolyChat subscription. Remember that you can use the `/resume` slash command to resume previous sessions. 
+Set `CCC_SKIP_UPDATE_CHECK=1` to disable the check (air-gapped or CI runs).

package/dist/cc-request.d.ts

@@ -0,0 +1,94 @@
+import type { ProjectMeta } from "./project-meta.js";
+/** Characters of system prompt kept for auditing a suspected side request. */
+export declare const SYSTEM_HEAD_CHARS = 120;
+export interface ClaudeCodeRequestInfo {
+    /** A Claude Code billing header was found in the system prompt. */
+    billingHeader: boolean;
+    ccVersion?: string;
+    entrypoint?: string;
+    /** `cc_turn_origin`, e.g. "human"; absent on side requests seen so far. */
+    turnOrigin?: string;
+    /** `cc_prompt_id` was present (the value itself is not logged). */
+    promptId: boolean;
+    /** Number of tool definitions sent; the main agent always sends its tools. */
+    tools: number;
+    /**
+     * Header present but no turn origin: the shape of the security monitor.
+     * Logged only, for now.
+     */
+    suspectedSideRequest: boolean;
+    /**
+     * Opening of the system prompt after the header, one line, only for a
+     * suspected side request (e.g. "You are a security monitor for autonomous
+     * AI coding agents."). Local log only.
+     */
+    systemHead?: string;
+    /**
+     * For a request with a header but no turn origin: the opening of its last
+     * user message (reminders removed), its message count, and a short hash of
+     * the session id. Recaps, /btw and background-notification turns share the
+     * main system prompt and differ only here. Local log only.
+     */
+    lastUserHead?: string;
+    messageCount?: number;
+    sessionTag?: string;
+}
+export declare function describeClaudeCodeRequest(body: Record<string, any>): ClaudeCodeRequestInfo;
+/** A short, non-reversible tag grouping requests of one session in the log. */
+export declare function sessionTag(sessionId: string | undefined): string | undefined;
+/**
+ * Claude Code's own side request (the auto-mode security monitor): a billing
+ * header, no turn origin, and no tools. The proxy forwards these untouched
+ * and never involves MemTree or the main thread's route state.
+ */
+export declare function isClaudeCodeSideRequest(info: ClaudeCodeRequestInfo): boolean;
+/**
+ * Shape of the monitor's `<transcript>` block, checked on every side request
+ * so a change in Claude Code's internal format shows up in the request log
+ * before anything relies on it. Observed on 2.1.281: one user message holding
+ * `<transcript>`, then one single-key JSON object per line (`{"user": ...}`,
+ * `{"<ToolName>": <input>}`, `{"meta": ...}`), then `</transcript>` and the
+ * grading instructions.
+ */
+export interface TranscriptShape {
+    ok: boolean;
+    /** Why the shape was not recognised; absent when ok. */
+    reason?: "no-transcript" | "unclosed" | "bad-line" | "empty";
+    lines: number;
+    userLines: number;
+    toolLines: number;
+    metaLines: number;
+    /** For a bad line: its 1-based index inside the block and its opening. */
+    badLine?: number;
+    sample?: string;
+}
+export declare function inspectMonitorTranscript(body: Record<string, any>): TranscriptShape;
+/**
+ * What the MemTree server stores about a request's client (usage_requests
+ * .client_meta), sent as one `x-client-meta` JSON header. Only short
+ * printable-ASCII values go out, so the header is always valid.
+ */
+export interface MemtreeClientMeta {
+    claude_code_version?: string;
+    entrypoint?: string;
+    turn_origin?: string;
+    lane?: string;
+    agent_id?: string;
+    parent_agent_id?: string;
+    requested_model?: string;
+    /** The session's project (project-meta.ts), for the sessions list's project filter. */
+    project_dir?: string;
+    git_repo?: string;
+    git_branch?: string;
+    git_commit?: string;
+}
+export declare function memtreeClientMeta(input: {
+    info?: ClaudeCodeRequestInfo;
+    lane?: string;
+    agentId?: string;
+    parentAgentId?: string;
+    model?: unknown;
+    /** Read once at startup (project-meta.ts); the same for every request. */
+    project?: ProjectMeta;
+}): MemtreeClientMeta;
+//# sourceMappingURL=cc-request.d.ts.map

package/dist/cc-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cc-request.d.ts","sourceRoot":"","sources":["../src/cc-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmBrD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,qBAAqB,CAqC1F;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE5E;AA6CD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAE5E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,wDAAwD;IACxD,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,eAAe,CAgCnF;AAWD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,IAAI,CAAC,EAAE,qBAAqB,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB,GAAG,iBAAiB,CAmBpB"}

package/dist/cc-request.js

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+/**
+ * What Claude Code says about a request in its billing header, for telling
+ * the main conversation apart from Claude Code's side requests (the auto-mode
+ * security monitor, recaps, titles, …).
+ *
+ * Claude Code puts `x-anthropic-billing-header: cc_version=…; cc_entrypoint=…;
+ * …` as the first system text block. Observed on 2.1.281: the main thread's
+ * requests carry `cc_turn_origin=human;` and `cc_prompt_id=…;`, while the
+ * security monitor's request carries neither.
+ *
+ * The request log (2026-09-24, 112 requests) showed a header without a turn
+ * origin also on recaps and on background-notification turns, which carry
+ * the full tool list and must keep MemTree. Only the security monitor sends
+ * zero tools, so ``isClaudeCodeSideRequest`` requires all three.
+ */
+const BILLING_HEADER_PREFIX = "x-anthropic-billing-header:";
+/** Characters of system prompt kept for auditing a suspected side request. */
+export const SYSTEM_HEAD_CHARS = 120;
+export function describeClaudeCodeRequest(body) {
+    const texts = systemTexts(body);
+    let fields;
+    const rest = [];
+    for (const text of texts) {
+        if (!fields && text.startsWith(BILLING_HEADER_PREFIX)) {
+            const parsed = parseHeader(text.slice(BILLING_HEADER_PREFIX.length));
+            fields = parsed.fields;
+            if (parsed.rest.trim())
+                rest.push(parsed.rest);
+        }
+        else {
+            rest.push(text);
+        }
+    }
+    const tools = Array.isArray(body?.tools) ? body.tools.length : 0;
+    const info = {
+        billingHeader: fields !== undefined,
+        promptId: fields?.cc_prompt_id !== undefined,
+        tools,
+        suspectedSideRequest: fields !== undefined && fields.cc_turn_origin === undefined,
+    };
+    if (fields?.cc_version)
+        info.ccVersion = fields.cc_version;
+    if (fields?.cc_entrypoint)
+        info.entrypoint = fields.cc_entrypoint;
+    if (fields?.cc_turn_origin)
+        info.turnOrigin = fields.cc_turn_origin;
+    if (info.suspectedSideRequest) {
+        const head = oneLine(rest.join(" ")).slice(0, SYSTEM_HEAD_CHARS);
+        if (head)
+            info.systemHead = head;
+        const messages = Array.isArray(body?.messages) ? body.messages : [];
+        info.messageCount = messages.length;
+        const lastUser = [...messages].reverse().find((m) => m?.role === "user");
+        if (lastUser) {
+            const text = oneLine(messageText(lastUser).replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, " ")).slice(0, SYSTEM_HEAD_CHARS);
+            info.lastUserHead = text || `[${lastUserPartTypes(lastUser)}]`;
+        }
+    }
+    return info;
+}
+/** A short, non-reversible tag grouping requests of one session in the log. */
+export function sessionTag(sessionId) {
+    return sessionId ? createHash("sha256").update(sessionId).digest("hex").slice(0, 8) : undefined;
+}
+function lastUserPartTypes(message) {
+    const content = message?.content;
+    if (!Array.isArray(content))
+        return typeof content;
+    return [...new Set(content.map((p) => p?.type ?? typeof p))].join(",");
+}
+/** Text of the top-level `system` value, then of leading `role: system` messages. */
+function systemTexts(body) {
+    const out = [];
+    const add = (value) => {
+        if (typeof value === "string")
+            out.push(value);
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                if (typeof item === "string")
+                    out.push(item);
+                else if (item && typeof item === "object" && typeof item.text === "string")
+                    out.push(item.text);
+            }
+        }
+    };
+    add(body?.system);
+    const messages = Array.isArray(body?.messages) ? body.messages : [];
+    for (const message of messages) {
+        if (message?.role !== "system")
+            break;
+        add(message.content);
+    }
+    return out;
+}
+/** `key=value;` pairs from the start of the header; whatever follows is prompt text. */
+function parseHeader(text) {
+    const fields = {};
+    const pair = /^\s*([a-z_]+)=([^;\n]*);/;
+    let remaining = text;
+    for (let match = pair.exec(remaining); match; match = pair.exec(remaining)) {
+        fields[match[1]] = match[2].trim();
+        remaining = remaining.slice(match[0].length);
+    }
+    return { fields, rest: remaining };
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * Claude Code's own side request (the auto-mode security monitor): a billing
+ * header, no turn origin, and no tools. The proxy forwards these untouched
+ * and never involves MemTree or the main thread's route state.
+ */
+export function isClaudeCodeSideRequest(info) {
+    return info.billingHeader && info.turnOrigin === undefined && info.tools === 0;
+}
+const TRANSCRIPT_OPEN = "<transcript>";
+const TRANSCRIPT_CLOSE = "</transcript>";
+const SAMPLE_CHARS = 80;
+export function inspectMonitorTranscript(body) {
+    const shape = { ok: false, lines: 0, userLines: 0, toolLines: 0, metaLines: 0 };
+    const messages = Array.isArray(body?.messages) ? body.messages : [];
+    const text = messages
+        .filter((m) => m?.role === "user")
+        .map((m) => messageText(m))
+        .find((t) => t.includes(TRANSCRIPT_OPEN));
+    if (text === undefined)
+        return { ...shape, reason: "no-transcript" };
+    const start = text.indexOf(TRANSCRIPT_OPEN) + TRANSCRIPT_OPEN.length;
+    const end = text.indexOf(TRANSCRIPT_CLOSE, start);
+    if (end < 0)
+        return { ...shape, reason: "unclosed" };
+    const lines = text.slice(start, end).split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            parsed = undefined;
+        }
+        const keys = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? Object.keys(parsed) : [];
+        if (keys.length !== 1) {
+            return { ...shape, reason: "bad-line", badLine: i + 1, sample: oneLine(line).slice(0, SAMPLE_CHARS) };
+        }
+        shape.lines++;
+        if (keys[0] === "user")
+            shape.userLines++;
+        else if (keys[0] === "meta")
+            shape.metaLines++;
+        else
+            shape.toolLines++;
+    }
+    if (shape.lines === 0)
+        return { ...shape, reason: "empty" };
+    return { ...shape, ok: true };
+}
+function messageText(message) {
+    const content = message?.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((p) => (typeof p === "string" ? p : p?.type === "text" && typeof p.text === "string" ? p.text : ""))
+        .join("");
+}
+const META_VALUE = /^[\x20-\x7e]{1,128}$/;
+export function memtreeClientMeta(input) {
+    const candidate = {
+        project_dir: input.project?.project_dir,
+        git_repo: input.project?.git_repo,
+        git_branch: input.project?.git_branch,
+        git_commit: input.project?.git_commit,
+        claude_code_version: input.info?.ccVersion,
+        entrypoint: input.info?.entrypoint,
+        turn_origin: input.info?.turnOrigin,
+        lane: input.lane,
+        agent_id: input.agentId,
+        parent_agent_id: input.parentAgentId,
+        requested_model: input.model,
+    };
+    const meta = {};
+    for (const [key, value] of Object.entries(candidate)) {
+        if (typeof value === "string" && META_VALUE.test(value))
+            meta[key] = value;
+    }
+    return meta;
+}
+//# sourceMappingURL=cc-request.js.map