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:

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

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

Installation

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

`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