@chroxify/eunoe 0.1.0 → 1.0.0

package/README.md

@@ -6,8 +6,8 @@
 
 **Context management for Claude Code that never forgets what matters.**
 
-A local proxy that replaces Claude Code's context compaction. No summary call,
-no two-minute pause, no agent that wakes up having forgotten what you told it.
+A local proxy that keeps long Claude Code sessions sharp. Smaller context,
+nothing lost, no pause, no restart.
 
 </div>
 
@@ -19,310 +19,389 @@ no two-minute pause, no agent that wakes up having forgotten what you told it.
 
 ## The problem
 
-Fill up a long Claude Code session and it compacts. The agent writes a summary
-of everything so far, throws the conversation away, and continues from the
-summary.
+Every long Claude Code session eventually turns dumb on you, and it happens
+well before the context window is full. The agent starts forgetting rules you
+gave it an hour ago, re-reading files it already read, and asking about
+decisions you made together. When compaction finally kicks in it makes things
+worse, because the whole conversation gets replaced by a summary and anything
+the summary left out is gone for good.
 
-You can feel it the moment it happens.
+At that point the only fix is a fresh session, which means explaining the
+project again, pasting the rules again, and hoping it gets further this time.
 
-```
-you    (turn 6)   from now on, deploy to staging yourself, don't ask me
-...
-you    (turn 41)  ok ship it
-agent             Here's the deploy command — want me to run it?
-```
-
-The instruction was five turns old and three paragraphs into a 21,000-character
-summary. So were the exact version ID from the last deploy, the error you spent
-two turns tracking down, and the approach you already ruled out.
+The reason is that every file the agent ever opened and every command it ever
+ran stays in the prompt, so two hundred turns in the model is still reading a
+log from the first hour on every request, with the thing you said five turns
+ago buried somewhere in the middle of it.
 
-Compaction keeps the gist. The gist is not what you need.
-
-It also costs real time. A measured compaction at 922k tokens: **the full
-context read for the summary call, 2½ minutes of generation**, then a brand-new
-prefix written to cache anyway.
+| | Claude Code | eunoe |
+|---|---|---|
+| **context** | grows with every tool call until it fills the window | finished turns fold to your message, the output lines that mattered and the reply; turns in progress go out whole |
+| **at the limit** | a two-minute summary call replaces the whole conversation | never reached |
+| **old details** | gone unless the summary kept them | come back the moment a message is about them |
+| **your instructions** | survive if the summary mentions them | kept word for word |
+| **the session** | one window, then you start over | as sharp at turn three hundred as at turn three |
+
+## Results
+
+Measured on 24 held-out sessions of 90 to 120 turns with 600 facts planted
+at known depths, such as a value a command printed once, an error, an
+instruction that was later revised or a decision with its rejected options,
+and scored by exact match with no judge involved.
+
+| | facts remembered | rules followed without a reminder | prompt size when asked | tokens per session | transcript lookups per session | time per session | said "I don't know" | answered wrong |
+|---|---|---|---|---|---|---|---|---|
+| Claude Code's compaction | 70% | 92% | 70k | 741k | 10.1 | 53s | 172 of 600 | 7 of 600 |
+| Claude Code, told a transcript exists | 99% | 92% | 71k | 1,315k | 23.0 | 88s | 3 of 600 | 6 of 600 |
+| keeping the whole history | 100% | 90% | 411k | 815k | 0 | 67s | 0 of 600 | 3 of 600 |
+| eunoe, folding only | 99% | 92% | 118k | 490k | 2.7 | 40s | 4 of 600 | 5 of 600 |
+| **eunoe** | **99%** | **95%** | **110k** | **305k** | **0.1** | **39s** | **1 of 600** | **3 of 600** |
+
+*Facts remembered* is how many of the planted facts the agent could still
+answer correctly after the cut. *Rules followed without a reminder* is how
+often it applied an instruction from earlier in the session when the task
+called for it, without being told again. *Prompt size* is the context the
+model was reading when the question came, while *tokens per session* adds up
+every request it took to get through the questions, so it grows whenever the
+agent has to go and look something up.
+
+That is **29 points more recall than Claude Code's compaction** (95% CI +17
+to +42), better on 12 sessions and worse on none, with 3 wrong answers out
+of 600, and the same margin holds on 27 cut points taken from real sessions.
+eunoe matches keeping the whole history at a quarter of the context and 40%
+of the tokens.
+
+The surprising part is not that eunoe remembers more, it is how. Telling
+Claude Code that a transcript exists gets it to 99% too, but it has to grep
+for the answer 23 times a session to do it, which is why it burns four times
+the tokens. eunoe reaches the same 99% with about one lookup every ten
+sessions, because the answer is already in the prompt when the question
+arrives, and it is faster than keeping the whole history even though that
+arm never searches at all. The two eunoe rows differ only in whether the
+exact lines of old output are kept and brought back, which is the part of
+the design explained below.
+
+The method was chosen on a separate development split and frozen before the
+test split ran. The suites, the pre-registered spec, every per-arm table and
+the limits of the study (one developer's repositories, one answering model,
+one run per arm) are in [`bench/`](bench/README.md).
 
 ## Install
 
 ```sh
-bun add -g @chroxify/eunoe   # puts `eunoe` on your PATH
-eunoe install                # background proxy + ANTHROPIC_BASE_URL in ~/.claude/settings.json
+bun add -g @chroxify/eunoe   # puts `eunoe` and the short `ee` on your PATH
+eunoe start                  # sets up the background proxy, routes Claude Code through it
 ```
 
-Then use Claude Code exactly as before. New sessions go through eunoe; restart
-any that are already running. `eunoe uninstall` reverses it.
+Then use Claude Code exactly as before. New sessions go through eunoe, and
+sessions that were already running pick it up when you restart them.
+`eunoe stop` turns it off again.
+
+Requires [Bun](https://bun.sh). On macOS `start` sets up a launchd agent that
+keeps the proxy alive; on other platforms keep `eunoe serve` running however
+you like and everything else works the same.
 
-Requires [Bun](https://bun.sh). `install` sets up a launchd agent on macOS; on
-other platforms, keep `eunoe serve` running however you like (systemd, a
-terminal) and the rest works the same.
+## How it works
 
-## What it does instead
+eunoe does three things, and each one was measured on its own before it was
+kept.
 
-Nothing, until the context is nearly full. Every request up to that point goes
-upstream byte for byte as Claude Code built it.
+### Folding
 
-At the limit, eunoe rewrites the conversation once. Your first message stays.
-Every turn after it collapses to **what you asked and what the agent answered**.
-The turn in progress is kept whole, down to the last tool call.
+A **turn** is one message from you and everything the agent did until your
+next one. Once a turn is finished, most of what it holds is tool output the
+agent needed in the moment and will never read again.
+
+A finished turn, as Claude Code keeps it (about 9,000 tokens):
 
 ```
-WHAT CLAUDE CODE HOLDS (~900k)          WHAT eunoe SENDS
-──────────────────────────────          ────────────────────────────────────────
-turn 1   first message                  turn 1   first message, byte for byte
-         + the agent's work + reply      ┌──────────────────────────────────────┐
-turn 2   prompt, 14 tool calls, reply    │ <context-compacted>                  │
-turn 3   prompt, 6 tool calls, reply     │ Tool calls before this point were    │
-  ⋮                                      │ removed. Earlier turns follow as     │
-turn 38  prompt, 9 tool calls ✋          │ your message + the final reply.      │
-         (you interrupted mid-work)      │ Instructions you gave still apply.   │
-turn 39  prompt, 3 tool calls, reply     │ Exact details → search the           │
-turn 40  prompt, 22 tool calls  ← LIMIT  │ transcript: <how>                    │
-                                         └──────────────────────────────────────┘
-                                        turn 2   your message → final reply
-                                        turn 3   your message → final reply
-                                          ⋮      every turn, ~580 tokens each
-                                        turn 38  your message → [interrupted:
-                                                 last words + its tool calls]
-                                        turn 39  your message → final reply
-                                        turn 40  your message + every tool call
-                                                 and result, exactly as it was
-                                        turn 41+ grows normally until the next cut
+[you]     fix the failing lease test
+
+[agent]   I'll look at the test first.
+  [tool]  Read src/lease.test.ts
+            ... 140 lines of file ...
+  [tool]  Bash bun test
+            ... 80 lines of output ...
+
+[agent]   The expiry check is off by one.
+  [tool]  Edit src/lease.ts
+  [tool]  Bash bun test
+            ... 80 lines of output ...
+
+[agent]   Fixed the off-by-one in renew(): the expiry check used <= instead
+          of <. All 4 tests pass. The 6011 code comes from LEASE_EXPIRED in
+          src/errors.ts.
 ```
 
-**Every turn survives.** A message plus its final reply averages ~580 tokens, so
-a hundred turns is ~60k. There is no reason to throw them away. This is what
-keeps *"what did we do about the Stripe thing"* and *"you told me to deploy it
-yourself"* answerable after a cut.
+The same turn after eunoe folds it (about 700 tokens):
 
-**The first message is kept verbatim.** Claude Code packs `CLAUDE.md`, your git
-status, your identity and the skill list into it. Dropping it drops your
-instructions. Its hash also travels in a billing header, so eunoe never edits it.
+```
+[you]       fix the failing lease test
 
-**The turn in progress is untouched.** The agent is mid-work: it needs the actual
-tool calls, their output and its own thinking blocks to carry on. If you
-interrupted it, the interruption marker is right there too, so it resumes from
-where it stopped rather than starting the turn over.
+[evidence]  Bash bun test
+              FAIL  lease renews after expiry
+              expected 6011, got undefined
+              3 pass, 1 fail
 
-## How it plugs in
+[agent]     Fixed the off-by-one in renew(): the expiry check used <= instead
+            of <. All 4 tests pass. The 6011 code comes from LEASE_EXPIRED in
+            src/errors.ts.
+```
+
+The agent already writes a usable summary of every turn in its final reply,
+so folding keeps that reply, your message and the evidence described below,
+and drops everything else. A hundred folded turns come to about 70k tokens,
+which is why eunoe never has to throw a turn away.
+
+The timing is what makes this cheap. The last 3 turns are always sent whole,
+down to the last tool call, and older turns stay whole too until the detail
+in them passes a budget of 100k tokens. At that point every turn except
+those 3 folds in one step.
 
 ```
- Claude CLI ─┐
- Desktop app ┼──►  eunoe (127.0.0.1:8788)  ──►  api.anthropic.com
- Agent SDK ──┘      rewrites /v1/messages
-                    passes everything else straight through
+turn   1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
+       -----------------------------------------------------------------------
+ t=10  W  W  W  W  W  W  W  W  W  L                           budget not reached
+ t=20  W  W  W  W  W  W  W  W  W  W  W  W  W  W  W  W  W  W  W  L
+ t=21  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  W  W  L   <- fold
+ t=24  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  F  W  W  W  W  W  L
+
+       W whole   F folded   L the live turn
 ```
 
-Claude Code honours `ANTHROPIC_BASE_URL` from its `settings.json`, so every
-harness built on it works with no code changes. Auth headers are forwarded
-untouched — your existing login keeps working, subscription or API key.
+It happens in a step rather than a slide because of the prompt cache. The
+cache is a prefix match, so changing anything in the middle rewrites
+everything after it at 1.25 times the price of a read. Folding one turn per
+message would rewrite the cache on every message, whereas folding a budget
+at a time writes the new prefix once and lets every request until the next
+step read it at a tenth of the price.
 
-Claude Code still keeps the whole conversation in memory and on disk at
-`~/.claude/projects/<project>/<session>.jsonl`. eunoe only changes what goes out
-on the wire. That untouched file is the transcript the agent gets pointed at.
+The first message is always kept verbatim, because Claude Code packs
+`CLAUDE.md`, your git status and your skills into it and its hash travels in
+a billing header. The live turns are untouched too, thinking blocks and
+interruptions included. If a turn was interrupted before the agent replied,
+the fold keeps its last words and the list of what it ran instead.
 
-## Modes
-
-| mode | before the limit | at the limit |
-|---|---|---|
-| **`compact`** (default) | everything, unchanged | the cut, above |
-| **`trim`** | every finished turn is already just your message + the final reply | rarely reached |
-| **`off`** | passthrough | Claude Code's own compaction |
+### Evidence
 
-`trim` is the aggressive option: tool output leaves context the moment a turn
-ends, so a long session never grows past a few tens of thousands of tokens. It
-is noticeably cheaper and, in benchmarks, no less accurate — but the agent has
-to search its transcript more often, so turns start slower.
+Folding on its own would lose the exact values in tool output, like the
+deployment id, the error code or the test count, so when a turn folds each
+command's output is scored line by line and the lines worth keeping are
+quoted verbatim under the command that produced them.
 
-```sh
-eunoe mode compact   # or trim, or off
+```
+score   line
+-----   ------------------------------------------------------------
+  +3    FAIL  lease renews after expiry           error words and codes
+  +3    Deployment ID: dpl_qgthe6u4p7              ids, hashes, URLs
+  +2    3 pass, 1 fail                             test and diff summaries
+  +2    ERR_LEASE_6011: lease expired              error codes
+  +2    took 412 ms                                durations, sizes, versions
+  +1    status: applied                            key: value
+   0    Compiling 14 modules...                    dropped
+   0    > lease@1.4.0 test                         dropped
 ```
 
-Whichever is on owns compaction: eunoe disables Claude Code's auto-compact while
-active and hands it back on `off` or `uninstall`.
+Every command keeps its best lines, and the highest scorers across the turn
+fill a budget of about 4,000 characters, which is a few hundred tokens. The
+cap exists because a long test or build log would otherwise fold to
+something bigger than the turn it came from, and the size was chosen on the
+development split, where it kept 97% of the planted values. Commands whose
+output can simply be run again, such as `Read`, `Grep`, `Glob`, `Edit` and
+`Write`, are skipped entirely.
 
-## What counts as a final reply
+### Recall
 
-A **turn** starts with a message you sent — text or an image, not a tool result —
-and runs until your next one.
+Each time you send a message, before the agent responds, eunoe uses it as a
+search query over every tool output that is no longer in context and
+everything the agent said while working. Matching excerpts are quoted
+exactly and appended to your message, oldest first.
 
-Its **final reply** is the last assistant message of that turn, if the turn ended
-on text with no tool call in it. Only the text is kept; thinking is dropped.
+```
+you     (turn 71)   deploy is failing with ERR_LEASE_6011 again
 
-Across 18,966 real turns:
+        eunoe appends:
 
-| how the turn ended | share | what eunoe keeps |
-|---|---|---|
-| on a text reply | 73% | that reply (median 1.9k chars; 57% name a file path) |
-| still running | 17% | nothing — it's the live turn, never reduced |
-| interrupted or steered | 10% | last words + the list of tool calls |
+        <recalled-context>
+        [turn 12] Bash `bun run deploy:staging`
+            Deployment ID: dpl_qgthe6u4p7
+            ERR_LEASE_6011: lease expired, retrying with --fresh
+        </recalled-context>
+```
 
-Only 1% of finished work turns end in a reply shorter than 120 characters.
-Agents already close turns with something usable; eunoe just stops throwing it
-away.
+Candidates come from BM25, the keyword ranking that search engines use,
+which takes about 6 ms and no model. Optionally [Jev](https://typesafe.ai),
+a small and very fast model, reorders the top 30 in about 300 ms, which
+lifted the right excerpt from 88% to 95% of questions and beat every other
+method and model that was tested. Without a key the BM25 order is used and
+nothing else changes. The recall is computed once per message and pinned to
+it, so it never disturbs the cache.
 
-In `trim` mode the system prompt tells the agent its final reply is the only
-thing it carries forward, and what belongs in it.
+## How it plugs in
 
-## Interruptions and steering
+```
+Claude Code  ------>  eunoe  ------>  api.anthropic.com
+CLI, desktop app,     127.0.0.1:8788
+Agent SDK             rewrites /v1/messages
+                      passes everything else through
+```
 
-Interrupted turns are where naive summarisation loses the most, so they get
-handled explicitly.
+Claude Code honours `ANTHROPIC_BASE_URL` from its `settings.json`, so every
+harness built on it works with no code changes, and because auth headers are
+forwarded untouched your existing login keeps working whether it is a
+subscription or an API key.
 
-| what happened | how eunoe treats it |
-|---|---|
-| **Esc mid-work**, then a new message | The interrupted turn ends there. Your new message, marker included, opens the next turn. |
-| **Typing while the agent works** | Claude Code sends a mid-conversation `system` message. It stays inside the running turn; in a reduced turn it is merged in right before the final reply. |
-| **An interrupted turn gets reduced** | No final reply exists, so eunoe writes one: `[This turn was interrupted before a final reply.] Last thing you said: … Tool calls (12): Edit src/app.ts; Bash \`bun test\`; …` |
-| **The cut lands on an interrupted turn** | Kept verbatim. The agent sees exactly where it stopped. |
-| **Esc-Esc rewind past the cut** | eunoe notices its cut turn is gone from the history and starts over from whatever Claude Code sends. |
+Claude Code still keeps the whole conversation on disk at
+`~/.claude/projects/<project>/<session>.jsonl`, since eunoe only changes
+what goes out on the wire.
 
-## Searching the transcript
+## The transcript
 
-Nothing is lost, so the agent is told where everything is and how to look.
-`search` picks the form:
+Nothing is ever lost, because eunoe keeps a readable copy of the whole
+session and teaches the agent to use it. The session file is rendered into a
+folder of markdown under `~/.eunoe/transcripts/<session>/`, with one file
+per turn and an index.
 
-| `search` | what the agent gets |
-|---|---|
-| `jsonl` | Claude Code's raw session file. Complete, but one long JSON-escaped line per entry. |
-| **`markdown`** (default) | `index.md` — one line per turn, what was asked and how it ended — plus `turn-0001.md`… with the message, every tool call tagged `[tool 3/12]` with its output, and the final reply. |
-| `xml` | The same, as `<turn>` / `<user>` / `<tool n name>` / `<output>` / `<final_reply>`. Easier for the model to parse, slightly harder to grep. |
-| `qmd` | The markdown folder indexed by [qmd](https://github.com/tobi/qmd) for semantic search, for when the agent doesn't know the exact words. |
+```
+index.md        one line per turn: what you asked and how the turn ended
+turn-0001.md    ## User            your message
+turn-0002.md    ### [tool 3/12]    every tool call, with its full output below it
+...             ## Final reply     the agent's reply
+```
 
-Rendering is fast and idempotent — a 199-turn session takes 0.13s — so it just
-runs again as the session grows. qmd's embedding pass takes ~83s and runs in the
-background; queries take 3–20s.
+Markdown is far easier for an agent to grep and read than Claude Code's raw
+JSONL, and the folder is rebuilt as the session grows. The agent is given the
+path and a short recipe for searching it, so when it needs an exact detail
+that neither evidence nor recall surfaced, it can find it in a couple of
+commands instead of guessing. In the benchmark that happened about once
+every ten sessions.
 
 ## Prompt caching
 
-A compaction scheme that breaks the cache costs more than it saves. Cache writes
-are 1.25× the input price and reads are 0.05×, so rewriting a cached prefix is
-25× more expensive than reading it.
-
-eunoe's output is deterministic. The same history always produces the same bytes,
-a reduced turn always reduces identically, and nothing time-based is ever
-inserted. The prefix changes only at a cut.
+Cache writes cost 1.25 times the input price and reads a tenth of it, so a
+context scheme that breaks the cache costs more than it saves. eunoe's
+output is deterministic, which means the same history always produces the
+same bytes, recall is pinned to the message it was computed for and nothing
+time-based is ever inserted, so the prefix only ever changes at a fold.
 
 ```
-turns 1–39   byte-identical to no proxy at all   → cache hits as usual
-turn 40      CUT: one new prefix, written once   → one cache write
-turns 41+    same prefix + new turns appended    → reads hit again
+turns  1-20   byte-identical to no proxy at all   -> cache hits as usual
+turn   21     fold: one new prefix, written once  -> one cache write
+turns  22-58  same prefix, new turns appended     -> reads hit again
+turn   59     next fold
 ```
 
-Measured through the proxy, right after a cut: **180k tokens read from cache,
-1.5k written.** Claude Code's own compaction instead reads the entire ~900k
-context into a summary call and *then* writes a new prefix.
-
-## Edge cases
+Measured through the proxy right after a fold, 180k tokens came from the
+cache and 1.5k were written. Claude Code's own compaction reads the entire
+context into a summary call and then writes a new prefix anyway.
 
-The interesting ones are all about what happens when the cut itself doesn't fit.
+## Modes
 
-| case | behaviour |
+| mode | |
 |---|---|
-| **Where a cut lands** | It aims for 30% of the room available — the window minus the fixed system prompt and tool definitions. Land at 70% and you compact again two turns later. |
-| **The cut doesn't fit** | Shrink in order, stopping as soon as it fits. **1.** Drop reduced turns, oldest first. **2.** Only then clear the *oldest* tool outputs of the live turn, half of what remains per step, shortening oversized inputs too. |
-| **Never removed from the live turn** | Your message, the agent's own text, every tool call, and the **latest 5 tool outputs** — what it is actually working from. |
-| **Compaction loops** | Impossible by construction. A cut only ever moves to a newer turn, every shrink step only removes more, and each step is persisted so the bytes stay cache-stable. |
-| **Nothing left to remove** | Sends anyway and logs `stuck`. |
-| **Context window** | Asked once per model via the Models API (`max_input_tokens`) and cached in `~/.eunoe/models.json`. If the lookup fails the window is unknown and **eunoe does not compact** — it won't cut against a limit it can't verify. |
-| **Images and PDFs** | Counted at ~1.6k tokens each, not at their base64 length. |
-| **Subagents, titles, side calls** | Each conversation is its own thread (session id + a fingerprint of its first turn) with its own cut. |
-| **Mid-conversation system messages** | Never dropped. The API only accepts them directly before an assistant message, so they are merged into that position. |
-| **Thinking blocks** | Kept with their signatures in the live turn, where tool use requires them. Dropped from reduced turns. |
-| **eunoe is down** | Every Claude request fails. launchd keeps it alive; `uninstall` leaves it running as a passthrough so sessions already pointed at it survive, and `stop` removes it once they're restarted. |
-
-## Early results
-
-A full, pre-registered benchmark is in progress and will be published with its
-harness, raw data and every per-point result. Until then, here is what an
-earlier internal run showed, with its limits stated.
-
-**Setup.** 45 cut points across 14 projects, from one developer's real Claude
-Code history: real auto-compactions, plus long sessions cut where they crossed
-350k tokens. At each point, every strategy answered the same 10 questions about
-the session — recent details, what was worked on 5–15 turns earlier, standing
-instructions, decisions, and what was in progress — through a real Claude Code
-session, with read-only access to a transcript that stopped at the cut. Answers
-were judged blind.
-
-| strategy | score | context after the cut | vs native, 95% CI |
-|---|---|---|---|
-| Claude Code's compaction | 84% | 82k | — |
-| **eunoe** | **95%** | 183k | **+11.0%** [+8.1, +13.9] |
-| eunoe, `trim` mode | 95% | 179k | +11.6% [+8.8, +14.4] |
-| eunoe, last 5 turns only | 90% | 164k | +6.4% [+2.4, +10.1] |
-| no compaction at all (ceiling) | 97% | 348k | — (7 points) |
-
-eunoe came within two points of never compacting at all, at about half the
-context. Claude Code's compaction lost most on what was worked on mid-session
-(74%), decisions (77%) and what was in progress (77%).
-
-**What this does not show yet.** The run had no budget-matched baseline — a plain
-sliding window given the same token budget — so it can't separate "eunoe keeps
-the right things" from "eunoe keeps more". It also used one judge, and many of its
-questions were easy enough that every strategy passed them. The full benchmark
-adds that baseline, a second judge, harder questions vetted before scoring, and a
-task-continuation test, and reports whatever it finds.
+| **`default`** | everything above, recommended |
+| **`compact`** | only the compaction is replaced: the context grows as it normally would, and at the limit eunoe folds instead of summarising, so you get the recall but none of the savings along the way |
+| **`off`** | passthrough, Claude Code compacts on its own |
+
+```sh
+eunoe mode           # pick one
+eunoe mode compact   # or name it
+```
+
+Whichever mode is on owns compaction, so eunoe disables Claude Code's
+auto-compact while it is active and hands it back on `off` or `stop`.
 
 ## Usage
 
 ```sh
-eunoe serve              # run in the foreground
-eunoe mode compact       # off | trim | compact
-eunoe status             # config, plus cache stats for recent requests
-eunoe install            # background proxy + Claude Code settings
-eunoe uninstall          # new sessions bypass eunoe; proxy stays up as a passthrough
-eunoe stop               # remove the background proxy
+eunoe start                  # route Claude Code through eunoe (sets up the proxy the first time)
+eunoe stop                   # new sessions bypass eunoe; running ones keep working
+eunoe mode                   # pick default | compact | off
+eunoe settings               # pick a setting and change it
+eunoe settings list          # show them all
+eunoe settings set keep 5    # change one directly
+eunoe status                 # what's running, every session, context and tokens saved
+eunoe uninstall              # stop and remove the background proxy
 ```
 
-`~/.eunoe/config.json`:
-
-```json
-{
-  "mode": "compact",
-  "compactAt": 0.9,
-  "keepTurns": "all",
-  "search": "markdown",
-  "port": 8788,
-  "claudeConfigDirs": []
-}
-```
+`ee` is an alias, so `ee status` and `eunoe status` are the same command.
+
+### Per session
 
-Tools that run Claude Code with their own config directory (one per account,
-say) need eunoe to know about it, both to find their transcripts and to route
-them through the proxy:
+Everything above takes `--session <id>` to apply to one session only. Session
+ids are in Claude Code's `/status`, `eunoe status` lists the ones it has seen
+with their working directory, and a unique prefix is enough.
 
 ```sh
-eunoe install --config-dir ~/.my-tool/claude-account-1
+eunoe start --session 1baada86        # manage only this session, pass the rest through untouched
+eunoe mode compact --session 1baada86
+eunoe settings set keep 5 --session 1baada86
+eunoe settings set keep default --session 1baada86   # back to the shared value
+eunoe stop --session 1baada86
 ```
 
-The directory is remembered in `claudeConfigDirs`.
+Sessions that aren't managed still go through the proxy, so any of them can
+be switched on later without a restart, and every change applies from the
+session's next request.
 
-`compactAt` is a share of the model's real context window. Claude Code compacts
-around 93%, so eunoe goes slightly earlier at 90% to win the race.
+### Settings
 
-Every request is logged to `~/.eunoe/requests.jsonl` with what eunoe did to it
-and the cache read/write that came back.
+| key | default | what it does |
+|---|---|---|
+| `keep` | `3` | turns kept whole at the end |
+| `budget` | `100000` | tokens of older detail that trigger a fold |
+| `compactAt` | `0.9` | share of the context window that triggers the full cut |
+| `keepTurns` | `all` | folded turns kept after a full cut |
+| `search` | `markdown` | transcript form for the agent: `markdown`, `xml`, `jsonl` or `qmd` (semantic, via [qmd](https://github.com/tobi/qmd)) |
+| `rerank` | `jev-preview` | Typesafe model that reorders recall, or `off` |
+
+`~/.eunoe/config.json` holds the same keys plus `port`, `claudeConfigDirs`
+and `sessions`. Tools that run Claude Code from their own config directory
+need eunoe to know about it, which `eunoe start --config-dir <dir>` does
+once and remembers.
+
+### Better recall with Jev
+
+Recall works out of the box, but it gets noticeably better with
+[Jev](https://typesafe.ai) reordering the candidates. To turn that on, put a
+Typesafe API key in `~/.eunoe/typesafe-key` or in the `TYPESAFE_API_KEY`
+environment variable, and `eunoe status` will show the reranker as active.
+It can't slow anything down, because if Jev errors or takes longer than four
+seconds the recall simply uses the plain keyword order instead. To switch it
+off, run `eunoe settings set rerank off`.
+
+### Logs
+
+Every request is written to `~/.eunoe/requests.jsonl` with what eunoe did
+to it and how much of it the API served from cache, which is also where
+`eunoe status` gets its numbers.
 
 ## What it doesn't do
 
-- **It is a proxy, so it is a single point of failure.** If it isn't running, and
-  `ANTHROPIC_BASE_URL` still points at it, every Claude request fails.
-- **It only understands Claude Code's shape** of conversation — first-message
-  system reminders, mid-conversation system messages, interruption markers. Other
-  Anthropic API clients pass through unchanged but get nothing out of it.
-- **It can't recover what Claude Code already compacted.** Turn it on before a
-  long session, not after.
-- **`trim` mode changes how the agent should write.** It's told to put state in
-  its final reply, and it mostly does — but a sloppy final reply costs more in
-  `trim` than in `compact`.
-
-## Prior art
-
-Claude Code's own compaction is the thing being replaced, and the summary format
-it produces is a reasonable piece of prompt engineering — it just runs after the
-conversation is already gone. [qmd](https://github.com/tobi/qmd) does the local
-semantic search for the `qmd` mode.
+- **It is a proxy, which makes it a single point of failure.** If it isn't
+  running while `ANTHROPIC_BASE_URL` still points at it, every Claude request
+  fails. launchd keeps it alive, and `stop` leaves it running so sessions
+  already pointed at it keep working.
+- **It only understands Claude Code's shape of conversation.** Other
+  Anthropic API clients pass through unchanged and get nothing out of it.
+- **It can't recover what Claude Code already compacted,** so turn it on
+  before a long session rather than after.
+- **Recall is keyword search.** Ask about "the deploy that failed" and it
+  finds the deploy output, but ask about "that thing from before" and it
+  finds nothing, leaving the agent to search the transcript itself. Jev
+  narrows this gap without closing it.
+- **It never cuts against a limit it can't verify.** The context window size
+  comes from the Models API for each model, and if that lookup fails the
+  budget folds still happen but the full cut does not.
+
+## Credits
+
+- [qmd](https://github.com/tobi/qmd) by Tobi Lütke provides the local
+  semantic search behind the `qmd` setting.
+- [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) by
+  Typesafe is the system-one model that reranks recall.
 
 ## License
 
-MIT
+eunoe is licensed under the [MIT License](LICENSE), and welcomes
+contributions and suggestions.