Cache Management

[gray cove]

How do I setup my agent to cache only stable facts like
Cache:
System prompts (rarely change)
SOUL.md (operator principles)
USER.md (goals and context)
Reference materials (pricing, docs, specs)
Tool documentation (rarely updated)
Project templates (standard structures)

Dont cache:
Daily memory files (change frequently)
Recent user messages (fresh each session)
Tool outputs (change per task)

[half temple]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[exotic isle]

Let me verify the exact config knobs instead of guessing.

Pretty close to what OpenClaw already does.

• Good stable cache candidates: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, optional MEMORY.md
• Not auto-injected on normal turns: memory/YYYY-MM-DD.md daily files
• Exception: bare /new and /reset can prepend recent daily memory once
• Recent user messages and current tool outputs are live turn context, not the stable bootstrap prefix

Use this in openclaw.json:

{
  agents: {
    defaults: {
      params: { cacheRetention: "long" }, // or "short"
      startupContext: {
        enabled: false, // stops /new and /reset from injecting recent daily memory

      },
      contextPruning: {
        mode: "cache-ttl",
        ttl: "1h",
      },
      heartbeat: {
        includeSystemPromptSection: false, // optional, if HEARTBEAT.md changes often
      },
    },
  },
}

Recommended split:

• AGENTS.md = stable operating rules

• SOUL.md = persona/principles
• USER.md = durable user context
• MEMORY.md = only evergreen facts
• memory/YYYY-MM-DD.md = daily/changing notes

Important gotcha: arbitrary docs in subfolders are not auto-injected every turn. So for pricing/specs/tool docs/templates, either:

• put a small stable summary in AGENTS.md or MEMORY.md, or
• keep the full docs as files/skills and let the agent read them on demand

To inspect what is actually injected, use:

• /context list
• /context detail

Docs:

• https://docs.openclaw.ai/reference/prompt-caching

• https://docs.openclaw.ai/concepts/system-prompt
• https://docs.openclaw.ai/reference/token-use

If you paste your current openclaw.json, I can trim it into a clean “stable-context only” setup.

[gray cove]

Can you explain what the Cache config you gave me does?

[exotic isle]

Yep. Short version: that config is not a per-file cache whitelist. It’s four knobs that make the reusable prompt prefix more stable and cheaper.

{
  agents: {
    defaults: {
      params: { cacheRetention: "long" },
      startupContext: { enabled: false },
      contextPruning: { mode: "cache-ttl", ttl: "1h" },
      heartbeat: { includeSystemPromptSection: false },
    },
  },
}

What each part does:

• params.cacheRetention: "long"

  • Tells the provider to keep prompt cache entries around longer.
  • Good for stable stuff like system prompt, SOUL.md, USER.md, etc.
  • It does not choose specific files, it just affects cache lifetime.

• startupContext.enabled: false

  • Disables the one-shot extra context OpenClaw can add on bare /new and /reset.
  • That extra block can include recent daily memory.
  • So this helps keep memory/YYYY-MM-DD.md out of first-turn prompt context.

• contextPruning: { mode: "cache-ttl", ttl: "1h" }

  • After the cache window expires, OpenClaw trims old tool results before re-caching.
  • This keeps old read, exec, search results, etc. from bloating the next cache write.
  • It does not delete transcript history on disk.

• heartbeat.includeSystemPromptSection: false

  • Optional.

• Removes the Heartbeat section from normal system prompt injection, and skips HEARTBEAT.md there too.
  • Useful if HEARTBEAT.md changes often and you do not want that churn.

What it doesn’t do:

• It does not auto-cache arbitrary files like docs/pricing.md or templates/api-spec.md
• It does not exclude the current user message from the live turn
• It does not give you a built-in “cache these exact files, never cache those files” list

So the real pattern is:

• Put evergreen stuff in auto-injected files: AGENTS.md, SOUL.md, USER.md, maybe MEMORY.md
• Keep daily/changing stuff in memory/YYYY-MM-DD.md
• Keep big docs/templates as on-demand files or skills, unless you want to summarize them into a stable injected file

If you want, I can give you a commented example config for:

1. strict stable-cache mode, or