Smart Memory (Zero Dep)

Enhanced memory system for agentic workflows. Automatic memory extraction from conversations, memory type classification (preference/project/technical/lesson...

Security Scan

The skill's files, scripts, and runtime instructions align with its stated purpose (local memory extraction, tagging, WAL-backed session state) and request no external credentials or network access, though there are a few small inconsistencies and conservative implementation assumptions you should be aware of.

Purpose & Capability

Overall coherent: name/description (memory extraction, tagging, decay, session cache) matches the included scripts (session_state.py, session_cache.py, extract_memories.sh, classify_memory.py, memory_decay.py, memory_health.sh). Minor inconsistency: registry metadata lists "Required binaries: none" but SKILL.md explicitly requires Python 3.10+ and Bash 4+. Also the package was marked "instruction-only" in install spec but includes multiple executable scripts — this is fine but worth noting as a mismatch between metadata and bundled files.

Instruction Scope

Instructions stay within the stated domain (local writes to ~/.openclaw/workspace and /tmp, no network endpoints). They direct the agent to write WAL entries before responding, run local classification/decay/health scripts, and optionally use the agent's own LLM for higher-quality extraction. Caution: the WAL requirement means the agent will persist extracted text before responding — if extraction misclassifies sensitive text, it may be written locally. The scripts implement regex-based blocking for common key/token patterns, but those checks are heuristic and can miss exotic credential formats.

Install Mechanism

No install spec — scripts are included and run directly. No external downloads or package installs. This is low-risk from an installation perspective (nothing downloaded/executed from remote URLs).

Credentials

The skill requests no secrets or privileged environment variables. SKILL.md documents two optional environment variables (OPENCLAW_WORKSPACE, OPENCLAW_SESSION_ID) used to locate workspace and session cache — these are reasonable and proportional to the functionality.

Persistence & Privilege

The skill writes and modifies files inside a user-local workspace (~/.openclaw/workspace) and /tmp session caches, which is expected for a memory system. always:false (normal). Because the agent is expected to autonomously invoke these scripts (disable-model-invocation: false by default), the skill can autonomously persist data to disk — this is expected for a memory plugin but increases blast radius if the agent is misconfigured or hostile.

Assessment

This skill appears to do what it says: local memory extraction, tagging, decay, and a session WAL. Before installing or enabling: 1) ensure Python 3.10+ and Bash 4+ are available (metadata omitted these but scripts require them), 2) back up any existing ~/.openclaw/workspace data (scripts will read/modify these files), 3) review/adjust OPENCLAW_WORKSPACE if you want files stored elsewhere, 4) understand the WAL rule (the agent will write remembered text to disk before replying) — if you worry about accidental persistence of secrets, test extraction on non-sensitive sample data and review the regex patterns that block tokens/keys, and 5) if you want to limit risk, disable autonomous invocation for the skill or run it in a sandboxed account until you’re comfortable with behavior.

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