Hermes memory

Hermes Agent (Nous Research) keeps its sessions and memory in a local ~/.hermes/state.db. hermes-persql is a Hermes memory provider that routes those turns and durable facts into a PerSQL database instead — one isolated SQLite per agent. The memory becomes portable across machines, survives ephemeral runs, and is queryable as plain SQL. Recall stays keyword-based (FTS5), matching Hermes’s own session search — no vector database.

Install

pip install hermes-persql
hermes-persql install            # writes ~/.hermes/plugins/persql/

Point Hermes at it and provide credentials:

memory:
  provider: persql

export PERSQL_TOKEN="psql_live_…"          # console.persql.com -> API tokens
export PERSQL_DATABASE="<workspace>/<slug>"

That’s it. On each turn Hermes records the exchange to PerSQL and recalls relevant prior turns and facts before the next one. The agent also gets persql_remember, persql_recall, and persql_profile tools (enable the memory toolset to expose them).

Why route memory to PerSQL

The default state.db lives on one machine. Backed by PerSQL, the same memory is:

Portable — reachable from any machine or process with the token, so a laptop, a server, and a CI runner share one agent memory.
Durable for headless runs — a hermes -z one-shot in cron, CI, or a container has no persistent local disk; here each run reads and writes the same memory.
Per-agent or pooled — point many Hermes instances at one database to share a memory pool, or give each agent its own database for isolated state, blast radius, and spend.

One database per agent

from persql import PerSQL

client = PerSQL(token=os.environ["PERSQL_TOKEN"])
info = client.databases.create(f"agent-{run_id}", ttl_days=1)
# export PERSQL_DATABASE=acme/<info['slug']> for that agent's Hermes process

For ephemeral runs, lease a branch with a TTL and a scoped token so the memory cleans itself up.

Inspect memory with SQL

Turns and facts are rows — query them from the console, MCP, or any SDK:

SELECT session_id, COUNT(*) AS turns, MAX(created_at) AS last_active
FROM hermes_turns GROUP BY session_id ORDER BY 2 DESC;

SELECT fact FROM hermes_facts ORDER BY id DESC LIMIT 20;

What this is not

Recall is lexical (FTS5), the same shape as Hermes’s built-in search — good for exact terms, not semantic similarity. Hermes’s built-in MEMORY.md/USER.md curation stays local and active alongside this. For a single machine that never moves, the default local store is simpler; the value here is portability, durability across ephemeral runs, sharing, and SQL inspection.

Next step

Pair it with structured agent memory — the same database can hold facts and episodes any agent recalls with SQL, not just Hermes.