memory-gateway/skills/memory-system-api/SKILL.md

name, description

name	description
memory-system-api	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:

{"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:

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/POST	/sessions/{session_id}/context	Read OpenViking session context plus EverOS recall	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:

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

If configured:

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:

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

Write messages:

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:

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

Search:

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
  }'

Session context:

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

GET with query parameters is also supported:

curl -sS "$BASE/memory-system/sessions/sessionA1/context?user_id=userA&user_key=$USER_KEY&query=我喜欢喝什么？&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.

Session context responses include OpenViking context under context, EverOS recall under items, and compact backend diagnostics under backends.

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:

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