openclaw - 💡(How to fix) Fix Question/RFC: would layered context and memory hygiene guidance fit OpenClaw docs?

Summary

I would like to ask whether guidance for long-running agent context and memory hygiene would fit OpenClaw docs or future optional conventions.

The reference pattern is: thin startup context, hot core persona, lazy-loaded topic/tool memory, searchable archives, provenance-aware summaries, live verification for volatile facts, and human-reviewed proposals for high-risk self-evolution.

This is intended as a docs/RFC question first, not a request to make a new mandatory runtime feature.

Problem to solve

Long-running personal agents can gradually accumulate a lot of context: workspace bootstrap files, persona notes, long-term memory, tool instructions, topic notes, daily logs, and runtime troubleshooting notes.

When these responsibilities are mixed into always-injected startup context, several issues can appear over time:

• Higher token cost and slower responses from repeated context injection.
• Increased truncation risk as AGENTS.md, MEMORY.md, TOOLS.md, or equivalent workspace files grow.
• Persona and safety instructions can be diluted by unrelated tool manuals, deployment notes, daily logs, or stale runtime facts.
• Operational facts such as ports, processes, provider/model state, gateway status, branches, and deployment state can become stale if memory is treated as truth.
• Agents can usefully improve their own workspace organization, but silent edits to persona, hot memory, tool routing, permission boundaries, or framework policy are risky.

I am not sure whether this belongs in OpenClaw core, docs, examples, or just community prior art. That is why I am opening this as a question/RFC rather than a concrete implementation request.

Proposed solution

If maintainers think this fits OpenClaw's scope, one conservative first step could be a docs page or guide for long-running agent context and memory hygiene.

Possible topics:

1. Layered context model

   • Hot layer: minimal behavior policy, core persona, memory index, tool index.
   • Warm layer: topic memory, profile notes, detailed tool docs.
   • Cold layer: daily logs, archives, transcripts, raw evidence.
   • Evidence layer: fresh local verification for volatile facts.

2. Bootstrap index convention

   • A small routing file that tells the agent which core files stay hot and which details should be loaded on demand.
   • Example entries for persona core, topic memory index, tool-doc index, and volatile-fact verification.

3. Thin startup-file guidance

   • Keep hot files compact and index-like.
   • Move detailed domain notes into topic files.
   • Move long tool manuals/troubleshooting notes into docs/tool files.
   • Keep daily logs and archives searchable but not always injected.

4. Provenance-aware memory promotion

   • Encourage summaries to preserve source references and review state.
   • Promote repeated daily notes into topic memory only when useful.
   • Treat memory about volatile runtime facts as hints, not authority.

5. Governed self-evolution

   • Agents may observe repeated context pressure, stale facts, oversized files, or recurring failures.
   • Agents may create pending improvement proposals.
   • Agents should not silently rewrite core persona, hot memory, tool routing, permission boundaries, or framework policy.
   • Human approval should be required for high-risk changes.

6. Possible optional runtime affordances later

   • Context budget / hot-file size health report.
   • Warning when hot files exceed recommended size.
   • Optional helpers for topic-memory promotion proposals.
   • Optional smoke-test hooks for persona drift, tool routing, and volatile-fact verification.

Reference design / prior art:

• https://github.com/tianxiaochannel-oss88/agent-context-memory-framework
• https://github.com/tianxiaochannel-oss88/agent-context-memory-framework/blob/main/docs/en/adapters/openclaw.md

The reference guide is intentionally non-destructive: backup first, inventory current files, move-and-index rather than delete, avoid secrets/provider credentials, do not rewrite core persona automatically, and verify volatile facts live.

If this direction is welcome, I would be happy to help shape it into a more focused docs PR. If it is outside OpenClaw's current scope, it can simply remain external prior art.

Alternatives considered

1. Keep all context hot-loaded

   • Simple, but may scale poorly for durable personalized agents.
   • Can raise cost, latency, truncation, and persona-drift risk.

2. Aggressively summarize or delete old memory

   • Reduces size, but can lose provenance and important preferences.
   • Risky if automated without review.

3. Rely only on vector/session search

   • Useful for retrieval, but not enough by itself.
   • Agents still need a stable routing map and clear hot-vs-lazy context rules.

4. Make a full framework mandatory in OpenClaw

   • This feels too invasive for a first step.
   • Documentation and optional conventions seem safer and easier to evaluate.

Impact

Potentially affected users/systems/channels:

• Users running long-lived OpenClaw personal agents with persona memory, workspace files, tool instructions, daily logs, and multiple channels.
• Tool-heavy agents that perform coding, deployment, creative workflows, runtime debugging, or proactive maintenance.

Severity:

• Medium for ordinary long-running agents.
• Higher for durable persona agents or large workspace contexts, where context bloat can degrade reliability and increase truncation/persona-drift risk.

Frequency:

• Grows over time as workspace files, memory files, and tool notes accumulate.
• More frequent in always-on agents with multiple recurring work domains.

Consequence:

• Higher token cost and slower responses.
• Lost or truncated important instructions.
• More stale-memory mistakes unless volatile state is verified live.
• More manual cleanup work for users.
• Higher risk if agents self-edit memory or policy without proposal/approval boundaries.

Evidence/examples

Reference implementation/design:

• Agent Context Memory Framework README: https://github.com/tianxiaochannel-oss88/agent-context-memory-framework
• Design document: https://github.com/tianxiaochannel-oss88/agent-context-memory-framework/blob/main/docs/en/agent-context-memory-framework-design.md
• OpenClaw adapter guide: https://github.com/tianxiaochannel-oss88/agent-context-memory-framework/blob/main/docs/en/adapters/openclaw.md

Observed local result from one OpenClaw-style workspace:

• Splitting oversized hot files into a compact memory index, thin tool index, topic notes, tool docs, and archives reduced approximate hot injected context by about two thirds.
• The workflow preserved important memory by moving detail into searchable/lazy-loaded files rather than deleting it.
• Runtime facts such as provider state, ports, processes, branches, and deployment state are treated as hints and verified live before action.

This is a single-workspace case study, not a formal benchmark.

Additional information

This is deliberately scoped as a question/RFC and documentation proposal first.

The idea should remain:

• Backward-compatible with existing OpenClaw workspaces.
• Optional rather than mandatory.
• Non-destructive by default.
• Safe for personalized agents with private memory.
• Clear that secrets, provider credentials, private memory contents, raw personal logs, and sensitive local paths should not be posted in public issues.

Main question for maintainers:

Would this kind of layered context and memory hygiene guidance be useful in OpenClaw docs/examples, or is it better kept as an external community pattern for now?