/mindmemos-cli

name: mindmemos-cli
description: Give an AI agent persistent, cross-session long-term memory through MindMemOS. Covers installing and authenticating the mindmemos CLI, the full command interface (add / search / get / update / delete / feedback / dreaming) with parameters and examples, guidance on which capability to use when, plus a Python SDK example. To wire memory into a specific agent host (OpenClaw, DeepSeek Harness, Codex, Claude, etc.), see references/.

MindMemOS CLI

MindMemOS is a long-term memory layer for AI agents. The `mindmemos` CLI is the integration surface: every memory operation is a subcommand that prints either a human-readable line or, with `--json`, stable machine-readable output. Any agent or script can drive memory by shelling out to it.

To connect memory to a specific agent host (e.g. an editor or assistant that supports plugins), the host calls this same CLI. Host-specific install guides live under `references/` — see [Host integrations](#host-integrations).

---

Install the CLI

The CLI ships as the Python package `mindmemos-sdk` and exposes a `mindmemos` executable.

pip install mindmemos-sdk
# or, isolated so it's on PATH globally (recommended):
pipx install mindmemos-sdk
uv tool install mindmemos-sdk

Authenticate once. This writes a local config (API key, default user id, base URL). Operations that require a user inherit the default user id, but `memory search` does not: omit `--user-id` for project-wide search or pass it explicitly for user-scoped search.

mindmemos auth
# non-interactive:
mindmemos auth --api-key sk-... --user-id alice --base-url https://api.mindmemos.example.com

Verify:

mindmemos config show          # masked key, base_url, user_id
mindmemos memory search "test" # confirms connectivity with a project-wide search

---

CLI interface

General shape: `mindmemos <group> <command> [args] [options]`.

• Memory commands do not accept a caller-provided request ID. The server generates

`request_id` and includes it in command responses for tracing.

• `search` / `add` support `--json` for stable machine-readable output (what scripts and host integrations parse).
• Exit codes: `0` = success, `1` = API/config error, `2` = bad arguments. On non-zero exit the error text (including server stderr) is printed to stdout/stderr.

Identity & scoping options (where accepted): `--user-id` (the human the memory belongs to), `--app-id`, `--agent-id`, `--session-id`. Project isolation is derived from the API key, not from these flags. For `memory search`, `--user-id` is per-request and does not inherit the user configured by `mindmemos auth`.

Typical flow

1. `mindmemos auth` once. 2. During a session: `memory search` to recall, `memory add` to store turns. 3. Maintenance / background: `memory get` to inspect, `memory update` / `memory delete` to correct, `memory feedback` and `memory dreaming` to let the system consolidate.

`memory add` — store new memory

Extracts durable facts from messages and persists them (with dedup/merge against existing memory).

| Option | Meaning | |---|---| | `--content TEXT` | single message body (paired with `--role`) | | `--role {user,assistant,system,tool}` | role for `--content` (default `user`) | | `--messages-json '[...]'` | JSON array of messages; overrides `--content` | | `--messages-json-file PATH` | read the JSON array from a file (`-` = stdin) | | `--user-id`, `--app-id`, `--agent-id`, `--session-id` | scoping | | `--metadata-json '{...}'` | business metadata object | | `--skill-context-json '[...]'` | explicit skill trace context | | `--async` | enqueue and return immediately (no extracted memories in response) | | `--json` | machine-readable output |

# single line
mindmemos memory add --content "I'm allergic to peanuts" --user-id alice

# a conversation turn
mindmemos memory add --messages-json \
  '[{"role":"user","content":"book me a window seat next time"},
    {"role":"assistant","content":"Noted, window seats going forward."}]' \
  --session-id sess-42 --json

# fire-and-forget
mindmemos memory add --content "prefers dark mode" --async

`memory search` — recall by relevance

Use before answering or acting when the agent needs prior user preferences, project facts, decisions, or past experience related to the current request.

| Option | Meaning | |---|---| | `query` (positional) | search text | | `--top-k N` | results to return (default 10) | | `--search-strategy {fast,agentic}` | `fast` = vector recall; `agentic` = multi-step reasoning over memory | | `--rerank` | rerank candidates for precision | | `--score-threshold N` | minimum rerank relevance score (0–1); only effective with `--rerank` | | `--token-budget N` | strict token budget for the result set; enables token-budget retention (packing under a token limit) — the result is still capped by `--top-k`, whichever limit is tighter | | `--filter '{...}'` | structured filter DSL, JSON object (e.g. `{"memory_type":"semantic"}`) | | `--user-id`, `--app-id`, `--agent-id`, `--session-id` | scoping; omit `--user-id` for project-wide search | | `--json` | machine-readable output |

mindmemos memory search "what are the user's dietary restrictions?" --top-k 5 --user-id alice
mindmemos memory search "travel prefs" --rerank --search-strategy agentic --token-budget 2000 --user-id alice --json
# project-wide search across all users in the API-key project
mindmemos memory search "project notes" --filter '{"memory_type":"semantic"}'

`memory get` — list / filter (no query)

Use for inspection, audits, dashboards, or manual curation when you need to enumerate stored memories rather than search by semantic relevance.

Returns memories in the current project, optionally filtered. Carries **no** actor identity — project scope comes from the API key.

mindmemos memory get --filter '{"app_id":"openclaw"}' --top-k 20

`memory update` / `memory delete` — correct by id