Skip to content

Memory System

Memory lets agents remember facts, preferences, and context across conversations. This page covers choosing a memory backend, configuring embeddings and extraction, file-based memory, and the memory tool.

Backend What it does Use it when
mem0 (default) Vector memory: relevant memories are retrieved before each reply and new ones are extracted automatically after each turn You want hands-off semantic memory
file Markdown files (MEMORY.md plus dated notes in memory/) that are the source of truth You want memory you can read and edit, or an OpenClaw-style workspace
none No built-in memory The agent should keep no memories

Before each reply, the mem0 and file backends add the three memories most relevant to the message to the prompt. File memory in semantic search mode adds up to five of the agent's own semantic matches instead: the closest match and any scored within 0.05 of it, at most 800 tokens together, so a closest match longer than that adds nothing; its teams' three best keyword matches follow, each only if it fits what is left of those 800 tokens, and until the semantic index is ready its own three best keyword matches are used. With rerank, on by default with an openai_decisions or typesafe reranker, a reranker chooses the semantic matches instead. search_memories returns up to its own limit in every mode.

Choosing a Backend

Set the global backend with memory.backend (mem0, file, or none; default mem0), and override it for one agent with agents.<name>.memory_backend. memory: none is shorthand for memory: {backend: none}.

memory:
  backend: mem0

agents:
  coder:
    display_name: Coder
    role: Write and review code
    memory_backend: file
  scratch:
    display_name: Scratch
    role: Stateless scratchpad agent
    memory_backend: none

With none, the agent gets no memories in its prompt, stores none after its turns, and does not receive the memory tool. Credential-like values are removed on a best-effort basis before conversation text reaches memory automatically, through mem0, auto-flush, a team's MEMORY.md, or a voice-call transcript sent to mem0; the transcript file itself is kept as spoken. What an agent writes itself, with the memory tool or in a dreaming run, is stored as written. Conversation history is separate and stays in the session; see History & Compaction. Memories retrieved for a reply stay in that conversation's history, so its later replies can still see them after the memory is deleted. OpenClaw-compatible agents use this same backend selection.

Memory Scopes

Scope ID Contents
Agent agent_<name> The agent's preferences and durable user context
Team team_<agent1>+<agent2>+... (member names sorted) Shared memory from team conversations

Each team fact is kept once: a team fact one member changes or deletes with the memory tool changes for every member that reads it. An agent's memory reads cover its own scope and the scopes of the configured teams it belongs to, searched through the agent's own backend. A team's replies are not given recalled memories; the team scope is filled from the conversations the team answers, and its members recall it in their own replies.

Team memory picks one backend from the members' effective backends:

  • All members use file: the team uses file memory.
  • All members use none: team memory is disabled.
  • Any other combination, including file plus none, uses Mem0 with the configured memory.embedder and memory.llm.

A member's none setting disables only its own memory, so team conversations it takes part in can still be remembered in the team scope. A file member of a team that uses Mem0 does not see that team's Mem0 memories in its own conversations.

Backend: mem0

Before each reply, Mem0 retrieves memories relevant to the message and adds them to the prompt. After each turn, the memory LLM extracts durable facts into a Chroma vector store under the agent's storage directory, or, for a team's turn, once into the one Mem0 store under team_memory/ that holds every team's memories, with each team's records kept apart. The mem0 and chromadb extras install on first use unless MINDROOM_NO_AUTO_INSTALL_TOOLS=1 is set; otherwise install mindroom[mem0,chromadb].

Embedder

memory.embedder sets the embedding model used by Mem0, semantic file-memory search, and knowledge bases. Mem0 supports the openai (default), ollama, huggingface, and sentence_transformers providers; semantic file memory and knowledge bases support their own set, which has vertex_ai instead of huggingface. Config load rejects vertex_ai while any memory would use Mem0, so with it set memory.backend and every agent's memory_backend to file, or all of them to none; a team whose members mix file and none uses Mem0.

Field Default Description
provider openai Embedding provider
config.model text-embedding-3-small Embedding model name
config.host null Base URL for OpenAI-compatible endpoints, or the Ollama host; for openai, without it the embedder uses OPENAI_BASE_URL, else OpenAI's API; for ollama, a configured OLLAMA_HOST takes precedence over host, and without either the host is http://localhost:11434
config.dimensions null Embedding dimension override (>= 1) for OpenAI-compatible providers and vertex_ai
config.api_key null Explicit API key for the openai provider
config.credentials_service null Credential service that supplies the openai provider's key
config.query_prefix null Text the openai and vertex_ai providers prepend to search queries
config.document_prefix null Text the openai and vertex_ai providers prepend to indexed documents and stored memories

Only the openai provider reads api_key and credentials_service, only openai and vertex_ai read query_prefix and document_prefix, and only openai and ollama read host; config load rejects a nonblank value in these fields for any other provider. Config load also rejects dimensions for ollama and sentence_transformers, which always return the model's full-size vectors.

memory:
  backend: mem0
  embedder:
    provider: openai
    config:
      model: text-embedding-3-small
      credentials_service: embedder # Optional strict credential binding
      dimensions: null              # Optional, for example 256

Fully local embedders:

memory:
  embedder:
    provider: sentence_transformers
    config:
      model: sentence-transformers/all-MiniLM-L6-v2
memory:
  embedder:
    provider: ollama
    config:
      model: nomic-embed-text
      host: http://localhost:11434

MindRoom installs the optional sentence_transformers extra the first time the sentence_transformers or huggingface embedder is used.

Some models expect a prompt in front of each text, different for queries and documents. With a local sentence_transformers model, knowledge, file-memory and knowledge-graph searches get the model's own prompts automatically, while Mem0 embeds without them. For the same model behind an OpenAI-compatible server such as llama.cpp, set the prompts as prefixes; the openai provider applies them everywhere, Mem0 included. For EmbeddingGemma 2:

memory:
  embedder:
    provider: openai
    config:
      model: embeddinggemma-2
      host: http://localhost:8080/v1
      dimensions: 768
      query_prefix: "task: search result | query: "
      document_prefix: "title: none | text: "

Knowledge-graph texts all get the query prefix, because Graphiti embeds names, facts and searches through the same calls. Changing the embedder provider, model, host, dimensions, or prefixes switches Mem0 to a separate collection, so memories stored with the previous embedder are no longer retrieved.

The openai embedder takes its API key from the first of these that is set:

  1. memory.embedder.config.api_key.
  2. The service named by memory.embedder.config.credentials_service; when it has no key, MindRoom does not fall back to another key.
  3. When no service is named, the dedicated embedder credential (seeded from EMBEDDER_API_KEY or EMBEDDER_API_KEY_FILE), then the shared openai provider key.

Use credentials_service when the embedding endpoint needs a different key than chat, voice, or other OpenAI-compatible models. With no key at all, keyless local OpenAI-compatible endpoints still work, while a keyed endpoint fails with an authentication error.

An Ollama server that requires a key gets OLLAMA_API_KEY. For knowledge bases, the knowledge graph, and semantic file-memory search, MindRoom reads it from the process environment, then the .env beside config.yaml. Mem0's own Ollama clients, for its embedder and an ollama memory LLM, read it only from the process environment. When the embedder rejects its credential, semantic memory search reports the cause in memory tool output and in the agent's prompt instead of returning empty results, and /api/health includes an embedder block until a request succeeds again.

Memory LLM

memory.llm sets the model Mem0 uses to extract memories. Supported providers are ollama, openai, openrouter, and anthropic. When memory.llm is omitted, MindRoom uses gemma4 on the Ollama server set by OLLAMA_HOST (default http://localhost:11434). With provider: ollama, config.host names the Ollama server only when no OLLAMA_HOST is configured, unlike a model's host; without either, extraction uses http://localhost:11434, and other providers ignore host. With provider: openai, use gpt-6-luna; other GPT-5 and GPT-6 models that support Chat Completions also work. With provider: openai, config.openai_base_url sets the server; without it, extraction uses OPENAI_BASE_URL, else OpenAI's API. With provider: anthropic, config.anthropic_base_url sets the server; without it, extraction uses ANTHROPIC_BASE_URL, else Anthropic's API. With provider: anthropic, Mem0 sends no temperature, top_p, or top_k, which Claude API version 2026-10-21 rejects on every model, so config sampling values have no effect. For GPT-5 and GPT-6 models, with provider: openai or as openai/<model> with provider: openrouter, Mem0 sends no temperature, top_p, or max_tokens from config unless config.is_reasoning_model is false; set config.reasoning_effort, for example low, to choose their reasoning effort.

memory:
  llm:
    provider: ollama
    config:
      model: gemma4

OpenRouter-only example, where both the memory LLM and the embeddings use the openrouter key:

memory:
  embedder:
    provider: openai
    config:
      model: openai/text-embedding-3-small
      host: https://openrouter.ai/api/v1
      credentials_service: openrouter
      dimensions: 1536
  llm:
    provider: openrouter
    config:
      model: openai/gpt-6-luna

The LLM uses memory.llm.config.api_key when set and not blank, and otherwise the provider's credential (for example openrouter, or a dashboard credential stored as OPENROUTER_API_KEY). When OPENROUTER_API_KEY is set in the process environment, the openai and openrouter memory LLMs send that key to OpenRouter, overriding memory.llm.config.api_key.

Backend: file

File memory keeps MEMORY.md and dated notes under memory/ in the agent's workspace, and those files are the source of truth.

memory:
  backend: file
  file:
    max_entrypoint_lines: 200
    max_entrypoint_tokens: 50000
  search:
    mode: keyword
    include:
      - memory/**/*.md
    include_entrypoint: false
  auto_flush:
    enabled: true

For a single agent, the file backend writes memory only when the agent uses the memory tool or edits the files, or when auto-flush is enabled; it does not extract memories after every turn like mem0. A team whose members all use file appends each message it answers to the team's MEMORY.md, even without auto-flush. Before each reply, MindRoom inlines MEMORY.md into the prompt under a header with its path, so the agent does not need to re-read it, and adds memories that match the message. An ongoing conversation's inlined copy can miss lines added to MEMORY.md since it last loaded the file, for example from another conversation: lines added anywhere while the file fits the preload caps below, and lines added at the end of a file a cap truncates, until an hour passes without a model request that sends that copy or its history is compacted; edited or deleted lines apply from its next reply, new conversations load the current file (its first lines that fit, when a cap truncates it), and the agent can read the file directly. On a route that keeps the system prompt unchanged while its cache is warm and sends changes as a system prompt update, such as Claude Opus through OpenRouter with the hour-long prompt cache, an edited or deleted line that an update can state exactly reaches the conversation as such an update, and the old line can stay quoted in that conversation's later requests until its held prompt starts over: when it idles past the cache lifetime, its history is compacted or its updates alone would need that, the route or model changes, or a change comes that an update cannot state, such as one too long or one whose lines appear more than once in the prompt. Such a change, and the first request after the hold starts over, sends the current prompt without the old line. memory.file.max_entrypoint_lines (default 200, minimum 1) caps the inlined lines, and memory.file.max_entrypoint_tokens (default 50000, minimum 1) caps their size in the turn model's tokens (how tokens are counted). A file over either cap inlines its first lines that fit both caps and withholds the rest, so lines add_memory appends past a cap never reach the prompt until the file is condensed, and they leave the inlined copy unchanged. Only whole lines are inlined, never part of a line. When either cap truncates, a marker reports the included and total line counts, both caps, and the path to read for the rest, and asks the agent to condense the file (moving detail into memory/ files) so its newest lines fit again.

File layout

Agent file memory lives in the agent workspace, agents/<agent>/workspace/ in the storage directory:

  • MEMORY.md, where add_memory writes
  • memory/YYYY-MM-DD.md, where auto-flush writes

Team file memory lives once per team, in team_memory/team_<sorted_members>/MEMORY.md in the storage directory. A team whose directory name would pass 255 characters gets a shortened one ending in a hash.

Memory files must be regular files; symlinks, FIFOs, and device nodes are ignored when reading and rejected when writing. Each file is read up to 1 MiB, cut at its last complete line, and updating a truncated or non-UTF-8 file fails so the rest of it is preserved.

Searching file memory

memory.search controls how search_memories and per-turn retrieval search file memory, and agents.<name>.memory_search overrides it per agent, with omitted fields inherited.

Field Default Description
mode keyword keyword or semantic
include [memory/**/*.md] Glob patterns relative to the file-memory root that semantic search indexes; must be non-empty
exclude [] Glob patterns relative to the file-memory root that semantic search leaves out of include, such as exclude: [memory/archive/**] for archived notes
include_entrypoint false Also index MEMORY.md for semantic search
rerank unset In semantic mode, rerank the hits with the root reranker; unset reranks only when that reranker's provider is openai_decisions or typesafe

In keyword mode, search_memories matches structured entries with IDs in MEMORY.md, plus entries and plain-text lines in memory/**/*.md. Ordinary prose in MEMORY.md reaches the agent through the prompt preload, not keyword search; to reach lines beyond the preload cap, read the file directly or use semantic search with include_entrypoint: true.

In semantic mode, MindRoom builds a vector index of the include files not matched by exclude with memory.embedder on first use and stores it under <storage-root>/knowledge_db/ (see Knowledge storage). Each memory entry (a - [id=...] line, or a Markdown section up to ###) is indexed and returned on its own, split at 1,200 characters; a # line inside a fenced code block is code, not a new section. Until the index is ready, or when embeddings fail, search falls back to keyword results. Writes through the memory tool, auto-flush, and an applied dreaming proposal refresh the index, but a ready index does not notice direct file edits until a later such write refreshes it. Semantic mode covers the agent's own memory; team file memory is always keyword searched.

Reranking is on with rerank: true, and with rerank unset when the reranker is openai_decisions or typesafe, the two that improved recall in the benchmark below; rerank: false turns it off, globally or in agents.<name>.memory_search. With reranking on and a reranker configured, semantic searches fetch 20 hits, or a search_memories call's larger limit, and the reranker orders them. Per-turn recall then adds, in the reranker's order, up to five hits that score at least the reranker's threshold (default 0.5, or 0.3 for judgment rerankers) within the same 800 tokens, instead of the hits within 0.05 of the closest; when no hit reaches the threshold, it adds none. If the reranker fails or takes more than 2 seconds, recall adds the hits it would add without reranking and logs a warning, so a reranker never holds up a reply. A hosted reranker, which vertex_ai, typesafe and openai_decisions always are and cohere is unless its url names your own server, adds its response time to every reply. So with an openai_decisions or typesafe reranker, every reply in semantic mode sends about 20 memory entries, clipped and with credential-like values redacted, to OpenAI or System One unless memory.search.rerank is false. With rerank: true and a cohere or vertex_ai reranker, memory entries and the message go to that service unredacted; only the judgment rerankers redact.

On three sets of real conversation turns (132 to 1,247 held-out turns each), judged by a language model for whether recall added a relevant memory, reranked recall at threshold 0.3 compared with recall without a reranker as follows.

Reranker Turns with a relevant memory Relevant memories per 1,000 recalled tokens Recalled tokens per turn Added latency (median / 95th percentile) Cost per turn
none 36.6% to 76.2% baseline 633 to 701 none none
typesafe +5.3 to +31.3 points 1.59 to 2.36 times 412 to 553 118 ms / 178 ms $0.00023 to $0.00033
openai_decisions +2.0 to +4.8 points 1.46 to 2.22 times 410 to 528 290 ms / 578 ms $0.00060 to $0.00088

Latency was measured on 200 turns of one set run one at a time, none of which fell back to recall without reranking; a second judge model gave gains of the same sign on that set and on the largest one. A local BAAI/bge-reranker-v2-m3 with sentence_transformers did not improve recall over recall without a reranker, and its scores bunch near 0, so the default threshold 0.5 makes recall add nothing for most turns; if you turn on memory.search.rerank with a local cross-encoder, set reranker.threshold: 0.

Behaviour change: memory reranking is on by default only with the openai_decisions and typesafe rerankers, which earlier releases did not offer, so a config from an earlier release recalls as before. memory.search.rerank: false stops reranking in recall and search_memories, but search_knowledge_base still reranks the agent's semantic file-memory hits with the root reranker.

agents:
  coder:
    display_name: Coder
    role: Write and review code
    memory_backend: file
    memory_search:
      mode: semantic

Once its semantic index is ready, an agent's file memory also appears as a read-only source in search_knowledge_base. That source is semantic-only, without keyword fallback, team memory, or memory IDs, so use search_memories when you need those.

Per-requester file memory

To give each requester their own file memory from one agent definition, combine memory_backend: file with private; the requester's private root then becomes the file-memory root.

File Auto-Flush Worker

Auto-flush periodically turns the new turns of file-backed agents' conversations into durable memories. It applies only to agents whose effective backend is file, including each requester's private instance.

  1. Every flush_interval_seconds, a background worker looks for conversations with new finished turns that have been quiet for idle_seconds.
  2. The agent's own model, or extractor.model when set, reads the new messages, plus existing memories to avoid duplicates, and writes durable facts; a longer backlog is read in order over later passes.
  3. When the model answers with the no_reply_token, nothing is written.
  4. Results are appended to memory/YYYY-MM-DD.md, and a retry never appends the same result twice.

Compacted turns and voice-call turns are included. Not auto-flushed: turns that automations start, tasks another agent delegated, team conversations, conversations through the OpenAI-compatible API, and context that hooks attach to messages, such as location. A message redacted before its turn is flushed stays out of memory, and so do the turn that read it and every later turn its redaction removes from history. A turn that waits for tool approval is flushed once it finishes. Enabling auto-flush starts with the turns after that; earlier conversation is not flushed, and turning it off and on again flushes the turns in between. An agent switched to file memory later starts with its turns from about one flush_interval_seconds before auto-flush first sees it, and its private instances, including new ones, keep all their turns since then.

memory:
  backend: file
  auto_flush:
    enabled: true
    flush_interval_seconds: 300
    idle_seconds: 120
    batch:
      max_sessions_per_cycle: 10
    extractor:
      max_messages_per_flush: 20
Field Default Description
enabled false Turn on auto-flush
flush_interval_seconds 300 (min 5) Time between worker passes
idle_seconds 120 (min 0) How long a conversation must be quiet before its new turns are flushed
stale_ttl_seconds 86400 (min 60) Give up on turns whose flush has kept failing for this long
retry_cooldown_seconds 30 (min 1) Wait before retrying a failed flush
max_retry_cooldown_seconds 300 (min 1) Upper bound for the growing retry wait
batch.max_sessions_per_cycle 10 (min 1) Conversations flushed per pass, across all agents
batch.max_sessions_per_agent_per_cycle 3 (min 1) Conversations flushed per pass for one agent or private instance
extractor.model none A key of models that runs extraction instead of the agent's own model; set a fast model when extractions time out
extractor.no_reply_token NO_REPLY Reply meaning nothing should be saved
extractor.max_messages_per_flush 20 (min 1) New messages read per extraction; a longer backlog is read over later passes
extractor.max_chars_per_flush 12000 (min 1) Message characters read per extraction
extractor.max_extraction_seconds 30 (min 1) Timeout for one extraction, retried in a later pass
extractor.include_memory_context.memory_snippets 5 (min 0) Existing memories shown to the model to avoid duplicates
extractor.include_memory_context.snippet_max_chars 400 (min 1) Characters per existing memory shown

The retired max_dirty_age_seconds and max_cross_session_reprioritize settings, which older dashboards saved under auto_flush, pass validation but have no effect, and the next dashboard save removes them.

Prompt Curation

Agents append to MEMORY.md and their context files more often than they condense them, so the prompt they send on every turn keeps growing. Enable the prompt_curation automation to have MindRoom check their size daily and, once they pass a trigger or the preload has to withhold part of MEMORY.md, ask the agent in a visible thread to condense them gradually, fold corrections into the entries they correct, and move detail into searchable memory/ files, then measure the result and ask the agent to re-check a cut outside the bounds.

agents:
  mind:
    memory_backend: file
    automations: [prompt_curation]

Dreaming

Facts in memory/ go stale when a later conversation corrects them. Enable the dreaming automation to have the agent reconcile memory/ nightly with new conversations and daily notes, through a proposal that a second run reviews before MindRoom applies it.

memory:
  auto_flush:
    enabled: true           # writes the daily notes dreaming reviews
agents:
  mind:
    memory_backend: file
    thread_exports: true    # also reviews threaded conversations
    automations: [dreaming]

[memory]

The memory tool lets an agent deliberately remember, look up, correct, or forget something, alongside automatic memory. It has no tool-specific configuration; it always uses the agent's effective backend and the memory.search settings, and agents with memory_backend: none do not receive it.

agents:
  assistant:
    tools: [memory]
add_memory("The user prefers terse release notes.")
search_memories("release notes", limit=3)   # default limit 5
list_memories(limit=20)                     # default limit 50
get_memory("abc123")
update_memory("abc123", "The user prefers terse release notes with dates.")
delete_memory("abc123")

The tool reaches every agent and team scope visible to the agent, as described in Memory Scopes. Search and list results include an ID: Mem0 memory IDs and file-backed file:<path>:<line> IDs work with get_memory, update_memory, and delete_memory. Semantic file-memory matches use read-only semantic:<source_file>:<rank> locators that these functions do not accept. After storing, add_memory lists up to three similar existing memories with their IDs, so the agent can rewrite an entry the new memory corrects; file memory finds them by keyword even in semantic mode, because semantic matches cannot be edited. Result metadata includes search_mode (keyword or semantic), showing which search produced each result. Failures are returned as readable error messages rather than raised into the conversation.

A listening agent writes memory from a silent turn through this tool when memory is in its listen.tools, or through a listed tool that writes files (see What listed tools can do). A silent turn stores no run, so neither automatic extraction nor the file auto-flush worker reads what the agent heard.

UI Configuration

The Dashboard Memory page edits the memory section: backend, embedder provider, model, credential service, and host, file settings (max_entrypoint_lines, max_entrypoint_tokens), search settings, and all auto-flush settings. The remaining fields, such as llm, are under More settings. Save from the Memory page to write the changes to config.yaml.