Mindmemos CLI Agent Skill

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

• mindmemos auth once.
• During a session: memory search to recall, memory add to store turns.
• 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 |

| --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 --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:

| Mode | When to use | Required context |

|---|---|---|

| Explicit feedback (--text) | Use when the user or host has a concrete correction or quality signal about a specific interaction, such as "that recalled preference was wrong." | Must include --messages-json or --messages-json-file; include recalled memories when available. |

| Implicit feedback (no --text) | Use when the service should mine recent add records and interaction traces for feedback signals without a caller-written correction. | No messages are passed on the CLI; the server derives context from recent records. |

| Option | Meaning |

|---|---|

| --text TEXT | explicit feedback text; requires message context |

| --messages-json '[...]' | JSON array of messages from the feedback round |

| --messages-json-file PATH | read feedback messages from a file (- = stdin) |

| --recalled-memories-json '[...]' | optional JSON array of memories recalled in that round |

| --recalled-memories-json-file PATH | read recalled memories from a file (- = stdin) |

| --user-id, --app-id, --agent-id, --session-id | scoping |

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.

| Option | Meaning |

|---|---|

| --sync | run synchronously |

| --async | enqueue asynchronously (default) |

| --user-id, --app-id, --agent-id, --session-id | scoping |

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:

| Intent | Use | Notes |

|---|---|---|

| "Remember this" — a new fact, preference, or conversation turn surfaced | add | Server extracts durable facts and dedups/merges against existing memory. Prefer passing real conversation messages over hand-written summaries. |

| "What do I already know about X?" — pull context before answering | search | Relevance-ranked. fast for latency-sensitive recall; agentic when the answer requires reasoning across several memories; add --rerank when precision matters more than speed. |

| "Show me everything in this project / a slice of it" | get | Filter/enumerate without a query; for inspection, audits, dashboards. |

| "This stored memory is stale or partly wrong" | update | Rewrite one known memory_id while keeping the memory as the corrected canonical record. |

| "This stored memory should not exist" | delete | Remove one known memory_id when the memory is invalid, duplicated, sensitive, or inappropriate to keep. |

| "The last recall was wrong/helpful/missing something" — the caller can provide the interaction context | explicit feedback --text | Pass --messages-json or --messages-json-file; pass recalled memories too when available so the planner can target the right memory. |

| "Review recent memory operations for quality signals" — no explicit correction text is available | implicit feedback | Omit --text; the server analyzes recent add records and traces itself. |

| "Consolidate in the background" — compress, link, reorganize accumulated memory | dreaming | An offline maintenance pass with no inputs. Run periodically (e.g. scheduled), not per-turn. |

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