memos-cloud-server

What this skill does

# 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

- *