# ADR-0020: Clipboard — Multi-Slot Session Scratchpad

**Status:** Accepted
**Date:** 2026-05-16
**Extension:** `extensions/clipboard/` (store.ts ~120 lines, index.ts ~160 lines)

## Problem

LLM agents re-derive the same values repeatedly within a session: shell commands,
file paths, build invocations, grep pipelines, computed expressions. This wastes
tokens and introduces drift (subtle variations between re-derivations). The root
cause is that the agent has no explicit scratchpad — every tool call is effectively
stateless with respect to previously computed artifacts.

## Evidence

Two recent studies confirm scratchpad access as the primary fix:

**WMF-AM** (Hou et al., arXiv:2603.27343, NeurIPS 2026). Evaluated 28 models
(21 open-weight 0.5B–70B, 7 closed-source API) on cumulative state tracking.
Without scratchpad, models degrade sharply under cumulative load (τ = 0.595
WMF-AM ↔ agent performance, p < 0.001). Permitting chain-of-thought (i.e.
scratchpad) raises 20/28 models to ≥ 0.90 accuracy — "the no-scratchpad
constraint is the primary source of difficulty." Load-shift ablation showed
mean Δ = 0.30 when history was removed, confirming intermediate-state access
is the bottleneck.

**VLA Scratchpad** (Haresh et al., arXiv:2602.21013). Cleanest A/B test:
stateless transformer VLA vs. same model + language scratchpad on 5
memory-dependent manipulation tasks. Results: **+48.8% average task success**
(per-task: +68% touch-reset-pick, +72% swap, +68% place-next-to-restore,
+30% stack-and-topple). Recurrent models also improved +11%. Real-world
pick-place-restore: 0% → 65% success. The scratchpad stores grounding
(positions), plan (subtasks), and progress — directly analogous to our
key→value store for commands, paths, and expressions.

## Decision

Two tools: `clipboard_write(key, value)` and `clipboard_read(key)`.

- **Key→value store** — named slots for different types of cached artifacts
- **Session-scoped, in-memory** — matches the stateless-vs-scratchpad paradigm
- **State reconstructed from session history** — survives compaction and branching
  (same pattern as `todo` extension)
- **Proactive-write prompting** — tool descriptions instruct the agent to write
  values on first derivation, read on subsequent use

## Alternatives

| Approach               | Why Rejected                                                |
| ---------------------- | ----------------------------------------------------------- |
| Single-slot clipboard  | Too restrictive — agent needs multiple concurrent values    |
| File-based persistence | Overkill — values are session-scoped and ephemeral          |
| Implicit (no tool)     | Agent has no mechanism to explicitly cache derived values   |
| In context window only | Lost after compaction; no explicit "store and retrieve" API |

## Trade-offs

- Two tools instead of one (write/read split) — keeps each tool's schema simple
  and the descriptions focused on behavioral prompting
- Session-scoped only — new session = clean slate. This is intentional: cached
  values (build commands, paths) are likely stale across sessions
- O(n) reconstruction on session_start — n is small (< 100 clipboard ops in practice)

## References

- Hou et al. (2026). "Beyond Completion: Probing Cumulative State Tracking to Predict
  LLM Agent Performance." arXiv:2603.27343.
- Haresh et al. (2026). "Notes-to-Self: Scratchpad Augmented VLAs for Memory Dependent
  Manipulation Tasks." arXiv:2602.21013.
- Nye et al. (2021). "Show Your Work: Scratchpads for Intermediate Computation with
  Language Models." arXiv:2112.00114.
