self-evolving-memory

Orchestrate the OpenClaw memory system so it actually runs reliably in practice. Use when the task involves capturing user preferences, current task state, c...

Security Scan

The skill's files, instructions, and behaviors are consistent with a workspace-oriented memory orchestration tool and do not request unrelated credentials or perform surprising actions.

Purpose & Capability

The skill's name/description (memory orchestration) matches the actual content: templates, routing rules, and a setup script that copies templates and checks embedding config. It does not request unrelated credentials or binaries.

Instruction Scope

SKILL.md and the references confine actions to the user's workspace (creating/templating memory files), reading openclaw.json for memorySearch configuration, and optionally using embedding providers for semantic search. There are no instructions to read arbitrary user files, shell history, or exfiltrate data.

Install Mechanism

There is no install spec; the only executable file is scripts/setup.sh which copies templates and checks configuration (benign). The documentation suggests running external commands to install Ollama (curl | sh) and pulling models; that guidance is optional and carries the usual caution about running remote install scripts.

Credentials

The skill itself requires no environment variables or credentials. Documentation explains how to configure embedding backends which may require API keys (OpenAI or remote Ollama endpoints). Requesting embedding API keys is proportionate to optional embedding features, but users should avoid storing secrets in plain templates or unsecured workspace files.

Persistence & Privilege

The skill is not always-enabled and is user-invocable. It does not modify other skills or system-wide settings beyond copying templates into the user-specified workspace and reading ~/.openclaw/openclaw.json to check config — behavior consistent with its purpose.

Assessment

This skill is coherent and appears to do what it claims: create and manage memory templates and provide routing rules. Before installing or running the setup script, review the templates and scripts (they only copy files and read ~/.openclaw/openclaw.json). Do not run suggested remote install commands (e.g., curl | sh) unless you trust the source; prefer installing embedding backends (like Ollama) via official instructions. Avoid putting API keys or secrets into workspace files; store them in secure config or environment variables per your platform's best practices. If you enable remote embedding providers, verify the remote baseUrl and apiKey targets are trusted. Finally, back up any existing memory files in your workspace before running the setup so nothing is accidentally lost.

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

{
  "memorySearch": {
    "enabled": true,
    "provider": "ollama",
    "model": "nomic-embed-text"
  }
}

Quick config example (OpenAI):

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