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.

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
docs		docs
npm		npm
scripts		scripts
skills/memos-memory		skills/memos-memory
src/memos_cli		src/memos_cli
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
MemOS CLI.md		MemOS CLI.md
README-zh.md		README-zh.md
README.md		README.md
memos.spec		memos.spec
package.json		package.json
pyproject.toml		pyproject.toml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

MemOS CLI

Project Structure

Installation

End Users

Development

Uninstall

Quick Start

1. Initialize

Native Hook

2. Add Memory

3. Search Memories

4. Chat with MemOS

5. Get Memories

6. Delete Memory

7. Get Memory Origin

Command Reference

memos add

memos search

memos get

memos delete

memos origin

memos extract

memos rerank

memos feedback

memos chat

memos message

memos status

memos kb

memos kb create

memos kb remove

memos kb add-file

memos kb get-file

memos kb list-file

memos kb delete-file

Output Modes

Global Options

Configuration

Environment Variables

Agent Integration

Telemetry & Source Tracking

Development

Run from source

Add new commands

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`memos add`

`memos search`

`memos get`

`memos delete`

`memos origin`

`memos extract`

`memos rerank`

`memos feedback`

`memos chat`

`memos message`

`memos status`

`memos kb`

`memos kb create`

`memos kb remove`

`memos kb add-file`

`memos kb get-file`

`memos kb list-file`

`memos kb delete-file`