# Fixing Session Memory and Context Management Issues in OpenClaw Session memory and context management are critical components of OpenClaw's architecture. When things go wrong—context windows overflow, important information gets lost during compaction, or sessions bloat uncontrollably—it can significantly impact your agent's performance and reliability. This guide will help you diagnose and fix these issues. ## Understanding OpenClaw's Session Architecture ### The Two-Layer Persistence System OpenClaw maintains session state through two distinct layers: 1. **Session Store (`sessions.json`)** - A key/value map storing session metadata - Location: `~/.openclaw/agents//sessions/sessions.json` - Tracks: session IDs, last activity, toggles, token counters, compaction counts - Safe to edit manually 2. **Session Transcript (`.jsonl`)** - Append-only JSONL file containing the full conversation tree - Location: `~/.openclaw/agents//sessions/.jsonl` - Stores: messages, tool calls, compaction summaries, branch points - Used to rebuild context for future turns **Critical principle**: The Gateway is the source of truth. In remote mode, these files live on the remote host, not your local machine. ### How Session Keys Work OpenClaw uses `sessionKey` to route and isolate conversations: - **Main/direct chat**: `agent::main` (default) - **Group chat**: `agent:::group:` - **Discord/Slack rooms**: `agent:::channel:` - **Cron jobs**: `cron:` - **Webhooks**: `hook:` Use `/status` in any chat to see your current session key and context usage. ## Understanding Context Windows and Compaction ### What Is Compaction? Every model has a **context window**—the maximum number of tokens it can process in one request. Long-running conversations accumulate messages and tool results, eventually approaching this limit. OpenClaw's **compaction** feature summarizes older conversation history into a compact summary, keeping only recent messages intact. Compaction is **persistent**: the summary is stored in the session transcript, so future requests see: - The compaction summary - Recent messages after the compaction point ### When Auto-Compaction Triggers OpenClaw's embedded Pi agent triggers auto-compaction in two scenarios: 1. **Overflow recovery**: The model returns a context overflow error → compact → retry 2. **Threshold maintenance**: After a successful turn, when: ``` contextTokens > contextWindow - reserveTokens ``` ### Compaction vs. Session Pruning These are two different mechanisms: | Feature | Compaction | Session Pruning | |---------|-----------|-----------------| | **What it does** | Summarizes and persists conversation history | Trims old tool results in-memory | | **Persistence** | Writes to JSONL transcript | Temporary, per-request only | | **Target** | All message types | Tool results only | | **Trigger** | Context window threshold | Cache TTL expiration | ## Common Session Memory Issues ### Issue #1: Credential Loss During Compaction **Symptom**: After auto-compaction, the agent "forgets" API keys, SSH credentials, or workspace state. **Root cause**: Critical context stored only in recent messages gets summarized away before the agent writes it to durable storage. **Solution**: Enable pre-compaction memory flush. The memory flush runs a silent agentic turn before compaction, prompting the agent to write important information to disk: ```json5 // ~/.openclaw/openclaw.json { agents: { defaults: { compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, systemPrompt: "Session nearing compaction. Store durable memories now.", prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store." } } } } } ``` **How it works**: - Triggers when: `contextTokens > (contextWindow - reserveTokensFloor - softThresholdTokens)` - Runs once per compaction cycle (tracked in `sessions.json`) - Uses `NO_REPLY` convention to suppress user-visible output - Only runs when workspace is writable ### Issue #2: Context Window Bloat from Tool Results **Symptom**: Sessions rapidly approach context limits despite few user messages. **Root cause**: Large tool outputs (e.g., `exec` logs, file reads, web scrapes) accumulate in the transcript. **Solution**: Enable cache-TTL session pruning. ```json5 { agents: { defaults: { contextPruning: { mode: "cache-ttl", ttl: "5m", keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" } } } } } ``` **Smart defaults for Anthropic users**: - OAuth/setup-token profiles: `cache-ttl` enabled, heartbeat `1h` - API key profiles: `cache-ttl` enabled, heartbeat `30m`, cache TTL `1h` **What gets pruned**: - Only `toolResult` messages (user/assistant messages never modified) - Tool results before the last N assistant messages - Oversized results get soft-trimmed (head + tail kept with `...` in between) - Very old results get hard-cleared with placeholder text - Image blocks are always protected ### Issue #3: Excessive Compaction Triggering **Symptom**: `🧹 Auto-compaction complete` appears frequently, even in short sessions. **Root causes**: 1. Model context window too small for workload 2. `reserveTokens` set too high relative to context window 3. Workspace files injected at session start are very large **Diagnosis**: ```bash # Check current session status # In chat: /status # From CLI: openclaw status # Inspect context breakdown # In chat: /context detail ``` **Solutions**: 1. **Increase reserve token floor** (leaves more headroom): ```json5 { agents: { defaults: { compaction: { reserveTokensFloor: 25000 // Default: 20000 } } } } ``` 2. **Reduce workspace file injection** (limit bootstrap file size): ```json5 { agents: { defaults: { bootstrapMaxChars: 15000 // Default: 20000 } } } ``` 3. **Use manual compaction strategically**: ``` /compact Focus on decisions and open questions ``` ### Issue #4: Session Isolation Leaking Private Context **Symptom**: Personal information from DMs appears in group chats, or multiple users see each other's context. **Root cause**: Default `session.dmScope = "main"` shares all DMs into one session key. **Solution**: Enable secure DM mode for multi-user scenarios. ```json5 { session: { // Isolate DM context per channel + sender dmScope: "per-channel-peer", // For multi-account inboxes: // dmScope: "per-account-channel-peer", // Optional: link same person across channels identityLinks: { alice: ["telegram:123456789", "discord:987654321"] } } } ``` **DM scope options**: - `main` (default): All DMs share one session—great for single-user continuity - `per-peer`: Isolate by sender ID across channels - `per-channel-peer`: Isolate by channel + sender (recommended for shared inboxes) - `per-account-channel-peer`: Isolate by account + channel + sender (multi-account) ## Manual Memory Management Best Practices ### The NO_REPLY Convention When running silent housekeeping operations, use the `NO_REPLY` prefix to suppress delivery: ``` NO_REPLY [Agent performs memory writes, file updates, etc.] ``` OpenClaw suppresses draft/typing indicators when output begins with `NO_REPLY`, preventing partial leaks during silent operations. ### Memory File Organization OpenClaw uses plain Markdown for memory: ``` ~/.openclaw/workspace/ ├── MEMORY.md # Long-term, curated memory (main session only) ├── memory/ │ ├── 2026-02-10.md # Daily logs (append-only) │ ├── 2026-02-11.md │ └── 2026-02-13.md └── AGENTS.md, SOUL.md, USER.md, etc. ``` **Best practices**: - **Decisions and preferences** → `MEMORY.md` - **Daily context and notes** → `memory/YYYY-MM-DD.md` - **Never rely on "mental notes"** → Write everything important to disk - **MEMORY.md loads only in main session** → Never in group contexts (security) ### Memory Search Configuration OpenClaw can build a vector index over memory files for semantic search: ```json5 { agents: { defaults: { memorySearch: { enabled: true, provider: "openai", // or "gemini", "local" model: "text-embedding-3-small", // Hybrid search (BM25 + vector) query: { hybrid: { enabled: true, vectorWeight: 0.7, textWeight: 0.3, candidateMultiplier: 4 } }, // Index extra directories extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"] } } } } ``` **Provider options**: - `openai`: Uses OpenAI embeddings API (supports batch indexing for cost savings) - `gemini`: Uses Google Gemini embeddings - `local`: Uses node-llama-cpp with GGUF models (auto-downloads to `~300MB`) **Hybrid search benefits**: - Vector: Semantic matching ("Mac Studio gateway host" ≈ "machine running gateway") - BM25: Exact tokens (IDs, error codes, code symbols) - Combined: Best of both worlds ## Debugging Token Costs and Context Usage ### Viewing Token Usage in Chat ```bash # Show current session status /status # Enable per-response usage footer /usage tokens # Shows token counts /usage full # Shows tokens + estimated cost (API key only) /usage cost # Shows local cost summary from logs # Disable usage footer /usage off # View context breakdown /context list # High-level breakdown /context detail # Detailed per-file sizes ``` ### Understanding Cost Estimation OpenClaw estimates costs from model pricing config: ```json5 { models: { providers: { anthropic: { models: [ { id: "claude-sonnet-4-5", cost: { input: 3.0, // USD per 1M tokens output: 15.0, cacheRead: 0.3, cacheWrite: 3.75 } } ] } } } } ``` **Cache behavior with pruning**: - Anthropic prompt caching only applies within TTL window - Cache-TTL pruning reduces cache write costs when cache expires - Heartbeat can keep cache warm (set interval just under cache TTL) **Example: Keep 1h cache warm**: ```json5 { agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" }, models: { "anthropic/claude-opus-4-5": { params: { cacheRetention: "long" } } }, heartbeat: { every: "55m" // Just under 1h cache TTL } } } } ``` ## Advanced: Long-Term Memory with LanceDB For production deployments with extensive memory requirements, OpenClaw supports LanceDB as an alternative memory backend: ```json5 { plugins: { slots: { memory: "memory-lancedb" // Instead of default "memory-core" } } } ``` **LanceDB benefits**: - Persistent vector storage optimized for large datasets - Better performance at scale (thousands of memory entries) - Automatic recall and capture workflows - Advanced filtering and metadata queries **Prerequisites**: - Separate LanceDB server/instance - Additional configuration for connection details ## Advanced: QMD Memory Backend (Experimental) QMD combines BM25 + vectors + reranking in a local-first search sidecar: ```json5 { memory: { backend: "qmd", qmd: { includeDefaultMemory: true, update: { interval: "5m", debounceMs: 15000 }, limits: { maxResults: 6, timeoutMs: 4000 }, scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }] }, paths: [ { name: "docs", path: "~/notes", pattern: "**/*.md" } ] } } } ``` **Prerequisites**: - Install QMD CLI: `bun install -g github.com/tobi/qmd` - SQLite with extension support: `brew install sqlite` (macOS) - First search auto-downloads GGUF models (~300MB) **QMD features**: - Local-first (no external API) - Hybrid retrieval (BM25 + vector + reranking) - Session transcript indexing (opt-in) - Custom collection support ## Troubleshooting Checklist ### 1. Session Key Issues ```bash # Check current session key /status # Verify session routing matches expectations openclaw sessions --json # Confirm dmScope configuration cat ~/.openclaw/openclaw.json | grep -A5 dmScope ``` ### 2. Context Window Problems ```bash # View current context usage /status # Detailed breakdown /context detail # Check model context window openclaw models list | grep # Trigger manual compaction /compact Include recent decisions and open tasks ``` ### 3. Memory Not Persisting ```bash # Verify memory files exist ls -la ~/.openclaw/workspace/memory/ # Check memory flush configuration cat ~/.openclaw/openclaw.json | grep -A10 memoryFlush # Verify workspace access (should be writable) openclaw status | grep workspace ``` ### 4. Excessive Token Costs ```bash # Enable session pruning # Edit ~/.openclaw/openclaw.json: { "agents": { "defaults": { "contextPruning": { "mode": "cache-ttl", "ttl": "5m" } } } } # Restart gateway openclaw gateway restart # Monitor cost reduction /usage cost ``` ### 5. Silent Operations Leaking Ensure operations start with exact `NO_REPLY` token: ``` NO_REPLY Performing memory write operation... ``` Requires OpenClaw build `2026.1.10` or later for streaming suppression. ## Session Lifecycle Management ### Reset Policies Control when sessions reset: ```json5 { session: { reset: { mode: "daily", // Options: "daily", "idle", "off" atHour: 4, // 4:00 AM gateway host local time idleMinutes: 120 // Also reset after 2h idle }, // Per-type overrides resetByType: { thread: { mode: "daily", atHour: 4 }, dm: { mode: "idle", idleMinutes: 240 }, group: { mode: "idle", idleMinutes: 120 } }, // Per-channel overrides resetByChannel: { discord: { mode: "idle", idleMinutes: 10080 } // 1 week } } } ``` **Reset triggers**: - `/new` or `/reset` commands (exact match) - Daily reset boundary (default 4:00 AM) - Idle timeout (when both daily and idle configured, first wins) ### Manual Session Management ```bash # Start fresh session /new # Start fresh with specific model /new opus-4 # Force compaction /compact # Check session health /status # View all sessions openclaw sessions --json # Clean old sessions # Edit sessions.json manually or delete JSONL transcripts ``` ## Configuration Reference ### Complete Example ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace", bootstrapMaxChars: 20000, model: { primary: "anthropic/claude-sonnet-4-5" }, compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, systemPrompt: "Session nearing compaction. Store durable memories now.", prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store." } }, contextPruning: { mode: "cache-ttl", ttl: "5m", keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5 }, memorySearch: { enabled: true, provider: "openai", model: "text-embedding-3-small", query: { hybrid: { enabled: true, vectorWeight: 0.7, textWeight: 0.3 } } }, heartbeat: { every: "55m" } } }, session: { dmScope: "per-channel-peer", reset: { mode: "daily", atHour: 4, idleMinutes: 120 }, resetTriggers: ["/new", "/reset"] } } ``` ## Conclusion OpenClaw's session memory and context management systems are powerful but require understanding to configure optimally. Key takeaways: 1. **Enable pre-compaction memory flush** to prevent credential loss 2. **Use cache-TTL session pruning** to control tool result bloat 3. **Configure secure DM mode** for multi-user scenarios 4. **Monitor token costs** with `/usage` and `/context` commands 5. **Write important information to disk** (never rely on in-memory state) 6. **Choose appropriate memory backend** (core, LanceDB, or QMD) for your scale With these configurations and troubleshooting techniques, you can maintain healthy sessions with reliable memory persistence and optimal token usage. ## Further Reading - [OpenClaw Session Documentation](https://docs.openclaw.ai/concepts/session) - [Compaction Deep Dive](https://docs.openclaw.ai/concepts/compaction) - [Memory Architecture](https://docs.openclaw.ai/concepts/memory) - [Token Usage & Costs](https://docs.openclaw.ai/token-use) - [Session Pruning](https://docs.openclaw.ai/concepts/session-pruning)