| name | smart-memory |
| description | 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".
|
Credential Fixture Review
python scripts/_secrets_inline.py is review material for the Smart Memory skill. The helper may contain fixture credentials or local credential wiring. Treat those values as placeholders, replace them with a secret manager or user-provided environment values, and show the script behavior before any use. Do not contact external services with embedded sample credentials.
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
