SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmemos-cloud-server

memos-cloud-server

Coding & development

View repository

Updated 10-16 00:28

About this skill

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"