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
+```