rote

<div align="center"><pre> ____ _ | _ \ ___ | |_ ___ | |_) / _ \ | __/ _ \ | _ < (_) || || __/ |_| \_\___/ \__\___| </pre> **The memory manager for browser agents.** Every harness has memory. None of them manages it. </div> --- ## The one-liner > **Agent harnesses have no memory manager. Rote is the memory manager.** Browser agents forget at three timescales, and pay again at every one. Rote treats the context window as a managed resource: a budget, an eviction policy, a layout contract, and a trust gate on the way back in. ## The problem A typical browser agent loop is expensive and serialized: ```text observe page → model thinks → act → wait → observe again ``` And it re-sends its whole transcript every step. A run of *n* steps sends `1 + 2 + … + n` prompt-units, so **cost is O(n²) in task length**. Measured on our own runs, input tokens climb every step: ``` B2 (10 steps): 637 → 677 → 716 → 759 → 800 → 839 → 876 → 917 → 953 (+38%) ``` **21% of that run's input bill is re-reading text it already sent** — on a page that distills to 10 nodes. Everything the field competes on (DOM serializers, element filtering, vision-vs-a11y) shrinks the *per-step* prompt. That lowers the constant. Nobody has touched the exponent.  ### The three amnesias | Tier | Scope | What it forgets | The bill | |---|---|---|---| | **0 — Working** | within a run | what it already sent this run | O(n²) in task length | | **1 — Episodic** | across runs of a task | the procedure that worked yesterday | run #50 costs what run #1 cost | | **2 — Semantic** | across tasks on a site | how the site behaves at all | every task re-learns the portal | And the precondition: **memory that might be wrong is worse than no memory.** Every tier is assertion-gated on the way back in — success is decided by page state, never by the absence of an exception. ## What Rote does Rote is a complete browser-agent harness with four efficiency planes (see [docs/02](docs/02-architecture.md)): 1. **Perception** — capture pages through CDP, distill them into compact interactive trees, assign stable element IDs, and send diffs instead of full page dumps when possible. 2. **Decision** — own the context layout, route routine steps to cheaper models, and skip model calls entirely when memory/replay can safely act. 3. **Action** — use typed browser actions, settledness detection, self-healing element resolution, per-step assertions, and later speculative pre-execution. 4. **Learning** — record every run, learn playbooks/site memory/transition models, and feed that knowledge back into replay, hints, resolution, and prediction. The first launch target is intentionally narrow and measurable: ```text same browser tasks as Browser Use → fewer tokens → success parity → raw benchmark data ```  ## Design invariants 1. **Never silently wrong** — every replayed step is assertion-gated; a final verify block must pass or the run escalates the repair ladder. 2. **Never worse than baseline** — full-agent fallback always exists. A Rote miss costs one cheap match call. 3. **Never cross environments** — a structural fingerprint (tool inventory, target-system identity) is a hard gate. A playbook learned on staging can't fire on prod. 4. **Everything versioned** — playbooks and repair patches are append-only, auditable, diffable, and exportable as human-readable YAML. ## Why "Rote" *Rote*: doing something from memory, by repetition, without re-deriving it. For browser agents, that means the harness remembers how sites behave — observations, stable elements, procedures, and verification signals — so the next run starts warmer. ## Status **Early build — no launch number yet, and the curve above is not yet drawn against anyone.** Built and working end to end: core schemas + Expect DSL, lossless recorder, verified replay executor, CDP browser backend, perception (distill → stable IDs → budget), **observation eviction**, the agent loop, tagged LLM accounting, and the benchmark + head-to-head gate. First live run against a real browser and model ([T1](docs/testing/T1-openai-dry-run.md)) completed B1 in the minimum four actions; B2 now passes 11/11 after [#49](https://github.com/kedarvartak/rote/issues/49). We are in **P1 = tier 0, working memory**. Its four levers, honestly: | Lever | State | |---|---| | Observation eviction — keep what you did, not what you saw | **built** (and never claimed until now) | | Diff observations | **built, CI-exercised** — grounded 10K-token bootstrap → diff works; real-page savings remain unmeasured (#67) | | Cache layout | **not built.** The docs marked it built; no `cache_control` is ever sent, and the accounting cannot see a cache hit ([#57](https://github.com/kedarvartak/rote/issues/57)) | | History compaction | not built — the lever that would make the curve linear rather than a smaller quadratic | Not built: the playbook distiller (V1 replays hand-written playbooks), the matcher, site memory, model routing, speculation. **Tier 1 is table stakes and we are late to it** — Skyvern ships record → codegen → zero-LLM replay → fallback today ([docs/04](docs/04-competition.md)). `docs/02-architecture.md` §Status is authoritative. **No number, no launch.** Two gates, neither run: the **curve** (cumulative tokens vs. task length, on the provider's own cache accounting) and the **level** (tokens-per-task at success parity). Until then this is a hypothesis with good arithmetic.  Solid packages exist today; dashed packages are the target composition described in [docs/02 — Architecture](docs/02-architecture.md). ## Docs | Doc | Contents | |---|---| | [01 — Problem](docs/01-problem.md) | Why agents re-derive everything; the reuse-path gap; where Rote fits and where it doesn't | | [02 — Architecture](docs/02-architecture.md) | **What is built vs designed**; the four planes; control loop; playbooks; repair ladder; memory; speculation; invariants | | [03 — Benchmark](docs/03-benchmark.md) | Task suite, metrics, fairness rules, the variance rule, the launch gate, generalization | | [04 — Competition](docs/04-competition.md) | The field, per-competitor teardown, capability matrix, steelmanned objections | | [05 — Roadmap](docs/05-roadmap.md) | Where we are; V1 scope and gates; P0–P5; open questions | | [06 — Optimizations](docs/06-optimizations.md) | The master catalog: every optimization, tier, status, evidence | | [07 — Execution plan](docs/07-execution-plan.md) | The work breakdown: epics, tasks, dependencies, acceptance criteria, RAID | | [testing/](docs/testing/) | Records of tests against real Rote — live browser, live model, live key | ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev workflow and PR conventions, and [CLAUDE.md](CLAUDE.md) for the full engineering ruleset. Please also read our [Code of Conduct](CODE_OF_CONDUCT.md). Found a security issue? See [SECURITY.md](SECURITY.md) — please don't file it as a public issue. ## License MIT — see [LICENSE](LICENSE).