Integrations

Hermes

Use Waystone as a drop-in MemoryProvider for Hermes. Persistent, graph-based memory that retrieves relevant context before every LLM call — automatically.

Why Waystone + Hermes

Hermes has a clean MemoryProvider interface and leaves memory implementation up to you. Most implementations fall back to flat files or simple vector stores. Waystone gives Hermes a structured knowledge graph with semantic retrieval, temporal decay, and automatic fact retirement:

• Context injected before every LLM call — prefetch() runs a BFS retrieval against your project graph and surfaces the most relevant facts in under a second
• Non-blocking extraction — sync_turn() buffers each turn and runs fact extraction in a background thread, so memory never slows the conversation
• Crash recovery — the turn buffer is persisted to disk between turns; nothing is lost if the session ends unexpectedly
• Scales across sessions — decisions from session 1 are just as retrievable in session 50

How Waystone compares

There are several MemoryProvider options available for Hermes. Here's how they stack up:

1. Install

# CLI in early access — request at unbidden.ai[hermes]

This installs Waystone plus the Hermes plugin adapter. Verify:

waystone --version
python -c "from waystone.hermes_plugin import WaystoneMemoryProvider; print('ok')"

2. Configure Hermes

In your Hermes config, set the memory provider to Waystone:

memory:
  provider: waystone
  project: my-project
  # Optional: point at hosted API for cross-machine sync
  # api_key: your-api-key
  # remote_url: https://api.waystone.unbidden.ai

Or via the interactive setup wizard:

hermes memory setup

Select Waystone when prompted for a provider. The wizard configures WAYSTONE_PROJECT and optionally WAYSTONE_API_KEY / WAYSTONE_REMOTE_URL for hosted mode.

How it works

The WaystoneMemoryProvider hooks into three points in the Hermes session lifecycle:

1. prefetch(task) — called before each LLM invocation. Runs a BFS retrieval against the Waystone project graph using the current task description as the query. Returns the 10–25 most relevant facts as structured context, injected into the system prompt. Sub-second — does not block the LLM call.
2. sync_turn(turn) — called after each conversation turn. Buffers the turn to disk (crash-safe), then dispatches fact extraction in a background thread. The LLM never waits on extraction.
3. on_session_end() — called when the session closes cleanly. Flushes any buffered turns that haven't been extracted yet. Also handles the case where a prior session crashed — it processes the recovered buffer on next startup.

LLM-accessible tools

Two tools are exposed to the Hermes LLM directly during a session:

• waystone_query — lets the LLM explicitly query project memory mid-session for a specific topic. Useful when context shifts significantly mid-conversation.
• waystone_recall — retrieves a specific node by ID or tag. Useful for the LLM to confirm or expand on a specific fact surfaced by prefetch().

Hosted API for cross-machine sync

By default, Waystone stores memory in a local SQLite file at ~/.waystone/. To sync memory across machines or share a project with a team, switch to the hosted API:

memory:
  provider: waystone
  project: my-project
  api_key: your-api-key
  remote_url: https://api.waystone.unbidden.ai

Get an API key from the Pro or Team plan. Local mode is free and has no rate limits.

Troubleshooting