Repository navigation
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 asraw_identitymetadata when it
differs. - Stale text fixed (L3) — the queue-full config description now says
"newest writes are dropped" (it always dropped the newest, the text said
"oldest"); the module docstring's tool list;normalize_identity's
reason list now documentsgroup-bucket.
Fixed
- H1 —
migrateno longer aborts on a runtime role other than
hermes. Migrations002and004'sGRANTblocks now resolve the
role from a session GUC andRAISE NOTICE(never error) when it does
not exist, so003,004, and005still run. - H2 —
replace()/remove()no longer rely solely on a caller-hint
old_textsubstringLIKE(lowest id), which could match a stale row
that merely contains the pattern rather than the row the built-in
store actually edited. When upstream'sprevious_contentis available
(memory_manager.notify_memory_tool_write), it is matched exactly
instead; aremovewith no exact match logs and does nothing rather
than falling back toLIKE. - H4 —
prefetch()no longer risks a 20-second worst case (two
sequential embed attempts at the old 10s timeout each) on the agent
thread;embed_timeoutdropped to5.0,embed()'sautoprotocol now
shares ONE deadline across both HTTP attempts instead of a fresh timeout
per attempt, andqueue_prefetch()lets a caller pre-compute the block
off the agent thread entirely. - L1 — the real-looking Colorado Springs phone number in docstrings and
tests is replaced with the fictional555-01xxrange (e.g.
15550100123). Git history was not rewritten; whether to purge the old
number from history is left to the maintainer. - L2 —
embed_url's default is no longer a private LAN address. - L5 — the unused, never-set
AsyncWriter._stopevent is removed (see
drainingabove). - L10 —
migrateno longer fails against aSQL_ASCII-encoded
database with'ascii' codec can't encode character: migration files are
now read and executed as raw UTF-8 bytes. The comments in002/004
(and the new005) are pure ASCII, enforced by a test;001and003
are never edited once shipped, so their comments keep their original
characters and rely on the byte-level execution. sync_turn()now accepts upstream's keyword-onlymessages/
turn_author(and any later keyword via**kwargs), found by the
conformance suite's signature-compatibility test. The host introspects
the signature, so this was not a live crash, but the plugin could not
receive them if upstream tightened the contract further.initialize()treats a non-stringagent_identity/
gateway_session_key/agent_workspaceas absent instead of raising
AttributeError, andon_memory_write()drops a non-dictmetadata
instead of raising — both found by fuzzing every hook for invariant #4
(nothing may raise into the agent loop).scripts/conformance.shstrips whitespace when reading
conformance/HERMES_AGENT_REF, so a CRLF checkout (core.autocrlf=true)
no longer produces an invalid ref.
PyPI: https://pypi.org/project/hermes-memory-pgvector/0.6.0/