memos-cloud-server

MemOS Cloud サーバースキル

このスキルを使うと、エージェントは MemOS Cloud API を利用して、メモリの検索、追加、削除、ナレッジベースの管理、フィードバックを行えます。

⚠️ セットアップと安全上のルール（必ずお読みください）

API 操作を実行する前に、これらの環境変数が設定されていることを確認してください。各変数には、設定の責任者を示す所有レイヤーがあります。これは、呼び出し時にその変数を上書きしてよいかどうかを決定します。

変数	必須	所有レイヤー	呼び出しごとの上書き	備考
MEMOS_API_KEY	はい	ユーザー／デプロイメントシークレット	いいえ	認証トークンです。LLM に絶対に公開しないでください。
MEMOS_USER_ID	はい	ユーザー／ホストプラットフォーム	いいえ	決定的な値（ハッシュ化したメールアドレス、従業員 ID など）にする必要があります。ランダムな ID やセッションごとに変わる ID は使用しないでください。
MEMOS_CLOUD_URL	いいえ	デプロイメント	いいえ	API のベース URL です。デフォルト：https://memos.memtensor.cn/api/openmem/v1
MEMOS_AGENT_ID	いいえ	ホストプラットフォーム（プロセスごとの注入）	はい — add_message／add_feedback の --agent-id で指定	エージェントごとにメモリを分離します。グローバルな環境変数 1 つで対応できるのは、マシンごとにエージェント 1 つだけです。1 台のデバイスで複数のエージェントを使う場合は、ホストプラットフォームにプロセスごとに注入させるか、呼び出しごとに --agent-id を渡してください。
MEMOS_APP_ID	いいえ	ホストプラットフォーム	はい — add_message／add_feedback の --app-id で指定	アプリケーションごとにメモリを分離します。複数テナントに関する注意点は MEMOS_AGENT_ID と同じです。
MEMOS_ALLOW_PUBLIC	いいえ	管理者／セキュリティポリシー	いいえ	true／false。デフォルトは false です。セキュリティ境界を定める設定です。LLM が呼び出しごとに切り替えられるようにしてはいけません。
MEMOS_ASYNC_MODE	いいえ	デプロイメント	いいえ	true／false。デフォルトは true です。add_message が処理完了前に戻るかどうかを指定します。

複数エージェントの分離パターン：ホストプラットフォームによるプロセスごとの環境変数の注入を優先してください（各エージェントに異なる MEMOS_AGENT_ID を設定し、それぞれ独自のプロセスツリーを持たせます）。プラットフォームが環境変数を注入できない場合は、各呼び出しで --agent-id／--app-id を渡してください。CLI フラグは環境変数より優先されます。これらの値はオーケストレーター／プラットフォームから取得する必要があります。LLM が値を推測して設定してはいけません。

必須の環境変数が設定されていない場合は、再試行する前にユーザーに設定を依頼してください（グローバルまたはプロセスごと）。

⚠️ 必須ワークフロー（必ず従ってください）

常時有効（ユーザーのオプトイン不要）

このシステムはすべてのターンで自動的に実行されます。ユーザーが「メモリを使って」「メモリを検索して」「これを覚えて」などと言うまで待ってはいけません。ツールを自動的に呼び出すのはエージェントの責任です。

毎ターン：3 ステップのワークフロー（自動実行）

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)

身元と好みに関する質問（必須）

ユーザーが自分自身について質問した場合は、search_memory と get_user_profile の両方を呼び出してください。

• 「私は何が好きですか？」
• 「私は誰ですか？」
• 「私について何を知っていますか？」
• 「私の好みは何ですか？」
• ユーザーの身元、習慣、好みに関するあらゆる質問（言語を問いません）

ツール選択ルール（厳守）

ユーザーの意図	正しいツール	誤ったツール
あらゆる質問（回答前に自動実行）	search_memory	-
身元／好みに関する質問（「私は何が好きですか？」など）	search_memory + get_user_profile	-
新しい情報／何かを覚えてもらう	add_message	add_feedback は使用しない
既存のメモリを変更／修正する	add_feedback	add_message は使用しない
メモリを削除する（ID の指定なし）	search → delete → add_feedback	add_message は使用しない
メモリを削除する（ID の指定あり）	delete を直接呼び出す	-

変更ワークフロー

ユーザーがメモリの変更を希望する場合：

1. 自然な言葉で修正内容を add_feedback に渡します
2. 例：feedback_content = "User prefers dark mode, not light mode"
3. 禁止事項：古いメモリを「置き換える」ために add_message を呼び出してはいけません

削除ワークフロー（ID なし）

ユーザーがメモリを削除したいものの、ID がわからない場合：

1. search_memory — 該当するメモリ ID を見つけます
2. delete — 見つかった ID を指定して削除します
3. add_feedback — 削除の意図を確認します（例：「ユーザーは X に関するメモリを削除したい」）
4. 重要：feedback_content に含めるのはユーザーの自然言語による意図であり、「ID [x, y]」のような技術的な詳細ではありません

削除ワークフロー（ID あり）

ユーザーが特定のメモリ ID を指定した場合：

1. delete — その ID を指定して直接削除します

禁止されている操作

• add_message を使って既存のメモリを変更・更新しないでください
• 「古いものを削除して新しいものを追加する」という回避策の一環として add_message を使わないでください
• feedback_content にメモリ ID や技術的なメタデータを含めないでください
• add_feedback が失敗したように見えても、再試行しないでください（結果を待たずに処理します）
• デフォルトでは --agent-id / --app-id を渡さないでください。次のいずれかに該当しない限り、両方のフラグを省略してください。（a）ユーザーがこのターンで使用する ID を明示的に指定している、または（b）システムプロンプト／オーケストレーターのコンテキストで ID が明示的に指定されている。ID を決して捏造、推測したり、前のターンの ID を引き継いだりしないでください。フラグを省略すると、環境変数（設定されている場合）が透過的に適用されます。
• 呼び出し時に MEMOS_ALLOW_PUBLIC を上書きしようとしないでください。これはデプロイ環境が管理するセキュリティ境界です。

呼び出さない場合（呼び出しを抑制する条件）

デフォルトの方針は「すべてのターンで回答前に検索」です。次の限られた場合にのみ、呼び出しを省略してください。

• ユーザーが現在のターンで明示的に検索を不要としている場合（例：「メモリを検索しないで」「メモリ検索をスキップして」「メモリを使わずに回答して」）。
• そのターンが、意味的な内容を伴わない純粋なツール／システム操作である場合（例：ユーザーがスタックトレースを貼り付けて修正を求めているだけで、パーソナライズを求めていない）。
• 必要な環境変数（MEMOS_API_KEY、MEMOS_USER_ID）が設定されていない場合。API を呼び出すのではなく、まず設定するようユーザーに促してください。
• 同じターン内の前回の呼び出しですでに必要なメモリが返されている場合。同じクエリで search_memory を二度呼び出さないでください。

判断に迷った場合は、呼び出すことを優先してください。誤検知のコストは低く、文脈を見落とすコストは高いためです。

---

🧵 会話 ID の方針（必ず従う）

conversation_id は、同じチャットセッションに属するメモリをまとめます。サーバーはこれを使用して、（a）セッション内のコンテキストに基づいて search_memory の結果に重み付けし、（b）add_feedback を適切なセッションのメモリに関連付けて修正の対象を定め、（c）add_message で一貫したターン履歴を蓄積します。

安定性のルール：1 つのチャットセッション内では、すべての search / add_message / add_feedback 呼び出しで同じ conversation_id を使用する必要があります。セッションが変わった場合は、必ず新しい ID に切り替えてください。

導出方法（優先順位順）

1. ホストから提供された ID — オーケストレーター／プラットフォームがセッション ID（環境変数、CLI 引数、フレームワーク変数）を公開している場合は、--conversation-id で直接渡してください。これが最も信頼できる方法です。
2. 最初のメッセージから導出 — セッション ID が利用できない場合は、現在のチャットセッションで最初に送られたユーザーメッセージを選び、以降このセッション内で行うすべての呼び出しで、同じ文字列を --conversation-first-message として渡してください。スクリプトは user_id + first_message を MD5 でハッシュするため、同じ入力からは常に同じ ID が生成されます（payloads.py::generate_conversation_id を参照）。
3. 決して現在のターンのユーザーメッセージを --conversation-first-message として渡さないでください。ターンごとに ID が再生成され、フィードバックとコンテキストの重み付けが気付かないうちに機能しなくなります。

「新しい会話」の意味

次の場合に限り、新しい conversation_id を生成する必要があります。

• ホストプラットフォームが新しいチャットセッションを開始する、または履歴を消去する場合
• ユーザーが明示的に「新しい話題にして」「最初からやり直して」「まったく別の話をしよう」と伝え、以前のコンテキストを破棄すると判断した場合

次の理由だけで新しい ID を生成してはいけません。

• 会話の途中でユーザーが話題を変えた（セッションは同じです）。
• エージェント自身のコンテキストウィンドウが切り詰められた（論理的には同じセッションです）。
• 前の ID を忘れた（同じ最初のメッセージから再導出してください。新しい ID を捏造しないでください）。

エージェント向け運用チェックリスト

• セッション開始時：セッションの最初のユーザーメッセージをそのまま記録し、セッションのアンカーとして扱い、作業メモに保持します。
• このセッションでの以降のすべての呼び出し：--conversation-first-message に同じアンカー文字列を使用します（または、ホストから提供された conversation_id がある場合はそれを再利用します）。
• フィードバック／修正：対象のメモリを書き込んだときに使用したものと同じ conversation_id（または同じアンカーの最初のメッセージ）を使用する必要があります。
• 新しいチャットを検出した場合：古いアンカーを破棄し、新しいセッションの最初のユーザーメッセージを記録して、最初からやり直します。

---

🛠 コアコマンド

操作は scripts/memos_cloud.py を通じて実行します。このスクリプトは環境変数を自動的に読み込みます。すべてのリクエストとレスポンスは JSON を使用します。

---

1. メモリを検索（/search/memory）

ユーザーのクエリに関連する長期メモリを検索します。

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

オプション：

• --conversation-id <id> — コンテキストの重み付けに使用する会話 ID。会話 ID の戦略を参照してください。
• --conversation-first-message "<msg>" — セッションアンカー（現在のセッションの最初のユーザーメッセージ。このセッションのすべての呼び出しで再利用します）。MD5 から安定した conversation_id を導出します。現在のターンのメッセージを渡さないでください — ターンごとに ID が変わり、コンテキストの重み付けが機能しなくなります。
• --filter '<json>' — JSON 文字列で指定するフィルター条件
• --knowledgebase-ids "<ids>" — カンマ区切りの KB ID、または "all"
• --memory-limit-number <n> — 事実に関するメモリの最大数（デフォルト 9、最大 25）
• --include-preference <bool> — 好みの想起を有効にします（デフォルト true）
• --preference-limit-number <n> — 好みに関するメモリの最大数（デフォルト 9、最大 25）
• --include-tool-memory <bool> — ツールメモリの想起を有効にします（デフォルト false）
• --tool-memory-limit-number <n> — ツールメモリの最大数（デフォルト 6、最大 25）
• --include-skill <bool> — スキルの想起を有効にします（デフォルト false）
• --skill-limit-number <n> — スキルの最大数（デフォルト 6、最大 25）
• --relativity <float> — 関連性のしきい値 0～1（デフォルト 0.45）

例：

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）

複数ターンの会話から価値の高い内容を保存します。

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

オプション：

• --conversation-first-message "<msg>" — 位置引数の conversation_id の代わりに使用します。セッションアンカー（現在のセッションの最初のユーザーメッセージ）を指定し、このセッションのすべての呼び出しで再利用する必要があります。会話 ID の戦略を参照してください。ターンごとに異なる文字列を渡すと、気付かないうちに会話が多数の単一ターンのセッションに分割されます。
• --tags "<tags>" — カンマ区切りのタグ
• --info '<json>' — JSON 文字列で指定するカスタムメタデータ
• --allow-knowledgebase-ids "<ids>" — メモリ書き込み範囲を指定するカンマ区切りの KB ID
• --agent-id "<id>" — MEMOS_AGENT_ID を任意で上書きします。デフォルトでは省略し、ユーザーまたはオーケストレーターのコンテキストで ID が明示的に指定された場合にのみ渡してください。
• --app-id "<id>" — MEMOS_APP_ID を任意で上書きします。--agent-id と同じルールです。

agent_id / app_id の解決順序：CLI フラグ（明示的に指定された場合のみ）> 環境変数 > 未設定。

環境変数のみのオプション（呼び出しごとの上書きはできません）：

• MEMOS_ALLOW_PUBLIC の allow_public
• MEMOS_ASYNC_MODE の async_mode

例：

# 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）

カンマ区切りのメモリ ID を指定して、保存済みのメモリを削除します。

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

例：

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

---

4. フィードバックを追加（/add/feedback）

メモリを修正または強化するためのフィードバックを追加します。ユーザーがメモリを変更または削除したい場合に使用します。

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

オプション：

• --conversation-first-message "<msg>" — 位置引数の conversation_id の代わりに使用します。対象のメモリを書き込んだときに使用したものと同じセッションアンカーである必要があります（そうでないと、フィードバックが正しいセッションに関連付けられません）。会話 ID の戦略を参照してください。
• --allow-knowledgebase-ids "<ids>" — カンマ区切りの KB ID
• --feedback-time "<time>" — フィードバック時刻の文字列
• --agent-id "<id>" — MEMOS_AGENT_ID をオプトインで上書きします。デフォルトでは省略し、ユーザーまたはオーケストレーターのコンテキストで ID が明示的に指定された場合にのみ渡してください。
• --app-id "<id>" — MEMOS_APP_ID をオプトインで上書きします。--agent-id と同じルールに従います。

agent_id / app_id の解決順序：CLI フラグ（明示的に指定された場合のみ） > 環境変数 > 未設定。

環境変数のみで指定するオプション（呼び出しごとの上書きはできません）：

• MEMOS_ALLOW_PUBLIC の allow_public

例：

# 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/knowledgebase-file）

ナレッジベースにファイルをアップロードします。オンライン URL、ローカルファイル、標準入力に対応しています。

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]

パラメーター：

• knowledgebase_id：対象のナレッジベース ID。
• files：URL（https://example.com/doc.pdf）またはローカルファイルパス（MIME タイプは自動検出され、コンテンツは自動的に base64 に変換されます）。
• --stdin：標準入力から base64 コンテンツを読み込みます。大きなファイルの場合、コンテンツがエージェントのコンテキストに読み込まれないようにするため、この方法を推奨します。
• --name：標準入力のコンテンツに付けるファイル名です。サーバーが MIME タイプを推定できるよう、--stdin を使用する場合は常に指定することを推奨します。
• --type：document（デフォルト）または skill。

---

6. ユーザープロファイルを取得（/get/memory）

統合されたユーザーメモリプロファイル（事実に関するメモリ、好み、ツールの操作履歴）を取得します。

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

オプション：

• --page <n> — ページ番号（デフォルトは 1）
• --size <n> — ページサイズ（デフォルトは 10、最大 50）
• --filter '<json>' — JSON 文字列で指定するフィルター条件
• --include-preference <bool> — 好みに関するメモリを含めるかどうか（デフォルトは true）
• --include-tool-memory <bool> — ツールに関するメモリを含めるかどうか（デフォルトは false）

例：

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/knowledgebase）

構造化ドキュメントを格納する、名前付きのコンテナーを作成します。

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

例：

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

---

8. ナレッジベースのドキュメントを取得（/get/knowledgebase-file）

ドキュメントのメタデータ／詳細を取得します。相互排他的な 2 つのモードがあります。

# 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/knowledgebase-file）

ファイル ID を指定して、ナレッジベースからドキュメントを削除します。

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

例：

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

---

10. ナレッジベースを削除（/delete/knowledgebase）

現在のプロジェクトからナレッジベースを削除します。

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

例：

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