memtensor/memos-cloud-server

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"