OpenClaw MongoDB Semantic Memory

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

Michael Lynn@mrlynn

Install

openclaw skills install @mrlynn/openclaw-memory-skill

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.

typescript

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:

json

{
  "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.

typescript

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.

typescript

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.

typescript

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.

typescript

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.

typescript

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:

json5

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

bash

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

bash

# 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

OpenClaw MongoDB Semantic Memory

Install

OpenClaw Memory — Agent Skill

When to Use

Available Tools

memory_search

memory_remember

memory_get

memory_forget

memory_list

memory_status

Configuration

Automatic Memory Capture

auto-remember Hook

session-to-memory Hook

memory-bootstrap Hook

memory-enriched-tools Hook

Workflow Examples

Example 1: Recall Prior Decision

Example 2: Store Preference

Example 3: Check Before Recommending

Example 4: Session Continuity

Tips & Best Practices

Troubleshooting

Advanced Features

Web Dashboard

Reflection Pipeline

Graph Relationships

Requirements

Installation

Summary

Related skills

`memory_search`

`memory_remember`

`memory_get`

`memory_forget`

`memory_list`

`memory_status`

`auto-remember` Hook

`session-to-memory` Hook

`memory-bootstrap` Hook

`memory-enriched-tools` Hook