Mem0

The Mem0 resource exposes the memories of a single scope — a user_id, agent_id, or run_id — as JSON files mounted at a prefix such as /memory/. Each memory is one file named <memory_id>.json. For API key setup, see Mem0 Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.resource.mem0 import Mem0Config, Mem0Resource

config = Mem0Config(
    api_key=os.environ["MEM0_API_KEY"],
    user_id=os.environ.get("MEM0_USER_ID"),
)
resource = Mem0Resource(config=config)
ws = Workspace({"/memory/": resource}, mode=MountMode.READ)

The resource is read-only and does not support snapshots. Set exactly one of user_id, agent_id, or run_id (see Setup).

Filesystem Layout

The tree is flat: the mount root lists one <memory_id>.json file per memory in the configured scope.

/memory/
  6d1ba0fc-1f0c-495b-b5b1-9141b2674b37.json
  4d221f85-b200-4cf1-8eff-05e0ba71d145.json

cat returns the full memory JSON, including memory, categories, metadata, created_at, updated_at, and structured_attributes:

{
  "id": "6d1ba0fc-1f0c-495b-b5b1-9141b2674b37",
  "memory": "User's name is Alex, follows a vegetarian diet, allergic to nuts",
  "categories": ["personal_details"],
  "created_at": "2026-06-15T00:34:18-07:00",
  "updated_at": "2026-06-15T00:34:22-07:00"
}

stat reports updated_at (falling back to created_at) as the modified time and exposes both timestamps.

Reading Memories

ls /memory/
find /memory/ -type f
cat /memory/6d1ba0fc-1f0c-495b-b5b1-9141b2674b37.json
jq '.memory' /memory/6d1ba0fc-1f0c-495b-b5b1-9141b2674b37.json
wc /memory/6d1ba0fc-1f0c-495b-b5b1-9141b2674b37.json

grep and rg search the JSON files

grep and rg follow normal filesystem semantics and search the same JSON bytes that cat returns. A match can therefore come from the memory text or from metadata such as categories and timestamps. Because the mount is a directory, plain grep needs -r (or a glob); rg recurses by default:

grep -r "banana" /memory/
grep "banana" /memory/*.json
rg "banana" /memory/

Search

The search command calls Mem0’s semantic search API within the configured scope. Use it when meaning matters more than exact text.

search "what does the user eat for breakfast" /memory/
search --top-k 5 "morning routine" /memory/
search --threshold 0.4 "movie preferences" /memory/

top-k defaults to default_search_limit (10). threshold must be between 0 and 1. Results are emitted one hit per block, ranked by score:

/memory/6d1ba0fc-1f0c-495b-b5b1-9141b2674b37.json:0.91
User asked for food recommendations to stay full in the morning

Cache

The resource uses Mirage’s index cache for the virtual tree. The first ls fetches the scope’s memories (following Mem0 pagination) and primes the cache; read commands reuse the cached metadata and rendered bytes until the cache expires or the workspace is recreated. search always calls the Mem0 API directly and is not cached.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.mem0 import Mem0Config, Mem0Resource

load_dotenv(".env.development")

config = Mem0Config(
    api_key=os.environ["MEM0_API_KEY"],
    user_id=os.environ.get("MEM0_USER_ID"),
)
resource = Mem0Resource(config=config)


async def main() -> None:
    ws = Workspace({"/memory/": resource}, mode=MountMode.READ)

    r = await ws.execute("ls /memory/")
    print(await r.stdout_str())

    r = await ws.execute("grep -r -i 'allergic' /memory/")
    print(await r.stdout_str())

    r = await ws.execute('search --top-k 5 "morning routine" /memory/')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

Shell Commands

Command	Notes
`ls`	List the memory files in the scope
`cat`	Read a memory’s full JSON
`jq`	Query a memory’s JSON fields
`head` / `tail`	Read the first or last lines/bytes of a memory JSON
`grep`	Search rendered JSON (use `-r` on a directory)
`rg`	Search rendered JSON, recursive by default
`find`	Search the virtual tree by name, type, depth, and size
`wc`	Count lines, words, bytes, characters, and max line length
`stat`	Show a memory’s size and timestamps
`search`	Semantic search through Mem0, ranked by score

Getting Started

Agents

Resources

Runtimes

Config

Filesystem Layout

Reading Memories

grep and rg search the JSON files

Search

Cache

Example

Shell Commands

​Config

​Filesystem Layout

​Reading Memories

​grep and rg search the JSON files

​Search

​Cache

​Example

​Shell Commands

Config

Filesystem Layout

Reading Memories

grep and rg search the JSON files

Search

Cache

Example

Shell Commands