fix: move context files after cache boundary to prevent invalidation by daniel-rudaev · Pull Request #61422 · openclaw/openclaw

daniel-rudaev · 2026-04-05T16:16:57Z

Summary

Context files (MEMORY.md, SOUL.md, USER.md, etc.) are currently rendered in the stable prefix before SYSTEM_PROMPT_CACHE_BOUNDARY. When memory plugins write between turns, the prefix changes and Anthropic's prompt cache is invalidated — resulting in ~0% cache hit rate for anyone using workspace files that change between turns.

This PR moves the # Project Context section to after the cache boundary, keeping the stable prefix (system prompt, identity, tools, skills, silent replies) constant across turns.

Dynamic context files were already placed after the boundary and are unaffected.
No logic changes — pure block move.

Impact

Measured on a production instance using memory-core plugin with frequent MEMORY.md writes:

Before: 0% cache hit rate (every turn invalidated the prefix)
After: cache reads observed (cache_read_input_tokens > 0 starting from turn 2)

This affects anyone using workspace files that are modified between turns (memory plugins, auto-updated context files, etc.).

Test plan

Verify prompt ordering: stable prefix → cache boundary → context files → dynamic context → extra system prompt
Verify cache_read_input_tokens > 0 on consecutive turns with Anthropic provider
Verify no regression in context file rendering (files still appear in system prompt)

* plugins: include resolved workspaceDir in provider hook cache keys resolveProviderPluginsForHooks, resolveProviderPluginsForCatalogHooks, and resolveProviderRuntimePlugin used the raw params.workspaceDir for cache keys and plugin-id discovery while resolvePluginProviders already fell back to the active registry workspace. Resolve workspaceDir once at the top of each function so cache keys, candidate filtering, and loading all use the same workspace root. * fix(plugins): inherit runtime workspace for snapshot loads * test(gateway): stub runtime registry seam * fix(plugins): restore workspace fallback after rebase --------- Co-authored-by: Vincent Koc <[email protected]>

@imechZhangLY

…8943) (thanks @imechZhangLY) * fix(infra): windows-task-restart fallback to startup entry when schtasks task is unregistered * fix code style problem * use /min for startup fallback and assert schtasks pre-check in test * fix: windows restart fallback when scheduled task is unregistered (#58943) (thanks @imechZhangLY) --------- Co-authored-by: Luyao Zhang <[email protected]> Co-authored-by: Ayaan Zaidi <[email protected]>

Co-authored-by: Vincent Koc <[email protected]>

…fahmedjoy

…fahmedjoy) * fix: implement Windows stale gateway process cleanup before restart findGatewayPidsOnPortSync() returned [] immediately on Windows, causing cleanStaleGatewayProcessesSync() to skip killing old gateway processes during self-restart (triggerOpenClawRestart -> schtasks path). This led to an infinite retry loop: 'gateway already running under schtasks; waiting 5000ms before retrying startup'. Changes: - Extract Windows port/process helpers into shared windows-port-pids.ts to break the circular import between restart-stale-pids.ts and gateway-processes.ts, with configurable timeoutMs for poll compliance - findGatewayPidsOnPortSync: discover + verify Windows gateway PIDs via readWindowsListeningPidsOnPortSync + readWindowsProcessArgsSync - pollPortOnceWindows: use short POLL_SPAWN_TIMEOUT_MS (400ms) so a single slow PowerShell call cannot exceed the 2s polling budget - terminateStaleProcessesSync: add terminateStaleProcessesWindows using taskkill.exe (graceful /T first, then /F force-kill) Fixes the Windows gateway restart infinite loop caused by the schtasks supervisor detecting a port conflict it cannot resolve. * fix: tighten windows stale gateway cleanup * fix: preserve windows restart probe failures * refactor: unify windows gateway pid verification * fix: preserve windows argv probe failures * fix: windows self-restart stale gateway cleanup (#60480) (thanks @arifahmedjoy) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

@ngutman

* fix(memory): avoid recursive provider discovery during register * test(memory): remove resetModules from provider adapter regression * fix: avoid recursive provider discovery during register (#61402) (thanks @ngutman)

Context files (MEMORY.md, SOUL.md, USER.md, etc.) were rendered in the stable prefix before SYSTEM_PROMPT_CACHE_BOUNDARY. When memory plugins write between turns, the prefix changes and Anthropic's prompt cache is invalidated — resulting in 0% cache hit rate. Move the "# Project Context" section to after the cache boundary so that the stable prefix (system prompt, identity, tools, skills) remains constant across turns. Dynamic context files were already after the boundary and are unaffected. Measured impact: 0% → cache hits observed after the fix on a production instance using memory-core plugin with frequent MEMORY.md writes.

greptile-apps · 2026-04-05T16:20:54Z

Greptile Summary

Moves the # Project Context block (MEMORY.md, SOUL.md, AGENTS.md, etc.) to after SYSTEM_PROMPT_CACHE_BOUNDARY so that memory-plugin writes between turns no longer invalidate the stable cached prefix. The implementation in src/agents/system-prompt.ts is correct, but the test at line 686 of src/agents/system-prompt.test.ts was not updated: line 710 asserts expect(boundaryIndex).toBeGreaterThan(memoryIndex), which describes the old ordering and will fail in CI with the new code.

Confidence Score: 4/5

Safe to merge after fixing the stale test assertion that directly contradicts the new ordering.

The implementation correctly addresses the cache invalidation problem described in the PR. One P1 test assertion on line 710 inverts the expected index relationship and will cause a CI failure.

src/agents/system-prompt.test.ts — the test at line 686 needs its assertion on line 710 and its name updated to match the new post-boundary ordering.

Comments Outside Diff (2)

src/agents/system-prompt.test.ts, line 686-716 (link)

Stale test assertion contradicts new ordering

Line 710 asserts expect(boundaryIndex).toBeGreaterThan(memoryIndex) — the boundary comes after MEMORY.md (old behavior). After this PR, all stable context files are placed after the boundary, so memoryIndex > boundaryIndex. This assertion will fail in CI. The test name also describes the old behavior ("orders stable project context before the cache boundary").

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agents/system-prompt.test.ts
Line: 686-716

Comment:
**Stale test assertion contradicts new ordering**

Line 710 asserts `expect(boundaryIndex).toBeGreaterThan(memoryIndex)` — the boundary comes after MEMORY.md (old behavior). After this PR, all stable context files are placed after the boundary, so `memoryIndex > boundaryIndex`. This assertion will fail in CI. The test name also describes the old behavior ("orders stable project context **before** the cache boundary").



How can I resolve this? If you propose a fix, please make it concise.

src/agents/system-prompt.ts, line 711-713 (link)

Stale comment contradicts new behavior

This comment says "Keep large stable prompt context above this seam", but the code immediately below now places stable context files (SOUL.md, AGENTS.md, etc.) after the seam. Update it to describe the new intent.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agents/system-prompt.ts
Line: 711-713

Comment:
**Stale comment contradicts new behavior**

This comment says "Keep large stable prompt context above this seam", but the code immediately below now places stable context files (SOUL.md, AGENTS.md, etc.) after the seam. Update it to describe the new intent.



How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/agents/system-prompt.test.ts
Line: 686-716

Comment:
**Stale test assertion contradicts new ordering**

Line 710 asserts `expect(boundaryIndex).toBeGreaterThan(memoryIndex)` — the boundary comes after MEMORY.md (old behavior). After this PR, all stable context files are placed after the boundary, so `memoryIndex > boundaryIndex`. This assertion will fail in CI. The test name also describes the old behavior ("orders stable project context **before** the cache boundary").

```suggestion
  it("places all context files after the cache boundary, preserving stable-file sort order", () => {
    const prompt = buildAgentSystemPrompt({
      workspaceDir: "/tmp/openclaw",
      contextFiles: [
        { path: "HEARTBEAT.md", content: "Check inbox." },
        { path: "MEMORY.md", content: "Long-term notes." },
        { path: "AGENTS.md", content: "Follow repo rules." },
        { path: "SOUL.md", content: "Warm but direct." },
        { path: "TOOLS.md", content: "Prefer rg." },
      ],
    });

    const agentsIndex = prompt.indexOf("## AGENTS.md");
    const soulIndex = prompt.indexOf("## SOUL.md");
    const toolsIndex = prompt.indexOf("## TOOLS.md");
    const memoryIndex = prompt.indexOf("## MEMORY.md");
    const boundaryIndex = prompt.indexOf(SYSTEM_PROMPT_CACHE_BOUNDARY);
    const heartbeatHeadingIndex = prompt.indexOf("# Dynamic Project Context");
    const heartbeatFileIndex = prompt.indexOf("## HEARTBEAT.md");

    expect(agentsIndex).toBeGreaterThan(-1);
    // All stable context files appear after the cache boundary
    expect(agentsIndex).toBeGreaterThan(boundaryIndex);
    // Stable files maintain their defined sort order
    expect(soulIndex).toBeGreaterThan(agentsIndex);
    expect(toolsIndex).toBeGreaterThan(soulIndex);
    expect(memoryIndex).toBeGreaterThan(toolsIndex);
    // Dynamic context follows stable context
    expect(heartbeatHeadingIndex).toBeGreaterThan(boundaryIndex);
    expect(heartbeatFileIndex).toBeGreaterThan(heartbeatHeadingIndex);
    expect(prompt).toContain(
      "The following frequently-changing project context files are kept below the cache boundary when possible:",
    );
  });
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/agents/system-prompt.ts
Line: 711-713

Comment:
**Stale comment contradicts new behavior**

This comment says "Keep large stable prompt context above this seam", but the code immediately below now places stable context files (SOUL.md, AGENTS.md, etc.) after the seam. Update it to describe the new intent.

```suggestion
  // Core instruction sections (identity, tooling, safety, workspace) live above this seam
  // so Anthropic-family transports can reuse them across turns. All context files —
  // including stable ones like AGENTS.md/SOUL.md — live below so memory writes between
  // turns do not invalidate the cached prefix.
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "fix: move context files after cache boun..." | Re-trigger Greptile}

clawsweeper · 2026-05-01T04:27:10Z

Codex review: needs changes before merge.

Summary
The PR moves Project Context rendering in buildAgentSystemPrompt from before to after SYSTEM_PROMPT_CACHE_BOUNDARY.

Reproducibility: yes. A high-confidence static reproduction exists by building a prompt with a changing MEMORY.md, checking its position relative to SYSTEM_PROMPT_CACHE_BOUNDARY, and comparing that with Anthropic payload shaping that cache-controls only the prefix.

Next step before merge
A narrow replacement PR can preserve the cache-invalidation goal while keeping stable workspace context cacheable and updating the required guards.

Security
Cleared: The PR only reorders prompt assembly text and does not change dependencies, workflows, permissions, secrets handling, downloads, or execution surfaces.

Review findings

[P2] Keep stable context cacheable — src/agents/system-prompt.ts:713-729
[P2] Update the prompt-order test — src/agents/system-prompt.test.ts:686-716

Review details

Best possible solution:

Implement a stable-vs-volatile context split: keep AGENTS/SOUL/IDENTITY/USER/TOOLS/BOOTSTRAP cacheable, move only volatile context such as auto-written memory or explicitly marked dynamic context below the boundary, and lock it with tests/docs/changelog.

Do we have a high-confidence way to reproduce the issue?

Yes. A high-confidence static reproduction exists by building a prompt with a changing MEMORY.md, checking its position relative to SYSTEM_PROMPT_CACHE_BOUNDARY, and comparing that with Anthropic payload shaping that cache-controls only the prefix.

Is this the best way to solve the issue?

No. Moving all Project Context below the boundary avoids invalidation but forfeits caching for stable workspace context; a narrower volatility classification is the maintainable fix.

Full review comments:

[P2] Keep stable context cacheable — src/agents/system-prompt.ts:713-729
This moves every stableContextFiles entry after SYSTEM_PROMPT_CACHE_BOUNDARY. The Anthropic shaper only applies cache_control to text before that marker, so stable AGENTS/SOUL/USER/TOOLS/BOOTSTRAP content would stop being cached. Please move only genuinely volatile context below the boundary.
Confidence: 0.88
[P2] Update the prompt-order test — src/agents/system-prompt.test.ts:686-716
The branch changes Project Context ordering but leaves the existing prompt-order test asserting the old boundary relationship. That will fail or preserve the wrong contract; update it to cover the intended stable-vs-volatile split.
Confidence: 0.82

Overall correctness: patch is incorrect
Overall confidence: 0.86

Acceptance criteria:

pnpm test src/agents/system-prompt.test.ts src/agents/system-prompt-cache-boundary.test.ts src/agents/anthropic-payload-policy.test.ts
pnpm exec oxfmt --check --threads=1 src/agents/system-prompt.ts src/agents/system-prompt.test.ts docs/reference/prompt-caching.md docs/concepts/system-prompt.md CHANGELOG.md
pnpm check:changed

What I checked:

Current main keeps stable context above the boundary: Current main sorts context files, classifies only dynamic files separately, includes stableContextFiles in the stable-prefix cache key, and renders those files before SYSTEM_PROMPT_CACHE_BOUNDARY. (src/agents/system-prompt.ts:758, 4532e5d85803)
Dynamic context follows the boundary: Current main renders stableContextFiles as # Project Context, then pushes SYSTEM_PROMPT_CACHE_BOUNDARY, then renders dynamicContextFiles below it. (src/agents/system-prompt.ts:1008, 4532e5d85803)
Anthropic cache control only covers the stable prefix: When the marker is present, Anthropic payload shaping emits the text before the boundary with cache_control and emits the suffix without cache control. (src/agents/anthropic-payload-policy.ts:89, 4532e5d85803)
Docs describe stable workspace files as cached-prefix content: Prompt-caching docs say workspace files and other relatively static context belong above the boundary, while volatile files such as HEARTBEAT.md belong below it. Public docs: docs/reference/prompt-caching.md. (docs/reference/prompt-caching.md:177, 4532e5d85803)
Existing test guards stable context before volatile sections: The current system-prompt test asserts # Project Context appears before the cache boundary and channel/session volatile sections appear after it. (src/agents/system-prompt.test.ts:1040, 4532e5d85803)
PR diff moves all stable context below the boundary: The PR removes the stable context block from above the boundary and reinserts it after SYSTEM_PROMPT_CACHE_BOUNDARY, making every Project Context file part of the uncached suffix. (src/agents/system-prompt.ts:713, 6615f97850e1)

Likely related people:

vincentkoc: Authored the merged cache-boundary PR that sorted workspace context into stable files above the boundary and HEARTBEAT.md below it. (role: introduced behavior; confidence: high; commits: 41fb09fd8002; files: src/agents/system-prompt.ts, src/agents/system-prompt.test.ts, CHANGELOG.md)
Peter Steinberger: Local current-main blame for the prompt assembly and Anthropic cache-policy files points to a recent maintainer refactor touching this area. (role: recent maintainer; confidence: medium; commits: 1466878c36ff; files: src/agents/system-prompt.ts, src/agents/anthropic-payload-policy.ts, docs/reference/prompt-caching.md)

Remaining risk / open question:

The replacement fix needs a clear volatile-context rule so frequently rewritten files stop busting the cache without moving stable instruction/profile files out of the cached prefix.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4532e5d85803.

steipete and others added 30 commits April 5, 2026 08:57

test: refresh simple completion provider fallback

570e863

test: use stable sandbox denied tool assertions

be00675

test: load browser fixture for sandbox policy

d8a1c7c

test: stabilize pi embedded text-end hooks

e5e689e

fix: recover unloaded macOS launch agents (#43766)

c59b03f

refactor: remove generated plugin sdk facades

7d0fda6

refactor: route capability runtime through channel stores

5e240f8

fix: clamp pi embedded fenced chunk splits

33520bc

fix(plugins): carry workspaceDir in runtime state

4687bff

test(gateway): align current response and callback types

d766e20

refactor: register channel bootstrap capabilities

ef8a811

test(nextcloud-talk): keep send runtime mock aligned

0241f83

fix(android): correct App Actions prompt parameter typing

612b721

build(android): fix flavored release bundle prep

8e09d70

refactor: extract daemon launchd recovery helper

0a1495a

fix(google): add managed gemini prompt caching

3147f60

fix: normalize huggingface refs and discovery timeout

1c012bf

docs: sync config reference with unreleased changes

4322924

refactor: remove plugin sdk facade generator

da33e29

fix(exec): keep notifyOnExit heartbeat wakes on exec-event (#41479)

a0ba15a

Co-authored-by: Vincent Koc <[email protected]>

fix(heartbeat): skip busy session lane wake delivery (#40526)

63986bb

Co-authored-by: Vincent Koc <[email protected]>

chore: ignore local artifacts workspace

6ac8142

style: normalize import ordering and wrapping

b548d52

feat: add implicit discovery toggles

517e737

docs: sync CLI and prompt-caching reference with code

41c8cd3

fix(ci): align google prompt cache stream typing

2698449

fix(config): align bluebubbles network schema

14d272a

fix: avoid eager web provider config reads

de82045

steipete and others added 17 commits April 5, 2026 16:20

fix(discord): honor explicit reply tags in delivery

1ae95cb

test: speed up minimax auth provenance fixtures

57ec649

test: speed up ollama provider discovery coverage

dfb35a6

style(repo): normalize imports and formatting

0866dfd

fix: swallow expired discord slash interactions

80615eb

refactor: remove provider-specific sdk shims from core

3ba1a5e

refactor: move legacy config migrations under doctor

479cc18

feat: allow occasional emoji in friendly openai overlay

1d82e1b

docs: refresh unreleased changelog

8c210b0

test: reduce models-config temp-home churn

ecb3633

refactor: route models-config planning through provider seam

f4fee89

fix(dev): forward run-node wrapper signals

696d19e

Matrix: keep approval reaction hint anchored

50df81c

docs(ios): document testflight release recovery

db6edea

openclaw-barnacle Bot added agents Agent runtime and tooling size: XS labels Apr 5, 2026

100yenadmin mentioned this pull request Apr 7, 2026

feat: prompt cache keep-warm pings to prevent TTL expiry between turns #62475

Closed

daniel-rudaev closed this May 11, 2026

daniel-rudaev force-pushed the fix/cache-context-files-order branch from 6615f97 to 1813c29 Compare May 11, 2026 14:08

openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 11, 2026

daniel-rudaev changed the title ~~fix: move context files after cache boundary to prevent invalidation~~ (withdrawn) May 11, 2026

daniel-rudaev changed the title ~~(withdrawn)~~ fix: move context files after cache boundary to prevent invalidation May 11, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: move context files after cache boundary to prevent invalidation#61422

fix: move context files after cache boundary to prevent invalidation#61422
daniel-rudaev wants to merge 10000 commits into
openclaw:mainfrom
D1DX:fix/cache-context-files-order

daniel-rudaev commented Apr 5, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Apr 5, 2026 •

edited

Loading

Comments Outside Diff (2)

Uh oh!

clawsweeper Bot commented May 1, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

Uh oh!

Uh oh!

Conversation

daniel-rudaev commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Impact

Test plan

Uh oh!

greptile-apps Bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Comments Outside Diff (2)

Uh oh!

clawsweeper Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

daniel-rudaev commented Apr 5, 2026 •

edited

Loading

greptile-apps Bot commented Apr 5, 2026 •

edited

Loading

clawsweeper Bot commented May 1, 2026 •

edited

Loading