Tool for maintaining agent memory continuity across model switches.
- OpenClaw Backend Default - Uses
openclaw agentCLI, no external API keys needed - Scans Reset/Deleted Files - Finds
*.jsonl.reset.*and*.jsonl.deleted.*sessions moved during compaction - User Conversation Priority - LLM summaries prioritize USER messages over cron/automated activity
- Telegram Envelope Stripping - Extracts actual message content from channel metadata wrappers
- Chunked Parallel Summarization - Large days (>80k chars) split into 60k chunks, 3 parallel workers
- Tool Result Truncation - Large API dumps (Notion JSON, web fetches) capped at 15k chars
OpenClaw agents maintain continuity through memory files (memory/YYYY-MM-DD.md, MEMORY.md). But there's a critical failure mode:
Model switches create memory isolation. When OpenClaw switches between models (Opus → Sonnet → GPT), each model instance operates independently. If one instance doesn't write to memory files, that context is lost to future instances.
In practice, this means:
- Daily memory files never get created (or are sparse)
- Important conversations vanish between model switches
- The agent "forgets" decisions, context, and relationships
- MEMORY.md drifts out of sync or stays empty
We discovered this when an entire day (330 messages) was missing, and another day had only 827 bytes for 598 messages—missing an important thread entirely.
The JSONL session logs are the ground truth. OpenClaw writes every message, tool call, and model transition to ~/.openclaw/agents/main/sessions/*.jsonl. These persist across ALL model switches.
This tool:
- Parses the native JSONL session logs
- Reconstructs daily memory files from the actual conversation history
- Optionally uses LLM summarization for coherent narratives
- Runs automated backfill to prevent future gaps
- Sanitizes secrets before writing anything to disk
Result: Memory continuity survives model switches because it's reconstructed from persistent logs, not dependent on any single model instance maintaining state.
- Memory gaps after model switches - Reconstruct memory that was lost during model transitions
- Verify memory coverage - Identify days with missing or sparse memory files
- Automated daily sync - Run via cron to keep memory files current
- Backfill historical data - Generate memory files for past sessions
- Recovery after failures - The logs are always there; memory can always be rebuilt
openclaw-memory-sync/
├── memory-sync/ # ClawHub skill folder (upload this folder)
│ ├── memory_sync.py # Single-file CLI tool (all logic here)
│ ├── SKILL.md # OpenClaw skill definition (agent instructions)
│ └── SECRET_PATTERNS.md # Documentation of secret detection patterns
├── tests/
│ ├── test_memory_sync.py # Consolidated test suite
│ ├── conftest.py # Pytest fixtures
│ └── fixtures/ # Test data files
└── README.md # This file
Requires Python 3.11+ and click:
pip install click
# Optional: for direct API summarization backends
pip install openaicd ~/.openclaw/skills
git clone git@github.com:mpesavento/openclaw-memory-sync.git
# Or download from ClawHub and copy the memory-sync folder
cp -r openclaw-memory-sync/memory-sync ~/.openclaw/skills/
# Create an alias for convenience
alias memory-sync="python ~/.openclaw/skills/memory-sync/memory_sync.py"# Check for gaps in memory coverage
memory-sync compare
# Backfill today's memory (simple extraction, fast)
memory-sync backfill --today
# Backfill with LLM narrative summary (recommended for quality)
memory-sync backfill --today --summarize --preserve
# Backfill all missing dates
memory-sync backfill --all| Command | Description |
|---|---|
compare |
Find gaps between session logs and memory files |
backfill |
Generate missing daily memory files |
summarize |
Generate LLM summary for a single day |
extract |
Extract conversations matching criteria |
transitions |
List model transitions |
validate |
Check memory files for consistency issues |
stats |
Show coverage statistics |
Simple Extraction (without --summarize):
- Fast, no LLM calls
- Extracts topics, key exchanges, and decisions via pattern matching
- Best for initial backfills or systems without LLM access
LLM Summarization (with --summarize):
- Generates coherent narrative summaries
- Uses OpenClaw's native model by default (no API key needed)
- Alternative backends:
--summarize-backend anthropicor--summarize-backend openai - User conversations prioritized - Summaries start with "User Conversations & Decisions" section
- Large days auto-chunked - Days >80k chars split into 60k chunks, processed in parallel
Recommended for daily use:
memory-sync backfill --today --summarize --preserve| Day Size | Time | Notes |
|---|---|---|
| Light (<100 msgs) | 30-60 sec | Single LLM call |
| Normal (100-500 msgs) | 1-2 min | Single LLM call |
| Heavy (500+ msgs) | 5-10 min | Chunked parallel (3 workers) |
| Very heavy (1000+ msgs) | 10-15 min | 15+ chunks |
All content is automatically sanitized before writing to memory files. Detected secrets are replaced with [REDACTED-TYPE] placeholders.
Supported patterns include:
- API keys (OpenAI, Anthropic, GitHub, AWS, Stripe, etc.)
- Tokens (JWT, OAuth, session tokens)
- Connection strings with credentials
- SSH keys and certificates
- Environment variable references
See memory-sync/SECRET_PATTERNS.md for the complete list of 30+ detection patterns.
Default paths:
- Session logs:
~/.openclaw/agents/main/sessions/*.jsonl - Memory files:
~/.openclaw/workspace/memory/
Override with CLI flags:
memory-sync compare --sessions-dir /path/to/sessions --memory-dir /path/to/memory# Run at 3am daily
0 3 * * * cd ~/.openclaw/skills/memory-sync && python memory_sync.py backfill --today --summarize --preserve >> ~/.memory-sync/cron.log 2>&1Only process days that have changed since the last run:
memory-sync backfill --incremental --summarize --preserveState is tracked in ~/.memory-sync/state.json.
pip install pytest
# Run all tests
pytest tests/
# Run specific test class
pytest tests/test_memory_sync.py::TestSummarizeWithOpenclaw -v- memory-sync/SKILL.md - OpenClaw skill definition with detailed usage instructions for agents
- memory-sync/SECRET_PATTERNS.md - Complete documentation of secret detection patterns
MIT