Mindmemos CLI

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.

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).

# 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.

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

Use memory update when a specific memory id is known and the stored content should be rewritten because it is stale, incomplete, or partially wrong.

Use memory delete when a specific memory id is known and the memory should be removed because it is invalid, duplicated, sensitive, or no longer appropriate.

mindmemos memory update mem_123 --content "allergic to peanuts and shellfish"
mindmemos memory delete mem_123 --yes

memory feedback — reinforce / correct memory quality

Use feedback after an outcome reveals whether recalled memory was helpful, missing, stale, or wrong; choose explicit or implicit mode based on whether the caller can provide the interaction context.

Feedback has two modes:

mindmemos memory feedback \
  --text "the lunch recommendation was wrong; user dislikes spicy food" \
  --messages-json '[{"role":"user","content":"I do not like spicy food."}]'

mindmemos memory feedback \
  --text "the coffee preference was wrong" \
  --messages-json-file turn.json \
  --recalled-memories-json '[{"id":"mem_123","memory":"User prefers hot coffee."}]'

mindmemos memory feedback   # omit --text: server analyzes recent adds

memory dreaming — consolidation pass

Use as a scheduled or background maintenance step to consolidate, merge, compress, or reorganize accumulated memories outside the hot request path.

mindmemos memory dreaming
mindmemos memory dreaming --sync --app-id openclaw

Other groups

• mindmemos auth / config show [--show-secret] / config reset [-y] — credentials & local settings.
• mindmemos skill <register|list|show|pull|push|update|rollback|history|diff|unregister> — SDK-managed skills. Use register <skill_dir_or_SKILL.md> --alias <alias> to save a local alias, then use that alias anywhere a skill id is accepted. Use push <skill> after editing local SKILL.md to upload a new version. Use update <skill|--all> [--yes] to checkout published heads, rollback <skill> --to <version_id> [--yes] to restore a cached/downloaded version after reviewing the replacement plan, and diff <skill> [--from <version_id>] --to <version_id> for a read-only unified diff.
• mindmemos memory add ... --skill-context-json '[...]' — optional explicit skill trace context. When omitted, the SDK has a best-effort fallback for OpenClaw-style SKILL.md tool-call text in the add messages; host integrations such as the OpenClaw plugin may still provide their own detection and pass this flag explicitly.
• mindmemos doctor — config/connectivity check.

Capabilities — when to use what

MindMemOS is a memory lifecycle, not just a key-value store. Pick the operation by intent:

Rules of thumb:

• add + search are the hot path — almost every agent turn does one or both.
• feedback and dreaming are the slow path — they improve memory quality over time. feedback is event-driven (an outcome happened); dreaming is schedule-driven (periodic consolidation), not for a hot request path.
• update / delete / get are manual curation — fixing mistakes and inspecting state, usually by a human or an admin tool, not in normal conversation flow.
• Always scope writes and reads with a stable --user-id (and --session-id where it matters) so memories don't leak across users.

Calling from Python

When memory operations live inside a Python agent/app rather than a shell call, use the SDK shipped in the same mindmemos package (same API, same mindmemos auth config). See references/python-sdk.md for the full sync + async example. Minimal sync usage:

from mindmemos_sdk import MindMemOSClient, DialogueMessage

with MindMemOSClient(user_id="alice") as client:   # reads base URL and API key from `mindmemos auth`
    client.memory.add(messages=[DialogueMessage(role="user", content="allergic to peanuts")])
    hits = client.memory.search("dietary restrictions", top_k=5, user_id="alice")
    for hit in hits.memories:
        print(hit.id, hit.memory)

Host integrations

To wire MindMemOS into an agent host so memory is recalled and stored automatically (rather than calling the CLI by hand), follow the host-specific guide. All hosts depend on the CLI installed and authenticated above.

• OpenClaw — references/openclaw-plugin.md
• DeepSeek Harness — references/deepseek-harness-plugin.md
• Codex — planned
• Claude — planned