Summary

A file-based memory layer (memory_bank/) that lives outside the session and is never compacted, providing persistent agent context across restarts, OOM-kills, and channel switches.

Problem to solve

Agent context is fragile. Session history is lost after gateway restarts (#21850), compaction destroys context the agent needs later (#21821, #21818), and there is no shared bootstrap workspace (#21802). The root cause: openclaw treats memory as a cache (evictable) rather than an asset (persistent). Operators who run agents long-term lose accumulated knowledge on every restart.

Proposed solution

Add a memory_bank/ directory convention with structured markdown files:

.openclaw/memory_bank/
├── activeContext.md     # Current focus, updated per session
├── userContext.md       # Persistent user/org profile
├── productContext.md    # Agent purpose & config
└── systemPatterns.md    # Learned decisions & architecture

On session start, the agent bootstrap hook reads memory bank files into system context (<2K tokens). On session end (or via a session:beforeSave hook), the agent appends key insights to activeContext.md. These files are never compacted because they exist outside the message history.

Alternatives considered

• Vector-only memory (lancedb): Provides semantic search but loses structured context and requires embedding overhead for simple key-value lookups.
• Session pinning: Prevents compaction but inflates token cost indefinitely.
• Manual system prompts: Work but cannot evolve over time.

Impact

• Affected: Any long-running agent (support bots, personal assistants, team agents)
• Severity: High — context loss forces users to re-explain preferences/history
• Frequency: Every restart, OOM-kill, or compaction event
• Consequence: Degraded agent quality, user frustration, operator churn

Evidence/examples

I have been running this pattern in production for 3+ months on Project Athena, an open-source AI agent framework. The Memory Bank pattern is documented here. Related open issues: #21850, #21821, #21818, #21802.

Additional information

Implementation should hook into agent:bootstrap for reads and session:beforeCompaction for writes. Must remain backward-compatible — agents without a memory_bank/ directory should behave identically to today.