Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

mindmemos-cli

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

mindscale-noah · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add mindscale-noah/MindMemOS --skill mindmemos-cli

About this skill


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.


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

OptionMeaning
--content TEXTsingle 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 PATHread the JSON array from a file (- = stdin)
--user-id, --app-id, --agent-id, --session-idscoping
--metadata-json '{...}'business metadata object
--skill-context-json '[...]'explicit skill trace context
--asyncenqueue and return immediately (no extracted memories in response)
--jsonmachine-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.

OptionMeaning
query (positional)search text
--top-k Nresults to return (default 10)
--search-strategy {fast,agentic}fast = vector recall; agentic = multi-step reasoning over memory
--rerankrerank candidates for precision
--score-threshold Nminimum rerank relevance score (0–1); only effective with --rerank
--token-budget Nstrict 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-idscoping; omit --user-id for project-wide search
--jsonmachine-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

Read the complete source ↗