Refresh mutable AGENTS.md guidance and preserve request history

[recallmenot]

AGENTS.md can change outside a conversation while Pi retains cached project instructions or a running subagent retains its launch-time instructions. Earlier work also lacks a reliable association with the guidance that accompanied it. This change refreshes guidance at each agent's next model request and preserves its history for detailed recall.

I use AGENTS.md to preserve the thinking behind a project: background, constraints, architectural choices, and the reasons for approaches that may be unusual. A concern here is the model’s pull toward familiar patterns. An agent can “improve” a deliberate design into something conventional, losing precisely the quality the user wanted to preserve. An unconventional choice may be where much of a project’s value lies. Keeping those choices and their rationale continuously available gives the main agent and its subagents a better basis for respecting that intent.

That intent also evolves as the human learns. Editing AGENTS.md should let me steer ongoing work without repeating each change in chat or remembering which agents need to reread it. Preserving earlier revisions makes those changes understandable: the agent can adapt to today’s direction while still seeing why yesterday’s decisions made sense. A conversation log alone can miss that reasoning when it lived only in automatically supplied guidance.

For a simple example of evolving requirements, a project initially says “Use SQLite,” and the agent implements accordingly. The user later changes the guidance to “Use PostgreSQL.” The next request replaces the full current guidance before memory and recent work, then adds a transition after the relevant work. The notice describes the difference, links the preserved previous version, and explains that earlier SQLite work may reflect earlier instructions. Original-message zoom and paged subagent transcripts expose the exact request's historical guidance without making those annotations summary material.

The two commits separate the stages:

• 26efb04: current guidance updates for main agents and subagents, including tool continuations, idle reports, restarts and context refresh; unchanged text and timestamp-only touches cause no new notices.
• 4ac1a73: content deduplication, durable request associations, historical recall, import/compaction retention, portable archive references and failure handling.

Source identity, ordering and Pi's worktree shadowing are retained. Profile instructions remain last among file sources; a newer revision does not override explicit user instructions. Notices remain at their work boundary, or are explicitly labeled as historical after that boundary leaves the visible context. Current guidance, archive contents and routine bookkeeping stay outside the summary tree. Recall annotations are projected from tool-result metadata, so canonical tool text and Pi compaction do not recycle them into summaries.

Storage and failure behavior are documented in docs/storage.md: original basenames and modification metadata are retained, identical contents share hard-linked objects, archive paths survive profile moves, and no automatic pruning occurs. The profile filesystem must support hard links. Missing sources are removed; read errors, invalid UTF-8, guidance over 1 MB and preservation failures stop the request. Request records establish what was prepared for injection, not that the provider accepted or obeyed it. Older work has no invented association. SDK hosts can supply their resource-loader directory/discovery policy explicitly.

Validation:

• GitHub Actions passed on Linux and Windows for 4ac1a73.
• npm run check
• npm test: 312 passed, 1 platform-specific skip, no failures
• npm pack --dry-run
• Real SDK lifecycle tests covering main/subagent updates, report wake, resume, actual Pi subagent compaction, memory refresh, source deletion, profile relocation, import rebuild, request/archive failures, and Windows-length checkpoint paths.
• Actual Anthropic, OpenAI Responses and Chat Completions adapter payload inspection verifies placement, stable unchanged prefixes and transition position.
• OPTCHAT_GUIDANCE_MODEL=gpt-6.1-sol npm run test:guidance:live: real OpenAI subscription requests with synthetic guidance. The model answered “SQLite” before the edit and “PostgreSQL; no” afterward, where “no” answers whether earlier SQLite work necessarily violated instructions.

Live request	Uncached input tokens	Cache-read tokens
Initial	8,160	0
Unchanged guidance	260	7,936
SQLite → PostgreSQL edit	8,534	0
Unchanged after edit	266	8,320

These are observations from one run, not guaranteed cache savings. The live test is opt-in and uses no private project context.