Smart Memory

Credential Fixture Review

python scripts/_secrets_inline.py is review material for the Smart Memory skill. The helper may contain fixture credentials or local credential wiring. Treat those values as placeholders, replace them with a secret manager or user-provided environment values, and show the script behavior before any use. Do not contact external services with embedded sample credentials.

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

Quick Reference

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

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