September 17, 2026

hermes-memory-pgvector v0.5.3: Bring Your Own Embedding Model

hermes-memory-pgvector v0.5.3: Bring Your Own Embedding Model

hermes-memory-pgvector is the open-source plugin that gives a fleet of hermes-agent agents shared, durable memory on PostgreSQL and pgvector. Version 0.5.3 is out on PyPI, and it removes the last hard-coded assumption in the plugin: which embedding model turns your memories into searchable vectors.

Why this release exists

Until now the embedding model was effectively fixed. The plugin checked every vector against a literal 768 dimensions, the size of the default nomic-embed-text model, and it had no way to send an API key, so hosted embedding services were out of reach.

That became a real limit for our own deployment. We moved the memory database to OpenAI's text-embedding-3-small, served through OpenRouter, because a hosted endpoint is always warm while a self-hosted model can take several seconds to wake up. The database columns changed to 1536 dimensions, and the plugin had no setting that could follow them. v0.5.3 adds those settings.

Three new settings

  • embed_dim is the vector length your model returns. The default is 768, so existing setups are unaffected. Every embedding is still checked, now against this value, so a mismatch fails fast instead of reaching the database.
  • embed_api_key_env is the name of an environment variable that holds a bearer token, such as OPENROUTER_API_KEY. The key never goes in the config file; it is read at call time and never logged.
  • embed_protocol is openai, ollama or auto. The default, auto, tries the OpenAI-compatible path and falls back to Ollama's native API. Choosing openai for a hosted service means an authentication or model error is reported as it is, instead of being hidden behind a 404 from the fallback.

Pointing the plugin at text-embedding-3-small through OpenRouter now looks like this:

plugins:
  pgvector:
    embed_url: "https://openrouter.ai/api"
    embed_model: "openai/text-embedding-3-small"
    embed_dim: 1536
    embed_api_key_env: "OPENROUTER_API_KEY"
    embed_protocol: "openai"

Two fixes that matter even if you change nothing

  • Embeddings under the hermes-agent plugin loader. After loading the plugin, the host's loader re-attaches every submodule to the package, including one named embed. That replaced the function the plugin called, so embedding failed with TypeError: 'module' object is not callable and memory writes were dropped instead of being stored as text. The plugin now calls a private alias the loader never touches.
  • Slow endpoints. A server that accepted the connection but answered after the timeout raised a bare TimeoutError, which slipped past the plugin's error handling: no fallback, no retries, and a lost write. It is now handled like every other endpoint failure.

Upgrading

The defaults did not change: 768 dimensions, no auth header, the auto protocol, and no new database migrations. Upgrade with:

pip install -U hermes-memory-pgvector

Switching to a model with a different vector size is a database migration, not just a config edit, because vectors from two different models are not comparable. The README walks through it: change the column type, re-embed the existing rows with hermes-pgvector backfill, then rebuild the HNSW indexes.

Source and the full configuration reference are on GitHub:

👉 github.com/andreab67/hermes-memory-pgvector

← Back to Blog