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#

LayerFilePurposeLifetimeHOT RAMSESSION-STATE.mdCurrent task, context, decisionsSession (survives compaction)DAILYmemory/YYYY-MM-DD.mdRaw daily notes with type tags90 days → archiveCURATEDMEMORY.mdPromoted long-term factsPermanentARCHIVEmemory/archive/YYYY-MM/Stale daily filesForever (compressed)CACHE/tmp/openclaw-session-*.jsonSession temp dataSession end / reboot

Quick Reference#

ActionScriptWAL shortcut (any command)scripts/wal task/decide/context/pending/done/blocker/get/snapshot/restoreSet current taskscripts/wal task "description"Log a decisionscripts/wal decide "chose X over Y"Add contextscripts/wal context key valueSnapshot & restorescripts/wal snapshot / scripts/wal restoreSession cachepython3 scripts/session_cache.py set/get/list/clearClassify (summary)python3 scripts/classify_memory.py --summaryDecay (promote only)python3 scripts/memory_decay.py --promote-onlyHealth reportbash scripts/memory_health.sh

WAL Protocol (Write-Ahead Log)#

Critical rule: Write BEFORE responding.

When the user provides information that should be remembered:

1. Write to SESSION-STATE.md (via session_state.py)
2. Then respond to the user

This prevents context loss if compaction, crash, or restart happens between response and write.

User ActionWAL WriteStates a preferencesession_state.py context "pref" "value"Makes a decisionsession_state.py decide "chose X"Gives a deadlinesession_state.py context "deadline" "date"Corrects agentsession_state.py decide "correction: X not Y"Assigns tasksession_state.py task "description"Mentions blockersession_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#

1. Read SESSION-STATE.md for current task/context
2. Run memory_search for relevant prior context
3. Check memory/YYYY-MM-DD.md for today's activity

During Conversation (WAL)#

1. User provides actionable info → write to SESSION-STATE.md FIRST
2. Important facts → append to memory/YYYY-MM-DD.md with type tag
3. Use session_cache.py for transient session data

Session End#

1. Update SESSION-STATE.md with final state
2. Promote durable items from daily notes to MEMORY.md
3. 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#

markdown

## [PREF] Preferences
- Favorite color: 深蓝色

## [PROJ] Active Projects
- 黄金三章: /root/黄金三章/, golden3.killclaw.xyz

## [LESSON] Lessons Learned
- Verify Telegram target before building notification workflows

Daily Notes#

markdown

# 2026-03-31

## [PROJ] 黄金三章
- Fixed scoring display to 10-point scale

SESSION-STATE.md#

markdown

## 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#

ScriptLanguagePurposeSecuritysession_state.pyPythonHOT RAM working memory (WAL protocol)Sensitive data filter + sanitizationsession_cache.pyPythonSession-scoped temp key-value cacheSensitive data filter + path-safe IDsextract_memories.shBashMemory extraction guide and daily file initRead-only outputmemory_health.shBashHealth report (stats, orphans, token estimate)Read-onlymemory_decay.pyPythonTemporal decay and archival of stale filesDry-run mode availableclassify_memory.pyPythonKeyword-based type classificationDry-run mode available

References#

• references/extraction_prompt.md — LLM prompt for auto-extraction
• references/memory_schema.md — Full schema and format spec
• references/decay_rules.md — Decay/archival rule set