Mem0

The Mem0 VFS 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. Install the extra:

pip install "mirage-ai[mem0]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.mem0 import Mem0Config, Mem0VFS

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

The VFS is read-only. A snapshot keeps its config, and a load needs the mount handed back through mounts=; it has no drift detection, so restored cache entries are served as saved and other reads reach the live backend. Set exactly one of user_id, agent_id, or run_id (see Setup).

Field	Description
`timeout` default `30`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`api_key` required, secret	Mem0 Platform API key.
`host` default `'https://api.mem0.ai'`	Mem0 API base URL.
`user_id`	Mount this user’s memories. Set exactly one of `user_id`, `agent_id` and `run_id`.
`agent_id`	Mount this agent’s memories. Set exactly one of `user_id`, `agent_id` and `run_id`.
`run_id`	Mount this run’s memories. Set exactly one of `user_id`, `agent_id` and `run_id`.
`default_page_size` default `100`	Memories fetched per request while listing the scope.
`default_search_limit` default `10`	How many results `search` returns unless the line sets `top_k`.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Mem0 mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`mem0`, read

`/<path>` layout

/<path>
  <memory-id>.json

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest).

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `mem0`, read |

## `/<path>` layout

```text
/<path>
  <memory-id>.json
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

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 CLI asks Mem0’s semantic search API within the configured scope. Use it when meaning matters more than exact text. Register it on the workspace:

from mirage.commands.cli.builtin.search import SEARCH

ws.register_cli("search", SEARCH)

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 VFS 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.commands.cli.builtin.search import SEARCH
from mirage.vfs.mem0 import Mem0Config, Mem0VFS

load_dotenv(".env.development")

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


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

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

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

    r = await ws.shell('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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Reading Memories

grep and rg search the JSON files

Search

Cache

Example

Shell Commands

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Reading Memories

​grep and rg search the JSON files

​Search

​Cache

​Example

​Shell Commands

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Reading Memories

grep and rg search the JSON files

Search

Cache

Example

Shell Commands