hermes-memory-pgvector 0.4.0__tar.gz → 0.4.2__tar.gz

{hermes_memory_pgvector-0.4.0 → hermes_memory_pgvector-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-memory-pgvector
-Version: 0.4.0
+Version: 0.4.2
 Summary: Postgres + pgvector memory provider plugin for hermes-agent. Multi-agent storage layer with per-minion themes, identity governance, agent attribution + delegation provenance, async writer, no LLM in the memory hot path.
 Author: Andrea Borghi
 License: BSD-3-Clause
@@ -106,6 +106,21 @@ Four capabilities, all storage-layer (still no LLM in the hot path):
 
 Maintenance CLI (`python -m pgvector`, installed as `hermes-pgvector`): `migrate · stats · backfill · prune · cleanup · remap` — destructive commands default to dry-run. v0.4.0 is a clean upgrade from v0.3.x: apply migration `002` to light up attribution/delegation; without it the new hooks no-op and everything else runs unchanged.
 
+## New in v0.4.1 — hybrid recall (vector + full-text)
+
+`recall_memory` and `recall_conversation` now fuse the HNSW **vector** ranking with a Postgres **full-text** ranking using **Reciprocal Rank Fusion** (RRF, `k=60`). A row surfaces if *either* ranker likes it, which fixes the two blind spots of pure cosine similarity:
+
+- **Exact-lexical hits** the embedding smooths away — a specific error code, hostname, flag name, or rare identifier the agent quotes verbatim.
+- **Text-only rows with a `NULL` embedding** (written while the embed endpoint was down) — invisible to the vector index, but the full-text leg finds them. So hybrid recall doubles as best-effort recovery until the next `backfill`.
+
+Still a storage-layer feature: **no LLM, no entity graph, no new tables or columns** — just a GIN index over the existing `content` column (migration `003`) and a fused query. It stays inside invariant #1 (a second index over the same text is not a parallel ontology). Fail-soft as ever: a hybrid hiccup degrades to the proven pure-vector path, and a query that *itself* fails to embed degrades to full-text-only instead of erroring. Toggle with `plugins.pgvector.hybrid_search` (default `true`); the ambient `prefetch()` path stays pure-vector. Works without migration `003` — the GIN index only makes the full-text leg faster.
+
+## New in v0.4.2 — pip-native install + hardening
+
+- **`hermes-pgvector install`** — makes a plain `pip install hermes-memory-pgvector` deployable on ANY hermes-agent install: generates the `$HERMES_HOME/plugins/pgvector/` discovery shim (see *Install · Option 1*). No more vendored copies or editable checkouts.
+- **Migration `004`** — `hermes-pgvector migrate` now grants the runtime role DML on `memory_entries`/`conversations` itself; the manual OWNER-transfer step is gone (fresh installs previously hit `permission denied` if it was skipped).
+- **Correctness fixes** from a full-codebase review: `replace`/`remove` now match `old_text` as a *literal* substring (LIKE `%`/`_`/`\` metacharacters no longer over- or under-match — parity with the built-in tool's `in` semantics); the async writer drains its queue on shutdown instead of silently abandoning up to 255 accepted writes when full; a wrong-dimension embed model now surfaces as `expected 768 dims, got N` instead of a masking 404; DM-key bucketing no longer sweeps ordinary `:signal:`-containing theme names into `whatsapp-dm`; bulk MEMORY.md import circuit-breaks after 3 consecutive embed failures (a hanging endpoint can no longer block session start for minutes); `remap` re-checks its duplicate-drop guard under the advisory lock; tool errors redact credential-looking fragments and preserve `score: null` for full-text-only hybrid hits (with `rrf_score` now included); `recall_memory(scope='session')` returns a helpful error instead of silently matching nothing.
+
 ## Multi-agent / per-minion themes
 
 Each systemd-run minion sets one header on its OpenAI client; everything else flows automatically:
@@ -130,7 +145,28 @@ Set `plugins.pgvector.allowed_themes` to that product/worker list to enforce it
 
 ## Install
 
-### Option 1: clone + run the installer script (recommended)
+### Option 1: pip + discovery shim (recommended, v0.4.2+)
+
+```bash
+# 1. Install the package into the SAME environment hermes-agent runs in
+pip install hermes-memory-pgvector
+
+# 2. Create the discovery shim
+hermes-pgvector install          # writes $HERMES_HOME/plugins/pgvector/
+
+# 3. Apply ALL migrations (schema + attribution + FTS + runtime grants)
+hermes-pgvector migrate --admin-dsn \
+    "dbname=<your-memory-db> user=postgres host=/var/run/postgresql"
+
+# 4. Activate + verify
+hermes config set memory.provider pgvector
+sudo systemctl restart hermes.service
+hermes memory status             # expect: Provider: pgvector; Status: available
+```
+
+**Why the shim?** hermes-agent discovers memory providers by scanning plugin *directories* — `plugins/memory/<name>/` (bundled) and `$HERMES_HOME/plugins/<name>/` (user) — and never looks at installed packages. `pip install` alone is therefore invisible to it. `hermes-pgvector install` writes a two-line shim whose absolute import resolves to the pip-installed package, so upgrades are just `pip install -U hermes-memory-pgvector` + restart, and rollback is `pip install hermes-memory-pgvector==<prev>` + restart — the shim never changes. `--remove` deletes it; if the package is uninstalled the shim import fails cleanly and hermes falls back to built-in memory.
+
+### Option 2: clone + run the installer script (from source)
 
 ```bash
 git clone https://github.com/andreab67/hermes-memory-pgvector.git
@@ -144,7 +180,7 @@ That:
 2. Copies `pgvector/` into `$HERMES_HOME/plugins/pgvector/` (defaults to `~/.hermes/plugins/pgvector/`).
 3. Prints the admin migration + activation commands you run next.
 
-### Option 2: manual
+### Option 3: manual
 
 ```bash
 # Python deps
@@ -167,15 +203,19 @@ sudo -u postgres psql -d <your-memory-db> \
 # runtime role needs — it self-grants, so no extra OWNER step for these).
 sudo -u postgres psql -d <your-memory-db> \
      -f ~/.hermes/plugins/pgvector/migrations/002_agent_attribution.sql
-# (or apply every migration in order:  hermes-pgvector migrate --admin-dsn "user=postgres host=/var/run/postgresql dbname=<your-memory-db>")
 
-# Hand ownership of the v0.1 tables to the hermes runtime role
-sudo -u postgres psql -d <your-memory-db> -c "
-ALTER TABLE memory_entries OWNER TO hermes;
-ALTER SEQUENCE memory_entries_id_seq OWNER TO hermes;
-ALTER TABLE conversations OWNER TO hermes;
-ALTER SEQUENCE conversations_id_seq OWNER TO hermes;
-"
+# v0.4.1: apply the hybrid-search full-text indexes (GIN over content on both
+# tables). Optional — hybrid recall works without it, just seq-scans the FTS
+# leg. No new tables/columns/GRANTs; needs no OWNER step.
+sudo -u postgres psql -d <your-memory-db> \
+     -f ~/.hermes/plugins/pgvector/migrations/003_hybrid_search_fts.sql
+
+# v0.4.2: grant the runtime role DML on the core tables (replaces the old
+# manual "ALTER TABLE ... OWNER TO hermes" step; skips with a NOTICE if your
+# runtime role isn't named 'hermes' — grant manually in that case).
+sudo -u postgres psql -d <your-memory-db> \
+     -f ~/.hermes/plugins/pgvector/migrations/004_runtime_grants.sql
+# (or apply every migration in order:  hermes-pgvector migrate --admin-dsn "user=postgres host=/var/run/postgresql dbname=<your-memory-db>")
 
 # Activate
 hermes config set memory.provider pgvector
@@ -299,4 +339,4 @@ Bug reports + PRs welcome. Open an issue describing the failure mode + your envi
 
 ## License
 
-[BSD 3-Clause](LICENSE) © 2026 Andrea Borghi.
+[BSD 3-Clause](LICENSE) © 2026 Green Yoga Inc

{hermes_memory_pgvector-0.4.0 → hermes_memory_pgvector-0.4.2}/README.md

@@ -73,6 +73,21 @@ Four capabilities, all storage-layer (still no LLM in the hot path):
 
 Maintenance CLI (`python -m pgvector`, installed as `hermes-pgvector`): `migrate · stats · backfill · prune · cleanup · remap` — destructive commands default to dry-run. v0.4.0 is a clean upgrade from v0.3.x: apply migration `002` to light up attribution/delegation; without it the new hooks no-op and everything else runs unchanged.
 
+## New in v0.4.1 — hybrid recall (vector + full-text)
+
+`recall_memory` and `recall_conversation` now fuse the HNSW **vector** ranking with a Postgres **full-text** ranking using **Reciprocal Rank Fusion** (RRF, `k=60`). A row surfaces if *either* ranker likes it, which fixes the two blind spots of pure cosine similarity:
+
+- **Exact-lexical hits** the embedding smooths away — a specific error code, hostname, flag name, or rare identifier the agent quotes verbatim.
+- **Text-only rows with a `NULL` embedding** (written while the embed endpoint was down) — invisible to the vector index, but the full-text leg finds them. So hybrid recall doubles as best-effort recovery until the next `backfill`.
+
+Still a storage-layer feature: **no LLM, no entity graph, no new tables or columns** — just a GIN index over the existing `content` column (migration `003`) and a fused query. It stays inside invariant #1 (a second index over the same text is not a parallel ontology). Fail-soft as ever: a hybrid hiccup degrades to the proven pure-vector path, and a query that *itself* fails to embed degrades to full-text-only instead of erroring. Toggle with `plugins.pgvector.hybrid_search` (default `true`); the ambient `prefetch()` path stays pure-vector. Works without migration `003` — the GIN index only makes the full-text leg faster.
+
+## New in v0.4.2 — pip-native install + hardening
+
+- **`hermes-pgvector install`** — makes a plain `pip install hermes-memory-pgvector` deployable on ANY hermes-agent install: generates the `$HERMES_HOME/plugins/pgvector/` discovery shim (see *Install · Option 1*). No more vendored copies or editable checkouts.
+- **Migration `004`** — `hermes-pgvector migrate` now grants the runtime role DML on `memory_entries`/`conversations` itself; the manual OWNER-transfer step is gone (fresh installs previously hit `permission denied` if it was skipped).
+- **Correctness fixes** from a full-codebase review: `replace`/`remove` now match `old_text` as a *literal* substring (LIKE `%`/`_`/`\` metacharacters no longer over- or under-match — parity with the built-in tool's `in` semantics); the async writer drains its queue on shutdown instead of silently abandoning up to 255 accepted writes when full; a wrong-dimension embed model now surfaces as `expected 768 dims, got N` instead of a masking 404; DM-key bucketing no longer sweeps ordinary `:signal:`-containing theme names into `whatsapp-dm`; bulk MEMORY.md import circuit-breaks after 3 consecutive embed failures (a hanging endpoint can no longer block session start for minutes); `remap` re-checks its duplicate-drop guard under the advisory lock; tool errors redact credential-looking fragments and preserve `score: null` for full-text-only hybrid hits (with `rrf_score` now included); `recall_memory(scope='session')` returns a helpful error instead of silently matching nothing.
+
 ## Multi-agent / per-minion themes
 
 Each systemd-run minion sets one header on its OpenAI client; everything else flows automatically:
@@ -97,7 +112,28 @@ Set `plugins.pgvector.allowed_themes` to that product/worker list to enforce it
 
 ## Install
 
-### Option 1: clone + run the installer script (recommended)
+### Option 1: pip + discovery shim (recommended, v0.4.2+)
+
+```bash
+# 1. Install the package into the SAME environment hermes-agent runs in
+pip install hermes-memory-pgvector
+
+# 2. Create the discovery shim
+hermes-pgvector install          # writes $HERMES_HOME/plugins/pgvector/
+
+# 3. Apply ALL migrations (schema + attribution + FTS + runtime grants)
+hermes-pgvector migrate --admin-dsn \
+    "dbname=<your-memory-db> user=postgres host=/var/run/postgresql"
+
+# 4. Activate + verify
+hermes config set memory.provider pgvector
+sudo systemctl restart hermes.service
+hermes memory status             # expect: Provider: pgvector; Status: available
+```
+
+**Why the shim?** hermes-agent discovers memory providers by scanning plugin *directories* — `plugins/memory/<name>/` (bundled) and `$HERMES_HOME/plugins/<name>/` (user) — and never looks at installed packages. `pip install` alone is therefore invisible to it. `hermes-pgvector install` writes a two-line shim whose absolute import resolves to the pip-installed package, so upgrades are just `pip install -U hermes-memory-pgvector` + restart, and rollback is `pip install hermes-memory-pgvector==<prev>` + restart — the shim never changes. `--remove` deletes it; if the package is uninstalled the shim import fails cleanly and hermes falls back to built-in memory.
+
+### Option 2: clone + run the installer script (from source)
 
 ```bash
 git clone https://github.com/andreab67/hermes-memory-pgvector.git
@@ -111,7 +147,7 @@ That:
 2. Copies `pgvector/` into `$HERMES_HOME/plugins/pgvector/` (defaults to `~/.hermes/plugins/pgvector/`).
 3. Prints the admin migration + activation commands you run next.
 
-### Option 2: manual
+### Option 3: manual
 
 ```bash
 # Python deps
@@ -134,15 +170,19 @@ sudo -u postgres psql -d <your-memory-db> \
 # runtime role needs — it self-grants, so no extra OWNER step for these).
 sudo -u postgres psql -d <your-memory-db> \
      -f ~/.hermes/plugins/pgvector/migrations/002_agent_attribution.sql
-# (or apply every migration in order:  hermes-pgvector migrate --admin-dsn "user=postgres host=/var/run/postgresql dbname=<your-memory-db>")
 
-# Hand ownership of the v0.1 tables to the hermes runtime role
-sudo -u postgres psql -d <your-memory-db> -c "
-ALTER TABLE memory_entries OWNER TO hermes;
-ALTER SEQUENCE memory_entries_id_seq OWNER TO hermes;
-ALTER TABLE conversations OWNER TO hermes;
-ALTER SEQUENCE conversations_id_seq OWNER TO hermes;
-"
+# v0.4.1: apply the hybrid-search full-text indexes (GIN over content on both
+# tables). Optional — hybrid recall works without it, just seq-scans the FTS
+# leg. No new tables/columns/GRANTs; needs no OWNER step.
+sudo -u postgres psql -d <your-memory-db> \
+     -f ~/.hermes/plugins/pgvector/migrations/003_hybrid_search_fts.sql
+
+# v0.4.2: grant the runtime role DML on the core tables (replaces the old
+# manual "ALTER TABLE ... OWNER TO hermes" step; skips with a NOTICE if your
+# runtime role isn't named 'hermes' — grant manually in that case).
+sudo -u postgres psql -d <your-memory-db> \
+     -f ~/.hermes/plugins/pgvector/migrations/004_runtime_grants.sql
+# (or apply every migration in order:  hermes-pgvector migrate --admin-dsn "user=postgres host=/var/run/postgresql dbname=<your-memory-db>")
 
 # Activate
 hermes config set memory.provider pgvector
@@ -266,4 +306,4 @@ Bug reports + PRs welcome. Open an issue describing the failure mode + your envi
 
 ## License
 
-[BSD 3-Clause](LICENSE) © 2026 Andrea Borghi.
+[BSD 3-Clause](LICENSE) © 2026 Green Yoga Inc

{hermes_memory_pgvector-0.4.0 → hermes_memory_pgvector-0.4.2}/hermes_memory_pgvector.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-memory-pgvector
-Version: 0.4.0
+Version: 0.4.2
 Summary: Postgres + pgvector memory provider plugin for hermes-agent. Multi-agent storage layer with per-minion themes, identity governance, agent attribution + delegation provenance, async writer, no LLM in the memory hot path.
 Author: Andrea Borghi
 License: BSD-3-Clause
@@ -106,6 +106,21 @@ Four capabilities, all storage-layer (still no LLM in the hot path):
 
 Maintenance CLI (`python -m pgvector`, installed as `hermes-pgvector`): `migrate · stats · backfill · prune · cleanup · remap` — destructive commands default to dry-run. v0.4.0 is a clean upgrade from v0.3.x: apply migration `002` to light up attribution/delegation; without it the new hooks no-op and everything else runs unchanged.
 
+## New in v0.4.1 — hybrid recall (vector + full-text)
+
+`recall_memory` and `recall_conversation` now fuse the HNSW **vector** ranking with a Postgres **full-text** ranking using **Reciprocal Rank Fusion** (RRF, `k=60`). A row surfaces if *either* ranker likes it, which fixes the two blind spots of pure cosine similarity:
+
+- **Exact-lexical hits** the embedding smooths away — a specific error code, hostname, flag name, or rare identifier the agent quotes verbatim.
+- **Text-only rows with a `NULL` embedding** (written while the embed endpoint was down) — invisible to the vector index, but the full-text leg finds them. So hybrid recall doubles as best-effort recovery until the next `backfill`.
+
+Still a storage-layer feature: **no LLM, no entity graph, no new tables or columns** — just a GIN index over the existing `content` column (migration `003`) and a fused query. It stays inside invariant #1 (a second index over the same text is not a parallel ontology). Fail-soft as ever: a hybrid hiccup degrades to the proven pure-vector path, and a query that *itself* fails to embed degrades to full-text-only instead of erroring. Toggle with `plugins.pgvector.hybrid_search` (default `true`); the ambient `prefetch()` path stays pure-vector. Works without migration `003` — the GIN index only makes the full-text leg faster.
+
+## New in v0.4.2 — pip-native install + hardening
+
+- **`hermes-pgvector install`** — makes a plain `pip install hermes-memory-pgvector` deployable on ANY hermes-agent install: generates the `$HERMES_HOME/plugins/pgvector/` discovery shim (see *Install · Option 1*). No more vendored copies or editable checkouts.
+- **Migration `004`** — `hermes-pgvector migrate` now grants the runtime role DML on `memory_entries`/`conversations` itself; the manual OWNER-transfer step is gone (fresh installs previously hit `permission denied` if it was skipped).
+- **Correctness fixes** from a full-codebase review: `replace`/`remove` now match `old_text` as a *literal* substring (LIKE `%`/`_`/`\` metacharacters no longer over- or under-match — parity with the built-in tool's `in` semantics); the async writer drains its queue on shutdown instead of silently abandoning up to 255 accepted writes when full; a wrong-dimension embed model now surfaces as `expected 768 dims, got N` instead of a masking 404; DM-key bucketing no longer sweeps ordinary `:signal:`-containing theme names into `whatsapp-dm`; bulk MEMORY.md import circuit-breaks after 3 consecutive embed failures (a hanging endpoint can no longer block session start for minutes); `remap` re-checks its duplicate-drop guard under the advisory lock; tool errors redact credential-looking fragments and preserve `score: null` for full-text-only hybrid hits (with `rrf_score` now included); `recall_memory(scope='session')` returns a helpful error instead of silently matching nothing.
+
 ## Multi-agent / per-minion themes
 
 Each systemd-run minion sets one header on its OpenAI client; everything else flows automatically:
@@ -130,7 +145,28 @@ Set `plugins.pgvector.allowed_themes` to that product/worker list to enforce it
 
 ## Install
 
-### Option 1: clone + run the installer script (recommended)
+### Option 1: pip + discovery shim (recommended, v0.4.2+)
+
+```bash
+# 1. Install the package into the SAME environment hermes-agent runs in
+pip install hermes-memory-pgvector
+
+# 2. Create the discovery shim
+hermes-pgvector install          # writes $HERMES_HOME/plugins/pgvector/
+
+# 3. Apply ALL migrations (schema + attribution + FTS + runtime grants)
+hermes-pgvector migrate --admin-dsn \
+    "dbname=<your-memory-db> user=postgres host=/var/run/postgresql"
+
+# 4. Activate + verify
+hermes config set memory.provider pgvector
+sudo systemctl restart hermes.service
+hermes memory status             # expect: Provider: pgvector; Status: available
+```
+
+**Why the shim?** hermes-agent discovers memory providers by scanning plugin *directories* — `plugins/memory/<name>/` (bundled) and `$HERMES_HOME/plugins/<name>/` (user) — and never looks at installed packages. `pip install` alone is therefore invisible to it. `hermes-pgvector install` writes a two-line shim whose absolute import resolves to the pip-installed package, so upgrades are just `pip install -U hermes-memory-pgvector` + restart, and rollback is `pip install hermes-memory-pgvector==<prev>` + restart — the shim never changes. `--remove` deletes it; if the package is uninstalled the shim import fails cleanly and hermes falls back to built-in memory.
+
+### Option 2: clone + run the installer script (from source)
 
 ```bash
 git clone https://github.com/andreab67/hermes-memory-pgvector.git
@@ -144,7 +180,7 @@ That:
 2. Copies `pgvector/` into `$HERMES_HOME/plugins/pgvector/` (defaults to `~/.hermes/plugins/pgvector/`).
 3. Prints the admin migration + activation commands you run next.
 
-### Option 2: manual
+### Option 3: manual
 
 ```bash
 # Python deps
@@ -167,15 +203,19 @@ sudo -u postgres psql -d <your-memory-db> \
 # runtime role needs — it self-grants, so no extra OWNER step for these).
 sudo -u postgres psql -d <your-memory-db> \
      -f ~/.hermes/plugins/pgvector/migrations/002_agent_attribution.sql
-# (or apply every migration in order:  hermes-pgvector migrate --admin-dsn "user=postgres host=/var/run/postgresql dbname=<your-memory-db>")
 
-# Hand ownership of the v0.1 tables to the hermes runtime role
-sudo -u postgres psql -d <your-memory-db> -c "
-ALTER TABLE memory_entries OWNER TO hermes;
-ALTER SEQUENCE memory_entries_id_seq OWNER TO hermes;
-ALTER TABLE conversations OWNER TO hermes;
-ALTER SEQUENCE conversations_id_seq OWNER TO hermes;
-"
+# v0.4.1: apply the hybrid-search full-text indexes (GIN over content on both
+# tables). Optional — hybrid recall works without it, just seq-scans the FTS
+# leg. No new tables/columns/GRANTs; needs no OWNER step.
+sudo -u postgres psql -d <your-memory-db> \
+     -f ~/.hermes/plugins/pgvector/migrations/003_hybrid_search_fts.sql
+
+# v0.4.2: grant the runtime role DML on the core tables (replaces the old
+# manual "ALTER TABLE ... OWNER TO hermes" step; skips with a NOTICE if your
+# runtime role isn't named 'hermes' — grant manually in that case).
+sudo -u postgres psql -d <your-memory-db> \
+     -f ~/.hermes/plugins/pgvector/migrations/004_runtime_grants.sql
+# (or apply every migration in order:  hermes-pgvector migrate --admin-dsn "user=postgres host=/var/run/postgresql dbname=<your-memory-db>")
 
 # Activate
 hermes config set memory.provider pgvector
@@ -299,4 +339,4 @@ Bug reports + PRs welcome. Open an issue describing the failure mode + your envi
 
 ## License
 
-[BSD 3-Clause](LICENSE) © 2026 Andrea Borghi.
+[BSD 3-Clause](LICENSE) © 2026 Green Yoga Inc

{hermes_memory_pgvector-0.4.0 → hermes_memory_pgvector-0.4.2}/hermes_memory_pgvector.egg-info/SOURCES.txt

@@ -16,6 +16,10 @@ pgvector/store.py
 pgvector/writer.py
 pgvector/migrations/001_schema.sql
 pgvector/migrations/002_agent_attribution.sql
+pgvector/migrations/003_hybrid_search_fts.sql
+pgvector/migrations/004_runtime_grants.sql
+tests/test_hybrid_search.py
 tests/test_identity.py
+tests/test_install_shim.py
 tests/test_smoke.py
 tests/test_store_v04.py

{hermes_memory_pgvector-0.4.0 → hermes_memory_pgvector-0.4.2}/pgvector/__init__.py

@@ -23,6 +23,7 @@ Config in $HERMES_HOME/config.yaml under plugins.pgvector:
         min_similarity: 0.30
         embed_on_write: true
         scope_default: "current"   # 'current' | 'all'
+        hybrid_search: true        # fuse vector + full-text (RRF) in recall tools
 
 Tools exposed: `recall_memory` (one explicit search tool). All built-in
 memory writes (add/replace/remove) are mirrored automatically via the
@@ -83,6 +84,17 @@ _NOISE_RE = re.compile(
 logger = logging.getLogger(__name__)
 
 
+# Credential-looking fragments that must never round-trip into a tool response
+# (psycopg/libpq errors can echo conninfo verbatim; tool errors flow back to
+# the model and can be persisted durably by conversation capture).
+_CRED_RE = re.compile(r"(password|passfile|sslkey|sslpassword)=\S+", re.IGNORECASE)
+
+
+def _safe_err(exc: BaseException) -> str:
+    """Exception text safe to return to the model: truncated + creds redacted."""
+    return _CRED_RE.sub(r"\1=[redacted]", str(exc)[:300])
+
+
 # ---------------------------------------------------------------------------
 # Tool schema — one explicit search over memory_entries
 # ---------------------------------------------------------------------------
@@ -182,12 +194,19 @@ DEFAULTS = {
     "min_similarity": 0.30,
     "embed_on_write": True,
     "scope_default": "current",
+    # v0.4.1 — hybrid recall: fuse the HNSW vector ranking with a Postgres
+    # full-text ranking via RRF in the recall_memory / recall_conversation
+    # tools. Recovers exact-lexical hits cosine smooths away + text-only rows
+    # with NULL embeddings. Degrades to pure vector on any error, and to
+    # full-text-only when the query fails to embed. Needs migration 003 for the
+    # GIN index (works without it, just slower — seq-scan FTS on a small table).
+    "hybrid_search": True,
     "write_queue_maxsize": 256,
     # v0.1.1 — bulk sync MEMORY.md / USER.md on init
     "bulk_sync_on_init": True,
     # v0.2 — conversation turn capture
     "sync_turns": True,
-    "turn_min_chars": 40,  # turns shorter than this are noise unless > 200 chars or contain tool refs
+    "turn_min_chars": 40,  # turns shorter than this (after strip) are boilerplate noise
     # v0.4 — identity governance
     "allowed_themes": None,        # None/empty = governance off; set a list to enforce an allow-list
     "identity_aliases": {},        # {raw: canonical} remaps applied before normalization
@@ -249,6 +268,11 @@ class PgvectorMemoryProvider(MemoryProvider):
 
     def initialize(self, session_id: str, **kwargs) -> None:
         self._session_id = session_id
+        # Per-session log-signal reset (v0.4.2): the provider instance is
+        # reused across sessions, so without this a single embed failure in
+        # any past session silences the one-time warning for the process
+        # lifetime — a later session with a broken endpoint gets zero signal.
+        self._embed_warned = False
         # Per-agent theme scoping — priority order:
         #   1. gateway_session_key — from the `X-Hermes-Session-Key` header on
         #      API requests. This is the EXPLICIT minion-scope signal sent by
@@ -568,7 +592,7 @@ class PgvectorMemoryProvider(MemoryProvider):
             logger.debug("pgvector on_delegation failed (ignored): %s", exc)
 
     def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
-        """Best-effort: bump this agent's last_seen in the registry. Fail-soft,
+        """Best-effort: capture session turns + bump last_seen. Fail-soft,
         non-blocking. No LLM summary (invariant #2). No-op until 002 applied."""
         if not self._healthy or not self._writer or not self._delegation_enabled:
             return
@@ -581,6 +605,36 @@ class PgvectorMemoryProvider(MemoryProvider):
                 extra={"kind": classify_kind(self._agent_identity)},
                 metadata={},
             )
+            # Capture substantive user/assistant turns for conversation recall.
+            if messages:
+                policy = self._config.get("conversation_embed_policy", "all")
+                for msg in messages:
+                    role = (msg.get("role") or "").lower()
+                    if role not in ("user", "assistant"):
+                        continue
+                    raw = msg.get("content") or ""
+                    content = (
+                        raw if isinstance(raw, str)
+                        else " ".join(
+                            p.get("text", "") for p in raw
+                            if isinstance(p, dict) and p.get("type") == "text"
+                        ) if isinstance(raw, list) else str(raw)
+                    )
+                    if self._is_noise(content, min_chars=40):
+                        continue
+                    self._writer.enqueue(
+                        action="turn",
+                        agent_identity=self._agent_identity,
+                        target="conversations",
+                        content=content[:8000],
+                        extra={
+                            "role": role,
+                            "session_id": self._session_id or "default",
+                            "embed": self._should_embed_turn(role, content, policy),
+                            "parent_session_id": self._parent_session_id,
+                        },
+                        metadata={},
+                    )
         except Exception as exc:  # noqa: BLE001
             logger.debug("pgvector on_session_end failed (ignored): %s", exc)
 
@@ -799,6 +853,14 @@ class PgvectorMemoryProvider(MemoryProvider):
             agent_filter: Optional[str] = self._agent_identity
         elif scope == "all":
             agent_filter = None
+        elif scope == "session":
+            # Only recall_conversation supports 'session'. Falling through
+            # would silently filter on a literal 'session' theme and return
+            # zero rows — indistinguishable from "nothing found" (v0.4.2).
+            return tool_error(
+                "scope='session' is only valid for recall_conversation; "
+                "use 'current', 'all', or a theme name here."
+            )
         else:
             agent_filter = scope
 
@@ -808,6 +870,7 @@ class PgvectorMemoryProvider(MemoryProvider):
         if target_filter not in (None, "memory", "user"):
             return tool_error(f"Invalid target: {target_arg!r}")
 
+        hybrid = bool(self._config.get("hybrid_search", True))
         try:
             vec = embed(
                 query,
@@ -815,31 +878,63 @@ class PgvectorMemoryProvider(MemoryProvider):
                 model=self._config["embed_model"],
             )
         except EmbeddingError as exc:
-            return json.dumps({"results": [], "count": 0, "error": f"embed: {exc}"})
+            if not hybrid:
+                return json.dumps({"results": [], "count": 0, "error": f"embed: {_safe_err(exc)}"})
+            # Hybrid on: the query text still drives a full-text search without a
+            # vector, so degrade to lexical recall instead of erroring.
+            logger.debug("recall_memory embed failed; full-text-only: %s", exc)
+            vec = None
 
         try:
-            rows = self._store.search(
-                query_embedding=vec,
-                agent_identity=agent_filter,
-                target=target_filter,
-                limit=limit,
-            )
+            if hybrid:
+                rows = self._store.hybrid_search(
+                    query_text=query,
+                    query_embedding=vec,
+                    agent_identity=agent_filter,
+                    target=target_filter,
+                    limit=limit,
+                )
+            else:
+                rows = self._store.search(
+                    query_embedding=vec,
+                    agent_identity=agent_filter,
+                    target=target_filter,
+                    limit=limit,
+                )
         except Exception as exc:  # noqa: BLE001
-            return json.dumps({"results": [], "count": 0, "error": f"db: {exc}"})
+            # Fail-soft: a hybrid hiccup with a usable vector falls back to the
+            # proven pure-vector path rather than returning nothing.
+            if hybrid and vec is not None:
+                try:
+                    rows = self._store.search(
+                        query_embedding=vec,
+                        agent_identity=agent_filter,
+                        target=target_filter,
+                        limit=limit,
+                    )
+                except Exception as exc2:  # noqa: BLE001
+                    return json.dumps({"results": [], "count": 0, "error": f"db: {_safe_err(exc2)}"})
+            else:
+                return json.dumps({"results": [], "count": 0, "error": f"db: {_safe_err(exc)}"})
 
         results = []
         for r in rows:
             ts = r.get("updated_at") or r.get("created_at")
-            results.append(
-                {
-                    "id": r.get("id"),
-                    "agent_identity": r.get("agent_identity"),
-                    "target": r.get("target"),
-                    "ts": ts.isoformat() if ts else None,
-                    "score": round(float(r.get("score") or 0.0), 4),
-                    "content": (r.get("content") or "")[:2000],
-                }
-            )
+            score = r.get("score")
+            entry = {
+                "id": r.get("id"),
+                "agent_identity": r.get("agent_identity"),
+                "target": r.get("target"),
+                "ts": ts.isoformat() if ts else None,
+                # None stays None (v0.4.2): a full-text-only hybrid hit has no
+                # cosine score; flattening it to 0.0 made a strong lexical
+                # match look identical to an orthogonal vector match.
+                "score": round(float(score), 4) if score is not None else None,
+                "content": (r.get("content") or "")[:2000],
+            }
+            if r.get("rrf_score") is not None:
+                entry["rrf_score"] = round(float(r["rrf_score"]), 6)
+            results.append(entry)
         return json.dumps({"results": results, "count": len(results)})
 
     def _handle_recall_conversation(self, args: Dict[str, Any]) -> str:
@@ -867,6 +962,7 @@ class PgvectorMemoryProvider(MemoryProvider):
         else:
             agent_filter = scope  # treat as a specific theme name
 
+        hybrid = bool(self._config.get("hybrid_search", True))
         try:
             vec = embed(
                 query,
@@ -874,32 +970,57 @@ class PgvectorMemoryProvider(MemoryProvider):
                 model=self._config["embed_model"],
             )
         except EmbeddingError as exc:
-            return json.dumps({"results": [], "count": 0, "error": f"embed: {exc}"})
+            if not hybrid:
+                return json.dumps({"results": [], "count": 0, "error": f"embed: {_safe_err(exc)}"})
+            logger.debug("recall_conversation embed failed; full-text-only: %s", exc)
+            vec = None
 
         try:
-            rows = self._store.search_turns(
-                query_embedding=vec,
-                agent_identity=agent_filter,
-                session_id=session_filter,
-                limit=limit,
-            )
+            if hybrid:
+                rows = self._store.hybrid_search_turns(
+                    query_text=query,
+                    query_embedding=vec,
+                    agent_identity=agent_filter,
+                    session_id=session_filter,
+                    limit=limit,
+                )
+            else:
+                rows = self._store.search_turns(
+                    query_embedding=vec,
+                    agent_identity=agent_filter,
+                    session_id=session_filter,
+                    limit=limit,
+                )
         except Exception as exc:  # noqa: BLE001
-            return json.dumps({"results": [], "count": 0, "error": f"db: {exc}"})
+            if hybrid and vec is not None:
+                try:
+                    rows = self._store.search_turns(
+                        query_embedding=vec,
+                        agent_identity=agent_filter,
+                        session_id=session_filter,
+                        limit=limit,
+                    )
+                except Exception as exc2:  # noqa: BLE001
+                    return json.dumps({"results": [], "count": 0, "error": f"db: {_safe_err(exc2)}"})
+            else:
+                return json.dumps({"results": [], "count": 0, "error": f"db: {_safe_err(exc)}"})
 
         results = []
         for r in rows:
             ts = r.get("ts")
-            results.append(
-                {
-                    "id": r.get("id"),
-                    "agent_identity": r.get("agent_identity"),
-                    "session_id": r.get("session_id"),
-                    "role": r.get("role"),
-                    "ts": ts.isoformat() if ts else None,
-                    "score": round(float(r.get("score") or 0.0), 4),
-                    "content": (r.get("content") or "")[:2000],
-                }
-            )
+            score = r.get("score")
+            entry = {
+                "id": r.get("id"),
+                "agent_identity": r.get("agent_identity"),
+                "session_id": r.get("session_id"),
+                "role": r.get("role"),
+                "ts": ts.isoformat() if ts else None,
+                "score": round(float(score), 4) if score is not None else None,
+                "content": (r.get("content") or "")[:2000],
+            }
+            if r.get("rrf_score") is not None:
+                entry["rrf_score"] = round(float(r["rrf_score"]), 6)
+            results.append(entry)
         return json.dumps({"results": results, "count": len(results)})
 
     # -- Setup hooks ---------------------------------------------------------
@@ -945,6 +1066,12 @@ class PgvectorMemoryProvider(MemoryProvider):
                 "default": DEFAULTS["scope_default"],
                 "choices": ["current", "all"],
             },
+            {
+                "key": "hybrid_search",
+                "description": "v0.4.1: fuse the HNSW vector ranking with a Postgres full-text ranking (Reciprocal Rank Fusion) in recall_memory / recall_conversation. Recovers exact-lexical hits cosine smooths away and text-only rows with NULL embeddings; degrades to pure vector on error and to full-text-only when the query fails to embed. Apply migration 003 for the GIN index (works without it, just slower).",
+                "default": "true",
+                "choices": ["true", "false"],
+            },
             {
                 "key": "write_queue_maxsize",
                 "description": "Bounded async-writer queue size; full = oldest writes drop with a warning",