Repository navigation
Releases
v1.0.4
Changed
- Raise the runtime
psycopg[binary]minimum to 3.3.9 across package metadata,
the plugin manifest, the source installer and the manual installation guide.
psycopg-poolkeeps its independently versioned minimum of 3.3.3.
Upgrade notes
- Install
hermes-memory-pgvector==1.0.4from PyPI and restart the services
that load the provider. No database schema migration or configuration change
is required for this patch release.
v1.0.3
Changed
- Raise the psycopg dependency floor from 3.3.7 to 3.3.8 across the package
metadata, plugin declaration and clone-install path. psycopg 3.3.8 stops the
Linux and macOS binary packages from using/etc/sslas their SSL directory,
which loaded the systemopenssl.cnfand could break connections, for
instance on FIPS-enabled systems (upstream #1476), and fixes the size of the
Linux x86_64 binary packages (upstream #1477). No public API, schema or
migration changes. - CI: update the pinned GitHub Actions and allow pytest 9 and twine 7 in the
development dependencies.
v1.0.2
Fixed
- Memory write hooks log and degrade if writer thread scheduling fails;
database pool construction failures leave the provider unavailable instead
of escaping initialization into the agent loop. - The test embedding server reads rejected POST bodies before closing the
connection, avoiding Windows TCP resets that hid HTTP authentication errors.
Changed
- Enforce the repository Ruff bug-prevention rules in CI and local hooks;
document architecture and test requirements in CONTRIBUTING.md. - Measure all runtime code with statement and branch coverage. Live CI runs
with zero skips and a 99.5% combined coverage floor. Add behavioral tests for
hook failures, store maintenance/races, CLI operations, HTTP errors, writer
lifecycle and host integration. - Releases depend on the complete CI suite, validate wheel/sdist contents
against source, and require README/ROADMAP/package/plugin version agreement. - Pin GitHub Actions by commit, automate dependency update proposals, explicitly
enable PyPI publish attestations and generate GitHub build provenance for
both archives. Existing 1.0.1 files remain unchanged.
v1.0.1
Changed
- Raise the psycopg dependency floor from 3.3.6 to 3.3.7 across the package
metadata, plugin declaration and clone-install path. No public API, schema
or migration changes. - CI: tag-triggered PyPI release via Trusted Publishing
(.github/workflows/release.yml). Pushing avX.Y.Ztag builds and tests
the package, publishes it to PyPI over OIDC (no stored token), and creates
the GitHub Release with the built artifacts attached. See
docs/release/RELEASING.md.
v1.0.0 - first stable release (pre-release review: 1 High, 10 Medium, 54 Low fixed)
First stable release. Declares the compatibility policy stable: the public
surface listed in the "Compatibility policy" section of
README.md is guaranteed stable across the 1.x series, with
breaking changes to that surface reserved for a future 2.0.
1.0.0 is not a plain re-tag of 1.0.0rc1 (which was never published
to PyPI): a full-codebase review before release
(docs/code-review/full-codebase-review-2026-09-28.md)
found one High and a number of Medium/Low defects, all fixed here. No schema
changes and no new migrations relative to 0.6.0.
Breaking / upgrade notes
hermes-pgvector remaprefuses blank or identical--old/--new
(error:on stderr, exit 1, dry-run included). Before, an identity-equal
remap --executedeleted everymemory_entriesrow of that identity.- An explicit
--configthat cannot be read or parsed is now an error
(exit 1) forstats,backfill,prune,cleanupandremap. It used
to print a warning and silently fall back to the built-in default DSN. - Boolean config keys honour only
1/true/yes/onand0/false/no/off;
blank or unrecognised values now mean the key's default. A blank value for
a default-on key (e.g.hybrid_search) used to read asfalse. prefetch_budget,prefetch_limitandmin_similarityare clamped to
the ranges the config schema already advertised (0.1-7.5 s, 1-50,
0.0-1.0).- Telegram forum, LINE room and webhook sessions are bucketed: session
keys with chat typeforum(Telegram supergroups with topics),room
(LINE multi-person rooms) orwebhooknow normalise to theexternal-grouptheme like other multi-party traffic.
Rows already written under those raw keys are not rewritten; find them
withSELECT DISTINCT agent_identity FROM conversations WHERE agent_identity ~ ':(forum|room|webhook):'and fold them withremapif wanted. - Install backups are hidden:
install.shandhermes-pgvector install --forcenow move a previous install toplugins/.pgvector.bak-<ts>, so
hermes-agent no longer discovers the backup as a second memory provider.
Check~/.hermes/plugins/for an old visiblepgvector.bak*directory
and remove it.
Fixed
- High —
remapdata loss:remap --old X --new X --executedeleted
everymemory_entriesrow forXand exited 0 (each row conflicted with
itself on the insert, then the delete removed the originals). identity_signature()read the config frozen at startup, so edits to
allowed_themes/identity_aliases/bench_mode/write_contexts
never rebuilt cached gateway agents until a restart. It now re-reads
config.yaml(onestatper call, re-parse only on change).- The
on_session_endbackstop wrote multimodal / multi-part user turns a
second time (it flattened content differently from the host), and stored
multi-KB/skillscaffolding for bare or trivial skill invocations. replace()with a blankold_textoverwrote an arbitrary row; editing an
entry into content that already exists left the stale row recallable.- Telegram
forum, LINEroomandwebhooksession keys were not
recognised as multi-party, so the raw key -- including a participant id -- became a
theme of its own, readable from any theme viascope='all'. The bare
per-platform DM keyagent:<ns>:<platform>:dm(a DM with no chat or
sender id) is now DM-bucketed too. - The embed client accepted vectors containing NaN/Infinity/null (or an
integer too large for a float), which the database then rejected, losing
the durable row; they now degrade to a text-only row like any other embed
failure. A blankembed_url:/embed_model:in config.yaml (loaded as
null) no longer crashes the write path, and no unexpected embed-side
exception can drop a durable row any more. backfill: blank rows made of non-ASCII whitespace (NBSP, U+2000-range,
U+3000, ...) or of U+001C-U+001F were retried and counted as failed on
every sweep, or left inremainingforever on some collations; the blank
filter now matches Python'sstr.strip()independent of locale. On
SQL_ASCIIdatabases backfill no longer fails every row (text = bytea),
and rows that are not valid UTF-8 are reported as failed instead of as a
concurrent edit.on_delegation: a host-supplied child identity is normalised like the
agent's own (it is NULL with current upstream, which does not pass one).scripts/conformance.shon a reused clone checked out a stale local branch
instead of the ref it had just fetched.- Docs:
hnsw.ef_searchDSN example (the unquoted form broke the
connection), manual-install migrations path, identity resolution order
(default-profile CLI/cron sessions resolve to the themehermes), the
cleanupPII scan not coveringmetadata.raw_identity, test environment
variables.
Changed
- CI: the live and conformance jobs fail on any skipped test, so a broken
environment can no longer pass green; many new regression tests (about
80) cover the fixes above. - The repro scripts under
docs/code-review/repro-2026-09-26/exit 2 (not
1, "bug present") on environment problems.
v0.6.0 - 1.0-readiness fixes, CI, conformance suite
Correctness release from a 1.0-readiness review
(docs/code-review/1.0-readiness-review-2026-09-26.md):
four High findings, seven Medium, ten Low. Also adds CI, a typed config
schema, an upstream conformance suite, and this changelog — the four items
that were blocking a 1.0 release.
Breaking / upgrade notes
Read all of these before upgrading. Full step-by-step procedure:
docs/upgrading.md.
-
embed_urldefault changed from a private LAN address to
http://localhost:11434. If you relied on the old default, set
plugins.pgvector.embed_urlexplicitly before upgrading. -
embed_timeoutdefault lowered from10.0to5.0. Ambient recall
(prefetch()) now has a hard wall-clockprefetch_budget(default5.0
seconds) and can be pre-computed in the background viaqueue_prefetch(),
so a slow embed endpoint degrades to full-text-only recall instead of
blocking the agent turn. -
Identities are lowercased.
Marketingandmarketingnow resolve to
the same theme. Thescopeargument ofrecall_memory/
recall_conversationis case-folded the same way, soscope='Marketing'
reads themarketingtheme. Find existing mixed-case themes before upgrading:SELECT DISTINCT agent_identity FROM memory_entries WHERE agent_identity <> lower(agent_identity); SELECT DISTINCT agent_identity FROM conversations WHERE agent_identity <> lower(agent_identity);
Then fold each one with
hermes-pgvector remap --old <Mixed> --new <mixed> --execute. -
Migration ordering matters this time. Upgrade the
hermes-memory-pgvectorpackage on every host that writes to the
database first, then runhermes-pgvector migrate(which applies
migration005). Migration005dropsmemory_entries_unique, the
index a pre-0.6.0 plugin'sON CONFLICT (agent_identity, target, content)names as its conflict target — running005before every
writer is upgraded makes everyadd()on the old code fail with
there is no unique or exclusion constraint matching the ON CONFLICT specification. Pass--runtime-role NAMEtomigrateif your runtime
role is nothermes. -
write_contexts(new key, defaultprimary,cron) gates writes by
agent_context. Contexts not in the list —subagent,flush— no
longer write to Postgres (recall is unaffected). Delegated subagent
output already reaches the parent viaon_delegation, so this should be
a no-op for most deployments; check youragent_contextusage if not. -
backfillexit codes changed:0= done (remaining: 0on every
table, no table aborted);2= embed endpoint unavailable or a table's
pass aborted;3= rows still remaining or failed, with no abort. Update
any timer/alerting that checked for a non-zero exit generically. -
conversations.parent_session_idon a delegation row now means the
delegating (parent) session, matching migration002's original
column definition. It previously held the child session id — the
reverse. The child session id is unchanged in
metadata.child_session_idand inmemory_agent_edges. -
health()returnsrow_count_estimate, notrow_count. Internal
API, but visible inhermes-pgvector statsoutput — the number is now an
approximation (pg_class.reltuples), not an exactCOUNT(*).
Added
hermes-pgvector migrate --runtime-role NAME(H1) — resolves the
runtime role migrations002/004grant DML to from a session GUC
(hermes_pgvector.runtime_role) instead of hard-codinghermes. Apsql -frun gets the same effect withPGOPTIONS='-c hermes_pgvector.runtime_role=NAME'. A role that does not exist yet gets
aNOTICE, never a failed migration.- Migration
005_content_md5_unique.sql(M1) — unique index on
(agent_identity, target, md5(content)), replacing the raw-text
UNIQUE(agent_identity, target, content)btree that could not hold an
entry over roughly 2.7 KB. replace()/remove()gain anexact_contentkeyword (H2) — an
exactcontent = %smatch (lowest id) instead of theold_text
substringLIKE, used when the caller has the upstream tool's exact
prior entry (metadata["previous_content"]).queue_prefetch(query, session_id=...)(H4) — a background,
single-worker cache that pre-computes a ready-to-use ambient-recall block
for a session;prefetch()consumes it on the next call instead of
embedding + searching synchronously.prefetch_budgetconfig key (default5.0s) (H4) — hard wall-clock
budget forprefetch()'s synchronous fallback path, kept below the
hermes-agent host's 8-second external-prefetch timeout.write_contextsconfig key (defaultprimary,cron) (M4) — which
agent_contextvalues are allowed to write.shutdown_drain_timeoutconfig key (default10.0s) (M3) — timeout
for the writer-queue drain onshutdown().AsyncWriter.drainingread-only property (M3/L5), replacing the
unused, never-set_stopevent.hermes-pgvector --version— prints the installed distribution
version viaimportlib.metadata.- Typed config schema — every
get_config_schema()entry now declares
a realtype(text/integer/number/boolean), a typeddefault,
andminimum/maximumwhere meaningful; new entries for
identity_aliases,embed_write_backoff,write_contexts,
prefetch_budget, andshutdown_drain_timeoutthat existed in code but
were previously undeclared. docs/configuration.md— full config reference, generated from
get_config_schema()+DEFAULTSbyscripts/gen_config_doc.py
(--checkverifies it is current; wired into CI).- CI (
.github/workflows/ci.yml) — lint, unit tests on Python
3.11/3.12/3.13, live tests against Postgres 16/17/18 (with a
no-hermes-role cluster for the H1 regression test), sdist/wheel build +
twine check+ wheel-contents assertion, the version-consistency check,
and the upstream conformance suite below. - Upstream conformance suite (
conformance/, pinned to
conformance/HERMES_AGENT_REF) — checksPgvectorMemoryProvideragainst
hermes-agent's actualMemoryProviderABC andMemoryManagercall
shapes: subclass/instantiation, per-method signature compatibility, the
hermes_agent.memory_providersentry point,previous_contentdelivery
throughnotify_memory_tool_write, and the external-prefetch timeout
contract. Runs on every push/PR at the pinned ref, plus a non-blocking
weekly drift check against hermes-agentmain. docs/operations.md,docs/scaling.md,
docs/troubleshooting.md,docs/upgrading.md,
docs/release/RELEASING.md,SECURITY.md— the docs set.
Changed
- Backfill re-architected (H3) — a single keyset-paginated pass per
table (id > last_id ORDER BY id LIMIT batch_size) instead of re-fetching
the same failing rows every batch; a consecutive-failure breaker
(default 20) aborts a table's pass early on a flapping endpoint instead
of looping forever, and the result gainsnote/
skipped_changedkeys. - Backfill's persisting
UPDATEis now guarded (M2) —
WHERE id = %s AND embedding IS NULL AND content = %s; a row changed or
deleted between the SELECT and the UPDATE (a concurrentreplace()/
remove()) is counted asskipped_changed, notfailedor
succeeded, and never gets stamped with a stale embedding. ON CONFLICT (agent_identity, target, content) DO NOTHING→ON CONFLICT DO NOTHING(M1, code) with no explicit conflict target, in
add()andremap_identity()— satisfied by either the old or the new
(005) unique index, so the same code works before and after migration
005.bulk_upsert_md()no longer aborts a whole file on one bad entry —
a per-entry insert error is now caught, logged once per file with a
count, and the import continues with the next entry (M1, related).health()no longer runsCOUNT(*)(M6) — returns
row_count_estimatefrompg_class.reltuples(an O(1) planner
estimate) instead of an exact, full-scan count.count()/
count_turns()are unchanged (scoped, index-backed).system_prompt_block()is computed once perinitialize()(M6),
matching the upstream contract that it is static per session, instead of
re-querying the database on every call.- Pure-vector
search()/search_turns()now filterembedding IS NOT NULL(L6) — withhybrid_search: false, a NULL-embedding row
(written during an embed-endpoint outage) no longer fills the result
tail withscore: null. scan_pii's default pattern is bounded (L8) —(^|[^0-9])[0-9]{10,11}([^0-9]|$)
no longer matches a 10-11 digit window inside a longer digit run.cleanuppasses--tablesthrough to the PII scan (L8) — scanning
no longer always covers the whole table whitelist when the operator
asked for one table.- Every CLI command closes its store in a
finallyblock (L4). on_session_end's turn-capture backstop no longer requires migration
002(L9) — it now runs wheneversync_turnsis enabled and the
provider is healthy; only theregister_agentenqueue (a migration-002
object) stays gated on it.- Delegation rows'
parent_session_idmeaning (M5, finding — not
roadmap milestone M5) — now the delegating session, matching migration
002's column definition; the child session id lives in
metadata.child_session_idandmemory_agent_edgesonly. - Identities are case-folded (M7) —
normalize_identity()lowercases
after strip; alias keys and allow-list entries are compared lowercased.
The raw value is still recorded as `raw_ide...
v0.5.4
v0.5.3 - configurable embedding model (dimension, auth, protocol)
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(default768) replaces the literal 768 in the response check, in the backfill dimension guard (backfill_null_embeddings(expected_dim=...)), and in thestatsdry-run. The check was moved, not relaxed: a mismatch still fails fast withexpected 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_envholds the name of an environment variable (for exampleOPENROUTER_API_KEY). When that variable is set and non-empty, the plugin sendsAuthorization: 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: openaiuses 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.ollamauses only/api/embed.autokeeps the old try-OpenAI-then-Ollama behaviour. Unknown values fall back toautowith a warning. - One embed path. Prefetch, both recall tools, the init-time bulk import, the writer drain and
hermes-pgvector backfillall resolve the endpoint through one helper, so the settings apply the same way everywhere (statsreads the sameembed_dim). Timeouts and retries are unchanged: one attempt on the agent thread, bounded retries on the writer.backfillgains--embed-dim,--embed-api-key-envand--embed-protocol(CLI flag >--configfile > default). - Fixed: embeds broke under hermes-agent's plugin loader. After it runs the package,
plugins/plugin_loader.py:load_plugin_modulebinds every sibling module back onto it, includingsetattr(pkg, "embed", <the embed submodule>). That replaced theembedfunction the provider called, so every embed raisedTypeError: 'module' object is not callable. That is not anEmbeddingError, 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-bindsembedinsideregister()is no longer needed, and does no harm if it is still present.from hermes_pgvector import embedstill 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 raisesTimeoutErrorfrom the response read. That slipped past everyexcept EmbeddingError: on the agent thread it raised out of prefetch and the recall tools,autonever 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 anEmbeddingError, like every other endpoint failure.
Install: pip install -U hermes-memory-pgvector (PyPI: https://pypi.org/project/hermes-memory-pgvector/0.5.3/)
v0.5.2 — documentation only
Documentation only — no redeploy needed
No code changes. git diff v0.5.1..v0.5.2 touches README.md, one test file, and the two version strings; the only change under hermes_pgvector/ is plugin.yaml's version string. An installed 0.5.2 behaves byte-for-byte like 0.5.1.
Why it exists
PyPI renders a project's README frozen at upload time, so two fixes that landed after v0.5.1 shipped were visible on GitHub but never on the package page:
- The v0.5.1 release notes were out of order — the section sat before v0.5.0 instead of after it, burying the newest release mid-list. These sections run oldest-to-newest.
- A test compared a
failedcount against a dry-run baseline that is hardcoded to0, making the comparison a no-op — and its own commit message described it as a "delta", which wasn't true of the code.
Also fixes a review finding on that test: an inline comment cited the module docstring for a "THROWAWAY database" requirement the docstring didn't state. Rather than drop the citation, the requirement is now stated — it's real and was missing. Those backfill cases call backfill_null_embeddings(), which sweeps the whole table, so on a shared database they would stamp every pre-existing NULL-embedding row with the test's constant [0.1]*768 vector, after which a genuine backfill can never repair them.
Which version should you be on?
| You are on | Action |
|---|---|
| v0.5.1 | Nothing — you already have every fix in this release |
| v0.5.0 or earlier | Upgrade. v0.5.1 fixed a data-loss bug where a single memory remove deleted a whole theme's mirrored memory |
| pre-0.5.0 | Upgrade, and note v0.5.0 renamed the import package — see its release notes for the one-time step |
Validation
117 tests skip-mode, 164 against live Postgres 16 + pgvector 0.8.6. Attached artifacts are sha256-identical to the PyPI files.
Full changelog: v0.5.1...v0.5.2
v0.5.1 — memory remove no longer wipes a whole theme
Upgrade promptly — this fixes a data-loss bug
memory remove deleted every mirrored entry for a theme, not one.
_worker passed old_text=item.content for a remove. But the built-in tool's remove op carries its target in old_text and leaves content empty (tools/memory_tool.py — remove requires old_text), and the host forwards it through metadata, not content. So item.content was always "", store.remove built content LIKE '%%', and that matches every row — one memory remove wiped the entire mirror for that (agent_identity, target).
Verified against Postgres: DELETE … WHERE c LIKE '%%' removes all rows. Checked the reference deployment for damage — none; every theme's history is continuous, so removes are evidently rare in practice.
Fixed at two layers, because one is not enough for a silent full-scope delete:
_workerreadsextra["old_text"]and refuses a remove with no usable targetstore.remove()rejects an empty pattern outright, so the destructive delete is unreachable by omission from any callerremove()now deletes at most one row (lowest id), matching the built-in — which requires a unique match and errors on ambiguity — and this class's ownreplace()
The built-in store was never affected; only the pgvector mirror.
Also fixed
- Empty-content rows are no longer created or retried forever. Nothing rejected empty
add/replace, so a row could exist thatembed()can never process (EmbeddingError("empty input")is unconditional for blank text). The nightly backfill then re-tried it on every run, pinningfailedabove zero and makingremaining == 0unreachable — destroying the one signal an operator watches, since a permanently-stuck row became indistinguishable from a new genuine failure. Empty writes are now skipped (removeexempt), and un-embeddable rows are excluded from the sweep and reported asunembeddable, soremainingcan reach zero again. - The whitespace predicate matches Python. Postgres
trim()strips spaces only, so a row holding just a newline or tab still slipped through and still failed forever. All sites now usecontent ~ '\S'. - Those predicates are raw strings. As plain f-strings,
\Sis an invalid Python escape — fourDeprecationWarnings today,SyntaxWarningon 3.12+, and under-W errorthe module fails to import, which would make hermes-agent's loader silently fall back to built-in memory. Both reproduced and fixed. hermes-pgvector statsreports backfillable and un-embeddable counts separately; the fail-soft backfill path returns theunembeddablekey its contract promises.
Validation
118 tests skip-mode, 164 against live Postgres 16 + pgvector 0.8.6 with all four migrations applied. Two review passes: the first found the data-loss bug, the second found the broken escape sequence in that fix. Attached artifacts are sha256-identical to the PyPI files.
Full changelog: v0.5.0...v0.5.1