Context paging

Opt-in rolling context, modeled on the Pi context-paging extension: the full record lives on disk, the working window stays small, and recovery returns exact text. Page exact content out to the project database before compaction or session end removes it; page it back in by search when a detail from earlier work is needed. Never store paraphrases — recovery must return exact content.

Store

SQLite at <project>/agents/context-paging/context.db (CP_DB overrides); keep /agents/context-paging/ gitignored next to /agents/tmp/. Any script auto-creates the schema. Tables: sessions; messages (captured conversation, foreign key to session; role is the entry type — user, thinking, assistant, tool_call, tool, system for harness reminders, triggered inputs, and task notifications); topics and tags (session-scoped); pages (curated context units, foreign keys to session and topic); page_tags. The subscription registry ${XDG_CONFIG_HOME:-~/.config}/context-paging/projects.json maps project roots to database and script paths; it is the only thing harness hooks check.

Scripts (scripts/, one operation each; env supplies defaults)

CP_SESSION names the current session (else manual); CP_TOPIC and CP_TAGS (comma-separated) supply defaults, so cp_page_out.py "<exact content>" is a complete call. A - content argument reads stdin. Read lookups (cp_search.py, cp_message_list.py, cp_page_in.py listings) default to the past hour, order oldest-first, and open with a compact [filters: …] line stating what was applied; widen with --since 30m|24h|7d|any. Every result line names its role, cp_search.py adds a [matches: …] line counting hits per role (and per page kind), and --role R,R retargets messages to specific roles — search broad first, read the counts, then narrow to the type that matters. Empty windowed results name how many matches lie beyond the window; exact loads (--id N, cp_around.py) are never time-filtered.

Working discipline

1. Page out exact, durable material as it is produced: decisions with rationale, file paths from long investigations, error text, large tool outputs worth keeping. One page per unit; the topic and tags name it for later retrieval.
2. Search returns compact references — ids and excerpts, never full contents — windowed to the past hour by default, with --since widening and --offset paging through further matches. Follow a hit with cp_around.py <message_id> to read it with its neighbors in order (--full for whole contents) or cp_page_in.py --id N for a full page, so minimal data enters the context until detail is needed. Page in when resuming (cp_page_in.py --all) or when a previously known detail is missing after compaction. When you author a compaction statement, follow context-compaction-procedure instead of the harness template.
3. Messages are capture, pages are curation: hooks record the conversation verbatim — user prompts, agent thinking, replies, tool calls and results; record your own summaries and decisions as pages.

Install into a project

1. The skill folder installs with the library (install-dev-skills); scripts/ stays inside it.
2. Add /agents/context-paging/ to the project .gitignore.
3. Insert the harness opt-in section below into the project AGENTS.md.
4. Execute that section now rather than deferring: skip on an existing subscription or recorded decline; otherwise ask whether to install the harness plugin, and on yes complete the harness wiring for your host — references/kimi-hooks.md or references/codex-hooks.md — code the hook dispatcher, register the hook rules, then run cp_subscribe.py last, so subscribed means installed and verified. A no writes the decline variable; any other answer defers to the section's next-session check.
5. Manual use needs no harness wiring; the scripts run directly.

Harness opt-in section (insert verbatim)

Context paging harness opt-in

The context-paging skill keeps this project's exact context recoverable in agents/context-paging/context.db (gitignored). Harness capture is per-project opt-in and only runs for subscribed projects. Once per session, before substantive work, check in order and stop at the first that holds:

1. Already installed and activated: scripts/cp_subscribed.py from the context-paging skill exits 0 for this project. Skip silently.
2. Declined: agents/tmp/context-paging.json contains {"harness_install": "declined"}. Skip silently.
3. Otherwise ask the user: "Install context paging in your harness for this project? It captures the full conversation automatically and keeps paged context recoverable." On yes, install per the skill's harness wiring this session. On no, write {"harness_install": "declined"} to agents/tmp/context-paging.json. Any other answer defers to the next session; ask at most once per session.

Harness wiring

The capture plugin is not shipped; code it at install time so it matches the host's current hook API — references/kimi-hooks.md (kimi code CLI) and references/codex-hooks.md (Codex) are the worked examples. Requirements for any host:

• Gate every invocation on the subscription registry entry for the event's project directory and exit immediately when absent; hooks are user-level in most harnesses, and this gate is what makes them per-project.
• Session start registers the session and runs the due-checked cleanup (this is the periodic cleanup check at the first message of a new session); user messages and tool calls/results insert messages rows live where the host provides event payloads, and after-tool/turn-end events sweep the harness transcript past a stored cursor for agent thinking, replies, and anything the events cannot carry (the cursor makes sweeps idempotent; each row has exactly one source, so nothing duplicates); session end sweeps once more and marks the session ended.
• Capture is fail-open: hook errors log and allow, never block the harness.
• The session-start hook prints a short paging notice (database path, cp_search.py, cp_page_out.py) so fresh sessions know older context is recoverable.