Skip to content

v0.5.3 - configurable embedding model (dimension, auth, protocol)

Choose a tag to compare

@andreab67 andreab67 released this 17 Sep 15:14
· 87 commits to main since this release

Defaults are unchanged: 768 dimensions, no Authorization header, auto protocol. No schema changes and no new migrations; a deployment that sets none of the new keys behaves as before, apart from the two fixes at the end of this list.

  • The embedding dimension is configuration, not code. embed_dim (default 768) replaces the literal 768 in the response check, in the backfill dimension guard (backfill_null_embeddings(expected_dim=...)), and in the stats dry-run. The check was moved, not relaxed: a mismatch still fails fast with expected N dims (embed_dim), got M. Changing the value on a database that already holds vectors needs a column migration; see Changing the embedding dimension.
  • Bearer auth for hosted endpoints. embed_api_key_env holds the name of an environment variable (for example OPENROUTER_API_KEY). When that variable is set and non-empty, the plugin sends Authorization: Bearer <value>. The value is read at call time and is never logged, stored in config, or included in exception messages. Unset or empty means no header, as before.
  • Explicit protocol selection. embed_protocol: openai uses only /v1/embeddings, so a 401 or an unknown-model error from a hosted endpoint is reported as-is instead of being replaced by a 404 from the Ollama-native fallback. ollama uses only /api/embed. auto keeps the old try-OpenAI-then-Ollama behaviour. Unknown values fall back to auto with a warning.
  • One embed path. Prefetch, both recall tools, the init-time bulk import, the writer drain and hermes-pgvector backfill all resolve the endpoint through one helper, so the settings apply the same way everywhere (stats reads the same embed_dim). Timeouts and retries are unchanged: one attempt on the agent thread, bounded retries on the writer. backfill gains --embed-dim, --embed-api-key-env and --embed-protocol (CLI flag > --config file > default).
  • Fixed: embeds broke under hermes-agent's plugin loader. After it runs the package, plugins/plugin_loader.py:load_plugin_module binds every sibling module back onto it, including setattr(pkg, "embed", <the embed submodule>). That replaced the embed function the provider called, so every embed raised TypeError: 'module' object is not callable. That is not an EmbeddingError, so nothing degraded gracefully: prefetch and the recall tools raised out of the hook, and the writer dropped each mirrored write and captured turn outright instead of storing it text-only. Call sites now use a private alias the loader never touches. An external patch that re-binds embed inside register() is no longer needed, and does no harm if it is still present. from hermes_pgvector import embed still works.
  • Fixed: a read timeout escaped as a bare TimeoutError. urllib wraps errors raised while sending a request, but a server that accepts the connection and answers slower than the timeout raises TimeoutError from the response read. That slipped past every except EmbeddingError: on the agent thread it raised out of prefetch and the recall tools, auto never tried its fallback, and on the writer the retries never ran and the write was dropped instead of being stored text-only. It is now an EmbeddingError, like every other endpoint failure.

Install: pip install -U hermes-memory-pgvector (PyPI: https://pypi.org/project/hermes-memory-pgvector/0.5.3/)