> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mem0

> Virtualize a Mem0 memory scope from Node or the browser.

`Mem0VFS` mounts the memories of one Mem0 scope, a user, an agent or a run,
read-only. Each memory is one `<memory-id>.json` file. Set up the API key and the scope as in [Mem0 setup](https://docs.mirage.strukto.ai/home/setup/mem0.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { Mem0VFS, MountMode, Workspace } from '@struktoai/mirage-node'

const memory = new Mem0VFS({
  apiKey: process.env.MEM0_API_KEY!,
  userId: process.env.MEM0_USER_ID!,
})
const ws = new Workspace({ '/memory': memory }, { mode: MountMode.READ })

const result = await ws.shell('ls /memory && grep -rl allergic /memory')
console.log(result.stdoutText)
await ws.close()
```

An agent or run scope sets `agentId` or `runId` instead of `userId`. `host`
(default `https://api.mem0.ai`) points at another Mem0 API host.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

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.

**apiKey** `string` *required*

Mem0 Platform API key.

**host** `string` (default: '[https://api.mem0.ai](https://api.mem0.ai)')

Mem0 API base URL.

**userId** `string` (default: null)

Mount this user's memories. Set exactly one of `userId`, `agentId` and `runId`.

**agentId** `string` (default: null)

Mount this agent's memories. Set exactly one of `userId`, `agentId` and `runId`.

**runId** `string` (default: null)

Mount this run's memories. Set exactly one of `userId`, `agentId` and `runId`.

**defaultPageSize** `number` (default: 100)

Memories fetched per request while listing the scope.

**defaultSearchLimit** `number` (default: 10)

How many results `search` returns unless the line sets `top_k`.

Fields marked secret are redacted in snapshots.

## Authentication

The mount sends a Mem0 Platform API key, created on the dashboard's **API
Keys** page; the organization and project come from the key. Exactly one of
`userId`, `agentId` and `runId` is set. A pair is refused: Mem0 splits a memory
added with both into separate memories, so a combined filter matches nothing.

## Layout

```text theme={null}
/memory/
  6d1ba0fc-1f0c-495b-b5b1-9141b2674b37.json
  b52e7a19-0c4d-4a8e-9f3b-2d6c1e8a7f40.json
```

The tree is flat: one file per memory in the scope, named by memory id. A file
holds the full record: `memory`, `categories`, `metadata`, `created_at`,
`updated_at` and the rest.

## Behavior

* **Read-only:** no command changes the memories.
* **Times:** `stat` reports `updated_at`, or `created_at` when unset, as the
  modified time.
* **grep:** `grep` and `rg` search the JSON that `cat` prints, so a match can
  come from metadata such as categories and timestamps.
* **Freshness:** the first `ls` fetches every memory in the scope, and reads
  reuse it until the cache expires. `search` always asks Mem0.

### Search

The `search` CLI runs Mem0's semantic search in the
same scope. Register it on the workspace before `ws.close()`:

```ts theme={null}
import { SEARCH } from '@struktoai/mirage-node'

ws.registerCli('search', SEARCH)
```

```bash theme={null}
search --top-k 5 "quarterly planning" /memory/
```

`--top-k` defaults to `defaultSearchLimit` (10). `--threshold` is between 0 and

1. Each hit prints its file and score, then the memory, ranked by score.

## Browser

The same `Mem0VFS` runs in the browser from `@struktoai/mirage-browser`.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { Mem0VFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const memory = new Mem0VFS({ apiKey: MEM0_API_KEY, userId: 'alex' })
const ws = new Workspace({ '/memory': memory }, { mode: MountMode.READ })
```

* A Mem0 API key is a secret. Never put a Platform key in a public browser
  bundle; a browser app calls a server-side proxy instead.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Mem0 mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `mem0`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<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.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `mem0`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```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.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.