Update memory system skill and plugin

skills/memory-system-api/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: memory-system-api
+description: "Use when an AI agent needs to work with this repository's lightweight Memory System API for OpenViking session memory and EverOS user profiles: starting the API, checking health, writing user/assistant conversation messages, committing or immediately extracting memory, searching memory with hybrid/agentic modes, reading user profiles, or debugging backend partial failures."
+---
+
+# Memory System API
+
+Use this skill to operate the lightweight Memory System API from an AI agent. The API hides two backends:
+
+- OpenViking stores session conversation memory.
+- EverOS stores user profile and episodic memory.
+
+Prefer this API over direct backend calls unless the user explicitly asks to debug OpenViking or EverOS directly.
+
+Implementation notes:
+
+- The caller never needs to manage OpenViking user keys. The API stores returned user keys locally when OpenViking provides them; if OpenViking reports that an account already exists or does not return a key, the API uses the configured root key with `X-OpenViking-Account` and `X-OpenViking-User` identity headers.
+- Search responses are sanitized before returning to callers. Large embedding arrays under JSON fields named `vector` are removed from both merged `items` and backend debug payloads. Metadata such as `vector_model` may still appear.
+
+## Before Calling
+
+1. Confirm the service is running or start it from the repository root:
+
+```bash
+python -m memory_system_api.server --config config.yaml --host 127.0.0.1 --port 1934
+```
+
+2. Check health:
+
+```bash
+curl -s http://127.0.0.1:1934/memory-system/health
+```
+
+3. If `server.api_key` is set in `config.yaml`, include `X-API-Key` on every request.
+
+See [references/api.md](references/api.md) for request examples and response handling.
+
+## Write Conversation Memory
+
+Use `POST /memory-system/messages`.
+
+Pass:
+
+- `user_id`: stable end-user ID.
+- `session_id`: stable conversation/session ID.
+- `user_message`: optional.
+- `assistant_message`: optional.
+
+At least one of `user_message` or `assistant_message` must be present. If both are present, the backend writes them as two separate messages, in user then assistant order.
+
+Important EverOS rule: assistant messages must not use the user ID as `sender_id`. The API handles this internally; do not bypass it by calling EverOS directly unless debugging.
+
+## Trigger Memory Extraction
+
+Use commit when the conversation turn/session should be finalized:
+
+```text
+POST /memory-system/sessions/{session_id}/commit
+```
+
+This runs OpenViking commit and EverOS flush concurrently. OpenViking commit is asynchronous; if the response includes a task ID, check it with:
+
+```text
+GET /memory-system/openviking/tasks/{task_id}?user_id=...
+```
+
+EverOS flush may be slower than OpenViking because it can call LLM extraction/rerank services. Treat `partial_success` as retryable when OpenViking succeeds but EverOS fails; inspect `backends.everos.error`, wait for the upstream service to recover, then commit the same session again.
+
+Use immediate extract only when the user explicitly asks to remember something now or when validating recent writes:
+
+```text
+POST /memory-system/sessions/{session_id}/extract
+```
+
+This wraps OpenViking extract only.
+
+## Search Memory
+
+Use `POST /memory-system/search`.
+
+- `use_llm=false`: OpenViking `find` plus EverOS `method=hybrid`.
+- `use_llm=true`: OpenViking `search` plus EverOS `method=agentic`.
+
+The API queries both backends concurrently and returns merged `items`. Preserve `source_backend` when presenting or using results so the caller can tell where each memory came from.
+
+The response also includes `backends` for debugging. Do not expect raw embedding vectors there; fields named `vector` are intentionally stripped to keep responses small.
+
+## Read User Profile
+
+Use:
+
+```text
+GET /memory-system/users/{user_id}/profile
+```
+
+This calls EverOS `memories/get` with `memory_type=profile`.
+
+## Error Handling
+
+Expect `status` to be one of:
+
+- `success`: all attempted backends succeeded.
+- `partial_success`: at least one backend succeeded and at least one failed.
+- `failed`: all attempted backends failed.
+
+When `partial_success` or `failed`, inspect `backends.openviking.error` and `backends.everos.error`. Do not hide backend-specific failures behind the top-level status.
+
+Empty backend exception messages are normalized to the exception type, for example `ReadTimeout`, so an empty `error` string should not be expected from current API versions.
+
+## Validation
+
+After changing the API or this skill, run:
+
+```bash
+python -m pytest -q
+python -m compileall -q memory_system_api tests
+python /home/tom/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/memory-system-api
+```

skills/memory-system-api/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Memory System API"
+  short_description: "Use the lightweight Memory System API from AI agents."
+  default_prompt: "Use the Memory System API skill to write conversation memory, trigger extraction, search memory, and read user profiles."

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

@@ -0,0 +1,126 @@
+# Memory System API Reference
+
+Base URL defaults to:
+
+```text
+http://127.0.0.1:1934
+```
+
+If `server.api_key` is configured, add:
+
+```bash
+-H "X-API-Key: <gateway-api-key>"
+```
+
+## Health
+
+```bash
+curl -s http://127.0.0.1:1934/memory-system/health
+```
+
+## Write Messages
+
+```bash
+curl -s -X POST http://127.0.0.1:1934/memory-system/messages \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "real_user_001",
+    "session_id": "real_sess_001",
+    "user_message": "我喜欢喝拿铁，不喜欢美式。",
+    "assistant_message": "好的，我会记住你的咖啡偏好。"
+  }'
+```
+
+`user_message` and `assistant_message` are optional independently, but at least one must be present.
+
+## Commit Session
+
+```bash
+curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/commit \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "real_user_001"}'
+```
+
+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"
+```
+
+`commit` can return `partial_success` if OpenViking accepted the archive but EverOS flush failed or timed out. This is retryable:
+
+```json
+{
+  "status": "partial_success",
+  "backends": {
+    "openviking": {"status": "success", "result": {"status": "ok"}},
+    "everos": {"status": "failed", "error": "ReadTimeout"}
+  }
+}
+```
+
+Wait for EverOS or its upstream LLM/rerank service to recover, then call the same commit endpoint again.
+
+## Immediate Extract
+
+```bash
+curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/extract \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "real_user_001"}'
+```
+
+## Search
+
+Without LLM planning:
+
+```bash
+curl -s -X POST http://127.0.0.1:1934/memory-system/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "real_user_001",
+    "session_id": "real_sess_001",
+    "query": "我喜欢喝什么咖啡？",
+    "use_llm": false,
+    "limit": 10
+  }'
+```
+
+With LLM planning:
+
+```bash
+curl -s -X POST http://127.0.0.1:1934/memory-system/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "real_user_001",
+    "session_id": "real_sess_001",
+    "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.
+
+## Profile
+
+```bash
+curl -s http://127.0.0.1:1934/memory-system/users/real_user_001/profile
+```
+
+## Response Interpretation
+
+Inspect backend status:
+
+```json
+{
+  "status": "partial_success",
+  "backends": {
+    "openviking": {"status": "success", "result": {}},
+    "everos": {"status": "failed", "error": "..."}
+  }
+}
+```
+
+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.