Big Memory
by @obekt
Structured task snapshot and automatic post-compaction recovery. Captures exact code, decisions, file paths, and task state before context compaction and rec...
clawhub install big-memoryπ About This Skill
name: big-memory description: Structured task snapshot and automatic post-compaction recovery. Captures exact code, decisions, file paths, and task state before context compaction and recovers them after. Use when context is lost, when the user says "you forgot" or "what was I working on", when approaching context limits, or before long multi-step sessions. Also activates on "/big-memory", "save snapshot", "checkpoint", or "restore context". Zero external dependencies. version: 1.0.0 metadata: openclaw: requires: {} emoji: "\U0001F9E0" homepage: https://github.com/obekt/big-memory
Big Memory
Structured task snapshots that survive context compaction. Three-phase protocol:
1. CAPTURE -- Save a structured task snapshot before compaction wipes your context 2. DETECT -- Recognize when compaction has occurred and context is missing 3. RECOVER -- Search memory for the latest snapshot and resume exactly where you left off
Uses only OpenClaw built-in tools (memory_search, memory_get, Read, Edit). No scripts, no external databases, no API keys.
Task Snapshot Schema
Every snapshot MUST follow this exact structure. Do not omit fields -- write "none" if a field is empty. For the full template with field-by-field guidelines, read {baseDir}/references/TASK-SNAPSHOT.md.
[SNAPSHOT] Active Goal
One sentence: what is the user trying to accomplish right now? Include the "why".[SNAPSHOT] Current State
Phase: {planning|implementing|debugging|testing|reviewing|deploying}
Branch: {git branch name or "n/a"}
Blocked: {yes|no} -- {blocker description if yes}
Progress: {rough percentage or milestone} [SNAPSHOT] Files In Play
/path/to/file.ts -- What is happening in this file/path/to/other.ts -- Purpose of this file in current task[SNAPSHOT] Decisions Made
1. Decision description -- rationale for why this was chosen
2. Another decision -- its rationale[SNAPSHOT] Code Context
Key code that must survive compaction. Only include what cannot be reconstructed from reading files (function signatures being designed, error messages being debugged, exact patterns being replicated). Keep under 50 lines total.[SNAPSHOT] Key Names & Values
Exact identifiers that are easy to forget:
API endpoint: POST /api/v1/users
Table name: user_sessions
Env var: DATABASE_URL
Error: ERR_DUPLICATE_KEY [SNAPSHOT] Blockers & Open Questions
Blocker: description with context
Question: unresolved decision with options considered [SNAPSHOT] Next Steps
Ordered, specific, actionable:
1. Finish implementing X in /path/to/file covering edge cases A, B, C
2. Write tests for Y endpoint: success (201), duplicate (409), missing fields (400)
3. Update config to include Z
The HTML comment markers ( and ) are critical. They act as machine-parseable delimiters that memory_search matches via BM25 exact-term matching, enabling precise retrieval.
When to Capture
Trigger 1: Pre-Compaction Flush (Automatic)
When you receive a system message related to compaction (containing "compact", "memory flush", "store durable memories", or "nearing compaction"), execute the CAPTURE protocol instead of writing generic notes. Create a full structured snapshot following the schema above.
Trigger 2: Milestone Capture (Agent-Initiated)
After completing a significant unit of work -- implementing a feature, fixing a bug, making an architecture decision -- self-assess: "If compaction happened right now, would I lose critical context?" If yes, create a snapshot.
Good times to snapshot:
Trigger 3: User Command (User-Initiated)
When the user says /big-memory save, "save snapshot", "checkpoint", or "big-memory save", create a snapshot immediately.
How to Store Snapshots
1. Read the current daily log memory/{YYYY-MM-DD}.md using Read. If it does not exist, you will create it.
2. APPEND the snapshot. Never overwrite existing content. Read the file first, then use Edit to append at the end. Alternatively, use Write with the full existing content plus the new snapshot.
3. Precede the snapshot with a horizontal rule and heading:
---Task Snapshot -- HH:MM
...
4. Multiple snapshots in the same file is expected. Each captures a point-in-time state. The most recent snapshot is the source of truth.
Post-Compaction Recovery Protocol
Step 1: Detect Compaction
Suspect compaction when ANY of these are true:
Step 2: Search for Latest Snapshot
Execute this search:
memory_search("BIG-MEMORY-SNAPSHOT")
This triggers hybrid vector + BM25 search across all memory files. The HTML comment markers ensure high BM25 relevance scoring.
If results are found, use memory_get or Read to retrieve the full file content at the matched path and line range.
If no results from the primary search, try broader queries:
memory_search("SNAPSHOT Active Goal Next Steps")
memory_search("{today's date} task snapshot")
Step 3: Inject and Orient
After retrieving a snapshot:
1. Parse the content between and markers
2. Inform the user: "I detected context was compacted. Restoring task state from snapshot taken at {timestamp}..."
3. Present the recovered state concisely:
- Goal: {from Active Goal}
- Phase: {from Current State}
- Working on: {from Files In Play}
- Next up: {from Next Steps}
4. Ask: "Does this match where we left off? Anything to update before I continue?"
5. Resume work from the Next Steps section
If No Snapshot Found
If no snapshot exists in memory:
1. Search more broadly: memory_search("{project name}"), memory_search("decided"), memory_search("working on")
2. Check MEMORY.md for any relevant long-term notes
3. Tell the user: "I couldn't find a structured snapshot. Can you briefly remind me what we were working on? I'll save a snapshot this time so it won't happen again."
Multiple Snapshots
If multiple snapshots are found:
/big-memory Command
/big-memory save
Create a snapshot now. Execute the full CAPTURE protocol:
1. Read {baseDir}/references/TASK-SNAPSHOT.md for the template (first time only)
2. Assess the current task state
3. Fill in all 8 schema sections
4. Append to today's daily log (memory/YYYY-MM-DD.md)
5. Confirm: "Snapshot saved to memory/{date}.md"
/big-memory recall
Search for and display the most recent snapshot:
1. Execute memory_search("BIG-MEMORY-SNAPSHOT")
2. Retrieve the full snapshot via memory_get or Read
3. Display the recovered state (goal, phase, files, next steps)
4. Ask if the user wants to resume from this state
/big-memory status
Show current snapshot information:
1. Search for snapshots in today's daily log
2. Report: number of snapshots today, timestamp of most recent, whether the current task state has diverged from the last snapshot
3. Suggest /big-memory save if no recent snapshot exists, or /big-memory recall if context seems incomplete
/big-memory (no arguments)
Default to status. Show the current state and suggest the most useful action.
Recommended Configuration
For optimal automatic capture, add these settings to your project's openclaw.json. See {baseDir}/references/openclaw-config.md for the full configuration.
The most impactful change is replacing the default generic flush prompt:
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 40000,
"systemPrompt": "You are capturing structured task state for post-compaction recovery. Follow the BIG-MEMORY-SNAPSHOT schema exactly.",
"prompt": "Context compaction is imminent. Create a structured task snapshot following the BIG-MEMORY-SNAPSHOT schema and APPEND it to memory/YYYY-MM-DD.md. Include: active goal, current state, files in play, decisions made, code context (key snippets only), key names/values, blockers, and next steps. Read the existing file first -- never overwrite. Reply NO_FLUSH if nothing worth storing."
}
}
}
}
}
This replaces the default "store durable memories now" with instructions that trigger our structured capture protocol.
Best Practices
MEMORY.md for long-term knowledge (project architecture, conventions, preferences). Use snapshots only for transient task state that needs to survive the next compaction.π Tips & Best Practices
MEMORY.md for long-term knowledge (project architecture, conventions, preferences). Use snapshots only for transient task state that needs to survive the next compaction.