hermes-memory-pgvector 0.6.0__tar.gz → 1.0.0__tar.gz

{hermes_memory_pgvector-0.6.0 → hermes_memory_pgvector-1.0.0}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2026, Andrea Borghi
+Copyright (c) 2026, Green Yoga Inc
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

{hermes_memory_pgvector-0.6.0 → hermes_memory_pgvector-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-memory-pgvector
-Version: 0.6.0
+Version: 1.0.0
 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
@@ -9,7 +9,7 @@ Project-URL: Source, https://github.com/andreab67/hermes-memory-pgvector
 Project-URL: Issues, https://github.com/andreab67/hermes-memory-pgvector/issues
 Project-URL: Roadmap, https://github.com/andreab67/hermes-memory-pgvector/blob/main/ROADMAP.md
 Keywords: hermes-agent,memory-provider,pgvector,postgres,multi-agent,llm-memory,semantic-search
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: BSD License
@@ -73,7 +73,7 @@ What was missing: a **storage layer** that gives the built-in `memory` model dur
 | `initialize()` | Verifies schema, opens a `psycopg_pool.ConnectionPool`, bulk-imports existing `MEMORY.md` + `USER.md` content. |
 | `on_memory_write(action, target, content, meta)` | Mirrors built-in `memory` writes into `memory_entries` (add / replace / remove). |
 | `sync_turn(user, assistant, session_id)` / `on_session_end(messages)` | Captures every substantive chat turn into `conversations`; `on_session_end` is a dedup'd backstop. |
-| `on_delegation(task, result, …)` | Records parent→child delegation provenance (`memory_agent_edges`) and stores the exchange as a recallable turn. |
+| `on_delegation(task, result, …)` | Records parent→child delegation provenance (`memory_agent_edges`) and stores the exchange as a recallable turn. `memory_agent_edges.child_identity` is only filled when the host passes a child identity; current upstream hermes-agent passes only the task, result and `child_session_id`, so it is NULL there (`child_session_id` is populated). |
 | `prefetch(query)` / `queue_prefetch(query, session_id=...)` | Ambient recall: top-K similar `memory_entries` for the current theme, injected into the system prompt. `queue_prefetch` pre-computes it off the agent thread. |
 | `recall_memory(query, scope, target, limit)` tool | Explicit cross-theme search of durable memory entries. |
 | `recall_conversation(query, scope, limit)` tool | Explicit search over past chat turns. `scope ∈ {current, session, all, <theme>}`. |
@@ -121,7 +121,7 @@ mkdir -p ~/.hermes/plugins
 cp -r hermes_pgvector ~/.hermes/plugins/pgvector
 ```
 
-Then apply migrations and activate as in Option 1 above (`hermes-pgvector migrate --admin-dsn ...`, or `psql -f` each `migrations/*.sql` in order — see [docs/operations.md](docs/operations.md) for the full admin walkthrough and [docs/upgrading.md](docs/upgrading.md) if you're coming from an older version).
+Then apply migrations and activate as in Option 1 above (`hermes-pgvector migrate --admin-dsn ...`, or `psql -f` each `hermes_pgvector/migrations/*.sql` in order — see [docs/operations.md](docs/operations.md) for the full admin walkthrough and [docs/upgrading.md](docs/upgrading.md) if you're coming from an older version).
 
 ## Configuration
 
@@ -152,11 +152,14 @@ client = AsyncOpenAI(
 
 The gateway plumbs `X-Hermes-Session-Key` through as `gateway_session_key=…` in `MemoryProvider.initialize` kwargs, taking priority over the profile default so unprofiled API traffic doesn't collapse every minion into one shared `default` scope.
 
-Convention: lowercase, dash-separated, stable (identities are case-folded automatically — `Marketing` and `marketing` are the same theme). Governed sinks that always exist regardless of your themes: `whatsapp-dm` (collapsed DM/session keys), `external-group` (collapsed group/channel/thread keys), `_bench` (benchmark traffic), `default` (last resort). Set `plugins.pgvector.allowed_themes` to your product/worker list to enforce an allow-list — an unknown or typo'd header then falls back to `default` (one-time warning) instead of silently minting a new theme.
+Identity resolution order in `initialize`: `gateway_session_key` > `agent_identity` (unless it is `default`) > `agent_workspace` > `default`. Upstream hermes-agent always passes `agent_workspace="hermes"` (and `agent_identity=<profile name>`), so a default-profile CLI or cron session with no gateway session key lands in the theme `hermes`, not `default`; named profiles land in their profile name. Set the `X-Hermes-Session-Key` header (or a non-default profile) if you want a scope other than `hermes`. When `allowed_themes` is set, `hermes` and your profile names are not exempt: include them in the list if you want those sessions to keep their own theme, otherwise they fall back to `default`.
+
+Convention: lowercase, dash-separated, stable (identities are case-folded automatically — `Marketing` and `marketing` are the same theme). Governed sinks that always exist regardless of your themes: `whatsapp-dm` (collapsed DM/session keys), `external-group` (collapsed group/channel/thread keys), `_bench` (benchmark traffic), `default` (only when the host passes no identity kwargs at all). Set `plugins.pgvector.allowed_themes` to your product/worker list to enforce an allow-list — an unknown or typo'd header then falls back to `default` (one-time warning) instead of silently minting a new theme.
 
 ## Compatibility policy
 
-This plugin follows semantic versioning on its **public surface**:
+This plugin follows semantic versioning on its **public surface**, stable as
+of `1.0.0`:
 
 - `plugins.pgvector.*` config keys (see [docs/configuration.md](docs/configuration.md))
 - Tool names and parameters (`recall_memory`, `recall_conversation`)
@@ -164,7 +167,11 @@ This plugin follows semantic versioning on its **public surface**:
 - Database table/column names
 - The `pgvector` provider name and the package's pip entry point
 
-`MemoryStore` and every other Python class/module are **internal** — not covered by semver, safe to change between minor releases. A migration file, once released, is never edited in place; schema changes land as a new numbered migration.
+Within the `1.x` series this surface is guaranteed stable: it may grow (new
+config keys, new optional params), but nothing already listed is renamed or
+removed, and no default changes behaviour, without a `2.0` release.
+
+`MemoryStore` and every other Python class/module are **internal** — not covered by semver, safe to change between minor releases, and excluded from the `1.x` guarantee above. A migration file, once released, is never edited in place; schema changes land as a new numbered migration.
 
 ## Support matrix
 
@@ -198,6 +205,18 @@ pytest -q                                    # no DB/embed endpoint: everything
 # Live mode (against a throwaway Postgres + your embed endpoint)
 export PG_TEST_DSN='dbname=hermes_test user=postgres host=/var/run/postgresql'
 export PG_TEST_EMBED_URL='http://your-embed-endpoint:11434'
+# Superuser DSN for the same database: the migration, CLI and empty-content
+# tests skip without it, and CI fails on any skip.
+export PG_TEST_ADMIN_DSN='dbname=hermes_test user=postgres host=/var/run/postgresql'
+pytest -q
+```
+
+The simplest path is the bundled harness (Postgres + pgvector in Docker and a
+fake embed server), which prints all the variables for you:
+
+```bash
+scripts/test-env.sh up pg17
+eval "$(scripts/test-env.sh db hermes_test)"
 pytest -q
 ```
 

{hermes_memory_pgvector-0.6.0 → hermes_memory_pgvector-1.0.0}/README.md

@@ -36,7 +36,7 @@ What was missing: a **storage layer** that gives the built-in `memory` model dur
 | `initialize()` | Verifies schema, opens a `psycopg_pool.ConnectionPool`, bulk-imports existing `MEMORY.md` + `USER.md` content. |
 | `on_memory_write(action, target, content, meta)` | Mirrors built-in `memory` writes into `memory_entries` (add / replace / remove). |
 | `sync_turn(user, assistant, session_id)` / `on_session_end(messages)` | Captures every substantive chat turn into `conversations`; `on_session_end` is a dedup'd backstop. |
-| `on_delegation(task, result, …)` | Records parent→child delegation provenance (`memory_agent_edges`) and stores the exchange as a recallable turn. |
+| `on_delegation(task, result, …)` | Records parent→child delegation provenance (`memory_agent_edges`) and stores the exchange as a recallable turn. `memory_agent_edges.child_identity` is only filled when the host passes a child identity; current upstream hermes-agent passes only the task, result and `child_session_id`, so it is NULL there (`child_session_id` is populated). |
 | `prefetch(query)` / `queue_prefetch(query, session_id=...)` | Ambient recall: top-K similar `memory_entries` for the current theme, injected into the system prompt. `queue_prefetch` pre-computes it off the agent thread. |
 | `recall_memory(query, scope, target, limit)` tool | Explicit cross-theme search of durable memory entries. |
 | `recall_conversation(query, scope, limit)` tool | Explicit search over past chat turns. `scope ∈ {current, session, all, <theme>}`. |
@@ -84,7 +84,7 @@ mkdir -p ~/.hermes/plugins
 cp -r hermes_pgvector ~/.hermes/plugins/pgvector
 ```
 
-Then apply migrations and activate as in Option 1 above (`hermes-pgvector migrate --admin-dsn ...`, or `psql -f` each `migrations/*.sql` in order — see [docs/operations.md](docs/operations.md) for the full admin walkthrough and [docs/upgrading.md](docs/upgrading.md) if you're coming from an older version).
+Then apply migrations and activate as in Option 1 above (`hermes-pgvector migrate --admin-dsn ...`, or `psql -f` each `hermes_pgvector/migrations/*.sql` in order — see [docs/operations.md](docs/operations.md) for the full admin walkthrough and [docs/upgrading.md](docs/upgrading.md) if you're coming from an older version).
 
 ## Configuration
 
@@ -115,11 +115,14 @@ client = AsyncOpenAI(
 
 The gateway plumbs `X-Hermes-Session-Key` through as `gateway_session_key=…` in `MemoryProvider.initialize` kwargs, taking priority over the profile default so unprofiled API traffic doesn't collapse every minion into one shared `default` scope.
 
-Convention: lowercase, dash-separated, stable (identities are case-folded automatically — `Marketing` and `marketing` are the same theme). Governed sinks that always exist regardless of your themes: `whatsapp-dm` (collapsed DM/session keys), `external-group` (collapsed group/channel/thread keys), `_bench` (benchmark traffic), `default` (last resort). Set `plugins.pgvector.allowed_themes` to your product/worker list to enforce an allow-list — an unknown or typo'd header then falls back to `default` (one-time warning) instead of silently minting a new theme.
+Identity resolution order in `initialize`: `gateway_session_key` > `agent_identity` (unless it is `default`) > `agent_workspace` > `default`. Upstream hermes-agent always passes `agent_workspace="hermes"` (and `agent_identity=<profile name>`), so a default-profile CLI or cron session with no gateway session key lands in the theme `hermes`, not `default`; named profiles land in their profile name. Set the `X-Hermes-Session-Key` header (or a non-default profile) if you want a scope other than `hermes`. When `allowed_themes` is set, `hermes` and your profile names are not exempt: include them in the list if you want those sessions to keep their own theme, otherwise they fall back to `default`.
+
+Convention: lowercase, dash-separated, stable (identities are case-folded automatically — `Marketing` and `marketing` are the same theme). Governed sinks that always exist regardless of your themes: `whatsapp-dm` (collapsed DM/session keys), `external-group` (collapsed group/channel/thread keys), `_bench` (benchmark traffic), `default` (only when the host passes no identity kwargs at all). Set `plugins.pgvector.allowed_themes` to your product/worker list to enforce an allow-list — an unknown or typo'd header then falls back to `default` (one-time warning) instead of silently minting a new theme.
 
 ## Compatibility policy
 
-This plugin follows semantic versioning on its **public surface**:
+This plugin follows semantic versioning on its **public surface**, stable as
+of `1.0.0`:
 
 - `plugins.pgvector.*` config keys (see [docs/configuration.md](docs/configuration.md))
 - Tool names and parameters (`recall_memory`, `recall_conversation`)
@@ -127,7 +130,11 @@ This plugin follows semantic versioning on its **public surface**:
 - Database table/column names
 - The `pgvector` provider name and the package's pip entry point
 
-`MemoryStore` and every other Python class/module are **internal** — not covered by semver, safe to change between minor releases. A migration file, once released, is never edited in place; schema changes land as a new numbered migration.
+Within the `1.x` series this surface is guaranteed stable: it may grow (new
+config keys, new optional params), but nothing already listed is renamed or
+removed, and no default changes behaviour, without a `2.0` release.
+
+`MemoryStore` and every other Python class/module are **internal** — not covered by semver, safe to change between minor releases, and excluded from the `1.x` guarantee above. A migration file, once released, is never edited in place; schema changes land as a new numbered migration.
 
 ## Support matrix
 
@@ -161,6 +168,18 @@ pytest -q                                    # no DB/embed endpoint: everything
 # Live mode (against a throwaway Postgres + your embed endpoint)
 export PG_TEST_DSN='dbname=hermes_test user=postgres host=/var/run/postgresql'
 export PG_TEST_EMBED_URL='http://your-embed-endpoint:11434'
+# Superuser DSN for the same database: the migration, CLI and empty-content
+# tests skip without it, and CI fails on any skip.
+export PG_TEST_ADMIN_DSN='dbname=hermes_test user=postgres host=/var/run/postgresql'
+pytest -q
+```
+
+The simplest path is the bundled harness (Postgres + pgvector in Docker and a
+fake embed server), which prints all the variables for you:
+
+```bash
+scripts/test-env.sh up pg17
+eval "$(scripts/test-env.sh db hermes_test)"
 pytest -q
 ```
 

{hermes_memory_pgvector-0.6.0 → hermes_memory_pgvector-1.0.0}/hermes_memory_pgvector.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-memory-pgvector
-Version: 0.6.0
+Version: 1.0.0
 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
@@ -9,7 +9,7 @@ Project-URL: Source, https://github.com/andreab67/hermes-memory-pgvector
 Project-URL: Issues, https://github.com/andreab67/hermes-memory-pgvector/issues
 Project-URL: Roadmap, https://github.com/andreab67/hermes-memory-pgvector/blob/main/ROADMAP.md
 Keywords: hermes-agent,memory-provider,pgvector,postgres,multi-agent,llm-memory,semantic-search
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: BSD License
@@ -73,7 +73,7 @@ What was missing: a **storage layer** that gives the built-in `memory` model dur
 | `initialize()` | Verifies schema, opens a `psycopg_pool.ConnectionPool`, bulk-imports existing `MEMORY.md` + `USER.md` content. |
 | `on_memory_write(action, target, content, meta)` | Mirrors built-in `memory` writes into `memory_entries` (add / replace / remove). |
 | `sync_turn(user, assistant, session_id)` / `on_session_end(messages)` | Captures every substantive chat turn into `conversations`; `on_session_end` is a dedup'd backstop. |
-| `on_delegation(task, result, …)` | Records parent→child delegation provenance (`memory_agent_edges`) and stores the exchange as a recallable turn. |
+| `on_delegation(task, result, …)` | Records parent→child delegation provenance (`memory_agent_edges`) and stores the exchange as a recallable turn. `memory_agent_edges.child_identity` is only filled when the host passes a child identity; current upstream hermes-agent passes only the task, result and `child_session_id`, so it is NULL there (`child_session_id` is populated). |
 | `prefetch(query)` / `queue_prefetch(query, session_id=...)` | Ambient recall: top-K similar `memory_entries` for the current theme, injected into the system prompt. `queue_prefetch` pre-computes it off the agent thread. |
 | `recall_memory(query, scope, target, limit)` tool | Explicit cross-theme search of durable memory entries. |
 | `recall_conversation(query, scope, limit)` tool | Explicit search over past chat turns. `scope ∈ {current, session, all, <theme>}`. |
@@ -121,7 +121,7 @@ mkdir -p ~/.hermes/plugins
 cp -r hermes_pgvector ~/.hermes/plugins/pgvector
 ```
 
-Then apply migrations and activate as in Option 1 above (`hermes-pgvector migrate --admin-dsn ...`, or `psql -f` each `migrations/*.sql` in order — see [docs/operations.md](docs/operations.md) for the full admin walkthrough and [docs/upgrading.md](docs/upgrading.md) if you're coming from an older version).
+Then apply migrations and activate as in Option 1 above (`hermes-pgvector migrate --admin-dsn ...`, or `psql -f` each `hermes_pgvector/migrations/*.sql` in order — see [docs/operations.md](docs/operations.md) for the full admin walkthrough and [docs/upgrading.md](docs/upgrading.md) if you're coming from an older version).
 
 ## Configuration
 
@@ -152,11 +152,14 @@ client = AsyncOpenAI(
 
 The gateway plumbs `X-Hermes-Session-Key` through as `gateway_session_key=…` in `MemoryProvider.initialize` kwargs, taking priority over the profile default so unprofiled API traffic doesn't collapse every minion into one shared `default` scope.
 
-Convention: lowercase, dash-separated, stable (identities are case-folded automatically — `Marketing` and `marketing` are the same theme). Governed sinks that always exist regardless of your themes: `whatsapp-dm` (collapsed DM/session keys), `external-group` (collapsed group/channel/thread keys), `_bench` (benchmark traffic), `default` (last resort). Set `plugins.pgvector.allowed_themes` to your product/worker list to enforce an allow-list — an unknown or typo'd header then falls back to `default` (one-time warning) instead of silently minting a new theme.
+Identity resolution order in `initialize`: `gateway_session_key` > `agent_identity` (unless it is `default`) > `agent_workspace` > `default`. Upstream hermes-agent always passes `agent_workspace="hermes"` (and `agent_identity=<profile name>`), so a default-profile CLI or cron session with no gateway session key lands in the theme `hermes`, not `default`; named profiles land in their profile name. Set the `X-Hermes-Session-Key` header (or a non-default profile) if you want a scope other than `hermes`. When `allowed_themes` is set, `hermes` and your profile names are not exempt: include them in the list if you want those sessions to keep their own theme, otherwise they fall back to `default`.
+
+Convention: lowercase, dash-separated, stable (identities are case-folded automatically — `Marketing` and `marketing` are the same theme). Governed sinks that always exist regardless of your themes: `whatsapp-dm` (collapsed DM/session keys), `external-group` (collapsed group/channel/thread keys), `_bench` (benchmark traffic), `default` (only when the host passes no identity kwargs at all). Set `plugins.pgvector.allowed_themes` to your product/worker list to enforce an allow-list — an unknown or typo'd header then falls back to `default` (one-time warning) instead of silently minting a new theme.
 
 ## Compatibility policy
 
-This plugin follows semantic versioning on its **public surface**:
+This plugin follows semantic versioning on its **public surface**, stable as
+of `1.0.0`:
 
 - `plugins.pgvector.*` config keys (see [docs/configuration.md](docs/configuration.md))
 - Tool names and parameters (`recall_memory`, `recall_conversation`)
@@ -164,7 +167,11 @@ This plugin follows semantic versioning on its **public surface**:
 - Database table/column names
 - The `pgvector` provider name and the package's pip entry point
 
-`MemoryStore` and every other Python class/module are **internal** — not covered by semver, safe to change between minor releases. A migration file, once released, is never edited in place; schema changes land as a new numbered migration.
+Within the `1.x` series this surface is guaranteed stable: it may grow (new
+config keys, new optional params), but nothing already listed is renamed or
+removed, and no default changes behaviour, without a `2.0` release.
+
+`MemoryStore` and every other Python class/module are **internal** — not covered by semver, safe to change between minor releases, and excluded from the `1.x` guarantee above. A migration file, once released, is never edited in place; schema changes land as a new numbered migration.
 
 ## Support matrix
 
@@ -198,6 +205,18 @@ pytest -q                                    # no DB/embed endpoint: everything
 # Live mode (against a throwaway Postgres + your embed endpoint)
 export PG_TEST_DSN='dbname=hermes_test user=postgres host=/var/run/postgresql'
 export PG_TEST_EMBED_URL='http://your-embed-endpoint:11434'
+# Superuser DSN for the same database: the migration, CLI and empty-content
+# tests skip without it, and CI fails on any skip.
+export PG_TEST_ADMIN_DSN='dbname=hermes_test user=postgres host=/var/run/postgresql'
+pytest -q
+```
+
+The simplest path is the bundled harness (Postgres + pgvector in Docker and a
+fake embed server), which prints all the variables for you:
+
+```bash
+scripts/test-env.sh up pg17
+eval "$(scripts/test-env.sh db hermes_test)"
 pytest -q
 ```
 

{hermes_memory_pgvector-0.6.0 → hermes_memory_pgvector-1.0.0}/hermes_memory_pgvector.egg-info/SOURCES.txt

@@ -43,4 +43,9 @@ tests/test_v060_identity_writer.py
 tests/test_v060_migrations_cli.py
 tests/test_v060_provider_reads.py
 tests/test_v060_provider_writes.py
-tests/test_v060_store.py
+tests/test_v060_store.py
+tests/test_v100_pass2_provider.py
+tests/test_v100_pass2_store.py
+tests/test_v100_pass3.py
+tests/test_v100_provider_fixes.py
+tests/test_v100_review_fixes.py

{hermes_memory_pgvector-0.6.0 → hermes_memory_pgvector-1.0.0}/hermes_pgvector/__init__.py

@@ -225,7 +225,7 @@ DEFAULTS = {
     # header, OpenAI-compatible path with the Ollama-native fallback.
     # embed_dim must equal the model's output AND the vector(N) columns;
     # changing it on an existing database needs a column migration + re-embed
-    # (see README, "Changing the embedding dimension").
+    # (see docs/upgrading.md, "Changing the embedding dimension").
     "embed_dim": 768,
     # NAME of an environment variable holding a bearer token (e.g.
     # "OPENROUTER_API_KEY"), never the token itself. Read at call time.
@@ -306,6 +306,20 @@ DEFAULTS = {
 }
 
 
+# Bounds for prefetch_budget. The maximum sits below the host's 8s hard cap on
+# an external provider's prefetch (upstream _EXTERNAL_PREFETCH_TIMEOUT_S); the
+# config schema and prefetch()'s clamp both read these so they cannot drift.
+_PREFETCH_BUDGET_MIN = 0.1
+_PREFETCH_BUDGET_MAX = 7.5
+
+# Bounds for prefetch_limit / min_similarity; get_config_schema advertises
+# them and _compute_prefetch_block clamps to them.
+_PREFETCH_LIMIT_MIN = 1
+_PREFETCH_LIMIT_MAX = 50
+_MIN_SIMILARITY_MIN = 0.0
+_MIN_SIMILARITY_MAX = 1.0
+
+
 def _as_bool(value: Any, default: bool) -> bool:
     """Coerce a config value to a real bool.
 
@@ -313,13 +327,22 @@ def _as_bool(value: Any, default: bool) -> bool:
     hand-edited config.yaml (YAML bools), and save_config(), which persists
     the config schema's declared values -- the STRINGS "true"/"false". A plain
     truthiness test silently inverts the string form (bool("false") is True),
-    so every boolean toggle reads through here.
+    so every boolean toggle reads through here. Only the explicit true/false
+    vocabularies are honoured; None, blank and unrecognized strings return
+    `default`.
     """
     if value is None:
         return default
     if isinstance(value, bool):
         return value
-    return str(value).strip().lower() in ("1", "true", "yes", "on")
+    text = str(value).strip().lower()
+    if text in ("1", "true", "yes", "on"):
+        return True
+    if text in ("0", "false", "no", "off"):
+        return False
+    # Blank / unrecognized: fall back to the default, like _as_int/_as_float,
+    # so a blank value for a default-true toggle does not silently disable it.
+    return default
 
 
 def _as_int(value: Any, default: int) -> int:
@@ -452,18 +475,52 @@ def _embed_with_config(
     key_env = config.get("embed_api_key_env")
     return _embed_text(
         text,
-        base_url=config.get("embed_url", DEFAULTS["embed_url"]),
-        model=config.get("embed_model", DEFAULTS["embed_model"]),
+        # `or`, not a .get default: a blank `embed_url:` in config.yaml loads
+        # as None and would otherwise reach embed() as base_url=None.
+        base_url=config.get("embed_url") or DEFAULTS["embed_url"],
+        model=config.get("embed_model") or DEFAULTS["embed_model"],
         timeout=timeout,
         retries=retries,
         backoff=backoff,
         max_total=max_total,
         dim=_embed_dim(config),
         api_key_env=str(key_env).strip() if key_env else None,
-        protocol=config.get("embed_protocol", DEFAULTS["embed_protocol"]),
+        protocol=config.get("embed_protocol") or DEFAULTS["embed_protocol"],
     )
 
 
+_TEXT_PART_TYPES = frozenset({"text", "input_text", "output_text"})
+_IMAGE_PART_TYPES = frozenset({"image_url", "input_image"})
+
+
+def _flatten_user_content(content: Any) -> str:
+    """Flatten user message content exactly as the host does before sync_turn().
+
+    Mirrors upstream agent.codex_responses_adapter._summarize_user_message_for_log
+    (called with a newline separator): text parts joined with newlines, images collapsed
+    to a "[N image(s)]" prefix, "" for None, str() for other scalars. The
+    on_session_end backstop fingerprints this form, so a multimodal turn hashes
+    the same as what sync_turn() already recorded.
+    """
+    if not isinstance(content, list):
+        return "" if content is None else str(content)
+    texts: List[str] = []
+    images = 0
+    for part in content:
+        if isinstance(part, str):
+            if part:
+                texts.append(part)
+        elif isinstance(part, dict):
+            ptype = str(part.get("type") or "").strip().lower()
+            text = part.get("text")
+            if ptype in _TEXT_PART_TYPES and isinstance(text, str) and text:
+                texts.append(text)
+            elif ptype in _IMAGE_PART_TYPES:
+                images += 1
+    note = f"[{images} image{'s' if images != 1 else ''}]" if images else ""
+    return " ".join(bit for bit in (note, "\n".join(texts).strip()) if bit)
+
+
 def _load_plugin_config() -> dict:
     try:
         from hermes_constants import get_hermes_home
@@ -508,6 +565,7 @@ class PgvectorMemoryProvider(MemoryProvider):
         self._healthy: bool = False
         self._delegation_enabled: bool = False        # set in initialize() iff migration 002 applied
         self._embed_warned: bool = False
+        self._embed_bug_warned: set = set()
         self._db_warned: bool = False
         # v0.6.0 (M4) -- agent_context gate. True until the first initialize()
         # decides otherwise, so a provider used without initialize() (unit
@@ -874,7 +932,13 @@ class PgvectorMemoryProvider(MemoryProvider):
         # embed() as its timeout, which is now ONE shared deadline across
         # embed_protocol='auto''s two HTTP attempts, not a fresh timeout for
         # each (see embed.py).
-        budget = _as_float(self._config.get("prefetch_budget"), DEFAULTS["prefetch_budget"])
+        budget = min(
+            max(
+                _as_float(self._config.get("prefetch_budget"), DEFAULTS["prefetch_budget"]),
+                _PREFETCH_BUDGET_MIN,
+            ),
+            _PREFETCH_BUDGET_MAX,
+        )
         deadline = time.monotonic() + budget
         return self._compute_prefetch_block(query, timeout=budget, deadline=deadline)
 
@@ -962,10 +1026,14 @@ class PgvectorMemoryProvider(MemoryProvider):
             rows = store.search(
                 query_embedding=vec,
                 agent_identity=self._agent_identity,
-                limit=_as_int(self._config.get("prefetch_limit"),
-                              DEFAULTS["prefetch_limit"]),
-                min_similarity=_as_float(self._config.get("min_similarity"),
-                                         DEFAULTS["min_similarity"]),
+                limit=max(_PREFETCH_LIMIT_MIN, min(
+                    _as_int(self._config.get("prefetch_limit"),
+                            DEFAULTS["prefetch_limit"]),
+                    _PREFETCH_LIMIT_MAX)),
+                min_similarity=max(_MIN_SIMILARITY_MIN, min(
+                    _as_float(self._config.get("min_similarity"),
+                              DEFAULTS["min_similarity"]),
+                    _MIN_SIMILARITY_MAX)),
             )
         except Exception as exc:  # noqa: BLE001
             logger.debug("pgvector prefetch query failed: %s", exc)
@@ -1090,12 +1158,20 @@ class PgvectorMemoryProvider(MemoryProvider):
         Guarded import, matching how this module already reaches for
         `agent.memory_provider` / `hermes_constants`: outside hermes-agent the
         content is simply used as-is.
+
+        When the host helper is present but returns None/empty (a bare
+        `/skill` with no user instruction) the host skips sync_turn()
+        entirely, so this returns "" -- callers must treat that as "nothing
+        to store" rather than falling back to the multi-KB skill body.
         """
         try:
             from agent.skill_commands import (
                 extract_user_instruction_from_skill_message as _strip,
             )
-            return _strip(content) or content
+        except Exception:  # noqa: BLE001 -- host internals are optional
+            return content
+        try:
+            return _strip(content) or ""
         except Exception:  # noqa: BLE001 -- host internals are optional
             return content
 
@@ -1178,6 +1254,19 @@ class PgvectorMemoryProvider(MemoryProvider):
             return
         try:
             child_identity = kwargs.get("child_identity") or kwargs.get("agent_identity")
+            if isinstance(child_identity, str) and child_identity:
+                # Same governance initialize() applies to this agent's own
+                # identity; a raw value would bypass the allow-list/aliases/
+                # bench isolation. Upstream does not pass this today
+                # (tools/delegate_tool_results.py), so None stays None.
+                child_identity, _, _ = normalize_identity(
+                    child_identity,
+                    allowed_themes=_as_theme_list(self._config.get("allowed_themes")),
+                    aliases=_as_alias_map(self._config.get("identity_aliases")),
+                    bench_mode=self._config.get("bench_mode", "bucket"),
+                )
+            else:
+                child_identity = None
             child_session_id = kwargs.get("child_session_id") or kwargs.get("session_id")
             self._writer.enqueue(
                 action="edge",
@@ -1265,23 +1354,20 @@ class PgvectorMemoryProvider(MemoryProvider):
                     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)
-                    )
+                    # The host flattens every role with the same helper
+                    # before sync_turn(), so do the same for a matching hash.
+                    content = _flatten_user_content(msg.get("content") or "")
+                    # Normalize user turns the way the host does: a /skill
+                    # turn reaches sync_turn() as just the user's instruction
+                    # (and not at all for a bare /skill). Noise-check, dedup
+                    # and STORE that same string, never the skill body.
+                    if role == "user":
+                        content = self._strip_skill_scaffolding(content)
+                        if not content:
+                            continue
                     if self._is_noise(content, min_chars=min_chars):
                         continue
-                    # Fingerprint the NORMALIZED form for user turns, so a
-                    # /skill turn matches what sync_turn() was handed.
-                    fp_content = (
-                        self._strip_skill_scaffolding(content)
-                        if role == "user" else content
-                    )
-                    fp = self._turn_fingerprint(role, fp_content)
+                    fp = self._turn_fingerprint(role, content)
                     if fp in self._turn_fingerprints:
                         continue  # already enqueued by sync_turn this session
                     accepted = self._writer.enqueue(
@@ -1866,18 +1952,39 @@ class PgvectorMemoryProvider(MemoryProvider):
         """Governance config that must bust a cached gateway agent when it
         changes. Upstream calls this on an UNINITIALIZED instance on every
         inbound message (agent.memory_provider.MemoryProvider.identity_signature),
-        so it reads self._config only -- no I/O, no self._store, cheap and
-        read-only. allowed_themes/identity_aliases/bench_mode decide which
+        and the gateway memoises ONE provider per process, so self._config
+        (frozen at register()) would never reflect an edit. Instead the values
+        come from config.yaml, memoised on (path, st_mtime_ns, st_size) -- one
+        stat per call, a re-parse only when the file changed (same pattern as
+        upstream's Honcho provider). self._config is never mutated and is the
+        fallback on any stat/parse failure. No self._store, never raises.
+        allowed_themes/identity_aliases/bench_mode decide which
         theme a raw identity normalizes to (identity.normalize_identity);
         write_contexts decides whether a context writes at all -- a cached
         agent built under the OLD values would keep routing/writing wrong
         until the process restarts, without this.
         """
+        try:
+            from hermes_constants import get_hermes_home
+            path = get_hermes_home() / "config.yaml"
+            stat = path.stat()
+            key = (str(path), stat.st_mtime_ns, stat.st_size)
+            memo = getattr(self, "_sig_memo", None)
+            if memo is not None and memo[0] == key:
+                return dict(memo[1])
+            values = self._signature_values({**DEFAULTS, **_load_plugin_config()})
+            self._sig_memo = (key, values)
+            return dict(values)
+        except Exception:  # noqa: BLE001 -- never raise; fall back to the frozen config
+            return self._signature_values(self._config)
+
+    @staticmethod
+    def _signature_values(config: Dict[str, Any]) -> Dict[str, Any]:
         return {
-            "pgvector.allowed_themes": _as_theme_list(self._config.get("allowed_themes")),
-            "pgvector.identity_aliases": _as_alias_map(self._config.get("identity_aliases")),
-            "pgvector.bench_mode": self._config.get("bench_mode", DEFAULTS["bench_mode"]),
-            "pgvector.write_contexts": _as_write_contexts(self._config.get("write_contexts")),
+            "pgvector.allowed_themes": _as_theme_list(config.get("allowed_themes")),
+            "pgvector.identity_aliases": _as_alias_map(config.get("identity_aliases")),
+            "pgvector.bench_mode": config.get("bench_mode", DEFAULTS["bench_mode"]),
+            "pgvector.write_contexts": _as_write_contexts(config.get("write_contexts")),
         }
 
     def get_config_schema(self) -> List[Dict[str, Any]]:
@@ -1904,7 +2011,7 @@ class PgvectorMemoryProvider(MemoryProvider):
             },
             {
                 "key": "embed_dim",
-                "description": "Vector length the embed model returns. Must also match the database's vector(N) columns (768 as created by migration 001). Changing it on an existing database requires migrating those columns and re-embedding every row -- see README, 'Changing the embedding dimension'.",
+                "description": "Vector length the embed model returns. Must also match the database's vector(N) columns (768 as created by migration 001). Changing it on an existing database requires migrating those columns and re-embedding every row -- see docs/upgrading.md, 'Changing the embedding dimension'.",
                 "type": "integer",
                 "default": DEFAULTS["embed_dim"],
                 "minimum": 1,
@@ -1927,16 +2034,16 @@ class PgvectorMemoryProvider(MemoryProvider):
                 "description": "Max ambient recall results injected per turn",
                 "type": "integer",
                 "default": DEFAULTS["prefetch_limit"],
-                "minimum": 1,
-                "maximum": 50,
+                "minimum": _PREFETCH_LIMIT_MIN,
+                "maximum": _PREFETCH_LIMIT_MAX,
             },
             {
                 "key": "min_similarity",
                 "description": "Cosine similarity cutoff for ambient prefetch",
                 "type": "number",
                 "default": DEFAULTS["min_similarity"],
-                "minimum": 0.0,
-                "maximum": 1.0,
+                "minimum": _MIN_SIMILARITY_MIN,
+                "maximum": _MIN_SIMILARITY_MAX,
             },
             {
                 "key": "embed_on_write",
@@ -2062,8 +2169,8 @@ class PgvectorMemoryProvider(MemoryProvider):
                 "description": "Hard wall-clock budget (seconds) for prefetch()'s synchronous fallback path (embed + search), used when queue_prefetch() has not already cached a block for the session. Must stay below the host's external-provider prefetch timeout (8s), or the host logs a timeout warning and skips this provider on later turns until the stuck call returns.",
                 "type": "number",
                 "default": DEFAULTS["prefetch_budget"],
-                "minimum": 0.1,
-                "maximum": 7.5,
+                "minimum": _PREFETCH_BUDGET_MIN,
+                "maximum": _PREFETCH_BUDGET_MAX,
             },
         ]
 
@@ -2137,6 +2244,16 @@ class PgvectorMemoryProvider(MemoryProvider):
                 logger.warning("pgvector embed failed (degrading to text-only): %s", exc)
                 self._embed_warned = True
             return None
+        except Exception as exc:  # noqa: BLE001 -- an embed-side bug must never drop a durable row
+            # Not an endpoint failure but a bug: never hide it behind the
+            # one-shot EmbeddingError warning (a transient outage earlier
+            # would otherwise silence it); warn once per exception type.
+            kind = type(exc).__name__
+            warned = self.__dict__.setdefault("_embed_bug_warned", set())
+            if kind not in warned:
+                warned.add(kind)
+                logger.warning("pgvector embed raised unexpectedly (degrading to text-only)", exc_info=exc)
+            return None
 
 
 # ---------------------------------------------------------------------------