OpenClaw Memory Upgrade

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:

CODEBLOCK0

Config explained:

• - mode: "safeguard" — compaction mode that preserves important context
• INLINECODE4 — always keep at least 20K tokens available for the agent to work with
• INLINECODE5 — trigger memory flush when only 4K tokens remain before compaction
• INLINECODE6 — injected as a system message to signal urgency
• INLINECODE7 — 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:

CODEBLOCK1

Config explained:

• - sessionMemory: true — indexes past session transcripts for search
• INLINECODE10 — 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:
CODEBLOCK2

How it works:

• - MEMORY.md — distilled, organized knowledge. Sections for user profile, projects, decisions, preferences, contacts, workflows. Updated periodically.
• INLINECODE12 — 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):
CODEBLOCK3

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:

CODEBLOCK4

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

CODEBLOCK5

Config explained:

• - hybrid search — combines keyword (BM25, weight 0.3) with semantic/vector (weight 0.7) for best of both worlds
• INLINECODE16 — ensures search results are diverse, not 8 near-identical matches. Lambda 0.7 balances relevance vs diversity.
• INLINECODE17 — 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.
• INLINECODE18 — keeps 90 days of session history searchable
• INLINECODE19 — re-indexes memory files every 5 minutes with 15-second debounce
• INLINECODE20 — 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:
CODEBLOCK6

Add to openclaw.json under plugins:

CODEBLOCK7

Config explained:

• - mode: "open-source" — runs locally, no external API calls
• INLINECODE24 — automatically saves important facts from conversations without being told
• INLINECODE25 — automatically searches memory before responding to questions
• INLINECODE26 — builds a knowledge graph of relationships between memories
• INLINECODE27 — returns up to 10 relevant memories per search
• INLINECODE28 — 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:
CODEBLOCK9

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

CODEBLOCK10

Verification

After applying all upgrades, restart the gateway:
CODEBLOCK11

Then verify:
CODEBLOCK12

You should see:

• - Memory: INLINECODE30
• Memory backend: INLINECODE31
• 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