MemOS CLI

MemOS CLI is designed for Agents and development environments that can execute shell commands. It wraps common memory operations into the memos command, so you can verify memory flows in a terminal or let an Agent search memories before answering and write useful new memories afterward.

1. When to Use It

• You want to quickly test memory operations such as add, search, get, and delete in a terminal.
• Your Agent framework can execute shell commands, but does not have a dedicated MemOS plugin.
• You want one reusable Skill to work across multiple Agents instead of writing a separate plugin for each framework.

If you use OpenClaw, prefer the OpenClaw Cloud Plugin. If your client supports MCP natively, see the MCP Guide.

2. Install

npm install -g @memtensor/memos-cloud-cli

After installation, confirm that the CLI is available:

memos --help

3. Choose a Usage Mode and Configure

MemOS CLI has two usage modes: install a memory Skill for an Agent, or manually run memos commands in a terminal.

3.1 Use with Agents

To let an Agent automatically search and write memories, use memos init to install the memory Skill. --agent is currently required; if it is omitted, the command fails because the CLI needs to know where to install the Skill.

memos init --agent codex

You can also write the API Key during initialization:

memos init --api-key YOUR_API_KEY --agent codex

The currently supported Agents are listed below. Pass the matching value via --agent:

For example, to install the memory Skill for Cursor:

memos init --agent cursor

Once installed, the Agent will automatically load the Skill. During each conversation turn, the Agent will:

1. Before answering — automatically run memos search to retrieve long-term memories related to the current task
2. After answering — automatically run memos add to write new facts, preferences, etc. into MemOS

If you already have a MemOS plugin installed (e.g. the OpenClaw cloud plugin), add --memos-plugin to generate plugin-aware Skill guidance:

memos init --agent openclaw --memos-plugin

3.2 Use Directly in Terminal

If you only use CLI commands manually in a terminal and do not install an Agent Skill, use memos config set to configure CLI variables. After these values are set, later commands automatically use them when the corresponding parameter is not provided.

Configure the API Key:

memos config set platform.api_key YOUR_API_KEY

Configure the default user ID:

memos config set defaults.user_id user_123

Configure the default conversation ID:

memos config set defaults.conversation_id conv_001

4. Quick Start

After completing Agent initialization or terminal configuration above, use the following commands to verify memory operations.

Add a memory:

memos add "The user prefers Python programming"

Search related memories:

memos search "programming language preference"

Chat with memory:

memos chat "Do you know my preference?"

Get memories for a user:

memos get user_123

Query the original text of a memory:

memos origin mem_123456

Delete one memory, or delete all memories for a user:

memos delete mem_123456
memos delete --user-id user_123

5. Command Reference

memos add

Write a memory into MemOS.

memos add "The user prefers Python for data analysis and often uses pandas"
memos add --message "The user frequently uses Jupyter Notebook" --user-id user_123

memos search

Search for memories related to a query.

memos search "data analysis tool preference"
memos search "programming language" --format json --detail detail

memos get

Get memories by user.

memos get user_123
memos get user_123 --format json --detail detail

memos origin

Query the original text of a memory by memory ID.

memos origin mem_123456
memos origin mem_123456 --format json

memos delete

Delete one memory, or delete all memories for a user.

memos delete mem_123456 --format json
memos delete --user-id user_123 --format json

memos chat

Chat using MemOS memories as context.

memos chat "Do you know my preferences?"
memos chat "Do you know my preferences?" --user-id user_123 --format table

memos extract

Extract candidate memories from a message without writing them.

memos extract "The user likes coffee and prefers dark mode" --format json

memos rerank

Rerank candidate documents by relevance.

memos rerank "python backend" "Flask guide" "React guide" --format json

memos feedback

Submit feedback to improve memory management quality.

memos feedback "Prefer concise, direct technical answers." --user-id user_123 --format json

memos message

Retrieve original conversation messages.

memos message --user-id user_123 --conversation-id conv_001
memos message --user-id user_123 --limit 10 --format table

memos status

Query the processing status of an async task. The task ID comes from the task_id returned by add or feedback in async mode.

memos status abc123-task-id --format json

Returned status values include running, completed, and failed.

memos kb

Knowledge base management subcommand group: create knowledge bases, upload documents, and query or delete files.

memos kb create

Create a knowledge base.

memos kb create --name "Product FAQ" --description "Common product questions" --format json

memos kb remove

Remove (delete) a knowledge base.

memos kb remove base_xxxxx --format json

memos kb add-file

Upload documents to a knowledge base. Supports PDF, DOCX, DOC, TXT, JSON, MD, XML.

memos kb add-file --kb-id base_xxxxx --files '["https://example.com/doc.pdf"]' --format json
memos kb add-file --kb-id base_xxxxx --files '[{"content":"https://cdn.example.com/file.docx"}]' --format json

memos kb get-file

Get knowledge base file details and processing status.

memos kb get-file --file-ids '["file_id_1", "file_id_2"]' --format json

memos kb list-file

List files in a knowledge base with pagination, optionally filtered by type.

memos kb list-file --kb-id base_xxxxx
memos kb list-file --kb-id base_xxxxx --type skill --page 2 --page-size 10 --format json

memos kb delete-file

Delete files from a knowledge base.

memos kb delete-file --kb-id base_xxxxx --file-ids '["file_id_1"]' --format json

6. Output Formats

All commands support --format. The default format is agent. search and get also support --detail.

memos search "python"
memos search "python" --format table --detail simple
memos search "python" --format markdown --detail detail
memos search "python" --format agent --detail simple
memos search "python" --format json --detail detail

7. Configuration Commands and Environment Variables

View or modify local configuration:

memos config show
memos config get platform.api_key
memos config set platform.api_key YOUR_API_KEY
memos config set defaults.user_id user_123
memos config set defaults.conversation_id conv_001

Global options:

All CLI requests include a source=cli tag. When the framework can be identified from environment variables or parent processes, the framework info is also attached to memory API requests.

8. CLI, Plugin, and MCP

The three approaches are complementary. Plugin is best for deep integration, CLI + Skill for general automation, and MCP for MCP-native clients.

Next Steps