the local agent must read an existing AGENTS.md and add it to the starting prompt of a session #29

New Issue

hugo · 2026-07-26T08:16:36Z

hugo commented

2026-07-26 08:16:36 +00:00

Goal

When the first user message starts a new local-agent session, include the selected project root AGENTS.md in the agent system prompt and reuse a cached KV bootstrap for the deterministic prompt prefix.

Required behavior

Creating or selecting a draft session does no prompt construction, tokenization, prefill, or KV-cache work.
On the first non-empty user submission, read AGENTS.md from the selected project root when it exists and include its contents in the system prompt before the user message.
A missing AGENTS.md is not an error.
The system prompt, AGENTS.md, and other injected system context are part of model context and KV state, but are not treated as user-visible chat turns.
First-title generation uses the actual first user message only. System instructions and injected context must not affect the title input.

KV bootstrap

Cache only the deterministic prefix shared by new sessions with the same effective configuration. This includes the rendered agent/tool prompt, configured system instructions, optional A2UI system instructions, AGENTS.md, model, and reasoning mode.

Session-specific data such as the current date/time, A2UI client metadata, and the user message remains in the uncached suffix.

On the first user submission:

Build the effective deterministic prefix.
Look for a compatible content-addressed bootstrap checkpoint using the existing KV-store and checkpoint compatibility rules.
On a hit, restore it and prefill only the remaining session-specific suffix.
On a miss, prefill the deterministic prefix once, store that checkpoint through the existing cache budget and eviction policy, then continue with the suffix.

Prompt identity is the invalidation mechanism. Any change to tools, configured system instructions, A2UI instructions, AGENTS.md, model, reasoning mode, tokenizer/rendering identity, context, or checkpoint-compatible execution settings must prevent stale reuse. Loading an invalid checkpoint falls back to rebuilding it.

Do not add a separate persisted component hash, file watcher, eager regeneration job, copy-on-write Metal buffers, or a new KV-slice ownership abstraction. The existing content-addressed key and checkpoint header provide invalidation and compatibility.

DS4 reference

The native ds4-agent uses a sysprompt.kv bootstrap checkpoint, verifies the exact rendered system-prompt text and model compatibility, and rebuilds the checkpoint on mismatch. DS4Server should preserve that behavior while reusing its existing prefix-aware KV store.

Acceptance criteria

Creating a new session produces no model or KV activity until a user submits text.
With AGENTS.md present, its exact contents reach the model as system context on the first turn.
Without AGENTS.md, the first turn works normally.
Title generation receives only the first user message.
A second new session with an unchanged deterministic prefix reports cached-prefix reuse.
Editing AGENTS.md or another deterministic component causes a cache miss and rebuild.
Dynamic session context does not invalidate the deterministic bootstrap.
Incompatible model or execution configuration never reuses the checkpoint.

## Goal When the first user message starts a new local-agent session, include the selected project root AGENTS.md in the agent system prompt and reuse a cached KV bootstrap for the deterministic prompt prefix. ## Required behavior - Creating or selecting a draft session does no prompt construction, tokenization, prefill, or KV-cache work. - On the first non-empty user submission, read AGENTS.md from the selected project root when it exists and include its contents in the system prompt before the user message. - A missing AGENTS.md is not an error. - The system prompt, AGENTS.md, and other injected system context are part of model context and KV state, but are not treated as user-visible chat turns. - First-title generation uses the actual first user message only. System instructions and injected context must not affect the title input. ## KV bootstrap Cache only the deterministic prefix shared by new sessions with the same effective configuration. This includes the rendered agent/tool prompt, configured system instructions, optional A2UI system instructions, AGENTS.md, model, and reasoning mode. Session-specific data such as the current date/time, A2UI client metadata, and the user message remains in the uncached suffix. On the first user submission: 1. Build the effective deterministic prefix. 2. Look for a compatible content-addressed bootstrap checkpoint using the existing KV-store and checkpoint compatibility rules. 3. On a hit, restore it and prefill only the remaining session-specific suffix. 4. On a miss, prefill the deterministic prefix once, store that checkpoint through the existing cache budget and eviction policy, then continue with the suffix. Prompt identity is the invalidation mechanism. Any change to tools, configured system instructions, A2UI instructions, AGENTS.md, model, reasoning mode, tokenizer/rendering identity, context, or checkpoint-compatible execution settings must prevent stale reuse. Loading an invalid checkpoint falls back to rebuilding it. Do not add a separate persisted component hash, file watcher, eager regeneration job, copy-on-write Metal buffers, or a new KV-slice ownership abstraction. The existing content-addressed key and checkpoint header provide invalidation and compatibility. ## DS4 reference The native ds4-agent uses a sysprompt.kv bootstrap checkpoint, verifies the exact rendered system-prompt text and model compatibility, and rebuilds the checkpoint on mismatch. DS4Server should preserve that behavior while reusing its existing prefix-aware KV store. ## Acceptance criteria - Creating a new session produces no model or KV activity until a user submits text. - With AGENTS.md present, its exact contents reach the model as system context on the first turn. - Without AGENTS.md, the first turn works normally. - Title generation receives only the first user message. - A second new session with an unchanged deterministic prefix reports cached-prefix reuse. - Editing AGENTS.md or another deterministic component causes a cache miss and rebuild. - Dynamic session context does not invalidate the deterministic bootstrap. - Incompatible model or execution configuration never reuses the checkpoint.

hugo added the enhancement label 2026-07-26 08:16:36 +00:00

hugo added the critical label 2026-07-26 08:33:55 +00:00

hugo commented

2026-07-27 16:37:07 +00:00

Implemented in 4adb49a. All required commit gates pass.

Implemented in 4adb49a. All required commit gates pass.

hugo closed this issue

2026-07-27 16:37:12 +00:00

hugo referenced this issue

2026-08-29 17:56:05 +00:00

Add DeepSeek-style hierarchical AGENTS.md instruction lifecycle #74

Sign in to join this conversation.