OpenClaw MongoDB Semantic Memory

MongoDB-backed long-term semantic memory for recalling, storing, searching, and managing facts, decisions, and user preferences across sessions.

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:

1. Call memory_search({ query: "API authentication decision" })
2. Review results
3. Answer based on stored memory
4. 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:

1. Acknowledge the preference
2. Call memory_remember({ text: "User prefers Material UI over Tailwind for React projects", tags: ["preference", "ui"] })
3. 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:

1. Call memory_search({ query: "CSS framework preference" })
2. If match found: "You previously preferred Material UI over Tailwind"
3. If no match: Provide recommendation based on context

Example 4: Session Continuity

New session starts:

1. memory-bootstrap hook auto-runs
2. Loads recent preferences, decisions, project context
3. 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 memory
• CONTRADICTS — conflicts with another memory
• DERIVES_FROM — built upon another memory
• CO_OCCURS — frequently appears together
• PRECEDES — temporal sequence
• MENTIONS_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:

1. Search semantically with memory_search
2. Store facts with memory_remember
3. Automatic capture via lifecycle hooks
4. MongoDB-backed with Voyage AI embeddings
5. 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