Memory & Storage

Use these tools to explicitly manage MindRoom memory or connect an agent to external memory providers.

What This Page Covers

This page documents the built-in tools in the memory-and-storage group. Use these tools when you need explicit memory CRUD operations, direct provider-specific memory access, or a clear separation between MindRoom memory and third-party memory services.

Tools On This Page

• [memory] - Explicitly add, search, list, read, update, and delete MindRoom memories visible to the current agent.
• [mem0] - Direct Mem0 toolkit for user-scoped persistent memory outside MindRoom's built-in memory API.
• [zep] - Direct Zep Cloud toolkit for session memory and user-graph search.

Common Setup Notes

memory is MindRoom-native and has no tool-specific configuration fields. It operates on the same MindRoom memory backend configured through memory.backend or agents.<name>.memory_backend, so it follows the effective mem0, file, or none backend for that agent. If the effective backend is none, MindRoom does not attach the memory tool to that agent. Use Memory System for the canonical docs on backend selection, automatic extraction, file-backed memory, Agno Learning, and storage layout. mem0 and zep are separate upstream Agno toolkits that talk to external memory providers directly. Enabling mem0 or zep does not change MindRoom's own memory backend, automatic memory extraction, or the behavior of the memory tool. mem0 can work with a hosted Mem0 API key or with local/default upstream Mem0 configuration. zep requires a Zep API key, either through stored credentials or the ZEP_API_KEY environment variable. If optional dependencies for these tools are missing, MindRoom can auto-install them at first use unless MINDROOM_NO_AUTO_INSTALL_TOOLS=1 is set. This page does not document conversation-scoped file attachments even though they are storage-like. Use Matrix & Attachments and Attachments for attachment IDs, retention, and Matrix media flow.

[memory]

memory gives an agent explicit control over the MindRoom memories available in its current scope.

What It Does

memory exposes add_memory(), search_memories(), list_memories(), get_memory(), update_memory(), and delete_memory(). It complements MindRoom's automatic post-response memory extraction by letting the agent deliberately remember or inspect something on demand. The tool always uses the current agent's configured MindRoom memory backend, so the same calls work whether that agent uses built-in mem0 storage or file-backed memory. Agents with memory_backend: none do not receive this tool. Search and list results include memory IDs, and those IDs are then used with get_memory(), update_memory(), and delete_memory(). The tool is bound to the current agent's MindRoom scope and can reach any agent or team memories that MindRoom makes visible to that agent.

Configuration

This tool has no tool-specific inline configuration fields.

Example

memory:
  backend: file

agents:
  assistant:
    tools:
      - memory

add_memory("The user prefers terse release notes.")
search_memories("release notes", limit=3)
list_memories(limit=20)
get_memory("abc123")
update_memory("abc123", "The user prefers terse release notes with dates.")
delete_memory("abc123")

Notes

• The tool uses whichever MindRoom backend is active for the agent, so enable and tune that backend through Memory System, not through tool-local options.
• This is the right tool when you want explicit control over MindRoom's built-in durable memory rather than a separate provider account.
• The tool returns user-facing error strings on failures instead of raising raw exceptions into the conversation.

[mem0]

mem0 connects an agent directly to the upstream Mem0 toolkit.

What It Does

mem0 exposes add_memory(), search_memory(), get_all_memories(), and delete_all_memories(). It uses the upstream mem0ai client directly rather than MindRoom's built-in memory API. If api_key is set, or MEM0_API_KEY is present in the environment, the toolkit connects to Mem0's hosted platform client. If no API key is present but config is supplied, the toolkit initializes upstream Mem0 from that local config object. If neither api_key nor config is supplied, the toolkit falls back to upstream Mem0 defaults. Operations need a user_id, either from tool config or from the run context, and they return an error string when no user ID can be resolved.

Configuration

Example

agents:
  assistant:
    tools:
      - mem0:
          user_id: assistant-memory
          infer: true

add_memory("The user prefers terse release notes.")
search_memory("release notes")
get_all_memories()
delete_all_memories()

Notes

• api_key is optional because the toolkit can use local/default upstream Mem0 initialization instead of the hosted Mem0 platform.
• This toolkit is separate from MindRoom's memory.backend: mem0 setting, so enabling mem0 here does not configure or replace MindRoom's built-in memory backend.
• If you want MindRoom's automatic memory extraction and built-in memory retrieval to use Mem0, configure that in Memory System instead of relying on this toolkit alone.
• Store API keys outside authored YAML even when the current metadata marks them as optional.

[zep]

zep connects an agent directly to Zep Cloud for conversational memory and user-graph search.

What It Does

zep exposes add_zep_message(), get_zep_memory(), and search_zep_memory(). The toolkit requires a Zep API key at initialization time and raises an error when neither api_key nor ZEP_API_KEY is available. If session_id is omitted, the toolkit generates a new session ID automatically. If user_id is omitted, the toolkit generates a new Zep user and creates it in the remote account. If user_id is provided but the user does not exist yet, the toolkit attempts to create it before use. get_zep_memory(memory_type="context") returns either session context or raw message history. search_zep_memory(query, search_scope="edges") searches the Zep user graph by facts or nodes. ignore_assistant_messages skips assistant-role content when messages are added to Zep.

Configuration

Example

agents:
  assistant:
    tools:
      - zep:
          user_id: assistant-user
          session_id: release-review

add_zep_message(role="user", content="The user prefers terse release notes.")
get_zep_memory(memory_type="context")
search_zep_memory(query="release notes", search_scope="edges")

Notes

• zep is an external provider toolkit and does not change MindRoom's built-in memory backend or the behavior of the memory tool.
• Use explicit user_id and session_id values when you want continuity across runs instead of a fresh generated identity.
• search_scope="edges" returns fact-style results, while search_scope="nodes" returns node summaries.
• Store the API key through credentials or ZEP_API_KEY rather than inline YAML.

Related Docs

• Tools Overview
• Memory System
• Matrix & Attachments
• Attachments