Smart Memory Plus#

Unified memory management + context compression for OpenClaw. Zero external dependencies.

⚠️ Conflict Warning: This skill replaces both smart-memory and context-compactor. Do NOT install alongside either of those skills — they share the same files ( SESSION-STATE.md, memory/, MEMORY.md) and will cause write conflicts.

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#

Write Restrictions (Hard Rules)#

The agent MUST use the provided scripts for ALL writes. Direct file writes are FORBIDDEN.

FileRequired ScriptForbiddenSESSION-STATE.md``session_state.py (WAL protocol)Direct write/overwritememory/compacts/*.md``compact_session.py --writeDirect write/overwritememory/*.md (daily notes)extract_memories.sh --auto or append via scriptDirect overwriteMEMORY.md``memory_decay.py --promote-onlyDirect overwrite/tmp/openclaw-session-*.json``session_cache.pyDirect write

Critical: Never use the agent's file-write tool directly on memory files. Always pipe through scripts — they enforce sanitization, deduplication, and append-only behavior.

The agent MUST NOT write to:

• Any directory outside the workspace
• System directories (/etc, /usr, /var, /tmp except session cache)
• User home directory root (~/.ssh, ~/.config, ~/.aws, etc.)
• Any .* dotfile or dotdir in workspace root

Sensitive Data Protection#

All write commands 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.

Privacy Boundaries#

• Compacts must NOT contain: file paths, internal URLs, IPs, passwords, tokens
• Use placeholders: <REDACTED_PATH>, <REDACTED_URL>, <INTERNAL_URL>
• All data stays local — all scripts make zero network calls, no LLM usage

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 factsPermanentCOMPACTmemory/compacts/YYYY-MM-DD-HHMM.mdSession digests30 max, auto-cleanupGRAPHmemory/.index/graph.dbEntity-relation knowledge graphRebuild from sourceARCHIVEmemory/archive/YYYY-MM/Stale daily filesForever (compressed)CACHE/tmp/openclaw-session-*.jsonSession temp dataSession end / reboot

Quick Reference#

Memory Management#

ActionScriptWAL shortcutscripts/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 valueSession cachepython3 scripts/session_cache.py set/get/list/clearClassify memoriespython3 scripts/classify_memory.py --summary/--applyDecay & archivepython3 scripts/memory_decay.py --dry-run/--promote-onlyHealth reportbash scripts/memory_health.sh

Search & Relations#

ActionScriptFull index rebuildpython3 scripts/memory_search_bm25.py buildIncremental updatepython3 scripts/memory_search_bm25.py updateSearch memories (BM25)python3 scripts/memory_search_bm25.py search "query" [--top N]Index statuspython3 scripts/memory_search_bm25.py statusFind related entriespython3 scripts/classify_memory.py --related "query" [--top N]Build knowledge graphpython3 scripts/memory_graph.py buildGraph relationspython3 scripts/memory_graph.py related "entity" [--depth N]Graph statspython3 scripts/memory_graph.py statsRaw graph querypython3 scripts/memory_graph.py query "SELECT ..."

Context Compression#

ActionScriptExtract compact (stdin)python3 scripts/compact_session.py --extractWrite compact (stdin)python3 scripts/compact_session.py --writeList compactspython3 scripts/compact_session.py --listRead latest compactpython3 scripts/compact_session.py --latestCompact statspython3 scripts/compact_session.py --stats

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. Search for relevant context:
   • python3 scripts/memory_search_bm25.py build (if index is stale or missing)
   • python3 scripts/memory_search_bm25.py search "current topic" (semantic search)
   • Also use memory_search (OpenClaw built-in tool) as complementary search
3. Check for recent compacts: python3 scripts/compact_session.py --latest
   • If output exists, read it and use relevant parts as context for the session
   • This is a manual agent step — the skill does not auto-inject
4. 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 (Compaction)#

1. Update SESSION-STATE.md with final state
2. If conversation > 50 turns or user says "compact":
   • Draft compact content (decisions, facts, pending, blockers)
   • Pipe through security checks: echo "content" | python3 scripts/compact_session.py --write
   • Include [TYPE] tags per smart-memory classification
3. Promote durable items from daily notes to MEMORY.md

Periodic Maintenance#

• Run memory_decay.py when MEMORY.md > 200 lines or 50+ daily files
• Run classify_memory.py to tag orphaned entries
• Run memory_search_bm25.py update to refresh search index after edits
• Run memory_graph.py build to refresh knowledge graph
• Archive daily files older than 90 days
• Compact auto-cleanup keeps only last 30

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

• extract_memories.sh --auto "text" — keyword matching, zero token cost, fully local

Compaction Mode#

• compact_session.py --extract — regex-based extraction, zero token cost, fully local

Do NOT Extract/Compact#

• Passwords, tokens, API keys, credentials (scripts hard-block these)
• Private conversations about third parties not relevant to work
• Speculation or uncertain information
• Transient state ("user is currently looking at page X")
• Information the user explicitly said not to remember

Scripts#

ScriptLanguagePurposeSecuritysession_state.pyPythonHOT RAM working memory (WAL)Sensitive data filter + sanitizationsession_cache.pyPythonSession-scoped temp cacheSensitive data filter + path-safe IDscompact_session.pyPythonContext compression & digestsPath containment + sensitive filterextract_memories.shBashMemory extraction guide & auto-extractRead-only + sensitive filter (Python)classify_memory.pyPythonKeyword + n-gram type classification, related searchDry-run mode, duplicate checkmemory_decay.pyPythonTemporal decay & LESSON promotionDry-run modememory_health.shBashHealth report (stats, orphans, tokens)Read-onlymemory_search_bm25.pyPythonBM25 semantic search over memoriesLocal-only, zero networkmemory_graph.pyPythonSQLite knowledge graph (entities + relations)Local-only, SELECT-only queries

References#

• references/extraction_prompt.md — Extraction prompt template (for agent-internal use)
• references/compaction_prompt.md — Compaction prompt template (for agent-internal use)
• references/decay_rules.md — Decay/archival rule set
• references/memory_schema.md — Full schema and format spec