OpenClaw MongoDB Semantic Memory

intent

use openclaw memory when you need persistent, searchable recall of facts, decisions, preferences, or context across multiple sessions. semantic search (via voyage ai embeddings) lets you find relevant information by meaning, not just keywords. do not use for temporary scratch notes, immediate conversation context (use native chat history), or large document storage (use filesystem or dedicated database). this skill is built on mongodb atlas search and fires lifecycle hooks that automatically capture preferences, decisions, and session summaries without manual intervention.

inputs

external connections:

• mongodb 8.0+ (local or atlas cloud) - stores all memories with vector embeddings
• voyage ai api key (optional) - for semantic embeddings; mock mode available for testing
• openclaw daemon at http://localhost:7654 (default, configurable)

configuration file: ~/.openclaw/openclaw.json

{
  plugins: {
    entries: {
      "openclaw-memory": {
        enabled: true,
        config: {
          daemonUrl: "http://localhost:7654",
          agentId: "openclaw",
          maxResults: 6,
          minScore: 0.5,
          defaultTtl: 2592000,
          hooksEnabled: true
        }
      }
    }
  }
}

environment variables:

• VOYAGE_API_KEY - required for production embeddings (optional if using mock mode)
• MONGODB_URI - connection string (if not using localhost)
• OPENCLAW_DAEMON_URL - override default daemon address

context needed to run:

• agentId (defaults to "openclaw" but can be overridden for multi-agent setups)
• current conversation or session context (optional, used by auto-remember hook)
• user preferences or project metadata (optional, enriches tagging)

procedure

step 1: search for existing memory before acting

call memory_search() when:

• answering questions about past decisions, preferences, or facts
• solving a problem similar to prior work
• building on previous context

input: natural language query string (e.g. "what did we decide about the database schema?") output: array of memory objects ranked by semantic similarity (0-1 score), each containing id, text, tags, createdAt, score

const results = await memory_search({
  query: "what did we decide about database schema?",
  maxResults: 6  // optional, returns top N matches
})
// returns { results: [{id, text, score, tags, createdAt}, ...] }

edge case: if no results returned (empty array), tell user "no memory of that" and proceed without prior context.

---

step 2: evaluate search results and retrieve full context if needed

review semantic similarity scores. scores above 0.7 are high confidence; 0.5-0.7 are moderate; below 0.5 are low confidence.

input: results array from step 1 output: curated list of relevant memories or decision to fetch full memory file

if you need full context (e.g., searching returned only metadata), call memory_get():

const fullMemory = await memory_get({
  path: "MEMORY.md",
  from: 1,
  lines: 100  // read up to 100 lines
})
// returns file contents as text

edge case: memory file may not exist if no structured memories have been written yet.

---

step 3: store important facts, decisions, or preferences using memory_remember

after a decision is made, user states a preference, or key insight emerges, call memory_remember() to persist it.

input:

• text (required): 1-2 sentence statement of the fact/decision/preference
• tags (optional): comma-separated or array of categories (e.g. "preference,ui,react")
• ttl (optional): time-to-live in seconds (default 2592000 = 30 days)

output: stored memory id and confirmation

const stored = await memory_remember({
  text: "User prefers Material UI over Tailwind for React projects",
  tags: ["preference", "ui", "react"],
  ttl: 7776000  // 90 days for long-term preference
})
// returns { id: "507f1f77bcf86cd799439011", confirmed: true }

best practices:

• be specific and concise (semantic search works better with clear language)
• use structured format when possible ("key: value")
• do not store temporary info, credentials, or sensitive data
• let auto-remember hook capture routine preferences/decisions (do not over-call manually)

edge case: duplicate detection runs at storage time (0.92 similarity threshold); very similar memories may be deduplicated by the system.

---

step 4: list or browse stored memories by tag or recency

if user asks "what have you remembered?" or you need to audit recent memories, call memory_list().

input:

• tags (optional): comma-separated filter (e.g. "decision,database")
• limit (optional): number of results, default 10
• sort (optional): "asc" or "desc" by creation date, default "desc" (newest first)

output: array of memories with metadata (no similarity scores)

const list = await memory_list({
  tags: "decision,database",
  limit: 10,
  sort: "desc"
})
// returns [{ id, text, tags, createdAt }, ...]

edge case: if no memories match filter, returns empty array.

---

step 5: delete a memory only after user explicitly requests it

call memory_forget() to remove a specific memory by id. always use memory_search or memory_list first to find the id.

input: memory id (required, obtained from search or list results) output: confirmation or error

const deleted = await memory_forget({
  memoryId: "507f1f77bcf86cd799439011"
})
// returns { deleted: true } or error

critical: never delete proactively. only delete if user explicitly asks to forget, correct, or remove outdated info.

edge case: attempting to forget non-existent id returns 404 error.

---

step 6: check system health before relying on memory for critical tasks

call memory_status() to verify daemon connectivity, mongodb connection, voyage ai embeddings, and system stats.

input: none output: daemon status, mongodb connection status, voyage ai status, total memory count, uptime

const status = await memory_status()
// returns { 
//   daemon: "up",
//   mongodb: "connected",
//   voyageAi: "ready",
//   totalMemories: 342,
//   uptime: "24h 35m"
// }

use rarely: only when debugging issues or before critical reliance on memory system.

edge case: if daemon is down, all memory tools fail with "daemon not reachable" error. restart with pnpm dev:daemon or docker compose up -d.

---

step 7: automatic lifecycle hooks (run without manual invocation)

these hooks fire automatically if hooksEnabled: true in config:

auto-remember hook: after every agent response, pattern-matching extracts:

• "i prefer..." > stored as preference tag
• "we decided..." > stored as decision tag
• "remember that..." > stored as fact tag
• "key: value" patterns > stored as structured data

limits: max 5 extractions per message, minimum 10 characters, automatic deduplication.

session-to-memory hook: when session ends, summarizes the conversation and stores as a single searchable memory for future session bootstrap.

memory-bootstrap hook: on agent startup, queries for relevant memories (recent preferences, decisions, pinned items) and injects into initial context automatically.

memory-enriched-tools hook: after tool results are returned (read, grep, glob, bash), appends related memories from the semantic index as context annotations.

decision points

if memory_search returns empty results:

• user asks about past decision/preference but nothing found
• action: tell user "i don't have any memory of that" and proceed without prior context or ask clarifying questions
• fallback: lower minScore threshold in config (default 0.5) if you suspect high-quality memories exist but are below threshold

if memory_search returns low-confidence results (score < 0.5):

• semantic similarity is below minimum threshold
• action: do not use those results; treat as if no memory found
• workaround: user can manually call memory_list() to browse by tag instead

if user asks to store something and auto-remember hook already captured it:

• memory_remember call detects duplicate (0.92 similarity)
• action: system deduplicates silently; do not call memory_remember again
• trust the hooks to handle routine storage

if daemon is unreachable (connection timeout or 404):

• openclaw daemon at http://localhost:7654 is not running
• action: fail gracefully and tell user "memory system is offline"
• recovery: user must start daemon (pnpm dev:daemon or docker compose up -d) before retrying

if voyage ai embeddings fail (api key invalid or rate-limited):

• embeddings needed for semantic search but voyage ai unavailable
• action: if mock mode enabled, fall back to keyword matching; if mock disabled, memory_search fails with error
• recovery: verify VOYAGE_API_KEY env var, check api quota, or enable mock mode in config

if ttl expires on a memory:

• memory is automatically deleted after ttl seconds
• no notification sent; memory simply becomes unretrievable via search or list
• user can set longer ttl (up to 365 days) for critical long-term memories

if user asks to forget a memory but you don't have the id:

• call memory_search() or memory_list() first to find the id
• action: locate the memory, extract id, then call memory_forget()
• never guess or construct fake ids

if reflection pipeline detects contradiction in stored memories:

• two stored memories conflict (heuristic or llm-detected)
• action: web dashboard at http://localhost:3002/graph shows contradictions
• user can manually resolve via dashboard or by forgetting incorrect memory

output contract

memory_search returns:

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

{
  "id": "507f1f77bcf86cd799439012",
  "confirmed": true
}

memory_get returns: raw text file contents (string)

memory_list returns:

[
  {
    "id": "507f1f77bcf86cd799439011",
    "text": "User prefers TypeScript",
    "tags": ["preference", "programming"],
    "createdAt": "2026-02-15T10:00:00Z"
  }
]

memory_forget returns:

{
  "deleted": true
}

memory_status returns:

{
  "daemon": "up",
  "mongodb": "connected",
  "voyageAi": "ready",
  "totalMemories": 342,
  "uptime": "24h 35m"
}

all errors return http status + error message:

{
  "error": "Memory not found",
  "status": 404
}

outcome signal

the skill worked if:

1. search retrieves relevant memories - user asks "what did we decide about X?" and you return matching memories ranked by semantic similarity, user confirms they are accurate
2. stored facts persist across sessions - memory_remember stores a preference/decision, you close the session, start a new session, bootstrap hook auto-injects that memory into context, user confirms continuity
3. automatic hooks fire silently - user states "i prefer X", you do not manually call memory_remember, but auto-remember hook captures it (user can verify with memory_list on next session)
4. daemon is healthy - memory_status returns all systems "up" or "connected", no timeouts or 404 errors
5. web dashboard reflects stored memories - user visits http://localhost:3002, sees stored memories in browser, graph relationships visible
6. contradictions are detected - if two conflicting memories are stored, dashboard shows them as "contradicts" edge in graph, or reflection pipeline surfaces them
7. ttl respects expiration - memory stored with 7-day ttl disappears from search results after 7 days, memory_list no longer shows it
8. tags filter correctly - memory_list with tags filter returns only memories matching those tags
9. semantic search understands paraphrase - search for "database preference" returns memory stored as "decided on mongodb" (meaning match, not keyword match)
10. user confirms memory improves decision-making - over time, user reports "i remembered i preferred X" or "we avoided repeating the same mistake" due to memory system

credits

original author: michael lynn (mrlynn). plugin repository: https://github.com/mrlynn/openclaw-mongodb-memory. version 0.2.1. license: mit.