MindMemOS CLI Guide

English   │   简体中文

1. Overview

mindmemos is the command-line tool shipped with the MindMemOS Python SDK (mindmemos_sdk). It lets you operate the memory service directly from the terminal: write and search memories, manage SDK-registered Skills, and inspect local configuration and connectivity.

It is a thin wrapper over the SDK: every command reads the local config file (~/.mindmemos/settings.json) and calls the mindmemos service over HTTP, so you neither hand-craft requests nor repeat the service address on the command line.

2. Installation

pip install mindmemos-sdk

Verify the command is available:

mindmemos --help

The command is exposed as a global mindmemos executable via project.scripts.

3. Quick Start

3.1 Configure authentication

Before first use, run mindmemos auth to configure the service address, API key, and default user:

mindmemos auth

You will be prompted for three settings:

Setting	Local self-hosted service	Official cloud service
Base URL	http://127.0.0.1:8000	https://mindmemos.cn
API key	An enabled key from config/mindmemos/api_keys.yaml	A key issued via the website
User id	A stable identifier, e.g. u_123	A stable identifier, e.g. u_123

Or pass them as flags to skip the prompts:

mindmemos auth --base-url http://127.0.0.1:8000 --api-key dev-api-key-001 --user-id u_123

The configuration is saved to ~/.mindmemos/settings.json. The local service auto-determines project_id from the API key, so you do not need to specify it.

3.2 Inspect configuration and connectivity

# Show current configuration (API key is masked by default)
mindmemos config show

# Show the full API key
mindmemos config show --show-secret

# Verify the config is valid and the service is reachable
mindmemos doctor

3.3 Add a memory

mindmemos memory add --content "I like iced Americanos."

3.4 Search memories

mindmemos memory search "What kind of coffee does the user like?" --top-k 5

See the "Memory commands" section below for more parameters. The CLI only makes the call and displays results; extraction, scoring, and storage all happen on the server.

4. Command Overview

mindmemos
├── auth                  Configure API key, user, and service address interactively
├── config                Show / reset local configuration
│   ├── show
│   └── reset
├── memory                Memory operations
│   ├── add               Add a dialogue message as memory
│   ├── search            Search memories
│   ├── get               List / filter memories in the current project
│   ├── update            Update a memory's content
│   ├── delete            Delete a memory
│   ├── feedback          Submit explicit / implicit feedback
│   └── dreaming          Trigger the dreaming pipeline
├── skill                 Manage SDK-registered Skills
│   ├── register          Register and upload a local Skill
│   ├── list              List registered Skills
│   ├── show              Show a single Skill
│   ├── evolve            Trigger cloud Skill evolution
│   ├── push              Upload local changes as a new version
│   ├── pull              Pull version metadata (without changing files)
│   ├── update            Update one or all Skills
│   ├── rollback          Roll back to a specific version
│   ├── history           Show version history
│   ├── diff              Show version differences
│   └── unregister        Remove a Skill from management
└── doctor                Check SDK configuration and connectivity

Every command supports --help for full parameter details:

mindmemos memory add --help

5. Memory Commands (mindmemos memory)

Memory commands use the credentials configured by mindmemos auth — no need to repeat them.

5.1 Add memory add

The most common form passes a single message:

mindmemos memory add --content "I like iced Americanos."

Specify a role (default user):

mindmemos memory add --content "Remember this preference" --role system

Multi-turn messages can be passed as JSON, either inline or from a file (when provided, --content / --role are ignored):

# Inline JSON
mindmemos memory add --messages-json \
  '[{"role":"user","content":"I like iced Americanos."},{"role":"assistant","content":"Got it."}]'

# From a file
mindmemos memory add --messages-json-file ./messages.json

Async mode (returns a request_id immediately, without waiting for extraction):

mindmemos memory add --content "I like iced Americanos." --async

Other options:

Option	Description
--user-id	Override the configured default user
--app-id / --agent-id / --session-id	Context identifiers for scoping / filtering
--metadata-json	Business metadata (JSON object)
--skill-context-json	Skill context array, overriding SDK auto-detection
--json	Print the full result as machine-readable JSON

Example output:

Added 1 memory item(s):
- [did] m_8f3a: I like iced Americanos.

5.2 Search memories search

mindmemos memory search "What kind of coffee does the user like?" --top-k 5

Common options:

Option	Description
--top-k	Number of results, default 10
--search-strategy	Search strategy, fast (default) or agentic
--rerank	Enable reranking
--score-threshold	Rerank relevance threshold (0-1); only meaningful with --rerank
--filter	Filter DSL (JSON object string)
--user-id etc.	Override request context
--json	Print the full result as JSON

5.3 List and filter get

List memories in the current project, optionally filtered:

# List the 20 most recent
mindmemos memory get --top-k 20

# Filter with a filter DSL
mindmemos memory get --filter '{"field":"value"}'

5.4 Update and delete

# Update a memory's content
mindmemos memory update <memory_id> --content "new content"

# Delete a memory (-y skips the confirmation)
mindmemos memory delete <memory_id> --yes

5.5 Feedback feedback

By default this runs implicit feedback, letting the server analyze recent adds; pass --text for explicit feedback:

# Implicit feedback
mindmemos memory feedback

# Explicit feedback, which also requires the messages that produced it
mindmemos memory feedback --text "This memory is inaccurate" \
  --messages-json '[{"role":"user","content":"..."}]'

5.6 Dreaming dreaming

Trigger the dreaming pipeline, either synchronously or asynchronously:

# Enqueue asynchronously (default)
mindmemos memory dreaming --async

# Wait for completion
mindmemos memory dreaming --sync

6. Skill Commands (mindmemos skill)

mindmemos skill manages local Skills that are registered with the SDK and can evolve in the cloud.

Register a local Skill (path may be a directory or a SKILL.md file):

mindmemos skill register ./my-skill
# Give it an alias for later commands
mindmemos skill register ./my-skill --alias my-skill

Common operations:

# List / show registered Skills
mindmemos skill list
mindmemos skill show <skill-id-or-alias>

# Trigger cloud evolution (sync by default; --async enqueues)
mindmemos skill evolve <skill-id-or-alias> --sync

# Push local changes as a new version; pull version metadata
mindmemos skill push <skill-id-or-alias>
mindmemos skill pull <skill-id-or-alias>

# Update one or all Skills (--all updates everything, -y skips confirmation)
mindmemos skill update <skill-id-or-alias> --yes
mindmemos skill update --all --yes

# Unregister (--delete-files also removes the local directory)
mindmemos skill unregister <skill-id-or-alias> --delete-files --yes

Version management:

# Show version history
mindmemos skill history <skill-id-or-alias>

# Roll back to a specific version
mindmemos skill rollback <skill-id-or-alias> --to <version-id> --yes

# Diff between two versions
mindmemos skill diff <skill-id-or-alias> --from <version-id> --to <version-id>

Before applying changes that may touch local files (update / rollback), the command prints a plan and asks for confirmation.

7. Configuration (mindmemos config)

# Show current configuration
mindmemos config show
mindmemos config show --show-secret   # Show the full API key

# Reset and delete the local configuration
mindmemos config reset
mindmemos config reset --yes          # Skip the confirmation

The config file lives at ~/.mindmemos/settings.json; set the MINDMEMOS_CONFIG_DIR environment variable to use a different config directory.

The API key is sensitive and is masked in config show by default (use --show-secret to reveal it).

8. Troubleshooting

Symptom	Possible cause / fix
No SDK config at … Run mindmemos auth first.	Not configured yet; run mindmemos auth
No api_key configured	API key missing; re-run mindmemos auth
transport: not ready …	doctor found the service unreachable. Confirm the service is up and base_url is correct: http://127.0.0.1:8000 for local, https://mindmemos.cn for cloud
Authentication error from the service	The API key is invalid or disabled; check the cloud key or an enabled key in config/mindmemos/api_keys.yaml
ENOENT in a plugin environment	A GUI-launched process does not inherit the terminal PATH; configure mindmemos as an absolute path or wrap it with uv run mindmemos. See OpenClaw plugin integration

Run mindmemos doctor anytime as a one-shot config / connectivity check.

9. Related Documentation

• Python SDK integration
• OpenClaw plugin integration
• Deployment & Configuration Guide
• API docs