Memory System API Reference

Base URL defaults to:

http://127.0.0.1:1934

If server.api_key is configured, add:

-H "X-API-Key: <gateway-api-key>"

Health

curl -s http://127.0.0.1:1934/memory-system/health

Write Messages

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

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:

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:

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

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:

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:

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

curl -s http://127.0.0.1:1934/memory-system/users/real_user_001/profile

Response Interpretation

Inspect backend status:

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

3.1 KiB Raw Blame History