betterdb-hermes-memory

A Hermes memory provider backed by betterdb-agent-memory on Valkey / valkey-search.

It gives a Hermes agent durable, semantic long-term memory: each completed turn is embedded and written to a Valkey vector index, and the next turn recalls the most relevant memories — ranked by a composite of similarity, recency (half-life decay), and importance — and injects them as a recall block. It also exposes explicit betterdb_remember / betterdb_recall / betterdb_forget tools.

How it maps to the MemoryProvider contract

prefetch() is non-blocking: queue_prefetch() submits the recall to a background event loop and stashes a formatted block in an in-memory cache; prefetch() only reads that cache, so a turn never waits on a Valkey round-trip. is_available() is network-free — it checks that the SDK imports, a connection target is configured, and an embedding source is resolvable.

Requirements

• Python 3.11–3.14 (matches Hermes's own >=3.11,<3.15).
• A Valkey server with the Search module (e.g. valkey/valkey-bundle).
• An embeddings endpoint. betterdb-agent-memory does not ship an embedding model — you point this provider at an OpenAI-compatible /v1/embeddings endpoint (OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, a gateway, …).

Install

As a dropped-in plugin

Copy the package into your Hermes plugins directory and select it:

cp -r packages/hermes-memory-py/betterdb_hermes_memory ~/.hermes/plugins/betterdb
# then, in Hermes config, set:  memory.provider: betterdb

As a pip package (entry point)

pip install betterdb-hermes-memory

The package registers the hermes_agent.memory_providers entry point betterdb = betterdb_hermes_memory:register, so Hermes discovers it by name. Select it with memory.provider: betterdb.

Configuration

Run hermes memory setup for the provider, or set the fields directly. Non-secret fields live in config.yaml under memory.betterdb; secrets go to the scoped secret store (env vars).

A custom embeddings_base_url (a local/self-hosted endpoint) is treated as needing no key; the hosted default requires embeddings_api_key.

Notes on the embeddings requirement

The SDK's MemoryStore takes an embed_fn that the host supplies — it is required for remember / recall / ensure_index. Because Hermes does not hand providers an embedding seam, this provider resolves one from the embeddings config above (see embeddings.py). You can also inject an embed_fn directly into BetterDBMemoryProvider(...) if you wire the provider yourself.

Development

pip install -e ".[dev]"
pytest

The unit tests mock the SDK client and the event-loop runtime, so they need neither a live Valkey nor an embeddings endpoint.

License

MIT