MemOS Memory Protocol

Command selection rules:

• if the user asks to uninstall, disable, remove, or stop using MemOS, use memos uninstall --agent <current_agent> --yes directly and do not run memos search or memos add for that turn; add --path only when the user also wants to remove the MemOS PATH entries from ~/.bash_profile and ~/.zshenv;
• if the user wants to preview what would be stored, use memos extract directly;
• at the start of a conversation, must use memos search directly with the user's original query;
• at the end of a conversation, must use memos add directly with both the user's question and the assistant's final answer;
• do not run memos search or memos add for intermediate states, including planning, partial progress, compact/resume, or continuation after context compaction;
• if the user wants a memory-aware response from MemOS itself, use memos chat directly;
• if the user already has a concrete memory id, use memos get, memos origin, or memos delete directly;
• if the user wants to manage knowledge bases (create, delete, upload, query files), use the corresponding memos kb subcommand;
• do not call memos --help by default when the intent already matches one of the commands below;
• use memos --help only when the command name, parameters, or route are genuinely unclear;
• do not use memos init as a discovery step when the CLI is already installed.

Identity rules:

• always prefer the exact configured user_id value when a command is scoped by user;
• if the user does not specify the user_id, omit the --user-id argument and use the user_id from the config file by default;

Hard mapping:

• store a durable fact, preference, decision, or long-term task -> memos add
• preview candidate memories before storing -> memos extract
• retrieve context at conversation start -> memos search
• ask MemOS to answer with memory context -> memos chat
• fetch memories by user_id -> memos get
• trace where one memory came from -> memos origin
• remove one concrete memory by id -> memos delete
• delete all memories for a user_id -> memos delete --user-id
• uninstall MemOS integration from the current agent -> memos uninstall --agent <current_agent> --yes
• create a knowledge base -> memos kb create
• remove a knowledge base -> memos kb remove
• upload documents to a knowledge base -> memos kb add-file
• check file processing status in a knowledge base -> memos kb get-file
• list files in a knowledge base -> memos kb list-file
• delete files from a knowledge base -> memos kb delete-file

Use this skill when:

• the task may depend on prior user, project, or conversation context;
• the user provides a stable new fact, preference, or background detail;
• you want to preview extracted memory candidates before storing them;
• you need to inspect, list, delete, or trace the source of an existing memory record;
• you need to create, remove, or manage a knowledge base and its documents.

Never store:

• secrets, API keys, tokens, or passwords;
• unverified guesses or speculative conclusions as user facts;
• short-lived task state that will not matter in future sessions;
• redundant paraphrases when one concise factual memory is enough.

Command examples:

• memos add "<fact>" --user-id <USER_ID> --format json
• memos extract "<message>" --user-id <USER_ID> --format json
• memos search "<query>" --user-id <USER_ID> --format agent --detail simple
• memos chat "<message>" --user-id <USER_ID> --format agent
• memos get <USER_ID> --format json --detail detail
• memos origin <MEMORY_ID> --format json
• memos delete <MEMORY_ID> --format json
• memos delete --user-id <USER_ID> --format json
• memos uninstall --agent <CURRENT_AGENT> --yes
• memos uninstall --agent <CURRENT_AGENT> --yes --path
• memos kb create --name "<name>" --description "<desc>" --format json
• memos kb remove <KB_ID> --format json
• memos kb add-file --kb-id <KB_ID> --files '["https://example.com/doc.pdf"]' --format json
• memos kb get-file --file-ids '["<FILE_ID>"]' --format json
• memos kb list-file --kb-id <KB_ID> --page 1 --page-size 20 --format json
• memos kb delete-file --kb-id <KB_ID> --file-ids '["<FILE_ID>"]' --format json

Choose commands by intent:

• use ./references/memos-add.md when the user gives a durable fact or preference worth saving;
• use ./references/memos-extract.md when the user wants a preview of memory candidates without storing;
• must use ./references/memos-search.md at conversation start;
• use ./references/memos-chat.md when interacting with MemOS chat capability directly;
• use ./references/memos-get.md for retrieval by user_id;
• use ./references/memos-origin.md when you need the original source messages behind a specific memory;
• use ./references/memos-delete.md only when you already have a concrete memory_id;
• use ./references/memos-uninstall.md when the user asks to uninstall, disable, remove, or stop using MemOS;
• use ./references/memos-kb-create.md to create a new knowledge base;
• use ./references/memos-kb-remove.md to remove a knowledge base;
• use ./references/memos-kb-add-file.md to upload documents to a knowledge base;
• use ./references/memos-kb-get-file.md to check file details and processing status;
• use ./references/memos-kb-list-file.md to browse files in a knowledge base;
• use ./references/memos-kb-delete-file.md to delete files from a knowledge base.

Process rules:

• the default workflow is: search at conversation start, work and answer through intermediate states without additional search/add, then add at conversation end;
• when you add at conversation end, must pass both the user's question and the assistant's final answer into memos add so the extractor can decide what is worth keeping;
• must not skip add at conversation end just because the current turn does not obviously contain a durable fact;
• per conversation, keep memory-tool usage bounded: at most 1 original-query search call at the start and at most 1 add call at the end;
• do not chain additional memory tools in the same turn unless the user explicitly asks for that specific operation;
• extract is only for previewing candidates, not for storing;
• feedback is a separate command and should only be used when the user explicitly wants feedback storage;
• do not start a memory-write request by checking config or running memos init;

Intent map:

• preview what would be stored -> memos extract
• retrieve context at conversation start -> memos search
• store at conversation end -> memos add
• get memories by user_id -> memos get
• trace where a memory came from -> memos origin
• delete one concrete memory -> memos delete
• delete all memories for a user_id -> memos delete --user-id
• ask MemOS to answer with memory context -> memos chat
• uninstall MemOS integration from the current agent -> memos uninstall --agent <current_agent> --yes
• create a knowledge base -> memos kb create
• remove a knowledge base -> memos kb remove
• upload documents to a knowledge base -> memos kb add-file
• check file details or processing status -> memos kb get-file
• list files in a knowledge base -> memos kb list-file
• delete files from a knowledge base -> memos kb delete-file

Working rules:

• must use the user's original query as the only query for memos search;
• do not rewrite, summarize, keyword-compress, retry, or run an additional search query;
• memos add uses a messages array payload; when adding at conversation end, include both the user's question and the assistant's answer in that array;
• in the memos add payload, the user message content must exactly match the original user query;
• in the memos add payload, the assistant message content must exactly match the final answer sent to the user; do not rewrite, summarize, compress, or modify it;
• when --format is omitted, treat the default as agent;
• append --format json at the end of the command whenever a later step needs exact memory_id or structured records;
• append --format agent at the end of the command when the result will be injected back into model context;
• keep --format at the end of every command line, and keep --detail at the end only for search and get;
• do not run memos init as a default preflight step if MemOS CLI is already installed;
• do not run memos search or memos add in a turn where the user is asking to uninstall, disable, remove, or stop using MemOS;
• only run memos init --agent <current_agent> when the CLI is missing and the user has explicitly provided an API key or asked to initialize MemOS;
• if initialization is needed but no API key is available, ask the user for the key instead of stopping the workflow;
• the active agent should initialize itself with its own --agent value, not a hardcoded different agent name;
• pass --user-id only when the user explicitly provides it; otherwise omit it and let the CLI use the config default;
• read result counts from count and structured payloads from data;
• if you already have memory_id, do not search first just to guess.

Examples:

memos add "User likes Python"
memos search "Python"

memos search "user preferences about restaurants" --user-id <USER_ID> --format agent --detail simple

memos extract "User likes coffee and prefers dark mode" --user-id <USER_ID> --format json

memos add "User is allergic to peanuts" --user-id <USER_ID> --format json

memos get <USER_ID> --format json --detail detail
memos origin <MEMORY_ID> --format json
memos delete <MEMORY_ID> --format json

memos uninstall --agent <CURRENT_AGENT> --yes

memos uninstall --agent <CURRENT_AGENT> --yes --path

memos kb create --name "Project docs" --description "Documentation for the project" --format json

memos kb add-file --kb-id <KB_ID> --files '["https://example.com/doc.pdf"]' --format json

memos kb list-file --kb-id <KB_ID> --type document --page 1 --page-size 10 --format json

memos kb get-file --file-ids '["file_abc123"]' --format json
memos kb delete-file --kb-id <KB_ID> --file-ids '["file_abc123"]' --format json
memos kb remove <KB_ID> --format json