| 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, 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 from this workspace
The CLI is included in this workspace and exposes a mindmemos executable.
uv sync
Authenticate once. This writes a local config (API key, default user id, base URL):
uv run mindmemos auth
uv run mindmemos auth --api-key sk-... --user-id alice --base-url http://127.0.0.1:8000
Verify:
uv run mindmemos config show
uv run mindmemos memory search "test"
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.
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 |
mindmemos memory add --content "I'm allergic to peanuts" --user-id alice
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
mindmemos memory add --content "prefers dark mode" --async
memory search — recall by relevance
| 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 |
--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 --json
mindmemos memory search "notes" --filter '{"memory_type":"semantic"}'
memory get — list / filter (no query)
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
mindmemos memory update mem_123 --content "allergic to peanuts and shellfish"
mindmemos memory delete mem_123 --yes
memory feedback — reinforce / correct memory quality
| Option | Meaning |
|---|
--text TEXT | explicit feedback text; omit to let the server analyze recent adds |
--user-id, --app-id, --agent-id, --session-id | scoping |
mindmemos memory feedback --text "the lunch recommendation was wrong; user dislikes spicy food"
mindmemos memory feedback
memory dreaming — consolidation pass
| 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. |
| "That stored memory is wrong / stale" | update (fix one) or delete (remove one) | Targeted by memory_id, which you get from search/get. |
| "Tell the system how it did" — the recalled/produced memory was right or wrong | feedback | Signals to reinforce or correct memory quality; with no --text, the server analyzes recent adds itself. Use after an interaction whose outcome reveals memory quality. |
| "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:
client.memory.add(messages=[DialogueMessage(role="user", content="allergic to peanuts")])
hits = client.memory.search("dietary restrictions", top_k=5)
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.
