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.

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

Quick Reference

Memory Management

Search & Relations

Context Compression

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.

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

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