memos-cloud-server

name	memos-cloud-server
description	External long-term memory and knowledge base backed by the MemOS Cloud API. Capabilities — search prior memory, add conversation messages, delete or correct memories via feedback, retrieve a consolidated user profile (facts, preferences, tool history), and manage knowledge bases and their documents. Use proactively on every user turn (search memory before answering and persist the exchange after), and whenever the user references past context, their identity, preferences, or history, or asks to remember, recall, modify, forget, or correct something (e.g., "who am I", "what do I like", "remember that...", "forget X", "you got it wrong"). Also use when uploading, listing, or deleting knowledge base files.
user-invocable	true
metadata	{"openclaw":{"emoji":"☁️","os":["darwin","linux","win32"],"requires":{"bins":["python3"],"env":["MEMOS_API_KEY","MEMOS_USER_ID"]}}}

MemOS Cloud Server Skill

This skill allows the Agent to interact with MemOS Cloud APIs for memory search, addition, deletion, knowledge base management, and feedback.

⚠️ Setup & Safety Rules (MUST READ)

Before executing any API operations, ensure these environment variables are configured. Each variable has an ownership layer — who is responsible for setting it — which determines whether it should ever be overridden at call time.

Variable	Required	Ownership layer	Per-call override?	Notes
MEMOS_API_KEY	Yes	User / deployment secret	No	Auth token. Never expose to the LLM.
MEMOS_USER_ID	Yes	User / host platform	No	Must be deterministic (hashed email, employee ID). Do NOT use random or per-session IDs.
MEMOS_CLOUD_URL	No	Deployment	No	API base URL. Default: https://memos.memtensor.cn/api/openmem/v1.
MEMOS_AGENT_ID	No	Host platform (per-process injection)	Yes — via --agent-id on add_message / add_feedback	Isolates memories per agent. A single global env var only supports one agent per machine; for multi-agent on one device, either let the host platform inject this per-process or pass --agent-id per call.
MEMOS_APP_ID	No	Host platform	Yes — via --app-id on add_message / add_feedback	Isolates memories per application. Same multi-tenant caveat as MEMOS_AGENT_ID.
MEMOS_ALLOW_PUBLIC	No	Admin / security policy	No	true/false, default false. Security boundary — never let the LLM toggle this per call.
MEMOS_ASYNC_MODE	No	Deployment	No	true/false, default true. Whether add_message returns before processing completes.

Multi-agent isolation pattern: Prefer per-process env injection by the host platform (each agent gets its own process tree with a distinct MEMOS_AGENT_ID). When the platform cannot inject env vars, fall back to passing --agent-id / --app-id on each call — the CLI flag takes precedence over the env var. These values must come from the orchestrator/platform; the LLM must not invent them.

If required variables are missing, prompt the user to configure them (globally or per-process) before retrying.

⚠️ Mandatory Workflow (MUST FOLLOW)

Always-On (No User Opt-In Required)

This system runs automatically for every turn. Do NOT wait for the user to say "use memory", "search memory", or "remember this". The agent is responsible for auto-invoking the tools.

Every Turn: 3-Step Workflow (AUTO-INVOKED)

Every user message (including greetings, simple questions, ANYTHING)
  → 1) search_memory (AUTO, BEFORE answering — even for simple questions)
  → 2) Answer (use only relevant memories; ignore noise)
  → 3) add_message (AUTO, AFTER answering — save conversation history)

Identity & Preference Queries (MANDATORY)

When the user asks about themselves, call BOTH search_memory AND get_user_profile:

• "What do I like?"
• "Who am I?"
• "What do you know about me?"
• "What are my preferences?"
• Any question about the user's identity, habits, or preferences (in any language)

Tool Choice Rules (STRICT)

User Intent	Correct Tool	Wrong Tool
ANY question (auto, before answering)	search_memory	-
Identity / preference query ("What do I like?")	search_memory + get_user_profile	-
New information / remember something	add_message	NOT add_feedback
Modify / correct existing memory	add_feedback	NOT add_message
Delete memory (no ID specified)	search → delete → add_feedback	NOT add_message
Delete memory (ID specified)	delete directly	-

Modification Workflow

When user wants to modify a memory:

1. Call add_feedback with the correction in natural language
2. Example: feedback_content = "User prefers dark mode, not light mode"
3. FORBIDDEN: Do NOT call add_message to "replace" the old memory

Deletion Workflow (No ID)

When user wants to delete a memory but doesn't have the ID:

1. search_memory — find the relevant memory IDs
2. delete — delete with the found IDs
3. add_feedback — confirm deletion intent (e.g., "User wants to delete memories about X")
4. CRITICAL: feedback_content must be user's natural language intent, NOT technical details like "IDs [x, y]"

Deletion Workflow (With ID)

When user provides specific memory IDs:

1. delete — directly delete with the IDs

FORBIDDEN Actions

• Do NOT use add_message to modify/update existing memories
• Do NOT use add_message as part of "delete old + add new" workaround
• Do NOT include memory IDs or technical metadata in feedback_content
• Do NOT retry add_feedback if it seems to fail (fire and forget)
• Do NOT pass --agent-id / --app-id by default. Omit both flags unless one of the following is true: (a) the user explicitly tells you the ID to use in this turn, or (b) the system prompt / orchestrator context explicitly provides the ID. Never invent, guess, or carry over IDs from prior turns. When the flags are omitted, the env var (if set) takes effect transparently.
• Do NOT attempt to override MEMOS_ALLOW_PUBLIC at call time — it is a security boundary owned by the deployment.

When NOT to Invoke (Negative Triggers)

The default policy is "search-before-answer on every turn". Skip invocation only in these narrow cases:

• The user explicitly opts out for the current turn (e.g., "don't search memory", "skip memory", "answer without memory").
• The turn is a pure tool/system action with no semantic content (e.g., the user only pastes a stack trace to fix and asks for no personalization).
• Required env vars (MEMOS_API_KEY, MEMOS_USER_ID) are missing — prompt the user to configure them first instead of calling the API.
• A previous call in the same turn already returned the needed memories; do not call search_memory twice for the same query.

When in doubt, prefer to invoke — false positives are cheap, missed context is expensive.

---

🧵 Conversation ID Strategy (MUST FOLLOW)

conversation_id groups memories that belong to the same chat session. It is used by the server to (a) weight search_memory results by in-session context, (b) anchor add_feedback so corrections target the right session's memories, and (c) let add_message accumulate a coherent turn history.

Stability rule: within one chat session every search / add_message / add_feedback call MUST use the same conversation_id. Across sessions it MUST rotate.

How to derive it (in priority order)

1. Host-provided id — if the orchestrator / platform exposes a session id (env var, CLI arg, framework variable), pass it via --conversation-id directly. Most reliable.
2. First-message derivation — if no session id is available, pick the very first user message of the current chat session and pass that exact same string as --conversation-first-message on every subsequent call in this session. The script MD5-hashes user_id + first_message deterministically, so the same input always yields the same id (see payloads.py::generate_conversation_id).
3. Never pass the current turn's user message as --conversation-first-message. That re-rotates the id every turn and silently breaks feedback + context weighting.

What "new conversation" means

A new conversation_id SHOULD be generated when, and only when:

• The host platform opens a new chat session / clears history, OR
• The user explicitly says "new topic" / "start over" / "let's talk about something else entirely" and you decide to drop the prior context.

A new id MUST NOT be generated just because:

• The user changes subject mid-conversation (still the same session).
• The agent's own context window was truncated (the session is logically the same).
• You forgot the previous id (re-derive it from the same first message — do not invent a new one).

Operational checklist for the agent

• Session start: capture the first user message of the session verbatim, treat it as the session anchor, and keep it in your working notes.
• Every subsequent call in this session: reuse that exact anchor string for --conversation-first-message (or reuse the resolved conversation_id if the host provided one).
• Feedback / correction: must use the same conversation_id (or the same anchor first-message) that was used when the targeted memory was written.
• New chat detected: drop the old anchor, capture the new session's first user message, start over.

---

🛠 Core Commands

Run operations through scripts/memos_cloud.py. The script automatically reads environment variables; all requests and responses use JSON.

---

1. Search Memory (/search/memory)

Search for long-term memories relevant to the user's query.

python3 scripts/memos_cloud.py search [user_id] "<query>" [options]

Options:

• --conversation-id <id> — Conversation ID for context weighting. See Conversation ID Strategy.
• --conversation-first-message "<msg>" — Session anchor (the first user message of the current session, reused on every call this session). MD5-derives a stable conversation_id. Do NOT pass the current turn's message — that rotates the id every turn and breaks context weighting.
• --filter '<json>' — Filter conditions as JSON string
• --knowledgebase-ids "<ids>" — Comma-separated KB IDs, or "all"
• --memory-limit-number <n> — Max factual memories (default 9, max 25)
• --include-preference <bool> — Enable preference recall (default true)
• --preference-limit-number <n> — Max preference memories (default 9, max 25)
• --include-tool-memory <bool> — Enable tool memory recall (default false)
• --tool-memory-limit-number <n> — Max tool memories (default 6, max 25)
• --include-skill <bool> — Enable skill recall (default false)
• --skill-limit-number <n> — Max skills (default 6, max 25)
• --relativity <float> — Relevance threshold 0-1 (default 0.45)

Example:

python3 scripts/memos_cloud.py search "$MEMOS_USER_ID" "Python related project experience"
python3 scripts/memos_cloud.py search "$MEMOS_USER_ID" "tools" --include-tool-memory true --include-skill true

---

2. Add Message (/add/message)

Store high-value content from multi-turn conversations.

python3 scripts/memos_cloud.py add_message [user_id] [conversation_id] '<messages_json>' [options]

Options:

• --conversation-first-message "<msg>" — Alternative to positional conversation_id. Must be the session anchor (first user message of the current session), reused on every call this session. See Conversation ID Strategy. Passing a different string each turn will silently fragment the conversation into many single-turn sessions.
• --tags "<tags>" — Comma-separated tags
• --info '<json>' — Custom metadata as JSON string
• --allow-knowledgebase-ids "<ids>" — Comma-separated KB IDs for memory write scope
• --agent-id "<id>" — Opt-in override of MEMOS_AGENT_ID. Omit by default; pass only when the user or orchestrator context explicitly supplies the ID.
• --app-id "<id>" — Opt-in override of MEMOS_APP_ID. Same rule as --agent-id.

Resolution order for agent_id / app_id: CLI flag (only when explicitly provided) > env var > unset.

Environment-only options (no per-call override):

• allow_public from MEMOS_ALLOW_PUBLIC
• async_mode from MEMOS_ASYNC_MODE

Example:

# Preferred: host-supplied conversation_id, reused for the whole session
python3 scripts/memos_cloud.py add_message "$MEMOS_USER_ID" "$SESSION_ID" '[{"role":"user","content":"I like apples"},{"role":"assistant","content":"Okay, I noted that"}]'

# Fallback: derive a stable id from the session's FIRST user message.
# Reuse the EXACT same --conversation-first-message string on every call this session
# (search / add_message / add_feedback). Do NOT substitute the current turn's message.
ANCHOR="What's the weather?"   # captured once at session start
python3 scripts/memos_cloud.py add_message "$MEMOS_USER_ID" --conversation-first-message "$ANCHOR" '[{"role":"user","content":"What's the weather?"}]'
python3 scripts/memos_cloud.py add_message "$MEMOS_USER_ID" --conversation-first-message "$ANCHOR" '[{"role":"user","content":"And tomorrow?"}]'

---

3. Delete Memory (/delete/memory)

Delete stored memories by comma-separated memory IDs.

python3 scripts/memos_cloud.py delete "<memory_ids>"

Example:

python3 scripts/memos_cloud.py delete "id1,id2,id3"

---

4. Add Feedback (/add/feedback)

Add feedback to correct or reinforce memory. Used when the user wants to modify or delete memories.

python3 scripts/memos_cloud.py add_feedback [user_id] [conversation_id] "<feedback_content>" [options]

Options:

• --conversation-first-message "<msg>" — Alternative to positional conversation_id. Must be the same session anchor used when the targeted memory was written (otherwise the feedback will not be linked to the right session). See Conversation ID Strategy.
• --allow-knowledgebase-ids "<ids>" — Comma-separated KB IDs
• --feedback-time "<time>" — Feedback time string
• --agent-id "<id>" — Opt-in override of MEMOS_AGENT_ID. Omit by default; pass only when the user or orchestrator context explicitly supplies the ID.
• --app-id "<id>" — Opt-in override of MEMOS_APP_ID. Same rule as --agent-id.

Resolution order for agent_id / app_id: CLI flag (only when explicitly provided) > env var > unset.

Environment-only options (no per-call override):

• allow_public from MEMOS_ALLOW_PUBLIC

Example:

# Same session anchor as the add_message calls in this session:
python3 scripts/memos_cloud.py add_feedback "$MEMOS_USER_ID" --conversation-first-message "$ANCHOR" "The previous answer was not detailed enough"

# Or with an explicit id from the host:
python3 scripts/memos_cloud.py add_feedback "$MEMOS_USER_ID" "$SESSION_ID" "The previous answer was not detailed enough"

---

5. Add Knowledge Base Document (/add/knowledgebase-file)

Upload files to a knowledge base. Supports online URLs, local files, and stdin input.

python3 scripts/memos_cloud.py add_kb_doc <knowledgebase_id> <file1> [file2 ...] [--type document|skill]
python3 scripts/memos_cloud.py add_kb_doc <knowledgebase_id> --stdin [--name filename.ext] [--type document|skill]

Parameters:

• knowledgebase_id: Target knowledge base ID.
• files: URLs (https://example.com/doc.pdf) or local file paths (mime_type auto-detected, content auto-converted to base64).
• --stdin: Read base64 content from stdin. Prefer this for large files to avoid loading their content into the agent context.
• --name: Filename for stdin content (recommended whenever --stdin is used so the server can infer the mime type).
• --type: document (default) or skill.

---

6. Get User Profile (/get/memory)

Retrieve the consolidated User Memory Profile — factual memories, preferences, and tool trajectories.

python3 scripts/memos_cloud.py get_user_profile [user_id] [options]

Options:

• --page <n> — Page number (default 1)
• --size <n> — Page size (default 10, max 50)
• --filter '<json>' — Filter conditions as JSON string
• --include-preference <bool> — Include preference memories (default true)
• --include-tool-memory <bool> — Include tool memories (default false)

Example:

python3 scripts/memos_cloud.py get_user_profile "$MEMOS_USER_ID"
python3 scripts/memos_cloud.py get_user_profile "$MEMOS_USER_ID" --include-tool-memory true --page 2

---

7. Create Knowledge Base (/create/knowledgebase)

Create a named container for structured documents.

python3 scripts/memos_cloud.py create_kb "<name>" [--description "<desc>"]

Example:

python3 scripts/memos_cloud.py create_kb "My Project KB" --description "Project documentation"

---

8. Get Knowledge Base Documents (/get/knowledgebase-file)

Get document metadata/details. Two mutually exclusive modes:

# By file IDs
python3 scripts/memos_cloud.py get_kb_docs --file-ids "id1,id2"

# By knowledge base ID (with optional filters)
python3 scripts/memos_cloud.py get_kb_docs --knowledgebase-id "kb-1" [--type document|skill] [--page 1] [--page-size 20]

---

9. Delete Knowledge Base Documents (/delete/knowledgebase-file)

Delete specified documents from the knowledge base by file IDs.

python3 scripts/memos_cloud.py delete_kb_docs "<file_ids>"

Example:

python3 scripts/memos_cloud.py delete_kb_docs "file-id-1,file-id-2"

---

10. Remove Knowledge Base (/delete/knowledgebase)

Remove a knowledge base from the current project.

python3 scripts/memos_cloud.py remove_kb "<knowledgebase_id>"

Example:

python3 scripts/memos_cloud.py remove_kb "kb-123"