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
fileplusnone, uses Mem0 with the configuredmemory.embedderandmemory.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
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:
memory.embedder.config.api_key.- The service named by
memory.embedder.config.credentials_service; when it has no key, MindRoom does not fall back to another key. - When no service is named, the dedicated
embeddercredential (seeded fromEMBEDDER_API_KEYorEMBEDDER_API_KEY_FILE), then the sharedopenaiprovider 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.
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, whereadd_memorywritesmemory/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.
- Every
flush_interval_seconds, a background worker looks for conversations with new finished turns that have been quiet foridle_seconds. - The agent's own model, or
extractor.modelwhen 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. - When the model answers with the
no_reply_token, nothing is written. - 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.
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.
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.