Smart Memory
Enhanced memory management for OpenClaw. Zero external dependencies. Inspired by Claude Code's memdir architecture.
Requirements
- Runtime: Python 3.10+ (standard library only), Bash 4.0+ (health/extract scripts only)
- OS: Linux, macOS
- Environment variables (all optional, with defaults):
OPENCLAW_WORKSPACE — Workspace root (default: ~/.openclaw/workspace)OPENCLAW_SESSION_ID — Session identifier for temp cache (default: default)
Security
Sensitive Data Protection
All write commands (session_state.py, session_cache.py) automatically reject inputs matching:
- API keys/tokens (OpenAI
sk-*, GitHub ghp_*, ClawHub clh_*)
- Passwords (
password=, passwd:, etc.)
- Private keys (
-----BEGIN PRIVATE KEY-----)
This is a hard block at the script level — the agent cannot bypass it. The regex patterns are conservative (high precision, may miss exotic formats); the agent should additionally avoid extracting any credential-like text even if not matched.
Input Sanitization
- Control characters stripped from all inputs
- Session ID sanitized to alphanumeric/hyphen/underscore only (prevents path traversal)
- Python-based scripts eliminate shell injection risks
Data Isolation
- All data stays local — no network calls, no cloud uploads
- Session cache uses
/tmp/ with sanitized session ID filenames
- No external dependencies or third-party packages
Memory Layers
| Layer |
File |
Purpose |
Lifetime |
| HOT RAM |
SESSION-STATE.md |
Current task, context, decisions |
Session (survives compaction) |
| DAILY |
memory/YYYY-MM-DD.md |
Raw daily notes with type tags |
90 days → archive |
| CURATED |
MEMORY.md |
Promoted long-term facts |
Permanent |
| ARCHIVE |
memory/archive/YYYY-MM/ |
Stale daily files |
Forever (compressed) |
| CACHE |
/tmp/openclaw-session-*.json |
Session temp data |
Session end / reboot |
Quick Reference
| Action |
Script |
| WAL shortcut (any command) |
scripts/wal task/decide/context/pending/done/blocker/get/snapshot/restore |
| Set current task |
scripts/wal task "description" |
| Log a decision |
scripts/wal decide "chose X over Y" |
| Add context |
scripts/wal context key value |
| Snapshot & restore |
scripts/wal snapshot / scripts/wal restore |
| Session cache |
python3 scripts/session_cache.py set/get/list/clear |
| Classify (summary) |
python3 scripts/classify_memory.py --summary |
| Decay (promote only) |
python3 scripts/memory_decay.py --promote-only |
| Health report |
bash scripts/memory_health.sh |
WAL Protocol (Write-Ahead Log)
Critical rule: Write BEFORE responding.
When the user provides information that should be remembered:
- Write to SESSION-STATE.md (via
session_state.py)
- Then respond to the user
This prevents context loss if compaction, crash, or restart happens between response and write.
| User Action |
WAL Write |
| States a preference |
session_state.py context "pref" "value" |
| Makes a decision |
session_state.py decide "chose X" |
| Gives a deadline |
session_state.py context "deadline" "date" |
| Corrects agent |
session_state.py decide "correction: X not Y" |
| Assigns task |
session_state.py task "description" |
| Mentions blocker |
session_state.py blocker "description" |
Memory Types
All entries tagged with a type prefix:
[PREF] — User preferences, habits, style[PROJ] — Project context, active work, goals[TECH] — Technical details, configs, system knowledge[LESSON] — Lessons learned, errors, corrections[PEOPLE] — People, relationships, social context[TEMP] — Session-scoped, auto-expires
Core Workflows
Session Start
- Read
SESSION-STATE.md for current task/context
- Run
memory_search for relevant prior context
- Check
memory/YYYY-MM-DD.md for today's activity
During Conversation (WAL)
- User provides actionable info → write to SESSION-STATE.md FIRST
- Important facts → append to
memory/YYYY-MM-DD.md with type tag
- Use
session_cache.py for transient session data
Session End
- Update
SESSION-STATE.md with final state
- Promote durable items from daily notes to
MEMORY.md
- Run
memory_health.sh periodically to check hygiene
Periodic Maintenance
- Run
memory_decay.py when MEMORY.md > 200 lines or 50+ daily files
- Run
classify_memory.py to tag orphaned entries
- Archive daily files older than 90 days
Agent Behavior
Auto-Extract When
- User shares preference, opinion, or personal fact
- Project decision is made or changed
- Error encountered and resolved (→ LESSON)
- New people, tools, or workflows mentioned
Extraction Modes
- Keyword mode (default):
extract_memories.sh --auto "text" — zero token cost, pure Python
- LLM mode (opt-in): Use
references/extraction_prompt.md template — costs tokens, better quality
- Use keyword mode for most conversations; LLM mode only for long/complex sessions (20+ turns)
Do NOT Extract
- Passwords, tokens, API keys, credentials (scripts hard-block these)
- Private conversations about third parties not relevant to work
- Speculation or uncertain information ("user might prefer X")
- Transient state ("user is currently looking at page X")
- Information the user explicitly said not to remember
Auto-Decay When
- MEMORY.md exceeds 200 lines
- memory/*.md totals > 50 files
- On heartbeat if configured
File Format
MEMORY.md
## [PREF] Preferences
- Favorite color: 深蓝色
## [PROJ] Active Projects
- 黄金三章: /root/黄金三章/, golden3.killclaw.xyz
## [LESSON] Lessons Learned
- Verify Telegram target before building notification workflows
Daily Notes
# 2026-03-31
## [PROJ] 黄金三章
- Fixed scoring display to 10-point scale
SESSION-STATE.md
## Current Task
Building smart-memory skill
## Key Context
- **platform**: ClawHub
## Recent Decisions
- **2026-03-31**: Use zero-dependency approach
## Pending Actions
- [ ] Publish to ClawHub
Scripts
| Script |
Language |
Purpose |
Security |
session_state.py |
Python |
HOT RAM working memory (WAL protocol) |
Sensitive data filter + sanitization |
session_cache.py |
Python |
Session-scoped temp key-value cache |
Sensitive data filter + path-safe IDs |
extract_memories.sh |
Bash |
Memory extraction guide and daily file init |
Read-only output |
memory_health.sh |
Bash |
Health report (stats, orphans, token estimate) |
Read-only |
memory_decay.py |
Python |
Temporal decay and archival of stale files |
Dry-run mode available |
classify_memory.py |
Python |
Keyword-based type classification |
Dry-run mode available |
References
references/extraction_prompt.md — LLM prompt for auto-extractionreferences/memory_schema.md — Full schema and format specreferences/decay_rules.md — Decay/archival rule set
1---2name: smart-memory-43description: Enhanced memory system for agentic workflows. Automatic memory extraction from conversations, memory type classification (preference/project/technical/lesson), temporal decay/archival, session-scoped temporary cache, and HOT RAM working memory with WAL protocol. Use when managing MEMORY.md, extracting insights from conversations, organizing memory files, archiving stale memories, searching memories by type, tracking current task state, or when the user says "remember this", "what do you know about X", "clean up memories", "what are we working on".4---56# Smart Memory78Enhanced memory management for OpenClaw. Zero external dependencies. Inspired by Claude Code's memdir architecture.910## Requirements1112- **Runtime**: Python 3.10+ (standard library only), Bash 4.0+ (health/extract scripts only)13- **OS**: Linux, macOS14- **Environment variables** (all optional, with defaults):15 - `OPENCLAW_WORKSPACE` — Workspace root (default: `~/.openclaw/workspace`)16 - `OPENCLAW_SESSION_ID` — Session identifier for temp cache (default: `default`)1718## Security1920### Sensitive Data Protection21All write commands (`session_state.py`, `session_cache.py`) automatically reject inputs matching:22- API keys/tokens (OpenAI `sk-*`, GitHub `ghp_*`, ClawHub `clh_*`)23- Passwords (`password=`, `passwd:`, etc.)24- Private keys (`-----BEGIN PRIVATE KEY-----`)2526This is a **hard block** at the script level — the agent cannot bypass it. The regex patterns are conservative (high precision, may miss exotic formats); the agent should additionally avoid extracting any credential-like text even if not matched.2728### Input Sanitization29- Control characters stripped from all inputs30- Session ID sanitized to alphanumeric/hyphen/underscore only (prevents path traversal)31- Python-based scripts eliminate shell injection risks3233### Data Isolation34- All data stays local — no network calls, no cloud uploads35- Session cache uses `/tmp/` with sanitized session ID filenames36- No external dependencies or third-party packages3738## Memory Layers3940| Layer | File | Purpose | Lifetime |41|-------|------|---------|----------|42| **HOT RAM** | `SESSION-STATE.md` | Current task, context, decisions | Session (survives compaction) |43| **DAILY** | `memory/YYYY-MM-DD.md` | Raw daily notes with type tags | 90 days → archive |44| **CURATED** | `MEMORY.md` | Promoted long-term facts | Permanent |45| **ARCHIVE** | `memory/archive/YYYY-MM/` | Stale daily files | Forever (compressed) |46| **CACHE** | `/tmp/openclaw-session-*.json` | Session temp data | Session end / reboot |4748## Quick Reference4950| Action | Script |51|--------|--------|52| WAL shortcut (any command) | `scripts/wal task/decide/context/pending/done/blocker/get/snapshot/restore` |53| Set current task | `scripts/wal task "description"` |54| Log a decision | `scripts/wal decide "chose X over Y"` |55| Add context | `scripts/wal context key value` |56| Snapshot & restore | `scripts/wal snapshot` / `scripts/wal restore` |57| Session cache | `python3 scripts/session_cache.py set/get/list/clear` |58| Classify (summary) | `python3 scripts/classify_memory.py --summary` |59| Decay (promote only) | `python3 scripts/memory_decay.py --promote-only` |60| Health report | `bash scripts/memory_health.sh` |6162## WAL Protocol (Write-Ahead Log)6364**Critical rule: Write BEFORE responding.**6566When the user provides information that should be remembered:67681. **Write to SESSION-STATE.md** (via `session_state.py`)692. **Then** respond to the user7071This prevents context loss if compaction, crash, or restart happens between response and write.7273| User Action | WAL Write |74|-------------|-----------|75| States a preference | `session_state.py context "pref" "value"` |76| Makes a decision | `session_state.py decide "chose X"` |77| Gives a deadline | `session_state.py context "deadline" "date"` |78| Corrects agent | `session_state.py decide "correction: X not Y"` |79| Assigns task | `session_state.py task "description"` |80| Mentions blocker | `session_state.py blocker "description"` |8182## Memory Types8384All entries tagged with a type prefix:8586- `[PREF]` — User preferences, habits, style87- `[PROJ]` — Project context, active work, goals88- `[TECH]` — Technical details, configs, system knowledge89- `[LESSON]` — Lessons learned, errors, corrections90- `[PEOPLE]` — People, relationships, social context91- `[TEMP]` — Session-scoped, auto-expires9293## Core Workflows9495### Session Start961. Read `SESSION-STATE.md` for current task/context972. Run `memory_search` for relevant prior context983. Check `memory/YYYY-MM-DD.md` for today's activity99100### During Conversation (WAL)1011. User provides actionable info → write to SESSION-STATE.md FIRST1022. Important facts → append to `memory/YYYY-MM-DD.md` with type tag1033. Use `session_cache.py` for transient session data104105### Session End1061. Update `SESSION-STATE.md` with final state1072. Promote durable items from daily notes to `MEMORY.md`1083. Run `memory_health.sh` periodically to check hygiene109110### Periodic Maintenance111- Run `memory_decay.py` when MEMORY.md > 200 lines or 50+ daily files112- Run `classify_memory.py` to tag orphaned entries113- Archive daily files older than 90 days114115## Agent Behavior116117### Auto-Extract When118- User shares preference, opinion, or personal fact119- Project decision is made or changed120- Error encountered and resolved (→ LESSON)121- New people, tools, or workflows mentioned122123### Extraction Modes124- **Keyword mode** (default): `extract_memories.sh --auto "text"` — zero token cost, pure Python125- **LLM mode** (opt-in): Use `references/extraction_prompt.md` template — costs tokens, better quality126- Use keyword mode for most conversations; LLM mode only for long/complex sessions (20+ turns)127128### Do NOT Extract129- Passwords, tokens, API keys, credentials (scripts hard-block these)130- Private conversations about third parties not relevant to work131- Speculation or uncertain information ("user might prefer X")132- Transient state ("user is currently looking at page X")133- Information the user explicitly said not to remember134135### Auto-Decay When136- MEMORY.md exceeds 200 lines137- memory/*.md totals > 50 files138- On heartbeat if configured139140## File Format141142### MEMORY.md143```markdown144## [PREF] Preferences145- Favorite color: 深蓝色146147## [PROJ] Active Projects148- 黄金三章: /root/黄金三章/, golden3.killclaw.xyz149150## [LESSON] Lessons Learned151- Verify Telegram target before building notification workflows152```153154### Daily Notes155```markdown156# 2026-03-31157158## [PROJ] 黄金三章159- Fixed scoring display to 10-point scale160```161162### SESSION-STATE.md163```markdown164## Current Task165Building smart-memory skill166167## Key Context168- **platform**: ClawHub169170## Recent Decisions171- **2026-03-31**: Use zero-dependency approach172173## Pending Actions174- [ ] Publish to ClawHub175```176177## Scripts178179| Script | Language | Purpose | Security |180|--------|----------|---------|----------|181| `session_state.py` | Python | HOT RAM working memory (WAL protocol) | Sensitive data filter + sanitization |182| `session_cache.py` | Python | Session-scoped temp key-value cache | Sensitive data filter + path-safe IDs |183| `extract_memories.sh` | Bash | Memory extraction guide and daily file init | Read-only output |184| `memory_health.sh` | Bash | Health report (stats, orphans, token estimate) | Read-only |185| `memory_decay.py` | Python | Temporal decay and archival of stale files | Dry-run mode available |186| `classify_memory.py` | Python | Keyword-based type classification | Dry-run mode available |187188## References189190- `references/extraction_prompt.md` — LLM prompt for auto-extraction191- `references/memory_schema.md` — Full schema and format spec192- `references/decay_rules.md` — Decay/archival rule set
knownasnaffy