添加 Memory Gateway Agent skill及其 CLI 实现，支持用户资源管理和记忆操作

skill/memory-gateway-agent/references/api.md

@@ -0,0 +1,221 @@
+# Memory Gateway API Reference
+
+## Contents
+
+- Configuration
+- Session IDs
+- CLI commands
+- Message format
+- Search scopes
+- Errors and result handling
+
+## Configuration
+
+The CLI reads:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MEMORY_GATEWAY_BASE_URL` | `http://127.0.0.1:8010` | Gateway URL |
+| `MEMORY_GATEWAY_USER_ID` | none | Authenticated user ID |
+| `MEMORY_GATEWAY_USER_KEY` | none | Authenticated user key |
+| `MEMORY_GATEWAY_TIMEOUT_SECONDS` | `120` | HTTP timeout |
+
+Global CLI flags `--base-url`, `--user-id`, `--user-key`, and `--timeout` override these values. Put global flags before the subcommand.
+
+## Session IDs
+
+| Memory source | Format |
+|---|---|
+| Chat | `chat:{conversation_id}` |
+| Uploaded resource | `resource:{user_id}:{resource_id}` |
+| Manual correction | `memory_edit:{user_id}` |
+
+Use the exact `session_id` returned by the API whenever possible.
+
+## CLI Commands
+
+Assume:
+
+```bash
+CLI="python skill/memory-gateway-agent/scripts/memory_gateway.py"
+```
+
+### Health
+
+```bash
+$CLI health
+```
+
+No credentials required. HTTP 200 may contain `"status": "degraded"` when EverOS is unavailable.
+
+### Create User
+
+```bash
+$CLI create-user u_123
+```
+
+Returns a randomly generated `user_key`. Store it securely. Repeating the same `user_id` returns the existing key.
+
+### Upload Resource
+
+```bash
+$CLI upload-resource ./document.pdf \
+  --app-id default \
+  --project-id default \
+  --title "Document title" \
+  --description "Optional description"
+```
+
+Requires credentials. Supported resources depend on the server MIME allowlist. Success returns:
+
+```json
+{
+  "resource_id": "r_xxx",
+  "session_id": "resource:u_123:r_xxx",
+  "uri": "resource://u_123/r_xxx",
+  "status": "extracted"
+}
+```
+
+`failed` means the record exists but EverOS ingestion failed. Identical active content for the same user/app/project may return the existing resource.
+
+### List, Get, and Delete Resources
+
+```bash
+$CLI list-resources
+$CLI get-resource r_xxx
+$CLI delete-resource r_xxx
+```
+
+Missing or foreign resource details return `{"resources": []}`. Delete excludes the resource from future `resources` searches.
+
+### Search
+
+```bash
+$CLI search "payment terms" --scope resources --top-k 8
+$CLI search "previous discussion" \
+  --scope current_chat \
+  --conversation-id c_456
+$CLI search "known preferences" --scope all_user_memory
+```
+
+Repeat `--scope` to combine scopes:
+
+```bash
+$CLI search "query" --scope current_chat --scope resources \
+  --conversation-id c_456
+```
+
+When no scope is provided, the CLI searches `resources` only unless a conversation ID is supplied; with a conversation ID it searches `current_chat` and `resources`. Explicit `current_chat` scope requires `--conversation-id`.
+
+Each result includes normalized `id`, `session_id`, `text`, `source_scope`, and optional resource metadata. The `raw` field preserves the EverOS response.
+
+### Add and Flush Memory
+
+Create `/tmp/messages.json` containing an array:
+
+```json
+[
+  {
+    "sender_id": "u_123",
+    "role": "user",
+    "timestamp": 1781172177000,
+    "content": [
+      {"type": "text", "text": "Remember this note"}
+    ]
+  }
+]
+```
+
+Then run:
+
+```bash
+$CLI add-memory --session-id chat:c_456 --messages /tmp/messages.json
+$CLI flush-memory --session-id chat:c_456
+```
+
+`--messages` accepts either a JSON array string or a path to a JSON file. Always flush after all messages for the session have been added.
+
+### Override and Delete Memory
+
+Use IDs from a search result:
+
+```bash
+$CLI override-memory mem_abc \
+  --session-id resource:u_123:r_xxx \
+  --text "Corrected memory text"
+
+$CLI delete-memory mem_abc \
+  --session-id resource:u_123:r_xxx \
+  --reason "User requested deletion"
+```
+
+These operations write Gateway overrides or tombstones. They do not modify EverOS files directly. The server rejects sessions not owned by the authenticated user.
+
+## Message Format
+
+Each message requires:
+
+| Field | Type | Notes |
+|---|---|---|
+| `sender_id` | string | Usually the current user ID |
+| `role` | string | `user`, `assistant`, or `tool` |
+| `timestamp` | integer | Unix milliseconds, greater than zero |
+| `content` | string or array | Text or EverOS content items |
+
+Common content items:
+
+```json
+{"type": "text", "text": "Plain text"}
+```
+
+```json
+{
+  "type": "image",
+  "base64": "BASE64_DATA",
+  "ext": "png",
+  "name": "image.png"
+}
+```
+
+```json
+{
+  "type": "audio",
+  "base64": "BASE64_DATA",
+  "ext": "wav",
+  "name": "audio.wav"
+}
+```
+
+Prefer base64 for local binary files. A `file://` URI is only usable when EverOS can access the same filesystem path.
+
+## Search Scopes
+
+| Scope | Behavior |
+|---|---|
+| `current_chat` | Searches `chat:{conversation_id}`; provide `--conversation-id` |
+| `resources` | Searches extracted, non-deleted resources belonging to the user/app/project |
+| `all_user_memory` | Searches user memory without a session filter |
+
+Use the narrowest scope that answers the request. This reduces unrelated results and prevents accidental cross-context use.
+
+## Errors and Result Handling
+
+The CLI exits nonzero and writes JSON to stderr:
+
+```json
+{"error": "Memory Gateway returned HTTP 401: invalid user credentials"}
+```
+
+Common statuses:
+
+| Status | Meaning |
+|---|---|
+| `401` | Invalid `user_id` or `user_key` |
+| `403` | Memory session is not owned by the user |
+| `404` | Resource not found for deletion |
+| `413` | Upload exceeds server size limit |
+| `415` | MIME type is not allowed |
+| `422` | Request fields are invalid or missing |
+
+Do not retry `401`, `403`, `413`, `415`, or `422` without changing the request. Retry connectivity or transient server failures only when appropriate for the caller's workflow.