Smart Memory (Zero Dep)

---

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".

---

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:

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

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

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

references/memory_schema.md — Full schema and format spec

references/decay_rules.md — Decay/archival rule set