Skip to content

v0.6.0 - 1.0-readiness fixes, CI, conformance suite

Choose a tag to compare

@andreab67 andreab67 released this 26 Sep 19:27
· 52 commits to main since this release

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_url default changed from a private LAN address to
    http://localhost:11434. If you relied on the old default, set
    plugins.pgvector.embed_url explicitly before upgrading.

  • embed_timeout default lowered from 10.0 to 5.0. Ambient recall
    (prefetch()) now has a hard wall-clock prefetch_budget (default 5.0
    seconds) and can be pre-computed in the background via queue_prefetch(),
    so a slow embed endpoint degrades to full-text-only recall instead of
    blocking the agent turn.

  • Identities are lowercased. Marketing and marketing now resolve to
    the same theme. The scope argument of recall_memory /
    recall_conversation is case-folded the same way, so scope='Marketing'
    reads the marketing theme. 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-pgvector package on every host that writes to the
    database first
    , then run hermes-pgvector migrate (which applies
    migration 005). Migration 005 drops memory_entries_unique, the
    index a pre-0.6.0 plugin's ON CONFLICT (agent_identity, target, content) names as its conflict target — running 005 before every
    writer is upgraded makes every add() on the old code fail with
    there is no unique or exclusion constraint matching the ON CONFLICT specification. Pass --runtime-role NAME to migrate if your runtime
    role is not hermes.

  • write_contexts (new key, default primary,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 via on_delegation, so this should be
    a no-op for most deployments; check your agent_context usage if not.

  • backfill exit codes changed: 0 = done (remaining: 0 on 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_id on a delegation row now means the
    delegating (parent) session
    , matching migration 002's original
    column definition. It previously held the child session id — the
    reverse. The child session id is unchanged in
    metadata.child_session_id and in memory_agent_edges.

  • health() returns row_count_estimate, not row_count. Internal
    API, but visible in hermes-pgvector stats output — the number is now an
    approximation (pg_class.reltuples), not an exact COUNT(*).

Added

  • hermes-pgvector migrate --runtime-role NAME (H1) — resolves the
    runtime role migrations 002/004 grant DML to from a session GUC
    (hermes_pgvector.runtime_role) instead of hard-coding hermes. A psql -f run gets the same effect with PGOPTIONS='-c hermes_pgvector.runtime_role=NAME'. A role that does not exist yet gets
    a NOTICE, 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 an exact_content keyword (H2) — an
    exact content = %s match (lowest id) instead of the old_text
    substring LIKE, 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_budget config key (default 5.0s) (H4) — hard wall-clock
    budget for prefetch()'s synchronous fallback path, kept below the
    hermes-agent host's 8-second external-prefetch timeout.
  • write_contexts config key (default primary,cron) (M4) — which
    agent_context values are allowed to write.
  • shutdown_drain_timeout config key (default 10.0s) (M3) — timeout
    for the writer-queue drain on shutdown().
  • AsyncWriter.draining read-only property (M3/L5), replacing the
    unused, never-set _stop event.
  • hermes-pgvector --version — prints the installed distribution
    version via importlib.metadata.
  • Typed config schema — every get_config_schema() entry now declares
    a real type (text/integer/number/boolean), a typed default,
    and minimum/maximum where meaningful; new entries for
    identity_aliases, embed_write_backoff, write_contexts,
    prefetch_budget, and shutdown_drain_timeout that existed in code but
    were previously undeclared.
  • docs/configuration.md — full config reference, generated from
    get_config_schema() + DEFAULTS by scripts/gen_config_doc.py
    (--check verifies 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) — checks PgvectorMemoryProvider against
    hermes-agent's actual MemoryProvider ABC and MemoryManager call
    shapes: subclass/instantiation, per-method signature compatibility, the
    hermes_agent.memory_providers entry point, previous_content delivery
    through notify_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-agent main.
  • 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 gains note /
    skipped_changed keys.
  • Backfill's persisting UPDATE is 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 concurrent replace() /
    remove()) is counted as skipped_changed, not failed or
    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() and remap_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 runs COUNT(*) (M6) — returns
    row_count_estimate from pg_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 per initialize() (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 filter embedding IS NOT NULL (L6) — with hybrid_search: false, a NULL-embedding row
    (written during an embed-endpoint outage) no longer fills the result
    tail with score: 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.
  • cleanup passes --tables through 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 finally block (L4).
  • on_session_end's turn-capture backstop no longer requires migration
    002
    (L9) — it now runs whenever sync_turns is enabled and the
    provider is healthy; only the register_agent enqueue (a migration-002
    object) stays gated on it.
  • Delegation rows' parent_session_id meaning (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_id and memory_agent_edges only.
  • 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_identity metadata 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 documents group-bucket.

Fixed

  • H1 — migrate no longer aborts on a runtime role other than
    hermes. Migrations 002 and 004's GRANT blocks now resolve the
    role from a session GUC and RAISE NOTICE (never error) when it does
    not exist, so 003, 004, and 005 still run.
  • H2 — replace() / remove() no longer rely solely on a caller-hint
    old_text substring LIKE (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's previous_content is available
    (memory_manager.notify_memory_tool_write), it is matched exactly
    instead; a remove with no exact match logs and does nothing rather
    than falling back to LIKE.
  • 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_timeout dropped to 5.0, embed()'s auto protocol now
    shares ONE deadline across both HTTP attempts instead of a fresh timeout
    per attempt, and queue_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 fictional 555-01xx range (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._stop event is removed (see
    draining above).
  • L10 — migrate no longer fails against a SQL_ASCII-encoded
    database with 'ascii' codec can't encode character: migration files are
    now read and executed as raw UTF-8 bytes. The comments in 002/004
    (and the new 005) are pure ASCII, enforced by a test; 001 and 003
    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-only messages /
    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-string agent_identity /
    gateway_session_key / agent_workspace as absent instead of raising
    AttributeError, and on_memory_write() drops a non-dict metadata
    instead of raising — both found by fuzzing every hook for invariant #4
    (nothing may raise into the agent loop).
  • scripts/conformance.sh strips 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/