@memtensor/memos-cloud-cli

MemOS CLI

Universal memory interface for AI agents.

Project Structure

MemOS-CLI/
├── src/memos_cli/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # python -m memos_cli entry
│   ├── main.py              # Main CLI app (Typer)
│   ├── config.py            # Configuration management
│   ├── output.py            # Output formatting (text/json)
│   ├── branding.py          # Brand colors and symbols
│   ├── state.py             # State management (agent mode)
│   ├── telemetry.py         # Telemetry reporting
│   ├── backend/             # API backend layer
│   │   ├── base.py          # Abstract base class
│   │   ├── memos_api.py     # MemOS Cloud API implementation
│   │   ├── message_api.py   # Message API
│   │   └── kb_api.py        # Knowledge base API
│   └── commands/            # CLI commands
│       ├── init.py          # memos init
│       ├── hook.py          # internal memos hook run entrypoint
│       ├── config_cmd.py    # memos config (show/get/set)
│       ├── memory.py        # add/search/get/origin/delete/extract/rerank/feedback/chat
│       ├── memory_cmd.py    # Memory command execution layer
│       ├── message.py       # memos message / memos status
│       ├── message_cmd.py   # Message command execution layer
│       ├── kb.py            # memos kb (create/remove/add-file/get-file/list-file/delete-file)
│       └── kb_cmd.py        # Knowledge base command execution layer
│   └── hooks/               # Native host hook adapters
│       ├── agents.py        # Native hook agent registry
│       ├── runner.py        # stdin/stdout lifecycle runner
│       ├── codex.py         # Shared payload and transcript parsing
│       ├── state_store.py   # Cross-process turn state
│       └── installer.py     # Safe hook config merge/uninstall
├── skills/
│   └── memos-memory/        # Memory domain skill
│       ├── SKILL.md         # Skill entry and usage protocol
│       └── references/      # Skill reference docs
│           ├── memos-add.md
│           ├── memos-chat.md
│           ├── memos-delete.md
│           ├── memos-extract.md
│           ├── memos-get.md
│           ├── memos-origin.md
│           ├── memos-search.md
│           ├── memos-uninstall.md
│           ├── memos-kb-create.md
│           ├── memos-kb-remove.md
│           ├── memos-kb-add-file.md
│           ├── memos-kb-get-file.md
│           ├── memos-kb-list-file.md
│           └── memos-kb-delete-file.md
├── pyproject.toml
├── package.json
├── bin/
│   └── memos.js            # npm launcher
├── scripts/
│   └── postinstall.js      # npm binary installer
├── npm/
│   └── README.md           # npm binary payload directory
└── README.md

Installation

End Users

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

The npm package downloads a prebuilt MemOS CLI binary for the current platform during installation, so end users do not need a local Python environment.

Development

pip install -e .

Uninstall

memos uninstall --agent codex --yes
npm uninstall -g @memtensor/memos-cloud-cli

Run memos uninstall --agent <agent> --yes before removing the npm package. For Codex it removes the native Hook, turn state, installed skill, and managed guidance block; npm uninstall only removes the global binary.

See skills/memos-memory/references/memos-uninstall.md for the agent-facing uninstall workflow.

Quick Start

1. Initialize

memos init --agent codex

For supported hook agents, this command installs the complete MemOS integration: API configuration, management skill, native Hook, Hook-aware guidance, and CLI PATH setup. The Hook automatically retrieves memory before the model call and captures the completed turn after the response. --agent is required, and installation to a generic global directory is not supported. --memos-plugin is a legacy option for non-hook targets and is ignored when a native Hook is available. It also installs shell completion automatically for the current shell when shell detection succeeds.

Native Hook

The native Hook is installed and removed together with the target agent integration:

memos init --agent codex
memos uninstall --agent codex --yes

The installed skill is management-only, so it does not repeat the Hook's automatic search/add lifecycle. The installer updates only MemOS-managed hook entries or plugins, preserves unrelated hooks/plugins, and is safe to run repeatedly. The API key remains in ~/.memos/config.yaml; it is never copied into agent hook configuration, plugins, or hook state. memos hook run --agent <agent> --event <event> is the internal command invoked by the host. Hook failures are fail-open and do not block the host conversation.

Native Hook lifecycle:

• Codex / Claude Code: UserPromptSubmit → search, Stop → add
• Cursor: beforeSubmitPrompt → search, afterAgentResponse → add
• Hermes: the user plugin at ~/.hermes/plugins/memos-memory/ registers pre_llm_call → search and post_llm_call → add across CLI / TUI / Gateway / Desktop; plugins.enabled in ~/.hermes/config.yaml enables it
• OpenCode V2: ctx.session.hook("context") → search, session.idle → add
• OpenClaw: before_prompt_build → search, agent_end → add

Supported targets:

• --agent codex → ~/.codex/skills/memos/
• --agent cursor → ~/.cursor/skills/memos/
• --agent claude → ~/.claude/skills/memos/
• --agent openclaw → ~/.openclaw/skills/memos/
• --agent hermes → ~/.hermes/skills/memos/
• --agent trae → ~/.trae/skills/memos/
• --agent trae-cn → ~/.trae-cn/skills/memos/
• --agent opencode → ~/.config/opencode/skills/memos/
• --agent antigravity → ~/.gemini/config/skills/
• --agent workbuddy → ~/.codebuddy/skills/memos/
• --agent cline → ~/.cline/skills/memos/
• --agent copilot → ~/.copilot/skills/memos/
• --agent deepseek → ~/.dsh/skills/memos-memory/ (or $DSH_HOME/skills/memos-memory/)

For DeepSeek Harness, the matching guidance is written to ~/.dsh/AGENTS.md, or $DSH_HOME/AGENTS.md when DSH_HOME is set.

Or with arguments:

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

For Codex, automatic search and add are already owned by the native Hook. The commands below are optional direct CLI operations, not additional per-turn lifecycle steps.

2. Add Memory

memos add "User likes Python programming"

3. Search Memories

memos search "programming languages"

4. Chat with MemOS

memos chat "What do you know about my preferences?"

5. Get Memories

memos get user_123

6. Delete Memory

memos delete mem_123456

7. Get Memory Origin

memos origin mem_123456

Command Reference

memos add

Write a memory into MemOS using simple text input.

Example:

memos add "User likes Python programming"

Parameters:

• [MESSAGE]: Memory content to add; required; use [MESSAGE] or --message.
• -m, --message: Memory content to add; optional; alias of [MESSAGE]; no separate default.
• --user-id: User scope for the memory write; optional; defaults to configured defaults.user_id.

memos search

Search memories with semantic retrieval and optional preference/tool/skill expansion.

Example:

memos search "programming languages" --user-id user_123 --format table --detail simple

Parameters:

• [QUERY]: Search query text; required; use [QUERY] or --query.
• -q, --query: Search query text; optional; alias of [QUERY]; no separate default.
• --user-id: User scope for retrieval; optional; defaults to configured defaults.user_id.
• --memory-limit-number: Main memory recall count; optional; defaults to 9.
• --include-preference: Whether to include preference memory; optional; accepts true or false; defaults to true when omitted.
• --preference-limit-number: Preference memory recall count; optional; defaults to 9.
• --include-tool-memory: Whether to include tool memory; optional; accepts true or false; defaults to false when omitted.
• --tool-memory-limit-number: Tool memory recall count; optional; defaults to 6.
• --include-skill-memory: Whether to include skill memory; optional; accepts true or false; defaults to false when omitted.
• --skill-memory-limit-number: Skill memory recall count; optional; defaults to 6.
• --relativity: Retrieval threshold; not exposed in the current CLI; API default is 0.45.
• --format: Output format; optional; defaults to agent.
• --detail: Output detail level for non-JSON formats; optional; defaults to simple; supported values: simple, detail.

memos get

Call the documented get_memory API to retrieve memories for a user.

Example:

memos get user_123 --format json --detail detail

Parameters:

• [USER_ID]: Retrieval scope; effectively required, but if omitted the CLI falls back to configured defaults.user_id.
• --user-id: Alias of [USER_ID]; optional; same fallback as [USER_ID].
• --page: Page number; optional; API default is 1 when omitted.
• --size: Number of items returned per memory category on the current page; optional; API default is 10 when omitted.
• --include-preference: Whether to include preference memory; optional; accepts true or false; defaults to true when omitted.
• --include-tool-memory: Whether to include tool memory; optional; accepts true or false; current CLI exposes this flag, but the official get_memory docs do not state the API default when omitted.
• --format: Output format; optional; defaults to agent.
• --detail: Output detail level for non-JSON formats; optional; defaults to simple; supported values: simple, detail.

memos delete

Delete one memory, or delete all memories for a user, using the documented delete API.

Example:

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

Parameters:

• MEMORY_ID: Memory ID to delete; conditionally required; use MEMORY_ID to delete one memory.
• --user-id: Delete all memories for the given user ID; conditionally required; use --user-id to delete all memories for a user.

memos origin

Get the original source payload for a specific memory by memory ID.

Example:

memos origin mem_123456
memos origin mem_123456 --detail simple
memos origin mem_123456 --detail detail
memos origin mem_123456 --format markdown --detail detail
memos origin mem_123456 --format json

Parameters:

• [MEMORY_ID]: Memory ID; required.
• --format: Output format; optional; defaults to agent.
• --detail: Output detail level; optional; defaults to simple; supported values: simple, detail.

Default display includes:

• simple: memory_id, memory summary, and source content.
• detail: memory_id, memory summary, source type, role, time, language, and source content.
• source messages are extracted from data.metadata.sources.

memos extract

Preview memory candidates from messages without storing them.

Example:

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

Parameters:

• [MESSAGE]: Message content to extract from; required; use [MESSAGE] or --message.
• -m, --message: Message content to extract from; optional; alias of [MESSAGE]; no separate default.
• --user-id: User scope; optional; defaults to configured defaults.user_id.

memos rerank

Rerank candidate documents for a query.

Example:

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

Parameters:

• [QUERY]: Query used for reranking; required; use [QUERY] or --query.
• [DOCUMENTS]...: Candidate documents; required; provide one or more documents as positional arguments, repeated --documents, or stdin.
• -q, --query: Query used for reranking; optional; alias of [QUERY]; no separate default.
• --documents: Candidate document, repeatable; optional; repeatable alternative to positional [DOCUMENTS]....
• --top-n: Return only the top N results; optional; no CLI default; omitted from the request unless provided.
• --format: Output format; optional; defaults to agent.

memos feedback

Submit feedback content to MemOS.

Example:

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

Parameters:

• [FEEDBACK_TEXT]: Feedback content to submit; required; use [FEEDBACK_TEXT] or --feedback-content.
• --feedback-content: Feedback content to submit; optional; alias of [FEEDBACK_TEXT]; no separate default.
• --user-id: User scope; optional; defaults to configured defaults.user_id.

memos chat

Ask MemOS for a memory-informed answer using the documented chat request fields.

Example:

memos chat "What do you know about my preferences?" --user-id user_123 --format agent

Parameters:

• [QUERY]: Chat query text; required; use [QUERY] or --query.
• -q, --query: Chat query text; optional; alias of [QUERY]; no separate default.
• --user-id: User scope; optional; defaults to configured defaults.user_id.

memos message

Retrieve original conversation messages.

Example:

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

Parameters:

• --user-id: User ID; required.
• --conversation-id: Conversation ID; optional; defaults to configured defaults.conversation_id.
• --limit: Max messages to return; optional; default 6, max 50.
• --format: Output format; optional; default agent.

memos status

Query async task processing status (from task_id returned by add or feedback with async_mode).

Example:

memos status abc123-task-id --format json

Parameters:

• [TASK_ID]: Async task ID; required.
• --format: Output format; optional; default agent.

Returned status values: running, completed, failed.

memos kb

Knowledge base management subcommand group.

memos kb create

Create a knowledge base.

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

Parameters:

• --name: Knowledge base name; required.
• --description: Knowledge base description; optional.
• --format: Output format; optional; default agent.

memos kb remove

Remove (delete) a knowledge base.

memos kb remove base_xxxxx --format json

Parameters:

• [KB_ID]: Knowledge base ID; required.
• --format: Output format; optional; default agent.

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

Parameters:

• --kb-id: Target knowledge base ID; required.
• --files: JSON array of file entries — URL strings or {"content": "..."} objects; required.
• --format: Output format; optional; default agent.

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

Parameters:

• --file-ids: JSON array of file IDs; required.
• --format: Output format; optional; default agent.

memos kb list-file

List files in a knowledge base with pagination and optional type filtering.

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

Parameters:

• --kb-id: Knowledge base ID; required.
• --type: Filter by file type: document or skill; optional.
• --page: Page number; optional; default 1.
• --page-size: Items per page; optional; default 20.
• --format: Output format; optional; default agent.

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

Parameters:

• --kb-id: Knowledge base ID; required.
• --file-ids: JSON array of file IDs to delete; required.
• --format: Output format; optional; default agent.

Output Modes

Each subcommand supports trailing --format. Only search and get also support trailing --detail:

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
memos get user_123 --format json --detail detail
memos add "User prefers TypeScript" --format json

Global Options

• --api-key KEY: Override API key from config
• --base-url URL: Override API base URL from config
• --version: Show version

Configuration

View current config:

memos config show

Example output includes:

• API Key
• Base URL
• Source
• Framework
• default User ID and Conversation ID

Get/Set specific values:

memos config get platform.api_key
memos config set defaults.user_id user123
memos config set defaults.multi_view_enabled true

Environment Variables

• MEMOS_API_KEY: Your API key
• MEMOS_BASE_URL: API base URL (default: https://memos.memtensor.cn/api/openmem/v1)
• MEMOS_FRAMEWORK: Override framework attribution (for example codex)
• MEMOS_MULTI_VIEW_ENABLED: Enable multi-view project scoping (true or false)

Agent Integration

Use the provided skill to enable memory operations in your agent framework.

Use this skill when:

• you need memory operations such as extract, add, search, chat, get, and delete: skills/memos-memory/SKILL.md
• you need to remove the MemOS skill and managed agent guidance: skills/memos-memory/references/memos-uninstall.md

Recommended entry point:

• Start with skills/memos-memory/SKILL.md.

Telemetry & Source Tracking

All CLI requests include:

• source=cli-<framework> header when the framework can be identified, for example source=cli-codex
• Framework detection (OpenClaw, Hermes, etc.)

Memory API requests also attach framework metadata when it can be detected from environment variables or the parent process.

This enables usage analytics and framework-specific optimizations.

Framework detection is resolved in this order:

• runtime override
• saved config value from memos init --agent ...
• MEMOS_FRAMEWORK
• shell / parent-process inference

Development

Run from source

python -m memos_cli --help

Add new commands

• Create command file in src/memos_cli/commands/
• Register in src/memos_cli/main.py
• Add to appropriate help panel

License

Apache 2.0 License.