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 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mindscale-noah/MindMemOS --skill 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.
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_idand includes it in command responses for tracing. search/addsupport--jsonfor 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 authonce.- During a session:
memory searchto recall,memory addto store turns. - Maintenance / background:
memory getto inspect,memory update/memory deleteto correct,memory feedbackandmemory dreamingto 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