---
name: memory-system-api
description: "Use when an AI agent needs to operate this repository's Memory System API, including creating users, writing session messages, committing or extracting memory, searching memories, reading profiles, or debugging OpenViking/EverOS backend results."
---

# Memory System API

This skill is for using the Memory Gateway service in this repo. Prefer it over direct OpenViking or EverOS calls unless the user explicitly asks to debug a backend.

## Current Contract

The API is user-gated:

- Create a user first with `POST /memory-system/users`.
- Save the returned `account.result.user_key`.
- Send that value back as `user_key` on business API calls.
- Do not send `account_id` on business APIs.

Do not assume business APIs will auto-create users. Non-user-creation endpoints fail when the user was not created first or when the supplied `user_key` does not match the stored key.

`X-API-Key` is separate. It protects the Memory System API itself only when `server.api_key` is configured.

## Identity Model

- `user_id`: end user.
- `user_key`: OpenViking key returned when the user is created.
- `session_id`: conversation ID and OpenViking session ID.

Internally the gateway always uses the fixed OpenViking admin workspace:

```json
{"account_id": "admin", "admin_user_id": "admin"}
```

On the first user creation, if the admin workspace is not stored in SQLite yet, the gateway creates it first and then creates the requested user. After that, later users go straight to `/api/v1/admin/accounts/admin/users`.

The SQLite store is the source of truth for:

- `user_id -> user_key`
- `user_id + session_id`
- `task_id`
- `archive_uri`

Session memory is retrieved under OpenViking using the explicit user/session URI paths:

```text
viking://user/<user_id>/memories/
viking://user/<user_id>/<session_id>
```

## Endpoints

Base path: `/memory-system`

| Method | Path | Purpose | Requires `user_key` |
|---|---|---|---|
| `GET` | `/health` | Check OpenViking and EverOS health | No |
| `POST` | `/users` | Create OpenViking user and store user key | No |
| `POST` | `/messages` | Write user/assistant messages to backends | Yes |
| `POST` | `/sessions/{session_id}/commit` | Commit OpenViking session and flush EverOS | Yes |
| `POST` | `/sessions/{session_id}/extract` | Trigger OpenViking extract only | Yes |
| `GET` | `/openviking/tasks/{task_id}` | Poll OpenViking task status | Yes |
| `POST` | `/search` | Search OpenViking and EverOS | Yes |
| `GET` | `/users/{user_id}/profile` | Read EverOS profile | Yes |

## Required Inputs

For business APIs:

```text
user_id: <user id from /users>
user_key: <account.result.user_key from /users>
```

If configured:

```text
X-API-Key: <server.api_key>
```

Never place OpenViking root keys in user-facing examples unless the user is explicitly configuring the server. Never ask callers to send `X-Account-Key`; that contract is obsolete.

## Examples

Create user:

```bash
curl -sS -X POST "$BASE/memory-system/users" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"userA"}'
```

Write messages:

```bash
curl -sS -X POST "$BASE/memory-system/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "userA",
    "user_key": "'"$USER_KEY"'",
    "session_id": "sessionA1",
    "user_message": "请记住：我喜欢拿铁。",
    "assistant_message": "好的。"
  }'
```

Commit:

```bash
curl -sS -X POST "$BASE/memory-system/sessions/sessionA1/commit" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"userA","user_key":"'"$USER_KEY"'"}'
```

Search:

```bash
curl -sS -X POST "$BASE/memory-system/search" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "userA",
    "user_key": "'"$USER_KEY"'",
    "session_id": "sessionA1",
    "query": "我喜欢喝什么？",
    "use_llm": false,
    "limit": 10
  }'
```

## Response Handling

Top-level `status` is one of:

- `success`: all attempted backends succeeded.
- `partial_success`: at least one backend succeeded and one failed.
- `failed`: all attempted backends failed.

Search responses include merged `items` and compact backend diagnostics under `backends`. Keep `source_backend` when using results. Fields named `vector` are stripped from returned payloads, and the raw EverOS `original_data` blob is not returned by search anymore.

## Common Mistakes

- Calling `/messages` before `/users`.
- Omitting `user_key` on business calls.
- Sending `account_id` to business APIs.
- Confusing `X-API-Key` with `user_key`.
- Expecting `backends.everos.result` to still contain full `episodes` or `original_data`.
- Assuming the gateway stores these values only in memory; it persists them in SQLite.

## Validation

After changing API behavior or this skill:

```bash
PYTHONPATH=/home/tom/memory-gateway pytest -q
python -m compileall -q memory_system_api plugins eval tests
```