Skill: hal-9909/self-evolving-memory (version 1.0.0)

--- name: self-evolving-memory description: > Orchestrate the OpenClaw memory system so it actually runs reliably in practice. Use when the task involves capturing user preferences, current task state, corrections, decisions, recurring issues, memory cleanup, memory migration, or deciding where information should live across the workspace memory layers, including hot state, daily memory, structured long-term memory, root summary, and enforcement files such as SOUL.md, AGENTS.md, and TOOLS.md. Also use when the user asks to save memory, remember something, adapt old memories to the new system, or make the memory system actually stick and keep working over time. --- # Memory Orchestrator This skill is the workflow layer for the memory system. It does **not** replace memory storage. It decides **what to capture, where to route it, when to promote it, and when to harden it**. ## Source of truth Use this order: 1. `MEMORY.md` + `memory/` = formal memory ledger 2. `SESSION-STATE.md` = current task state only 3. `.learnings/` = auxiliary scratch/noise layer only 4. vector recall = derived index, never source of truth Never create a second formal ledger. ## Memory layers ### 1) Hot state Use `SESSION-STATE.md` for: - current task - current blocker - next actions - recent decision needed for immediate continuity - handoff / anti-compaction notes Do **not** store durable history here. ### 2) Daily working memory Use `memory/YYYY-MM-DD.md` for: - user corrections - task outcomes - debugging notes - temporary conclusions - short self-reflection after non-trivial work - observations that are not yet stable enough for long-term memory ### 3) Structured long-term memory Route stable items to: - `memory/preferences.md` — user preferences / communication style / stable likes-dislikes - `memory/system.md` — stable environment facts / endpoints / toolchain constraints / paths - `memory/projects.md` — long-running project context / decisions / status - `memory/MEMORY.md` — cross-cutting long-term stable conclusions ### 4) Root summary Use root `MEMORY.md` only for the few high-value facts worth automatic injection every session. Keep it short. ### 5) Enforcement layer If a recurring problem should change future behavior, also update one or more of: - `SOUL.md` - `AGENTS.md` - `TOOLS.md` - relevant `SKILL.md` - relevant script/hook ## Embedding / vector recall setup This skill supports semantic memory search via `memory_search`. Multiple embedding backends are supported. See `references/embedding-setup.md` for full configuration: - **Ollama** (local, recommended for privacy): `nomic-embed-text`, `mxbai-embed-large`, etc. - **OpenAI Embeddings**: `text-embedding-3-small` / `text-embedding-3-large` - **OpenAI-compatible APIs**: LocalAI, LM Studio, third-party providers - **No embedding**: Rule-based routing still works without vector recall Quick config example (Ollama, local): ```json { "memorySearch": { "enabled": true, "provider": "ollama", "model": "nomic-embed-text" } } ``` Quick config example (OpenAI): ```json { "memorySearch": { "enabled": true, "provider": "openai", "model": "text-embedding-3-small", "remote": { "baseUrl": "https://api.openai.com/v1", "apiKey": "YOUR_OPENAI_API_KEY" } } } ``` ## First-run setup check When this skill is triggered for the **first time**, or when the user asks to "set up" / "initialize" / "check" the memory system, run this setup check: ### Auto-detect missing files Check the current workspace for these files. If any are missing, create them from templates OR tell the user exactly which command to run: **Required files:** ``` SESSION-STATE.md → templates/SESSION-STATE.md MEMORY.md → templates/MEMORY.md HEARTBEAT.md → templates/HEARTBEAT.md memory/preferences.md → templates/memory/preferences.md memory/system.md → templates/memory/system.md memory/projects.md → templates/memory/projects.md memory/MEMORY.md → templates/memory/MEMORY.md ``` **Recommended agent files (prompt user to create if missing):** ``` SOUL.md — add memory discipline section (see references/setup-checklist.md Step 3) AGENTS.md — add memory closeout protocol TOOLS.md — add memory-related tool discipline ``` **Action:** - If files are missing: create them automatically, then confirm to the user what was created. - If agent files (SOUL.md etc.) are missing: warn the user and point to `references/setup-checklist.md`. - If embedding is not configured: remind user to check `references/embedding-setup.md`. ### One-command setup Tell the user they can also run the setup script: ```bash bash scripts/setup.sh [optional-workspace-path] ``` This will copy all templates and report what's missing. ## Runtime protocol For the concrete operating protocol, read: - `references/runtime-protocol.md` Use that reference when the memory system needs to **operate reliably over time**, not just route one memory item. For setup and initialization: - `references/setup-checklist.md` — step-by-step first-time setup - `scripts/setup.sh` — automated setup script For embedding setup options, read: - `references/embedding-setup.md` ## Routing rules ### A. User says "remember this" / gives a durable preference - Write to `memory/YYYY-MM-DD.md` - If clearly stable, also write to `memory/preferences.md` or other structured file - If it must shape every session, also reflect it in root `MEMORY.md` or enforcement files ### B. Current task state changes Before or during longer work, update `SESSION-STATE.md` with: - current task - key context - pending actions - blockers Use hot state for continuity, not archiving. ### C. Error / correction / better approach discovered - Log to `memory/YYYY-MM-DD.md` - If it is noisy or needs raw staging, optionally also log to `.learnings/` - If recurring or broadly applicable, promote to structured memory and/or enforcement layer ### D. Stable system fact discovered - Daily first - Then `memory/system.md` - Only put in root `MEMORY.md` if it is worth automatic injection every session ### E. Project decision / project context - Daily first - Then `memory/projects.md` - If very stable and cross-project, also `memory/MEMORY.md` ## Promotion / hardening state machine Use this mental model: - `observed` → captured in `SESSION-STATE.md` or daily - `curated` → moved into structured long-term memory - `hardened` → promoted into SOUL / AGENTS / TOOLS / skill / script - `stable` → repeatedly validated, remains in long-term memory until marked stale Rule: - If the same issue appears **2+ times**, or the user is clearly annoyed, do not stop at memory. Harden it. ## Hygiene workflow When asked to clean memory, adapt old memory, or audit the system: 1. Check whether old daily files contain content that already lives in structured memory 2. Add "converged/migrated/stale" style notes when appropriate 3. Ensure root `MEMORY.md` remains summary-only 4. Check `SESSION-STATE.md` is not stale or pretending to be long-term memory 5. Check `.learnings/` is not drifting into primary-ledger status 6. Check recall/reference docs still point to the new architecture ## When NOT to over-store Do not promote every temporary detail. Good memory systems are selective. If uncertain, prefer: - `SESSION-STATE.md` for immediate continuity - `memory/YYYY-MM-DD.md` for tentative notes - structured long-term only after stability is clear ## Trigger phrases / situations Use this skill when the user asks or implies any of: - remember / save memory / note this down - adapt old memory / migrate memory / converge old memory - memory cleanup / memory hygiene / memory system optimization - current task state / handoff / anti-compaction continuity - recurring issue / repeated annoyance / make it stick - where should this memory go? - should this be promoted to SOUL / AGENTS / TOOLS? ## Expected output style Keep replies short. Actually perform the routing/editing work. Do not just say memory was saved — save it. Do not ask for permission again when the memory action is already clear. ## Reliability requirements For non-trivial memory operations, do not stop at classification. Make sure the system actually advances: - update `SESSION-STATE.md` when current continuity matters - update `memory/YYYY-MM-DD.md` for daily capture - promote stable items to structured long-term memory - harden recurring issues into the enforcement layer - use the closeout protocol from `references/runtime-protocol.md` when a task or phase ends If any of these are skipped, the memory system is only partially operating.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)