OpenClaw Memory Optimization

Reusable playbook and skill for optimizing any OpenClaw instance running ClawVault. Battle-tested on two production instances.

What's Included

File	Purpose
PLAYBOOK.md	9-phase optimization plan with checklists, templates, and success criteria
skills/memory-maintenance/SKILL.md	OpenClaw skill for weekly automated maintenance sweeps

Results (Production Runs)

Metric	Before	After	Change
Knowledge graph nodes	230	461	+100%
Knowledge graph edges	144	973	+576%
Daily log total size	290 KB	44 KB	-85%
Files with frontmatter	0	100+	--
Files with wiki-links	0	100+	--
People profiles	0	13	--
clawvault doctor errors	multiple	0	clean

Quick Start

One-Time Full Optimization

Follow PLAYBOOK.md phases 0-9 in order. Each phase has a checklist. The most impactful phase is Phase 2 (YAML Frontmatter & Wiki-Links) — it builds the knowledge graph that powers multi-hop context retrieval.

Ongoing Weekly Maintenance

Install the skill into your OpenClaw instance:

cp -r skills/memory-maintenance/ ~/.openclaw/workspace/skills/memory-maintenance/

Then invoke it weekly (or add to HEARTBEAT.md for automatic runs):

/memory-maintenance

Prerequisites

• OpenClaw gateway running with a workspace directory
• ClawVault npm package installed globally (npm i -g clawvault)
• qmd CLI available (bundled with ClawVault)
• Git repo initialized in workspace

Phases Overview

Phase	Name	Goal
0	Safety & Security Backup	Commit dirty state, audit secrets, verify tooling
1	ClawVault Init & Config	Initialize vault, set optimal config, verify env vars
2	YAML Frontmatter & Wiki-Links	Add structured metadata to ALL files (most impactful)
3	File Reorganization	Enforce consistent directory structure
4	People Profiles	Create a profile for every person mentioned
5	Daily Log Trimming	All logs under 2KB, extract detail to destination files
6	MEMORY.md Audit	Keep under 3KB with wiki-link pointers
7	AGENTS.md & HEARTBEAT.md	Add ClawVault lifecycle, memory hygiene rules
8	Rebuild Index & Graph	Re-index, re-embed, rebuild graph
9	Git Commit & Push	Commit and push all changes

Key Concepts

• Wiki-links ([[entity-name]]): THE most important feature. They build the knowledge graph. Must match filenames (lowercase, no .md extension).
• YAML frontmatter: Required on all memory files. Fields: title, type, tags, related, updated.
• Memory tiers: Tier 1 = MEMORY.md (always loaded, <3KB). Tier 2 = daily logs (auto-loaded, <2KB). Tier 3 = everything else (search-only).
• Knowledge graph: Built from wiki-links + frontmatter related arrays. Enables multi-hop context retrieval via clawvault inject.

License

MIT