purple-horizons/memory-tools/memory-tools

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

clawhub install memory-tools

Step 2: Build the plugin

cd skills/memory-tools
npm install
npm run build

Step 3: Activate the plugin

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

Step 4: Restart the gateway

openclaw gateway restart

Optional: Install QMD for better search

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 does not override the base system prompt by default. before_agent_start uses prependContext only.
• allowSystemPromptOverride exists as an explicit compatibility opt-in and defaults to false.
• The plugin can auto-migrate legacy v1 data from ~/.openclaw/memory/tools/memory.db when autoMigrateLegacy=true.
• Defaults are conservative: autoInjectInstructions, autoMigrateLegacy, and allowSystemPromptOverride are all false.

Storage Format

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

~/.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:

---
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

Tool Reference

memory_store

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

memory_search

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

memory_update

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

memory_forget

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

memory_summarize

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

memory_list

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

CLI Commands

# 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:

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

Export all memories:

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