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

Security

Sensitive Data Protection

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

Quick Reference

WAL Protocol (Write-Ahead Log)

Critical rule: Write BEFORE responding.

When the user provides information that should be remembered:

1. 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
• INLINECODE36 — Project context, active work, goals
• INLINECODE37 — Technical details, configs, system knowledge
• INLINECODE38 — Lessons learned, errors, corrections
• INLINECODE39 — People, relationships, social context
• INLINECODE40 — Session-scoped, auto-expires

Core Workflows

Session Start

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

Daily Notes

SESSION-STATE.md

Scripts

References

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