119 lines
4.6 KiB
Markdown
119 lines
4.6 KiB
Markdown
---
|
|
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
|
|
```
|