atmem 2.3.7b2__tar.gz → 2.3.8__tar.gz

{atmem-2.3.7b2/atmem.egg-info → atmem-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atmem
-Version: 2.3.7b2
+Version: 2.3.8
 Summary: Host-neutral Agent Black Box and reversible memory control plane.
 Author-email: Javad Taghia <taghia.javad@gmail.com>
 Maintainer-email: Aetna / AtMem <aetna000@gmail.com>
@@ -25,16 +25,23 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: atmem-atbot==0.1.0
-Requires-Dist: atflows==0.1.2
+Requires-Dist: atflows==0.1.4b3
 Requires-Dist: cryptography<49,>=42
 Provides-Extra: atflows
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: numpy<3,>=1.26; extra == "dev"
+Requires-Dist: PyYAML<7,>=6; extra == "dev"
+Requires-Dist: jsonschema<5,>=4.23; extra == "dev"
+Requires-Dist: certifi>=2024.2.2; extra == "dev"
+Requires-Dist: loguru<1,>=0.7; extra == "dev"
 Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
 Provides-Extra: semantic
 Requires-Dist: sentence-transformers<6.0.0,>=5.0.0; extra == "semantic"
 Provides-Extra: semantic-accelerated
 Requires-Dist: numpy<3,>=1.26; extra == "semantic-accelerated"
+Provides-Extra: encrypted
+Requires-Dist: sqlcipher3==0.6.2; extra == "encrypted"
 Provides-Extra: mem0
 Requires-Dist: mem0ai<3,>=2.0.20; extra == "mem0"
 Provides-Extra: langgraph-provider
@@ -79,12 +86,17 @@ Dynamic: license-file
 
 # AtMem
 
-[![Version 2.3.7b2](https://img.shields.io/badge/version-2.3.7b2-blue)](./docs/releases/v2.3.7b2.md)
+[![Version 2.3.8](https://img.shields.io/badge/version-2.3.8-blue)](./docs/releases/v2.3.8.md)
 [![CI](https://github.com/aetna000/atmem/actions/workflows/ci.yml/badge.svg)](https://github.com/aetna000/atmem/actions/workflows/ci.yml)
 
 **AtMem is a host-neutral Agent Black Box and reversible memory control plane.**
 
-> **Release status:** AtMem 2.3.6 remains the stable release. AtMem 2.3.7b2 is a Windows concurrency and durability prerelease; see its [release note](./docs/releases/v2.3.7b2.md). The stable [memory-integrity benchmark](./docs/benchmarks/memory-integrity.md) remains unchanged. AtFlows telemetry and read-only review leads remain separate and explicit.
+> **AtMem 2.3.8:** Source-linked typed context, bounded evidence packing and
+> one-command Hermes setup extend the existing governed continuity surface. The
+> exact AtFlows companion is 0.1.4b3. See the [release note](./docs/releases/v2.3.8.md),
+> [technical report](./docs/releases/v2.3.7-to-v2.3.8-technical-report.md), and
+> [bounded evaluation evidence](./benchmarks/retrieval_quality/reports/five-percent-results-20261010.md).
+> Previous benchmarks retain their tested-version provenance.
 > It records exact host-observed text and supported multimodal boundaries by default,
 > while keeping every claim limited to what the connected agent actually supplied.
 
@@ -101,7 +113,7 @@ authorizes, stores, scopes, injects, corrects, and deletes memory.
 ### 1. Install AtMem and choose memory intelligence
 
 ```bash
-python -m pip install --upgrade atmem==2.3.6
+python -m pip install --upgrade atmem==2.3.8
 atmem atbot setup
 atmem atbot doctor
 atmem init
@@ -114,7 +126,26 @@ always-present local vector index. Do **not** install AtBot separately. During
 hosted provider, or the safe deterministic fallback. API keys stay in
 environment variables; AtMem does not save them.
 
-In 2.3.7b2, `pip install atmem` installs the Python packages only; pip does not
+For encrypted local households, install the SQLCipher extra and verify the
+runtime before migration:
+
+```bash
+# Ubuntu/Debian first: sudo apt-get install libsqlcipher-dev build-essential
+# Then install with the system SQLCipher headers and library:
+CFLAGS="-I/usr/include/sqlcipher" LDFLAGS="-lsqlcipher" \
+  python -m pip install --upgrade 'atmem[encrypted]'
+
+# macOS and Windows can install the extra directly:
+python -m pip install --upgrade 'atmem[encrypted]'
+atmem household status ~/.atmem/memories.db
+atmem household migrate ~/.atmem/memories.db
+```
+
+Stop every writer before migration. AtMem validates SQLite integrity,
+SQLCipher page integrity and per-table row counts before the atomic cutover;
+see [SaaS integration and recovery](docs/saas-integration.md#privacy-retention-and-deletion).
+
+In 2.3.8, `pip install atmem` installs the Python packages only; pip does not
 run a post-install downloader. On the first `atmem init`, if compatible Bun is not
 already installed, AtMem clearly announces and downloads its pinned official
 Bun runtime for AtFlows, verifies the archive against a release-pinned SHA-256,
@@ -143,7 +174,7 @@ package yourself.
 Already using AtMem 2.1 with OpenClaw? Upgrade in place:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.6
+python -m pip install --upgrade atmem==2.3.8
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -166,7 +197,7 @@ selected by `python`, rather than an unrelated `pip` executable on `PATH`.
 #### Pydantic AI — native capability
 
 ```bash
-python -m pip install 'atmem[pydantic-ai]==2.3.6'
+python -m pip install 'atmem[pydantic-ai]==2.3.8'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -191,7 +222,7 @@ agent = Agent("openai:gpt-5-mini", capabilities=[memory])
 #### LangChain/LangGraph — native middleware
 
 ```bash
-python -m pip install 'atmem[langgraph]==2.3.6'
+python -m pip install 'atmem[langgraph]==2.3.8'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -359,7 +390,7 @@ and restores it exactly.
 ## Installation details
 
 ```bash
-python -m pip install atmem==2.3.6
+python -m pip install atmem==2.3.8
 atmem --version
 ```
 
@@ -369,7 +400,7 @@ embedding model, while the semantic extra adds local sentence-transformer
 choices:
 
 ```bash
-python -m pip install 'atmem[semantic]==2.3.6'
+python -m pip install 'atmem[semantic]==2.3.8'
 ```
 
 For repository development, install both workspace packages:
@@ -478,7 +509,7 @@ evidence, activate AtMem, and return it to shadow.
 ## Dashboard
 
 ```bash
-atmem dashboard daemon start   # http://127.0.0.1:8766/
+atmem dashboard daemon start   # http://127.0.0.1:8768/ on a new install; existing daemon ports are preserved
 atmem dashboard daemon open
 atmem dashboard daemon status
 atmem dashboard daemon restart
@@ -557,7 +588,7 @@ atmem control restore
 Existing 2.1 installations upgrade without starting a new migration:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.6
+python -m pip install --upgrade atmem==2.3.8
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -689,7 +720,7 @@ atmem mcp --db ~/.atmem/memories.db --subject user-1
 ```
 
 MCP tools: `memory_remember`, `memory_observe`, `memory_recall`,
-`memory_recall_decision`,
+`memory_recall_decision`, `memory_form_episode`,
 `memory_get_record`, `memory_get_source`, `memory_recall_block`,
 `memory_persona`, `memory_context_pack`, `memory_capture`, `memory_list`,
 `memory_forget`, `memory_forget_artifact`, `memory_promote`, `memory_audit`,
@@ -790,10 +821,11 @@ npm test
 npm run smoke
 ```
 
-The latest stable release is **2.3.6** with matching OpenClaw bridge source
-**2.3.6**. Release validation requires exact Python/bridge alignment; AtBot
-retains its independent stable compatible version **0.1.0** and AtFlows remains
-**0.1.2**.
+The current source candidate is **2.3.8** with matching OpenClaw bridge source
+**2.3.8**. Release validation requires exact Python/bridge alignment; AtBot
+retains its independent compatible version **0.1.0** and the tested AtFlows pin
+is **0.1.4b3**. The published package remains 2.3.7 until the candidate is
+reviewed, tagged and registry-verified.
 
 ## License
 

{atmem-2.3.7b2 → atmem-2.3.8}/README.md

@@ -1,11 +1,16 @@
 # AtMem
 
-[![Version 2.3.7b2](https://img.shields.io/badge/version-2.3.7b2-blue)](./docs/releases/v2.3.7b2.md)
+[![Version 2.3.8](https://img.shields.io/badge/version-2.3.8-blue)](./docs/releases/v2.3.8.md)
 [![CI](https://github.com/aetna000/atmem/actions/workflows/ci.yml/badge.svg)](https://github.com/aetna000/atmem/actions/workflows/ci.yml)
 
 **AtMem is a host-neutral Agent Black Box and reversible memory control plane.**
 
-> **Release status:** AtMem 2.3.6 remains the stable release. AtMem 2.3.7b2 is a Windows concurrency and durability prerelease; see its [release note](./docs/releases/v2.3.7b2.md). The stable [memory-integrity benchmark](./docs/benchmarks/memory-integrity.md) remains unchanged. AtFlows telemetry and read-only review leads remain separate and explicit.
+> **AtMem 2.3.8:** Source-linked typed context, bounded evidence packing and
+> one-command Hermes setup extend the existing governed continuity surface. The
+> exact AtFlows companion is 0.1.4b3. See the [release note](./docs/releases/v2.3.8.md),
+> [technical report](./docs/releases/v2.3.7-to-v2.3.8-technical-report.md), and
+> [bounded evaluation evidence](./benchmarks/retrieval_quality/reports/five-percent-results-20261010.md).
+> Previous benchmarks retain their tested-version provenance.
 > It records exact host-observed text and supported multimodal boundaries by default,
 > while keeping every claim limited to what the connected agent actually supplied.
 
@@ -22,7 +27,7 @@ authorizes, stores, scopes, injects, corrects, and deletes memory.
 ### 1. Install AtMem and choose memory intelligence
 
 ```bash
-python -m pip install --upgrade atmem==2.3.6
+python -m pip install --upgrade atmem==2.3.8
 atmem atbot setup
 atmem atbot doctor
 atmem init
@@ -35,7 +40,26 @@ always-present local vector index. Do **not** install AtBot separately. During
 hosted provider, or the safe deterministic fallback. API keys stay in
 environment variables; AtMem does not save them.
 
-In 2.3.7b2, `pip install atmem` installs the Python packages only; pip does not
+For encrypted local households, install the SQLCipher extra and verify the
+runtime before migration:
+
+```bash
+# Ubuntu/Debian first: sudo apt-get install libsqlcipher-dev build-essential
+# Then install with the system SQLCipher headers and library:
+CFLAGS="-I/usr/include/sqlcipher" LDFLAGS="-lsqlcipher" \
+  python -m pip install --upgrade 'atmem[encrypted]'
+
+# macOS and Windows can install the extra directly:
+python -m pip install --upgrade 'atmem[encrypted]'
+atmem household status ~/.atmem/memories.db
+atmem household migrate ~/.atmem/memories.db
+```
+
+Stop every writer before migration. AtMem validates SQLite integrity,
+SQLCipher page integrity and per-table row counts before the atomic cutover;
+see [SaaS integration and recovery](docs/saas-integration.md#privacy-retention-and-deletion).
+
+In 2.3.8, `pip install atmem` installs the Python packages only; pip does not
 run a post-install downloader. On the first `atmem init`, if compatible Bun is not
 already installed, AtMem clearly announces and downloads its pinned official
 Bun runtime for AtFlows, verifies the archive against a release-pinned SHA-256,
@@ -64,7 +88,7 @@ package yourself.
 Already using AtMem 2.1 with OpenClaw? Upgrade in place:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.6
+python -m pip install --upgrade atmem==2.3.8
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -87,7 +111,7 @@ selected by `python`, rather than an unrelated `pip` executable on `PATH`.
 #### Pydantic AI — native capability
 
 ```bash
-python -m pip install 'atmem[pydantic-ai]==2.3.6'
+python -m pip install 'atmem[pydantic-ai]==2.3.8'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -112,7 +136,7 @@ agent = Agent("openai:gpt-5-mini", capabilities=[memory])
 #### LangChain/LangGraph — native middleware
 
 ```bash
-python -m pip install 'atmem[langgraph]==2.3.6'
+python -m pip install 'atmem[langgraph]==2.3.8'
 atmem control shadow --host generic --memory-db ~/.atmem/memories.db
 ```
 
@@ -280,7 +304,7 @@ and restores it exactly.
 ## Installation details
 
 ```bash
-python -m pip install atmem==2.3.6
+python -m pip install atmem==2.3.8
 atmem --version
 ```
 
@@ -290,7 +314,7 @@ embedding model, while the semantic extra adds local sentence-transformer
 choices:
 
 ```bash
-python -m pip install 'atmem[semantic]==2.3.6'
+python -m pip install 'atmem[semantic]==2.3.8'
 ```
 
 For repository development, install both workspace packages:
@@ -399,7 +423,7 @@ evidence, activate AtMem, and return it to shadow.
 ## Dashboard
 
 ```bash
-atmem dashboard daemon start   # http://127.0.0.1:8766/
+atmem dashboard daemon start   # http://127.0.0.1:8768/ on a new install; existing daemon ports are preserved
 atmem dashboard daemon open
 atmem dashboard daemon status
 atmem dashboard daemon restart
@@ -478,7 +502,7 @@ atmem control restore
 Existing 2.1 installations upgrade without starting a new migration:
 
 ```bash
-python -m pip install --upgrade atmem==2.3.6
+python -m pip install --upgrade atmem==2.3.8
 atmem openclaw upgrade
 atmem control verify
 ```
@@ -610,7 +634,7 @@ atmem mcp --db ~/.atmem/memories.db --subject user-1
 ```
 
 MCP tools: `memory_remember`, `memory_observe`, `memory_recall`,
-`memory_recall_decision`,
+`memory_recall_decision`, `memory_form_episode`,
 `memory_get_record`, `memory_get_source`, `memory_recall_block`,
 `memory_persona`, `memory_context_pack`, `memory_capture`, `memory_list`,
 `memory_forget`, `memory_forget_artifact`, `memory_promote`, `memory_audit`,
@@ -711,10 +735,11 @@ npm test
 npm run smoke
 ```
 
-The latest stable release is **2.3.6** with matching OpenClaw bridge source
-**2.3.6**. Release validation requires exact Python/bridge alignment; AtBot
-retains its independent stable compatible version **0.1.0** and AtFlows remains
-**0.1.2**.
+The current source candidate is **2.3.8** with matching OpenClaw bridge source
+**2.3.8**. Release validation requires exact Python/bridge alignment; AtBot
+retains its independent compatible version **0.1.0** and the tested AtFlows pin
+is **0.1.4b3**. The published package remains 2.3.7 until the candidate is
+reviewed, tagged and registry-verified.
 
 ## License
 

atmem-2.3.8/atmem/adapters/hermes/__init__.py

@@ -0,0 +1,5 @@
+"""Product-owned Hermes memory binding; does not import the Hermes runtime."""
+
+from .binding import HermesMemoryBinding, RecallResult
+
+__all__ = ["HermesMemoryBinding", "RecallResult"]

atmem-2.3.8/atmem/adapters/hermes/assets/plugin_entry.py

@@ -0,0 +1,85 @@
+"""AtMem Hermes directory plugin; the host needs no AtMem Python dependency."""
+import json
+import os
+from pathlib import Path
+import stat
+
+from .client import HermesRPCClient
+from .provider import create_provider
+
+
+def _private_read(path, limit):
+    if os.name == "nt":
+        raise RuntimeError("native Windows credential ACL qualification is pending; use a qualified WSL installation")
+    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | os.O_NONBLOCK)
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+            raise PermissionError("Hermes connection files must be owner-only regular files")
+        value = os.read(descriptor, limit + 1)
+        if len(value) > limit:
+            raise ValueError("Hermes connection file exceeds its size limit")
+        return value.decode("utf-8")
+    finally:
+        os.close(descriptor)
+
+
+SETUP_HINT = ("AtMem local CLI preview: connection is unavailable. "
+              "Run atmem hermes status --hermes-home PATH for this profile. "
+              "Installation alone does not activate memory; keep the current provider selected.")
+
+
+def _unavailable_provider():
+    from agent.memory_provider import MemoryProvider
+
+    class UnconfiguredAtMem(MemoryProvider):
+        name = "atmem"
+
+        def is_available(self):
+            return False
+
+        def unavailable_reason(self):
+            return SETUP_HINT
+
+        def initialize(self, session_id, **kwargs):
+            raise RuntimeError(SETUP_HINT)
+
+        def get_tool_schemas(self):
+            return []
+
+        def post_setup(self, hermes_home, config):
+            print(SETUP_HINT)
+
+        def get_status_config(self, config=None):
+            return {"available": False, "platform": "local CLI only", "setup": SETUP_HINT}
+
+    return UnconfiguredAtMem()
+
+
+def _configured_provider():
+    home = Path(__file__).resolve().parents[2]
+    private = home / ".atmem"
+    if private.is_symlink():
+        raise PermissionError("Hermes connection directory cannot be a symbolic link")
+    info = private.stat()
+    if info.st_uid != os.getuid() or info.st_mode & 0o077:
+        raise PermissionError("Hermes connection directory must be owner-only")
+    config = json.loads(_private_read(private / "connection.json", 16384))
+    if not isinstance(config, dict):
+        raise ValueError("invalid connection")
+    if config.get("format") != "atmem-hermes-connection-v1":
+        raise ValueError("unsupported AtMem Hermes connection")
+    if Path(config["hermes_home"]).resolve() != home:
+        raise PermissionError("AtMem connection belongs to another Hermes profile")
+    client = HermesRPCClient(config["endpoint"], _private_read(private / "credential", 256).strip(),
+                             profile_id=config["profile_id"], user_id=config.get("user_id"), timeout=10.0)
+    return create_provider(client, hermes_home=str(home))
+
+
+def register(ctx):
+    try:
+        provider = _configured_provider() if os.name != "nt" else _unavailable_provider()
+    except Exception:
+        # Discovery must remain possible, but never echo credential/config data.
+        provider = _unavailable_provider()
+    ctx.register_memory_provider(provider)

atmem-2.3.8/atmem/adapters/hermes/binding.py

@@ -0,0 +1,215 @@
+"""Fresh-recall authorization using the ordinary AtMem control plane.
+
+This is the trusted service-side binding, not an HTTP authentication boundary.
+The installer/service supplies identity; model tool arguments cannot change it.
+It deliberately makes no claim about replayed Hermes conversation history.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+import hashlib
+from typing import Any
+
+from atmem.adapters.base import AtMemAdapterIdentity
+from atmem.core.canonical import canonical_json
+from atmem.service import APIError, APIPrincipal, AtMemApplication
+
+
+PROFILE = "authorized-at-recall-v1"
+
+
+def _identifier(value: str, name: str) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > 512:
+        raise ValueError(f"{name} must be a nonempty identifier of at most 512 characters")
+    if any(ord(char) < 32 for char in value):
+        raise ValueError(f"{name} contains a control character")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class RecallResult:
+    context: str
+    reason: str
+    candidate_ids: tuple[str, ...] = ()
+    exposure_id: str | None = None
+    context_receipt_id: str | None = None
+    profile: str = PROFILE
+
+
+class HermesMemoryBinding:
+    """One immutable administrator-selected identity, checked on each operation.
+
+    Constructed inactive. Enabling the binding does not activate the control
+    plane: both this explicit selection and AtMem's own active policy are needed.
+    No query/context cache is retained. Background scheduling belongs to the host
+    bridge; these methods return only after the product operation has finished.
+    """
+
+    def __init__(self, manager: Any, identity: AtMemAdapterIdentity, *,
+                 profile_id: str, enabled: bool = False, influence: bool | None = None,
+                 max_context_chars: int = 4096):
+        self.manager = manager
+        self.identity = replace(identity, framework="hermes")
+        self.profile_id = _identifier(profile_id, "profile_id")
+        for name in ("agent_id", "workspace_id", "subject_id"):
+            _identifier(getattr(identity, name), name)
+        if not identity.authenticated_user:
+            raise PermissionError("Hermes binding requires an authenticated operator identity")
+        if isinstance(max_context_chars, bool) or not isinstance(max_context_chars, int) or not 1 <= max_context_chars <= 4096:
+            raise ValueError("max_context_chars must be between 1 and 4096")
+        self.enabled = bool(enabled)
+        self.influence = self.enabled if influence is None else bool(influence)
+        self.max_context_chars = max_context_chars
+        self.application = AtMemApplication(manager)
+
+    def _scope(self) -> None:
+        """Topology, not request content, binds agent/subject/workspace."""
+        authority = getattr(self.manager, "authority_topology", None)
+        topology = authority() if callable(authority) else self.manager.agent_topology()
+        workspaces = topology.get("workspaces", [])
+        match = any(
+            row.get("workspace_id") == self.identity.workspace_id
+            and row.get("subject_id") == self.identity.subject_id
+            and self.identity.agent_id in (row.get("agent_ids") or [])
+            for row in workspaces
+        )
+        subject_rows = [row for row in workspaces if row.get("subject_id") == self.identity.subject_id]
+        agent_rows = [row for row in workspaces if self.identity.agent_id in (row.get("agent_ids") or [])]
+        if not match or len(subject_rows) != 1 or len(agent_rows) != 1:
+            raise PermissionError("Hermes binding no longer matches AtMem topology")
+
+    def _session(self, session_id: str) -> str:
+        value = [_identifier(self.profile_id, "profile_id"), _identifier(session_id, "session_id")]
+        return "hermes_" + hashlib.sha256(canonical_json(value).encode()).hexdigest()
+
+    def _run_id(self, session_id: str, turn_id: str) -> str:
+        session = self._session(session_id)
+        turn = _identifier(str(turn_id), "turn_id")
+        return "hermes_run_" + hashlib.sha256(
+            canonical_json([self.profile_id, session, turn]).encode()
+        ).hexdigest()
+
+    def record_event(self, event_type: str, *, session_id: str, turn_id: str,
+                     payload: dict[str, Any], context_event_id: str | None = None,
+                     context_receipt_id: str | None = None,
+                     retrieval_id: str | None = None,
+                     event_time: str | None = None) -> dict[str, Any] | None:
+        """Project a local Hermes turn into AtMem's ordinary session evidence."""
+        recorder = getattr(self.manager, "record_blackbox_event", None)
+        if not callable(recorder):
+            return None
+        session = self._session(session_id)
+        turn = _identifier(str(turn_id), "turn_id")
+        run_id = self._run_id(session_id, turn)
+        order = {
+            "turn.input": 1,
+            "context.disposition": 2,
+            "model.input": 3,
+            "model.output": 4,
+            "turn.ended": 5,
+        }
+        sequence = order.get(event_type)
+        if sequence is None:
+            raise ValueError("unsupported Hermes lifecycle event")
+        stable_event_id = "hermes_event_" + hashlib.sha256(
+            canonical_json([self.profile_id, session, turn, event_type]).encode()
+        ).hexdigest()
+        observed_at = event_time or datetime.now(timezone.utc).isoformat(
+            timespec="milliseconds"
+        ).replace("+00:00", "Z")
+        return recorder(
+            event_type=event_type, run_id=run_id, session_id=session,
+            turn_id=turn, agent_id=self.identity.agent_id,
+            workspace_id=self.identity.workspace_id,
+            subject_id=self.identity.subject_id,
+            context_event_id=context_event_id,
+            context_receipt_id=context_receipt_id,
+            retrieval_id=retrieval_id,
+            event_id=stable_event_id,
+            producer_instance_id=f"hermes:{self.profile_id}",
+            producer_epoch=run_id,
+            producer_sequence=sequence,
+            event_time=observed_at,
+            payload={key: value for key, value in payload.items() if value is not None},
+        )
+
+    def recall(self, query: str, *, session_id: str, turn_id: str) -> RecallResult:
+        if not self.enabled:
+            return RecallResult("", "inactive")
+        if not self.influence:
+            return RecallResult("", "withheld")
+        if not isinstance(query, str) or not query.strip() or len(query) > 65536:
+            return RecallResult("", "invalid_query")
+        try:
+            self._scope()
+            session = self._session(session_id)
+            turn = _identifier(turn_id, "turn_id")
+            run_id = self._run_id(session_id, turn)
+            prepared = self.manager.prepare(
+                query, allow_delegation=False, session_id=session,
+                host_run_id=run_id, turn_id=turn,
+                workspace_id=self.identity.workspace_id,
+                subject_id=self.identity.subject_id, agent_id=self.identity.agent_id,
+                max_chars=self.max_context_chars,
+                deterministic=True,
+            )
+            if not prepared.get("inject"):
+                # Shadow previews must never be returned as active context.
+                return RecallResult("", "withheld")
+            context = prepared.get("context")
+            if not isinstance(context, str) or not context:
+                return RecallResult("", "no_context")
+            if len(context) > self.max_context_chars:
+                return RecallResult("", "context_limit")
+            # Only fresh canonical preparation can supply bytes. Do not fall
+            # back to a previous successful recall if this operation fails.
+            return RecallResult(
+                context, "authorized",
+                tuple(str(value) for value in prepared.get("candidate_ids", [])),
+                prepared.get("exposure_id"), prepared.get("context_receipt_id"),
+            )
+        except (OSError, RuntimeError, ValueError, TypeError, PermissionError):
+            # Never disclose exception details (paths/queries/provider secrets)
+            # in a model-facing result. No successful-delivery receipt is made.
+            return RecallResult("", "unavailable_or_denied")
+
+    def observe_user(self, text: str, *, session_id: str, observation_id: str) -> dict[str, Any]:
+        """Persist an authenticated user's source via ordinary governed capture.
+
+        Assistant summaries and tool output are not authenticated user messages;
+        the host bridge must not feed them to this method as such.
+        """
+        if not self.enabled:
+            return {"captured": False, "reason": "inactive"}
+        self._scope()
+        if not isinstance(text, str) or not text.strip() or len(text) > 65536:
+            raise ValueError("user text must contain 1–65536 characters")
+        session = self._session(session_id)
+        observation = _identifier(observation_id, "observation_id")
+        key = hashlib.sha256(canonical_json([session, observation]).encode()).hexdigest()
+        principal = APIPrincipal(
+            principal_id=self.profile_id, role="agent",
+            subject_id=str(self.identity.subject_id), agent_id=self.identity.agent_id,
+            workspace_id=self.identity.workspace_id,
+        )
+        try:
+            return self.application.create_memory(
+                principal, text, idempotency_key=key, session_id=session,
+            )
+        except APIError:
+            raise
+        except Exception:
+            raise APIError("observation_uncertain", "inspect the observation receipt before retrying", status=409) from None
+
+    def status(self) -> dict[str, Any]:
+        return {
+            "profile": PROFILE, "enabled": self.enabled,
+            "mode": "active" if self.enabled and self.influence else
+                    "shadow" if self.enabled else "inactive",
+            "profile_id": self.profile_id, "agent_id": self.identity.agent_id,
+            "workspace_id": self.identity.workspace_id,
+            "capture_coverage": "memory_operations_only",
+            "per_model_call_revalidation": False,
+            "previous_context_retraction": False,
+        }