Refine memory system user-key flow and search output

skills/memory-system-api/references/api.md

@@ -1,12 +1,14 @@
 # Memory System API Reference
 
-Base URL defaults to:
+Use the deployed service URL supplied by the user, runtime, or configuration:
 
 ```text
-http://127.0.0.1:1934
+<MEMORY_SYSTEM_BASE_URL>
 ```
 
-If `server.api_key` is configured, add:
+Do not assume a localhost address. In agent workflows, resolve the endpoint from `MEMORY_SYSTEM_ENDPOINT`, Hermes memory config, platform config, or user input.
+
+If an API key is configured, add:
 
 ```bash
 -H "X-API-Key: <gateway-api-key>"
@@ -15,17 +17,18 @@ If `server.api_key` is configured, add:
 ## Health
 
 ```bash
-curl -s http://127.0.0.1:1934/memory-system/health
+curl -s <MEMORY_SYSTEM_BASE_URL>/memory-system/health
 ```
 
 ## Write Messages
 
 ```bash
-curl -s -X POST http://127.0.0.1:1934/memory-system/messages \
+curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/messages \
   -H "Content-Type: application/json" \
   -d '{
-    "user_id": "real_user_001",
-    "session_id": "real_sess_001",
+    "user_id": "<USER_ID>",
+    "user_key": "<USER_KEY>",
+    "session_id": "<SESSION_ID>",
     "user_message": "我喜欢喝拿铁，不喜欢美式。",
     "assistant_message": "好的，我会记住你的咖啡偏好。"
   }'
@@ -36,15 +39,15 @@ curl -s -X POST http://127.0.0.1:1934/memory-system/messages \
 ## Commit Session
 
 ```bash
-curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/commit \
+curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/sessions/<SESSION_ID>/commit \
   -H "Content-Type: application/json" \
-  -d '{"user_id": "real_user_001"}'
+  -d '{"user_id": "<USER_ID>", "user_key": "<USER_KEY>"}'
 ```
 
 Use the returned OpenViking task ID, if present:
 
 ```bash
-curl -s "http://127.0.0.1:1934/memory-system/openviking/tasks/<TASK_ID>?user_id=real_user_001"
+curl -s "<MEMORY_SYSTEM_BASE_URL>/memory-system/openviking/tasks/<TASK_ID>?user_id=<USER_ID>&user_key=<USER_KEY>&session_id=<SESSION_ID>"
 ```
 
 `commit` can return `partial_success` if OpenViking accepted the archive but EverOS flush failed or timed out. This is retryable:
@@ -64,9 +67,9 @@ Wait for EverOS or its upstream LLM/rerank service to recover, then call the sam
 ## Immediate Extract
 
 ```bash
-curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/extract \
+curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/sessions/<SESSION_ID>/extract \
   -H "Content-Type: application/json" \
-  -d '{"user_id": "real_user_001"}'
+  -d '{"user_id": "<USER_ID>", "user_key": "<USER_KEY>"}'
 ```
 
 ## Search
@@ -74,11 +77,12 @@ curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/extra
 Without LLM planning:
 
 ```bash
-curl -s -X POST http://127.0.0.1:1934/memory-system/search \
+curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/search \
   -H "Content-Type: application/json" \
   -d '{
-    "user_id": "real_user_001",
-    "session_id": "real_sess_001",
+    "user_id": "<USER_ID>",
+    "user_key": "<USER_KEY>",
+    "session_id": "<SESSION_ID>",
     "query": "我喜欢喝什么咖啡？",
     "use_llm": false,
     "limit": 10
@@ -88,23 +92,72 @@ curl -s -X POST http://127.0.0.1:1934/memory-system/search \
 With LLM planning:
 
 ```bash
-curl -s -X POST http://127.0.0.1:1934/memory-system/search \
+curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/search \
   -H "Content-Type: application/json" \
   -d '{
-    "user_id": "real_user_001",
-    "session_id": "real_sess_001",
+    "user_id": "<USER_ID>",
+    "user_key": "<USER_KEY>",
+    "session_id": "<SESSION_ID>",
     "query": "我的偏好是什么？",
     "use_llm": true,
     "limit": 10
   }'
 ```
 
-Search responses include merged `items` plus backend debug data. Fields named `vector` are stripped recursively before the API returns JSON, so responses stay small even when EverOS includes `original_data`. Metadata keys such as `vector_model` may still be present.
+Raw API search responses include merged `items` plus compact backend diagnostics. Fields named `vector` are stripped recursively before the API returns JSON. The API does not return EverOS `original_data` or full episode payloads inside `backends` anymore.
+
+The search response shape should now look more like:
+
+```json
+{
+  "status": "success",
+  "items": [
+    {
+      "source_backend": "everos",
+      "memory_type": "episode",
+      "id": "episode-1",
+      "user_id": "userB",
+      "session_id": "sessionB1",
+      "timestamp": "2026-05-22T07:50:51.750000Z",
+      "summary": "userB 在对话中表示自己喜欢拿铁。",
+      "score": 0.72
+    }
+  ],
+  "backends": {
+    "everos": {
+      "status": "success",
+      "result": {
+        "counts": {"episodes": 1, "profiles": 0, "raw_messages": 0},
+        "query": {"text": "我喜欢喝什么？", "method": "agentic"}
+      }
+    }
+  }
+}
+```
+
+When the API is used through the Hermes `memory_system` provider, the tool result is intentionally compact and should look like:
+
+```json
+{
+  "status": "success",
+  "items": [
+    {
+      "source_backend": "openviking",
+      "memory_type": "event",
+      "score": 0.92,
+      "text": "Relevant recalled memory text",
+      "uri": "viking://..."
+    }
+  ]
+}
+```
+
+Use the compact `text` fields for answering. Only inspect raw `backends` when debugging API/backend failures.
 
 ## Profile
 
 ```bash
-curl -s http://127.0.0.1:1934/memory-system/users/real_user_001/profile
+curl -s "<MEMORY_SYSTEM_BASE_URL>/memory-system/users/<USER_ID>/profile?user_key=<USER_KEY>"
 ```
 
 ## Response Interpretation
@@ -123,4 +176,4 @@ Inspect backend status:
 
 Use backend-specific errors for debugging.
 
-OpenViking user keys are intentionally hidden from callers. If OpenViking already has an account but the local API has no stored key, Memory System API falls back to the configured OpenViking root key plus identity headers internally.
+OpenViking user keys are intentionally hidden from other users, but the caller must present the matching `user_key` for business APIs. The gateway stores the created `user_id/user_key`, `session_id`, `task_id`, and `archive_uri` in SQLite.