# Memory System API Reference

Use the deployed service URL supplied by the user, runtime, or configuration:

```text
<MEMORY_SYSTEM_BASE_URL>
```

Do not assume a localhost address. In agent workflows, resolve the endpoint from `MEMORY_SYSTEM_ENDPOINT`, Hermes memory config, platform config, or user input.

If an API key is configured, add:

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

## Health

```bash
curl -s <MEMORY_SYSTEM_BASE_URL>/memory-system/health
```

## Write Messages

```bash
curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/messages \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<USER_ID>",
    "user_key": "<USER_KEY>",
    "session_id": "<SESSION_ID>",
    "user_message": "我喜欢喝拿铁，不喜欢美式。",
    "assistant_message": "好的，我会记住你的咖啡偏好。"
  }'
```

`user_message` and `assistant_message` are optional independently, but at least one must be present.

## Commit Session

```bash
curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/sessions/<SESSION_ID>/commit \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<USER_ID>", "user_key": "<USER_KEY>"}'
```

Use the returned OpenViking task ID, if present:

```bash
curl -s "<MEMORY_SYSTEM_BASE_URL>/memory-system/openviking/tasks/<TASK_ID>?user_id=<USER_ID>&user_key=<USER_KEY>&session_id=<SESSION_ID>"
```

`commit` can return `partial_success` if OpenViking accepted the archive but EverOS flush failed or timed out. This is retryable:

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

```bash
curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/sessions/<SESSION_ID>/extract \
  -H "Content-Type: application/json" \
  -d '{"user_id": "<USER_ID>", "user_key": "<USER_KEY>"}'
```

## Search

Without LLM planning:

```bash
curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/search \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<USER_ID>",
    "user_key": "<USER_KEY>",
    "session_id": "<SESSION_ID>",
    "query": "我喜欢喝什么咖啡？",
    "use_llm": false,
    "limit": 10
  }'
```

With LLM planning:

```bash
curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/search \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<USER_ID>",
    "user_key": "<USER_KEY>",
    "session_id": "<SESSION_ID>",
    "query": "我的偏好是什么？",
    "use_llm": true,
    "limit": 10
  }'
```

Raw API search responses include merged `items` plus compact backend diagnostics. Fields named `vector` are stripped recursively before the API returns JSON. The API does not return EverOS `original_data` or full episode payloads inside `backends` anymore.

The search response shape should now look more like:

```json
{
  "status": "success",
  "items": [
    {
      "source_backend": "everos",
      "memory_type": "episode",
      "id": "episode-1",
      "user_id": "userB",
      "session_id": "sessionB1",
      "timestamp": "2026-05-22T07:50:51.750000Z",
      "summary": "userB 在对话中表示自己喜欢拿铁。",
      "score": 0.72
    }
  ],
  "backends": {
    "everos": {
      "status": "success",
      "result": {
        "counts": {"episodes": 1, "profiles": 0, "raw_messages": 0},
        "query": {"text": "我喜欢喝什么？", "method": "agentic"}
      }
    }
  }
}
```

When the API is used through the Hermes `memory_system` provider, the tool result is intentionally compact and should look like:

```json
{
  "status": "success",
  "items": [
    {
      "source_backend": "openviking",
      "memory_type": "event",
      "score": 0.92,
      "text": "Relevant recalled memory text",
      "uri": "viking://..."
    }
  ]
}
```

Use the compact `text` fields for answering. Only inspect raw `backends` when debugging API/backend failures.

## Profile

```bash
curl -s "<MEMORY_SYSTEM_BASE_URL>/memory-system/users/<USER_ID>/profile?user_key=<USER_KEY>"
```

## Response Interpretation

Inspect backend status:

```json
{
  "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 other users, but the caller must present the matching `user_key` for business APIs. The gateway stores the created `user_id/user_key`, `session_id`, `task_id`, and `archive_uri` in SQLite.