OpenClaw Memory Upgrade

Complete guide to upgrading OpenClaw's memory system for persistent, searchable context across sessions. Implements 6 upgrades including enhanced memory flus...

Security Scan

The guide generally matches a memory-upgrade purpose but contains instructions that could capture and store sensitive secrets, edits global OpenClaw config files, and asks you to install a plugin without declaring an install plan — these mismatches warrant caution.

Purpose & Capability

The skill's name and description (persistent searchable memory) align with the instructions to add memoryFlush, session indexing, and file-based memory. However, the SKILL.md requires access to and edits of the global openclaw.json and AGENTS.md and asks for npm for a Mem0 plugin while the registry metadata declares no required config paths or install steps. Asking to modify top-level config and to install plugins is more privileged than the registry metadata indicates.

Instruction Scope

The runtime instructions explicitly tell the agent to read and write workspace memory files (MEMORY.md, memory/YYYY-MM-DD.md), modify openclaw.json and AGENTS.md, and index past session transcripts. Critically, the memoryFlush prompt directs extraction of 'TECHNICAL DETAILS (commands, configs, API keys, endpoints, file paths)', which would cause the agent to capture secrets and highly sensitive data into persistent files — this is scope creep beyond ordinary memory capture and is a privacy/security risk.

Install Mechanism

There is no install spec in the registry (instruction-only), but SKILL.md lists 'npm (for Mem0 plugin installation)' as a prerequisite and refers to a Mem0 plugin. The skill gives no vetted install source or package name and does not declare an install plan. Instruction-only distribution reduces direct install risk, but the missing, unverified npm install step is an operational gap and potential vector for supply-chain compromise.

Credentials

The registry declares no required environment variables or credentials, yet the instructions would cause the agent to extract and persist 'API keys' and other technical secrets into memory files. Requesting or instructing capture of secrets without declaring or justifying credential access is disproportionate and dangerous: it enables long-term storage (and possible exfiltration) of secrets in plaintext files.

Persistence & Privilege

always:false and normal autonomous invocation are fine, but the skill's recommended edits are to global OpenClaw config (openclaw.json, AGENTS.md) and creation of persistent memory files. That amounts to changing system-wide agent behavior and persistent data storage — acceptable for a memory upgrade but should be explicit and consented to. The skill does not declare these config paths in metadata, so it grants implicit, broad persistence privilege without transparency.

What to consider before installing

Before installing or applying these instructions: - Review and back up openclaw.json and any AGENTS.md files before making edits; the SKILL.md proposes global config changes. - Remove or edit the 'TECHNICAL DETAILS' category in the memoryFlush prompt so the agent does NOT capture API keys, passwords, private keys, tokens, or other secrets into persistent memory files. Storing secrets in daily logs or MEMORY.md is unsafe. - If you must use a plugin (Mem0), identify the exact npm package name and inspect its source code (or use a vetted package) before running npm install. The skill provides no install spec or trusted URL. - Run changes in a sandbox or dev environment first to observe file I/O and behaviour, and search created memory files for unintended sensitive data. - Limit autonomous invocation until you trust the configuration: consider disabling auto-run of memoryFlush or require explicit user approval for writes. - If you want to proceed, create policies or scripts that redact secrets (API keys, tokens, credentials, private endpoints) from things the agent writes to memory, and consider encrypting persistent memory storage. If you want, I can: (a) produce a redacted memoryFlush prompt that excludes secret capture, (b) generate a safe checklist for reviewing openclaw.json changes, or (c) help draft an explicit install and verification plan for the Mem0 plugin.

Turn your OpenClaw agent from a goldfish into an elephant. This skill implements 6 memory upgrades that give your agent persistent, searchable memory across sessions — so it actually remembers who you are, what you're working on, and what happened yesterday.

The Problem

By default, OpenClaw agents wake up blank every session. Conversations are isolated. Context is lost at compaction. Your agent forgets decisions, preferences, and project status the moment the session ends.

What This Fixes

After applying these upgrades, your agent will:

• Extract and save 8 categories of important information before context is lost
• Search across all past sessions and memory files before answering
• Use hybrid keyword + semantic search with diversity and recency ranking
• Auto-capture and auto-recall memories via the Mem0 plugin
• Maintain curated long-term memory separately from raw daily logs

Prerequisites

• OpenClaw 2026.2.26 or later
• Access to openclaw.json config file
• npm (for Mem0 plugin installation)

---

Upgrade 1: Enhanced memoryFlush Prompt

What it does: When a conversation nears compaction (context window filling up), this automatically scans for 8 categories of important information and writes them to daily memory files before context gets trimmed.

Why it matters: Without this, compaction silently discards conversation details. With it, decisions, preferences, technical details, and more survive compaction.

Add to openclaw.json under agents.defaults.compaction:

{
  "compaction": {
    "mode": "safeguard",
    "reserveTokensFloor": 20000,
    "memoryFlush": {
      "enabled": true,
      "softThresholdTokens": 4000,
      "systemPrompt": "Session nearing compaction. Analyze the conversation and extract durable memories NOW before context is lost.",
      "prompt": "Scan the current conversation and write any of the following to memory/YYYY-MM-DD.md (use today's date):\n\n1. DECISIONS made (with reasoning and context)\n2. USER PREFERENCES or corrections expressed\n3. TECHNICAL DETAILS (commands, configs, API keys, endpoints, file paths)\n4. PROJECT STATUS changes or milestones\n5. PEOPLE mentioned (names, roles, contact info, relationships)\n6. WORKFLOWS or processes described\n7. ERRORS encountered and their solutions\n8. OPINIONS or feedback the user gave\n\nFor each item, include timestamps and enough context that future-you can understand it without the conversation. If nothing meaningful happened, reply with NO_REPLY."
    }
  }
}

Config explained:

• mode: "safeguard" — compaction mode that preserves important context
• reserveTokensFloor: 20000 — always keep at least 20K tokens available for the agent to work with
• softThresholdTokens: 4000 — trigger memory flush when only 4K tokens remain before compaction
• systemPrompt — injected as a system message to signal urgency
• prompt — the actual extraction instructions with 8 categories

---

Upgrade 2: Session Indexing

What it does: Makes past conversation sessions searchable. Without this, each session is a black box once it ends. With it, the agent can search across old conversations to find things discussed days or weeks ago.

Add to agents.defaults.memorySearch:

{
  "memorySearch": {
    "enabled": true,
    "experimental": {
      "sessionMemory": true
    },
    "sources": ["memory", "sessions"]
  }
}

Config explained:

• sessionMemory: true — indexes past session transcripts for search
• sources: ["memory", "sessions"] — searches both memory files AND past sessions

---

Upgrade 3: Manual Memory Management

What it does: Establishes a two-tier file-based memory system that the agent reads at the start of every session.

Structure:

workspace/
  MEMORY.md          ← Curated long-term memory (the agent's brain)
  memory/
    YYYY-MM-DD.md    ← Daily logs (raw notes from each day)

How it works:

• MEMORY.md — distilled, organized knowledge. Sections for user profile, projects, decisions, preferences, contacts, workflows. Updated periodically.
• memory/YYYY-MM-DD.md — raw daily logs. Auto-written by memoryFlush, also written manually by the agent during conversations. One file per day.

Agent instructions (add to AGENTS.md):

## Every Session
1. Read MEMORY.md — this is your long-term brain
2. Read memory/YYYY-MM-DD.md for today + yesterday
3. If something important happens, write it to today's daily file
4. Periodically review daily files and distill key learnings into MEMORY.md
5. Never rely on "mental notes" — if it matters, write it to a file

Key principle: Text > Brain. The agent's memory files ARE its continuity. Without them, it wakes up blank.

---

Upgrade 4: QMD Backend (Hybrid Search)

What it does: Replaces basic memory search with QMD — a hybrid system combining keyword matching (BM25) and semantic understanding (vector embeddings), with diversity ranking and recency bias.

Add to openclaw.json at the top level:

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "update": {
        "interval": "5m",
        "debounceMs": 15000
      },
      "limits": {
        "maxResults": 8,
        "timeoutMs": 5000
      },
      "sessions": {
        "enabled": true,
        "retentionDays": 90
      }
    }
  }
}

Also add the query configuration under agents.defaults.memorySearch:

{
  "memorySearch": {
    "query": {
      "hybrid": {
        "enabled": true,
        "vectorWeight": 0.7,
        "textWeight": 0.3,
        "candidateMultiplier": 4,
        "mmr": {
          "enabled": true,
          "lambda": 0.7
        },
        "temporalDecay": {
          "enabled": true,
          "halfLifeDays": 30
        }
      }
    },
    "cache": {
      "enabled": true,
      "maxEntries": 50000
    }
  }
}

Config explained:

• hybrid search — combines keyword (BM25, weight 0.3) with semantic/vector (weight 0.7) for best of both worlds
• MMR (Maximal Marginal Relevance) — ensures search results are diverse, not 8 near-identical matches. Lambda 0.7 balances relevance vs diversity.
• temporalDecay — recent memories rank higher than old ones. 30-day half-life means a memory from today scores 2x higher than one from a month ago.
• retentionDays: 90 — keeps 90 days of session history searchable
• update interval: 5m — re-indexes memory files every 5 minutes with 15-second debounce
• cache: 50000 entries — caches search results for speed

---

Upgrade 5: Mem0 Plugin (Auto-Capture & Auto-Recall)

What it does: Adds a separate memory layer that automatically captures important information from conversations and automatically recalls relevant memories before the agent responds.

Install:

openclaw plugin install @mem0/openclaw-mem0

Add to openclaw.json under plugins:

{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "mode": "open-source",
          "autoCapture": true,
          "autoRecall": true,
          "enableGraph": true,
          "topK": 10,
          "searchThreshold": 0.5
        }
      }
    }
  }
}

Config explained:

• mode: "open-source" — runs locally, no external API calls
• autoCapture: true — automatically saves important facts from conversations without being told
• autoRecall: true — automatically searches memory before responding to questions
• enableGraph: true — builds a knowledge graph of relationships between memories
• topK: 10 — returns up to 10 relevant memories per search
• searchThreshold: 0.5 — only returns memories above 50% relevance score

Note: Requires the Ollama npm module. If you see errors about missing ollama module, run:

cd ~/.openclaw/extensions/openclaw-mem0 && npm install ollama

---

Upgrade 6: Cognee (Optional — Requires Docker)

What it does: Graph-based memory system for advanced knowledge representation.

Status: Optional. Requires Docker to be running. Also flagged by OpenClaw security audit for environment variable harvesting patterns in its code. Recommended to skip unless you have Docker running AND have audited the plugin source code.

If you want to install it anyway:

openclaw plugin install @cognee/cognee-openclaw

Recommendation: Skip this one. Upgrades 1-5 provide comprehensive memory coverage. Cognee adds complexity without proportional benefit for most setups.

---

How It All Fits Together

Conversation happens
    │
    ├── Mem0 auto-captures important facts (real-time)
    │
    ├── Agent writes to memory/YYYY-MM-DD.md (manual)
    │
    ├── memoryFlush triggers before compaction (automatic, 8 categories)
    │
    └── QMD indexes everything (every 5 min)
            │
            ├── BM25 keyword search
            ├── Vector semantic search
            ├── MMR diversity ranking
            ├── Temporal decay (recent > old)
            └── Session history (90 days)

Next session starts
    │
    ├── Agent reads MEMORY.md + today's daily note
    ├── Mem0 auto-recalls relevant memories
    └── QMD searches across all files + sessions

Verification

After applying all upgrades, restart the gateway:

openclaw gateway restart

Then verify:

openclaw status --deep

You should see:

• Memory: enabled (plugin openclaw-mem0)
• Memory backend: qmd
• Session indexing: active

Test by telling your agent something specific, ending the session, starting a new one, and asking about it. If the memory system is working, it should find it.

Estimated Token Overhead

The memory system adds minimal overhead:

• memoryFlush: ~2,000-5,000 tokens per compaction event (only when needed)
• Mem0 auto-recall: ~500-1,000 tokens per query (injected relevant memories)
• QMD search: runs server-side, no token cost
• File reading (MEMORY.md + daily notes): depends on file size, typically 2,000-8,000 tokens at session start