OpenClaw Memory — Agent Skill
MongoDB-backed long-term memory with Voyage AI semantic search
When to Use
Use OpenClaw Memory when:
- ✅ You need to recall prior conversations, decisions, or preferences
- ✅ Building context across multiple sessions
- ✅ Tracking facts, insights, or learnings over time
- ✅ Searching for relevant information semantically (not just keywords)
- ✅ Remembering user preferences, project details, or domain knowledge
NOT for:
- ❌ Immediate/short-term context (use conversation history instead)
- ❌ Temporary scratch notes (use files in workspace)
- ❌ Large document storage (use file system or database)
Available Tools
memory_search
Semantically search long-term memory. Use this to recall prior decisions, preferences, context, or facts.
memory_search({
query: "What did we decide about the database schema?",
maxResults: 6 // optional, default: 6
})
Returns: Array of memories with similarity scores, text, tags, and metadata.
When to use:
- Before answering questions about past work
- When user asks "remember when..." or "what did we say about..."
- To check for existing context before making new decisions
- When solving similar problems to past ones
Example output:
{
"results": [
{
"id": "507f1f77bcf86cd799439011",
"text": "Decided to use MongoDB for vector storage with Atlas Search",
"score": 0.89,
"tags": ["decision", "database"],
"createdAt": "2026-02-20T14:30:00Z"
}
]
}
memory_remember
Store a fact, decision, preference, or important context in long-term memory.
memory_remember({
text: "User prefers TypeScript over JavaScript for new projects",
tags: ["preference", "programming"], // optional
ttl: 2592000 // optional, 30 days default
})
Returns: Stored memory ID and confirmation.
When to use:
- After important decisions are made
- When user states a preference ("I prefer X over Y")
- Key facts or insights discovered during work
- Context that should persist across sessions
- User explicitly asks you to remember something
Best practices:
- Be specific and concise (1-2 sentences ideal)
- Include relevant tags for categorization
- Don't store temporary/ephemeral information
- Use structured format when possible (e.g., "Key: value")
memory_get
Read a specific memory file from the workspace. Use memory_search for semantic recall; use this for targeted file reads.
memory_get({
path: "MEMORY.md",
from: 1, // optional, starting line
lines: 50 // optional, number of lines
})
Returns: File contents (text).
When to use:
- After memory_search to get full context
- Reading structured memory files (MEMORY.md, memory/YYYY-MM-DD.md)
- Targeted line-range reads for efficiency
memory_forget
Delete a specific memory by ID. Use memory_search first to find the memory ID.
memory_forget({
memoryId: "507f1f77bcf86cd799439011"
})
Returns: Confirmation or error.
When to use:
- User explicitly asks to delete/forget something
- Correcting incorrect memories
- Removing outdated information
- Never use proactively without user request
memory_list
Browse stored memories by recency or tag.
memory_list({
tags: "decision,database", // optional, comma-separated
limit: 10, // optional, default: 10
sort: "desc" // optional, "desc" or "asc"
})
Returns: Array of memories with metadata (no similarity scores).
When to use:
- Browsing recent memories
- Filtering by specific tags
- Audit/review of stored memories
- When user asks "what have you remembered?"
memory_status
Check memory system health and stats.
memory_status()
Returns: Daemon status, MongoDB connection, Voyage AI status, total memories, uptime.
When to use:
- Debugging memory system issues
- User asks about memory capacity or health
- Before relying on memory for critical tasks
- Rarely needed in normal operation
Configuration
Memory tools connect to a daemon at http://localhost:7654 by default. Configuration is set in ~/.openclaw/openclaw.json:
{
plugins: {
entries: {
"openclaw-memory": {
enabled: true,
config: {
daemonUrl: "http://localhost:7654",
agentId: "openclaw",
maxResults: 6,
minScore: 0.5,
defaultTtl: 2592000 // 30 days
}
}
}
}
}
Automatic Memory Capture
OpenClaw Memory includes lifecycle hooks that capture memories automatically:
auto-remember Hook
Fires after every agent response. Extracts facts, decisions, and preferences using pattern matching:
- "I prefer..." → stored as preference
- "We decided..." → stored as decision
- "Remember that..." → stored as fact
- "Key: value" patterns (structured data)
Limits: Max 5 extractions per message, min 10 chars, deduplicates.
session-to-memory Hook
Fires when starting a new session. Summarizes the ending session and stores it as a searchable memory.
memory-bootstrap Hook
Fires on agent startup. Queries for relevant memories (preferences, recent decisions, pinned items) and injects them into context.
memory-enriched-tools Hook
Fires before tool results are saved. Appends related memories as context annotations to Read/Grep/Glob/Bash outputs.
To disable hooks: Set hooksEnabled: false in plugin config.
Workflow Examples
Example 1: Recall Prior Decision
User asks: "What did we decide about the API authentication?"
Agent response:
- Call
memory_search({ query: "API authentication decision" })
- Review results
- Answer based on stored memory
- If no results, say "I don't have any memory of that decision"
Example 2: Store Preference
User says: "I prefer Material UI over Tailwind for all React projects"
Agent response:
- Acknowledge the preference
- Call
memory_remember({ text: "User prefers Material UI over Tailwind for React projects", tags: ["preference", "ui"] })
- Confirm it's stored: "Got it, I'll remember that preference"
Example 3: Check Before Recommending
User asks: "What CSS framework should we use?"
Agent response:
- Call
memory_search({ query: "CSS framework preference" })
- If match found: "You previously preferred Material UI over Tailwind"
- If no match: Provide recommendation based on context
Example 4: Session Continuity
New session starts:
memory-bootstrap hook auto-runs- Loads recent preferences, decisions, project context
- Agent has continuity without user repeating everything
Tips & Best Practices
Do:
- ✅ Use
memory_search before answering questions about past work
- ✅ Store concise, specific facts (1-2 sentences)
- ✅ Tag memories for easy filtering (
preference, decision, fact, project-name)
- ✅ Trust semantic search (it understands meaning, not just keywords)
- ✅ Let hooks handle routine memory capture (preferences, decisions)
Don't:
- ❌ Store temporary/ephemeral information
- ❌ Duplicate conversation history (that's already stored)
- ❌ Store sensitive credentials (use secure storage instead)
- ❌ Forget without user permission (use
memory_forget sparingly)
- ❌ Overwhelm with too many manual
memory_remember calls (hooks handle most)
Search Tips:
- Use natural language: "database preference" > "db pref"
- Be specific when possible: "TypeScript vs JavaScript decision" > "language"
- Results are ranked by semantic similarity (0-1 score)
- Default
minScore: 0.5 filters low-relevance results
TTL Guidelines:
- 7 days: Temporary project context
- 30 days (default): Most facts, decisions, preferences
- 90 days: Important long-term context
- 365 days: Critical knowledge that should persist long-term
Troubleshooting
"Memory daemon not reachable"
- Check daemon is running:
curl http://localhost:7654/health
- Start daemon:
cd openclaw-memory && pnpm dev:daemon
- Or use Docker:
docker compose up -d
"No memories found"
- Verify memories exist:
memory_list({ limit: 5 })
- Check agentId matches (
openclaw by default)
- Try broader search queries
- Lower
minScore threshold in config
"Memory search returns irrelevant results"
- Be more specific in query
- Increase
minScore threshold (default: 0.5)
- Check tags to filter results
- Verify Voyage AI embeddings are working (not mock mode)
"Tools not available"
- Verify plugin is enabled in
openclaw.json
- Restart OpenClaw gateway
- Check plugin installation:
openclaw plugins list
Advanced Features
Web Dashboard
Full installation includes a web dashboard at http://localhost:3002:
- Memory browser with semantic search
- Graph visualizer (relationship mapping)
- Conflict resolution (contradiction detection)
- Timeline and analytics
Reflection Pipeline
9-stage processing pipeline for:
- Duplicate detection (0.92 similarity threshold)
- Contradiction detection (heuristic + LLM)
- Confidence scoring
- Graph relationship extraction
- Entity extraction
- Temporal decay
Trigger reflection:
curl -X POST http://localhost:7654/reflect \
-H "Content-Type: application/json" \
-d '{"agentId":"openclaw"}'
Graph Relationships
Memories can be connected via edges:
SUPPORTS — reinforces/supports another memoryCONTRADICTS — conflicts with another memoryDERIVES_FROM — built upon another memoryCO_OCCURS — frequently appears togetherPRECEDES — temporal sequenceMENTIONS_ENTITY — references an entity
Access via web dashboard at /graph.
Requirements
- MongoDB 8.0+ (local or Atlas)
- Node.js 18+
- OpenClaw CLI
- Optional: Voyage AI API key (mock mode available)
Installation
# Install plugin
openclaw plugins install openclaw-memory
# Start daemon
cd openclaw-memory
pnpm install && pnpm dev:daemon
# Or use Docker
docker compose up -d
Summary
OpenClaw Memory gives agents persistent, searchable memory across sessions:
- Search semantically with
memory_search
- Store facts with
memory_remember
- Automatic capture via lifecycle hooks
- MongoDB-backed with Voyage AI embeddings
- Web dashboard for visualization and management
Use it to build agents that remember, learn, and improve over time. 🧠
Version: 0.2.1
Author: Michael Lynn
License: MIT
Repository: https://github.com/mrlynn/openclaw-mongodb-memory
