Skip to content

PEEK: Orientation Cache for Recurring-Context Agents

A constant-sized prompt artifact caching orientation knowledge — what a recurring context holds and how it is organized. Pays off only on stable, re-entered contexts.

When this pattern applies

PEEK is conditional. The cache wins over per-session orientation (grep, file tree, token-fitted repo maps) only when three conditions hold:

  • The same large context is re-entered repeatedly — a long-lived repo, a corpus the agent revisits, a knowledge base touched across sessions. One-shot use does not amortize the cache.
  • The context is stable enough to outpace drift — entities, constants, and schemas change slower than the agent re-enters. Fast-moving migrations invalidate entries before they pay back. (Atlan, 2026)
  • An invalidation surface exists — a hook, watcher, lint, or test fails when the cache disagrees with the source of truth. Without one, drift accumulates silently as plausible-but-wrong claims. (Tacnode, 2026)

Without all three, fall through to per-session orientation: a tree-sitter repo map for code, or just-in-time corpus retrieval.

What PEEK is not

Pattern Stores Lifecycle
PEEK orientation cache What is in the context, how it is organized, useful entities/constants/schemas Persisted; updated each re-entry under a fixed token budget
Evolving Playbooks (ACE) Strategies — how the agent worked successfully Persisted; grows via incremental delta entries
Repository Map Pattern Top-ranked AST symbols of a code repository Rebuilt per session, fitted to a token budget
AOCI Symbolic-plus-semantic blueprint Built once offline, read whole before each task
Seeding Agent Context Static breadcrumbs (AGENTS.md, comments) Edited by humans, discovered by the agent

The closest neighbor is Evolving Playbooks (ACE), which PEEK was evaluated against. ACE preserves trajectories and strategies — what worked. PEEK preserves orientation knowledge of the context — what is there. (Gu et al., 2026)

The three-stage cache

PEEK frames the orientation artifact as a cache with a fixed token budget and three components. (Gu et al., 2026)

graph LR
    A[Inference-time signals<br>tool calls, retrievals, outcomes] -->|Distiller| B[Transferable knowledge<br>entities, constants, schemas, layout]
    B -->|Cartographer| C[Structured edits to context map]
    C --> D[Context map<br>fixed token budget]
    D -->|Evictor| D
    D -->|read on re-entry| E[Next session]

    style D fill:#2c3e50,color:#fff
  • Distiller — extracts transferable orientation knowledge from inference-time signals (directories entered, symbols used, schemas looked up).
  • Cartographer — converts that knowledge into structured deltas on the context map, not rewrites, so prior knowledge survives each update.
  • Evictor — when the map approaches its fixed token budget, removes entries by priority so the artifact stays constant-sized.

The fixed token budget is load-bearing — without the evictor the cache grows monotonically and re-introduces the lost-in-the-middle problem it was meant to avoid.

Why it works

Re-entry into the same large context is the dominant cost driver for recurring agent workloads — each session otherwise re-pays for discovery. A constant-sized artifact amortizes that discovery across sessions, and the fixed token budget stops it from crowding out task-specific context. PEEK cuts cost for repeated re-entry by skipping re-discovery. It does not improve reasoning, and it does not replace retrieval or tool design.

In the PEEK paper's evaluation, the cache improved long-context reasoning and information-aggregation tasks by 6.3–34.0% and in-context learning by 6.0–14.0%, against ACE — the strongest prior framework for evolving prompts. It also cut iterations by 93–145 and cost by 1.7–5.8×, and results held across models and architectures, including OpenAI Codex. These numbers come from one team's evaluation and are not yet independently replicated; treat them as a directional signal. (Gu et al., 2026)

When this backfires

  • Fast-changing context — codebases under heavy refactor, schemas in active migration, corpora that update daily. The cache drifts faster than it pays for itself and the agent acts on stale claims. Context drift is reported as the top failure mode of standing context files. (Atlan, 2026, Tacnode, 2026)
  • Small or single-session contexts — a one-shot script, a small repo, a corpus touched once. Cache construction and maintenance cost exceeds the savings. (Wojtyna, 2026)
  • No invalidation surface — nothing fails when the cache disagrees with the source of truth, so it becomes a confident-sounding source of falsehood. (Atlan, 2026)
  • High-stakes claims without cross-check — a stale entry the agent trusts about a constant or schema can produce silently incorrect behavior in security, finance, or compliance code.
  • Single-source benchmark — the strong numbers come from one paper; adopting on those alone extrapolates from one team's setup. (Gu et al., 2026)

Where any of these holds, prefer per-session orientation: a token-fitted repo map, agentic search, or seeded breadcrumbs the agent rediscovers each session.

Example

A practitioner analogue exists in repos that maintain a small, agent-authored orientation file alongside the human-authored AGENTS.md — the human file declares conventions, the agent file caches what successive sessions have learned about the codebase. Reported variants include dedicated agents/ meta-repos that amortize re-exploration across multi-repo workloads. (Augment Code, 2026)

A simplified entry the Cartographer might add after touching the authentication module:

# Orientation cache entry — written by the Cartographer, read every session
domain: auth
entry_points:
  - src/auth/auth_service.py: AuthService.authenticate
  - src/auth/middleware.py: AuthMiddleware.__call__
useful_constants:
  - SESSION_TTL_S = 900    # src/config/auth.py
  - REFRESH_WINDOW_S = 300 # src/config/auth.py
schema_notes:
  - "Sessions live server-side; tokens are opaque references, not JWT claims"
  - "Rate-limit middleware sits before AuthService.authenticate on every path"
last_verified: "session-014"

Every session without the cache re-discovers the entry points, re-reads the config for the constants, and re-deduces the session model. The cache carries that orientation forward for the cost of a handful of tokens, provided a session-end hook fails when last_verified lags behind git log -- src/auth/.

Key Takeaways

  • Choose among orientation patterns by what you need stored: PEEK for orientation knowledge of the context, Evolving Playbooks for trajectories, a Repository Map Pattern for per-session symbol maps.
  • The cache pays off only under three conditions together: repeated re-entry, stable-enough context, and a working invalidation surface.
  • Check for an eviction step before trusting a "PEEK-style" cache: a Distiller/Cartographer pair with no Evictor will grow past its token budget and reintroduce the lost-in-the-middle problem it was meant to avoid.
  • Reported gains versus ACE are substantial (6.3–34.0% with 1.7–5.8× lower cost) but single-source; treat as a directional signal.
  • If any condition fails, skip the cache and default to per-session orientation — a repo map, agentic search, or seeded breadcrumbs — rather than building one anyway.
Emerging — single recent source Last reviewed: 2026-06-02