Skip to content

Releases

v1.0.4

Choose a tag to compare

@github-actions github-actions released this 12 Nov 13:52
1406023

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-pool keeps its independently versioned minimum of 3.3.3.

Upgrade notes

  • Install hermes-memory-pgvector==1.0.4 from 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

Choose a tag to compare

@github-actions github-actions released this 04 Nov 15:10
fac7a80

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/ssl as their SSL directory,
    which loaded the system openssl.cnf and 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

Choose a tag to compare

@github-actions github-actions released this 03 Nov 16:29
75d94c0

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

Choose a tag to compare

@andreab67 andreab67 released this 03 Nov 12:07
bcbd011

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 a vX.Y.Z tag 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)

Choose a tag to compare

@andreab67 andreab67 released this 28 Sep 23:07
14136d4

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 remap refuses blank or identical --old/--new
    (error: on stderr, exit 1, dry-run included). Before, an identity-equal
    remap --execute deleted every memory_entries row of that identity.
  • An explicit --config that cannot be read or parsed is now an error
    (exit 1) for stats, backfill, prune, cleanup and remap. It used
    to print a warning and silently fall back to the built-in default DSN.
  • Boolean config keys honour only 1/true/yes/on and 0/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 as false.
  • prefetch_budget, prefetch_limit and min_similarity are 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 type forum (Telegram supergroups with topics), room
    (LINE multi-person rooms) or webhook now normalise to the external-group theme like other multi-party traffic.
    Rows already written under those raw keys are not rewritten; find them
    with SELECT DISTINCT agent_identity FROM conversations WHERE agent_identity ~ ':(forum|room|webhook):' and fold them with remap if wanted.
  • Install backups are hidden: install.sh and hermes-pgvector install --force now move a previous install to plugins/.pgvector.bak-<ts>, so
    hermes-agent no longer discovers the backup as a second memory provider.
    Check ~/.hermes/plugins/ for an old visible pgvector.bak* directory
    and remove it.

Fixed

  • High — remap data loss: remap --old X --new X --execute deleted
    every memory_entries row for X and 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 (one stat per call, re-parse only on change).
  • The on_session_end backstop wrote multimodal / multi-part user turns a
    second time (it flattened content differently from the host), and stored
    multi-KB /skill scaffolding for bare or trivial skill invocations.
  • replace() with a blank old_text overwrote an arbitrary row; editing an
    entry into content that already exists left the stale row recallable.
  • Telegram forum, LINE room and webhook session 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 via scope='all'. The bare
    per-platform DM key agent:<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 blank embed_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 in remaining forever on some collations; the blank
    filter now matches Python's str.strip() independent of locale. On
    SQL_ASCII databases 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.sh on a reused clone checked out a stale local branch
    instead of the ref it had just fetched.
  • Docs: hnsw.ef_search DSN example (the unquoted form broke the
    connection), manual-install migrations path, identity resolution order
    (default-profile CLI/cron sessions resolve to the theme hermes), the
    cleanup PII scan not covering metadata.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

Choose a tag to compare

@andreab67 andreab67 released this 26 Sep 19:27

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_ide...
Read more

v0.5.4

Choose a tag to compare

@andreab67 andreab67 released this 18 Sep 18:46
3c8612e
v0.5.4 - psycopg 3.3.6 / psycopg-pool 3.3.2 floor

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

Choose a tag to compare

@andreab67 andreab67 released this 17 Sep 15:14

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/)

v0.5.2 — documentation only

Choose a tag to compare

@andreab67 andreab67 released this 07 Sep 16:34
b9912f6

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 failed count against a dry-run baseline that is hardcoded to 0, 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

Choose a tag to compare

@andreab67 andreab67 released this 07 Sep 15:20
37b72d5

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:

  • _worker reads extra["old_text"] and refuses a remove with no usable target
  • store.remove() rejects an empty pattern outright, so the destructive delete is unreachable by omission from any caller
  • remove() 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 own replace()

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 that embed() can never process (EmbeddingError("empty input") is unconditional for blank text). The nightly backfill then re-tried it on every run, pinning failed above zero and making remaining == 0 unreachable — destroying the one signal an operator watches, since a permanently-stuck row became indistinguishable from a new genuine failure. Empty writes are now skipped (remove exempt), and un-embeddable rows are excluded from the sweep and reported as unembeddable, so remaining can 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 use content ~ '\S'.
  • Those predicates are raw strings. As plain f-strings, \S is an invalid Python escape — four DeprecationWarnings today, SyntaxWarning on 3.12+, and under -W error the module fails to import, which would make hermes-agent's loader silently fall back to built-in memory. Both reproduced and fixed.
  • hermes-pgvector stats reports backfillable and un-embeddable counts separately; the fail-soft backfill path returns the unembeddable key 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