# Hermes Memory System Plugin

This Hermes memory provider talks to the Memory System API instead of calling OpenViking or EverOS directly.

It stores completed Hermes turns through:

- `POST /memory-system/messages`
- `POST /memory-system/sessions/{session_id}/commit` on session end
- `POST /memory-system/search` for recall
- `GET /memory-system/users/{user_id}/profile` for user profile reads
- `GET/POST/DELETE /memory-system/memories` for direct memory URI management

## Configure

Put these values in the Hermes profile env file, usually `~/.hermes/.env`:

```dotenv
MEMORY_SYSTEM_ENDPOINT=http://127.0.0.1:1934
MEMORY_SYSTEM_USER_ID=default
MEMORY_SYSTEM_USER_KEY=
MEMORY_SYSTEM_API_KEY=
MEMORY_SYSTEM_SEARCH_USE_LLM=false
MEMORY_SYSTEM_COMMIT_EVERY_TURNS=5
MEMORY_SYSTEM_COMMIT_INTERVAL_SECONDS=300
MEMORY_SYSTEM_TIMEOUT_SECONDS=180
```

You can also keep a separate file and point to it with `MEMORY_SYSTEM_ENV_FILE`.
Real environment variables still override file values.

`MEMORY_SYSTEM_USER_KEY` is the key returned by `POST /memory-system/users`.
If it is omitted, the plugin calls `/memory-system/users` during initialization and uses the returned key for the current process.

Then select this provider in Hermes memory config:

```yaml
memory:
  provider: memory_system
```

## Tools

- `memory_system_search`: search OpenViking and EverOS via Memory System API.
- `memory_system_profile`: read the EverOS profile memory for the active user.
- `memory_system_remember`: explicitly write an important memory and commit the session.
- `memory_system_memory_list`: list OpenViking memory URIs under `viking://user/memories`.
- `memory_system_memory_read`: read one memory URI.
- `memory_system_memory_write`: create, replace, or append one memory URI.
- `memory_system_memory_delete`: delete one memory URI, non-recursive by default.

Use the direct memory URI tools only when the model needs to inspect or edit a specific `viking://user/memories/...` item. Normal conversation recall should still use `memory_system_search`, and normal explicit remembering should still use `memory_system_remember`.

The plugin commits after 5 new turns or 300 seconds by default, whichever comes first.
Set either value to `0` to disable that trigger. Session end still commits any new turns that were not already committed.

`MEMORY_SYSTEM_TIMEOUT_SECONDS` should be long enough for commit/search calls that wait on EverOS LLM extraction or rerank services. The default is 180 seconds.

If commit returns `partial_success`, the plugin logs the response and does not mark the pending turns as committed, so a later periodic commit or session-end commit can retry EverOS flush.

Search responses from current Memory System API versions do not include raw `vector` fields. The API strips those large embedding arrays before returning merged results or backend debug payloads.

The plugin is intentionally thin. User identity, session identity, backend writes, OpenViking commit, and EverOS flush stay owned by Memory System API.