OpenClaw Memory

Manage, optimize, and troubleshoot the OpenClaw memory system — MEMORY.md curation, daily logs (memory/YYYY-MM-DD.md), memory_search tuning, compaction survi...

Security Scan

The skill's instructions match its stated purpose (managing OpenClaw memory files) but include opaque, autonomous behaviors (silent background flushes that write conversation content to disk) and reference provider API keys without declaring them — these practices raise privacy and transparency concerns.

Purpose & Capability

The name/description align with the instructions: the skill is about managing MEMORY.md, daily logs, memory_search/memory_get, compaction, and embedding providers. Access to ~/.openclaw/workspace and memory files is appropriate for this purpose. The SKILL does reference embedding providers and API keys as selectable backends, which is consistent with a memory/search capability.

Instruction Scope

The instructions explicitly direct the agent to read and write workspace memory files (MEMORY.md, memory/YYYY-MM-DD.md) and to perform an autonomous 'memory flush' before compaction. The flush is described as 'silent' (agent replies with NO_REPLY) so the user would not see those background writes. The skill also instructs editing AGENTS.md to mandate memory_search before acting. These behaviors are within the stated domain but are broad: they persist conversation content to disk (possibly including secrets), modify agent behavior, and perform hidden actions without explicit user-visible confirmation.

Install Mechanism

Instruction-only skill with no install spec and no code files. This minimizes installation risk (nothing is downloaded or written by an installer).

Credentials

The registry metadata lists no required env vars or credentials, which is consistent with being an instruction-only helper. However the instructions reference selecting embedding providers (openai, gemini, voyage, mistral, local) based on available API keys; those keys are not declared as required. That is not necessarily malicious, but it's a mismatch between declared requirements and runtime expectations: the skill may behave differently if provider keys exist and can read/use them if the agent environment exposes them.

Persistence & Privilege

always:false (good), but the skill encourages persistent changes to workspace files (MEMORY.md, AGENTS.md) and autonomous behavior (automatic memory flushes triggered before compaction). Because default platform behavior allows autonomous invocation, the combination of autonomous, silent writes and instructions to make retrieval mandatory increases the privacy/operational blast radius. The skill does not request system-wide privileges, but it requests persistent modification of user-visible configuration and data files.

What to consider before installing

This skill appears to do what it says (manage OpenClaw memory files), but it instructs the agent to write conversation content to files and to perform 'silent' background flushes that the user won't see. Before installing or enabling it: (1) Decide whether you want the agent to persist chat content to ~/.openclaw/workspace (may include sensitive info). (2) If you do not want silent writes, set workspaceAccess to read-only or disable memoryFlush in your config. (3) Review any automatic edits it suggests to AGENTS.md or MEMORY.md before applying. (4) If you use provider API keys (OpenAI, Gemini, etc.), be aware the skill references them although it does not declare them; ensure only intended keys are available. If you want lower risk, test the skill in an isolated account or environment and audit the memory files it creates.

OpenClaw Memory — Setup, Optimization & Troubleshooting

Core Principle

OpenClaw memory is plain Markdown on disk. The files are the single source of truth. The model only "remembers" what gets written to disk — nothing stays in RAM between sessions. Memory search tools are provided by the active memory plugin (default: memory-core).

---

1. Memory Architecture (Two Layers)

Layer 1: Daily Logs — memory/YYYY-MM-DD.md

• Append-only session notes, running context, events of the day.
• OpenClaw reads today + yesterday at session start.
• If someone says "remember this" → write it here immediately.
• These accumulate over time; old logs are searchable via memory_search.

Layer 2: Long-Term Memory — MEMORY.md

• Curated durable facts: decisions, preferences, iron-law rules, project context.
• Loaded at session start in private/main sessions only (never in group contexts).
• If both MEMORY.md and memory.md exist, only MEMORY.md is loaded.
• Keep it short — anything not needed every session belongs in daily logs.
• Files over ~20,000 characters get truncated (bootstrapMaxChars).
• Combined bootstrap cap: ~150,000 characters across all workspace files.

Workspace Layout

~/.openclaw/workspace/
├── MEMORY.md              # Long-term curated memory (main session only)
├── memory/
│   ├── 2026-03-17.md      # Today's daily log
│   ├── 2026-03-16.md      # Yesterday's log (also auto-loaded)
│   └── ...                # Older logs (searchable, not auto-loaded)
├── AGENTS.md              # Operating manual, boot sequence
├── SOUL.md                # Persona, tone, values
├── USER.md                # Human profile
└── TOOLS.md               # Environment-specific config

What Goes Where

Content Type	Destination	Why
Durable decisions & preferences	MEMORY.md	Loaded every session
Iron-law rules the agent must always follow	MEMORY.md	Survives compaction
Today's work notes, events, context	memory/YYYY-MM-DD.md	Append-only log
One-time instructions	Chat (or daily log)	Ephemeral by design
Behavioral rules	AGENTS.md or SOUL.md	Always in context

---

2. Memory Tools

OpenClaw exposes two agent-facing tools:

memory_search — Semantic Recall

• Searches across all indexed memory files (MEMORY.md + daily logs).
• Returns snippet text (~700 chars max), file path, line range, score.
• Uses hybrid search: vector similarity + BM25 keyword matching.
• Vector finds paraphrases ("deployment process" matches "how we ship code").
• BM25 finds exact tokens (IDs, env vars, error strings, code symbols).
• Results are ranked by weighted fusion: finalScore = vectorWeight × vectorScore + textWeight × textScore.

memory_get — Targeted File Read

• Reads a specific memory file by path + optional line range.
• Degrades gracefully if file doesn't exist (returns empty text, no error).
• Use when you know exactly which file has the information.

Best Practice: Make Retrieval Mandatory

Add this rule to AGENTS.md:

## Memory Protocol
- ALWAYS run memory_search before acting on tasks that reference past context.
- Do NOT guess from conversation history alone — check your notes.

Without this, the agent guesses instead of checking its memory files.

---

3. Compaction & Memory Flush

The Problem

Long conversations fill the context window. When it hits the threshold, OpenClaw compacts (summarizes/truncates) older messages. Anything only in the conversation — including instructions typed in chat — can vanish.

The Safety Net: Automatic Memory Flush

Before compaction fires, OpenClaw triggers a silent agentic turn that reminds the model to write durable notes to disk.

Default config:

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

Key Points

• Soft threshold: flush triggers at contextWindow - reserveTokensFloor - softThresholdTokens.
• One flush per compaction cycle (tracked in sessions.json).
• Silent: agent replies with NO_REPLY so user doesn't see it.
• Requires writable workspace: skipped if workspaceAccess: "ro" or "none".
• Verify it's working: check config and ensure memoryFlush.enabled = true with enough buffer.

Survival Rules

1. Put durable rules in files, not chat. MEMORY.md and AGENTS.md survive compaction.
2. Verify memory flush is enabled and has enough buffer to trigger.
3. Make retrieval mandatory via AGENTS.md rules.

---

4. Vector Memory Search Configuration

Embedding Providers (auto-selection order)

1. local — if memorySearch.local.modelPath is configured + file exists
2. openai — if OpenAI API key is available
3. gemini — if Gemini API key is available
4. voyage — if Voyage API key is available
5. mistral — if Mistral API key is available
6. Disabled if none configured

Also supported: ollama (local/self-hosted, not auto-selected).

Important: Codex OAuth covers only chat/completions — it does NOT work for embeddings. You need a separate API key for your embedding provider.

Hybrid Search Config

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small",
        "query": {
          "hybrid": true
        }
      }
    }
  }
}

Indexing Details

• Chunks: ~400 token target, 80-token overlap.
• Storage: per-agent SQLite at ~/.openclaw/memory/<agentId>.sqlite.
• File watcher: debounce 1.5s, re-indexes on change.
• Auto-reindex when provider/model/chunking params change.

---

5. Advanced: Post-Processing Pipeline

Vector + Keyword → Weighted Merge → Temporal Decay → Sort → MMR → Top-K Results

Temporal Decay (Recency Boost)

Old notes can outrank recent ones by raw similarity. Enable decay to fix this:

• Applies exponential multiplier based on age.
• Today's note (score 0.82 × 1.00 = 0.82) beats a 148-day-old note (score 0.91 × 0.03 = 0.03).
• When to enable: months of daily notes where stale info outranks current context.

MMR Re-Ranking (Diversity)

Near-duplicate daily logs can crowd out diverse results. MMR removes redundancy:

• Penalizes results too similar to already-selected ones.
• When to enable: memory_search returns redundant/near-duplicate snippets.

---

6. QMD Backend (Experimental)

For power users who want better search quality:

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "update": { "interval": "5m", "debounceMs": 15000 },
      "limits": { "maxResults": 6, "timeoutMs": 4000 },
      "paths": [
        { "name": "docs", "path": "~/notes", "pattern": "**/*.md" }
      ]
    }
  }
}

• QMD combines BM25 + vectors + reranking locally via Bun + node-llama-cpp.
• Requires separate install: bun install -g https://github.com/tobi/qmd.
• Falls back to builtin SQLite if QMD fails or is missing.
• First search may be slow (downloads GGUF models on first run).
• Session indexing available: memory.qmd.sessions.enabled = true.

---

7. Additional Memory Paths

Index files outside the default workspace:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"]
      }
    }
  }
}

• Directories scanned recursively for .md files.
• Symlinks ignored.
• Multimodal indexing (images/audio) available with Gemini Embedding 2.

---

8. Troubleshooting

Diagnosis: Always Start Here

Run /context list in your OpenClaw session to check:

• Is MEMORY.md loading? If "missing" → not in context → zero effect.
• Is anything TRUNCATED? Files over 20,000 chars get cut.
• Do injected chars match raw chars? If not → content is being trimmed.

Common Problems

Symptom	Cause	Fix
Agent "forgot" a rule	Rule was in chat, not a file	Move to MEMORY.md or AGENTS.md
memory_search returns nothing	Embedding provider not configured	Set API key for openai/gemini/ollama
memory_search returns stale results	No temporal decay	Enable decay in memorySearch config
memory_search returns duplicates	No MMR re-ranking	Enable MMR diversity filter
MEMORY.md not loading	File too large or in group session	Trim file; check session type is private
401 errors on search	Wrong/missing embedding API key	Set correct key (Codex OAuth won't work)
Agent loses context mid-conversation	Compaction wiped it	Enable memoryFlush; put rules in files

Health Check Checklist

1. MEMORY.md exists and is < 10,000 chars (ideal) or < 20,000 chars (max)
2. memory/ directory exists with recent daily logs
3. memoryFlush.enabled = true in compaction config
4. Embedding provider is configured and API key is valid
5. AGENTS.md includes "search memory before acting" rule
6. Run wc -c ~/.openclaw/workspace/*.md to audit file sizes

---

9. Memory Plugins (External)

For users who need memory beyond the built-in system:

Mem0 (@mem0/openclaw-mem0)

• Stores memory outside the context window → survives compaction.
• Auto-Capture: extracts facts from conversations automatically.
• Auto-Recall: injects relevant memories before every response.
• Separates long-term (user-scoped) and short-term (session-scoped) memory.
• Cloud or self-hosted (Ollama + Qdrant + any LLM).

Cognee (Knowledge Graph)

• Adds relational reasoning to memory ("Alice manages auth team" → graph traversal).
• Scans memory files on startup, syncs after each session.
• Good for: cross-project context, "who should I talk to about X?" queries.
• Requires Docker for the Cognee server.

Supermemory (openclaw-supermemory)

• Cloud-based persistent memory with user profiles.
• Custom container routing (work vs personal).
• No local infrastructure required.

---

10. Memory Maintenance Routine

Weekly

• Review MEMORY.md — remove outdated facts, promote important daily-log entries.
• Check daily logs aren't growing excessively large.

Monthly (Memory Distillation)

• Scan memory/*.md for recurring patterns and hard-won rules.
• Promote mature rules to MEMORY.md or to skill SKILL.md files.
• Archive old daily logs (> 30 days) if desired.

Backup

cd ~/.openclaw/workspace
git init  # if not already
git add memory/ MEMORY.md
git commit -m "Memory backup $(date +%Y-%m-%d)"

Exclude: ~/.openclaw/credentials/ and openclaw.json (contain secrets).

---

Quick Reference: File Priority

File	Loaded When	Scope	Survives Compaction
AGENTS.md	Every session start	All sessions	✅ Yes
SOUL.md	Every session start	All sessions	✅ Yes
MEMORY.md	Session start (private only)	Main session	✅ Yes
memory/today.md	Session start	Main session	✅ Yes
memory/yesterday.md	Session start	Main session	✅ Yes
memory/older.md	Via memory_search only	On-demand	✅ Yes
Chat instructions	During conversation	Current context	❌ No