Memory Tools v2#

Agent-controlled persistent memory for OpenClaw.

What's New in v2#

• File-based storage — Memories stored as readable markdown files
• No external APIs — No OpenAI dependency, everything runs locally
• QMD search (optional) — BM25 + vector + reranking via local GGUF models
• Auto-migration — Seamlessly upgrades from v1 SQLite/LanceDB storage

Why Memory-as-Tools?#

Traditional memory systems auto-capture everything, flooding context with irrelevant information. Memory Tools follows the AgeMem approach: the agent decides when to store and retrieve memories.

Features#

• 6 Memory Tools: memory_store, memory_update, memory_forget, memory_search, memory_summarize, memory_list
• Confidence Scoring: Track how certain you are (1.0 = explicit, 0.5 = inferred)
• Importance Scoring: Prioritize critical instructions over nice-to-know facts
• Decay/Expiration: Temporal memories automatically become stale
• Human-readable storage: Markdown files with YAML frontmatter
• Conflict Resolution: New info auto-supersedes old (no contradictions)

Installation#

Step 1: Install from ClawHub#

bash

clawhub install memory-tools

Step 2: Build the plugin#

bash

cd skills/memory-tools
npm install
npm run build

Step 3: Activate the plugin#

bash

openclaw plugins install --link .
openclaw plugins enable memory-tools

Step 4: Restart the gateway#

bash

openclaw gateway restart

Optional: Install QMD for better search#

bash

npm install -g @tobilu/qmd

Without QMD, basic filtering works. With QMD, you get semantic search (BM25 + vector + reranking).

Node Compatibility (QMD)#

• QMD may not be compatible with the newest Node ABI immediately.
• If QMD fails (for example NODE_MODULE_VERSION mismatch), memory-tools falls back to basic mode.
• To force basic mode: MEMORY_TOOLS_DISABLE_QMD=true.
• For best QMD stability, use a Node LTS version supported by your installed QMD build.

Security Model#

• No API keys or external credentials are required.
• Data is stored locally in ~/.openclaw/memories (or configured memoriesPath).
• The plugin can prepend standing-instruction context at before_agent_start when autoInjectInstructions=true.
• The plugin can auto-migrate legacy v1 data from ~/.openclaw/memory/tools/memory.db when autoMigrateLegacy=true.
• Defaults are conservative: both autoInjectInstructions and autoMigrateLegacy are false.

Storage Format#

Memories are stored as markdown files in ~/.openclaw/memories/:

text

~/.openclaw/memories/
├── facts/
│   └── abc123-def4-5678-90ab-cdef12345678.md
├── preferences/
│   └── def456-7890-abcd-ef12-345678901234.md
├── instructions/
│   └── ghi789-0abc-def1-2345-678901234567.md
└── .deleted/
    └── old-memory.md

Each memory file:

markdown

---
id: abc123-def4-5678-90ab-cdef12345678
category: preference
confidence: 0.9
importance: 0.7
created_at: 2024-01-15T10:30:00Z
tags: [ui, settings]
---

User prefers dark mode in all applications.

Memory Categories#

CategoryUse ForExamplefactStatic information"User's dog is named Rex"preferenceLikes/dislikes"User prefers dark mode"eventTemporal things"Dentist Tuesday 3pm"relationshipPeople connections"Sarah is user's wife"instructionStanding orders"Always respond in Spanish"decisionChoices made"We decided to use PostgreSQL"contextSituational info"User is job hunting"entityNamed things"Project Apollo is their startup"

Tool Reference#

memory_store#

text

memory_store({
  content: "User prefers bullet points",
  category: "preference",
  confidence: 0.9,
  importance: 0.7,
  tags: ["formatting", "communication"]
})

memory_search#

text

memory_search({
  query: "formatting preferences",
  category: "preference",
  limit: 10
})

memory_update#

text

memory_update({
  id: "abc123",
  content: "User now prefers numbered lists",
  confidence: 1.0
})

memory_forget#

text

memory_forget({
  query: "bullet points",
  reason: "User corrected preference"
})

memory_summarize#

text

memory_summarize({
  topic: "user's work projects",
  maxMemories: 20
})

memory_list#

text

memory_list({
  category: "instruction",
  sortBy: "importance",
  limit: 20
})

CLI Commands#

bash

# Show memory statistics
openclaw memory-tools stats

# List memories
openclaw memory-tools list
openclaw memory-tools list --category fact

# Search memories (requires QMD)
openclaw memory-tools search "dark mode"

# Export all memories as JSON
openclaw memory-tools export

# Force re-index with QMD
openclaw memory-tools reindex

# Show storage path
openclaw memory-tools path

Debugging#

Memories are plain markdown files — just read them:

bash

cat ~/.openclaw/memories/facts/*.md
ls ~/.openclaw/memories/

Export all memories:

bash

openclaw memory-tools export > memories.json

Migration from v1#

v2 automatically detects v1 databases and migrates them:

1. On startup, v2 checks for ~/.openclaw/memory/tools/memory.db
2. If found, exports all memories to markdown files
3. Original database preserved as backup
4. No manual action required

To enable auto-migration, set autoMigrateLegacy: true in plugin config.

License#

MIT — Purple Horizons