Memory Tools

Agent-controlled persistent memory for OpenClaw.

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
• Semantic Search: Vector-based similarity via LanceDB
• Hybrid Storage: SQLite (debuggable) + LanceDB (fast vectors)
• 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

Standard (systemd):

openclaw gateway restart

Docker (no systemd):

# Kill existing gateway
pkill -f openclaw-gateway

# Start in background
nohup openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &

Requirements

• OPENAI_API_KEY environment variable (for embeddings)

Memory Categories

| Category | Use For | Example |

|----------|---------|---------|

| fact | Static information | "User's dog is named Rex" |

| preference | Likes/dislikes | "User prefers dark mode" |

| event | Temporal things | "Dentist Tuesday 3pm" |

| relationship | People connections | "Sarah is user's wife" |

| instruction | Standing orders | "Always respond in Spanish" |

| decision | Choices made | "We decided to use PostgreSQL" |

| context | Situational info | "User is job hunting" |

| entity | Named things | "Project Apollo is their startup" |

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

Debugging

Inspect what your agent knows:

sqlite3 ~/.openclaw/memory/tools/memory.db "SELECT id, category, content FROM memories"

Export all memories:

openclaw memory-tools export > memories.json

Troubleshooting

"Database connection not open" error:

• Hard restart the gateway: pkill -f openclaw-gateway
• Check permissions: chown -R $(whoami) ~/.openclaw/memory/tools

Plugin not loading:

• Verify build: ls skills/memory-tools/dist/index.js
• Check doctor: openclaw doctor --non-interactive

License

MIT — Purple Horizons