Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(hermes): mirror native memory replacements and removals (#5281)

z1gonc2c6407314e1
diff --git a/examples/hermes-plugin/DEVELOPMENT.md b/examples/hermes-plugin/DEVELOPMENT.md
index b3889ab9e..a8b0ca89d 100644
--- a/examples/hermes-plugin/DEVELOPMENT.md
+++ b/examples/hermes-plugin/DEVELOPMENT.md
@@ -23,6 +23,14 @@ The active-session commit lifecycle was ported from
with the original author retained. The OpenViking adaptation uses a configurable
pending-token threshold instead of the original six-turn trigger.
+Native memory mirroring is adapted from
+[Hermes PR #100187](https://github.com/NousResearch/hermes-agent/pull/100187),
+commit `32f75a9e6728a9a3d2f50a870dab3715a1f34fd7`, which continues
+[austinlaw076's PR #85860](https://github.com/NousResearch/hermes-agent/pull/85860).
+The external plugin uses relative imports and Hermes's context-preserving worker
+helper. Its connection cache and session-commit lifecycle retain the later
+OpenViking fixes.
+
Gateway sender attribution and recall scope adapt
[Hermes PR #105812](https://github.com/NousResearch/hermes-agent/pull/105812),
including liuhao1024's capture change from
@@ -54,8 +62,17 @@ install or package the OpenViking server.
## Validation
-Use a Hermes checkout with its development dependencies installed. From that
-checkout, run its canonical test runner against this directory:
+Use a Hermes checkout with its development dependencies installed.
+
+The complete mirror tests require the committed-entry event contract introduced
+in [Hermes PR #118903](https://github.com/NousResearch/hermes-agent/pull/118903)
+and merged through [#120003](https://github.com/NousResearch/hermes-agent/pull/120003)
+(commit `5908e1aaa83e82aaf12541d7a9d90762d0b46a64`):
+`MemoryManager` forwards `previous_content` for each successful replace/remove.
+The legacy compatibility tests verify that missing metadata skips these remote
+mutations. Do not substitute a guessed match in tests or production.
+
+From that checkout, run its canonical test runner against this directory:
```bash
PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" HERMES_TEST_FILE_RETRIES=0 \
@@ -66,14 +83,20 @@ PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" HERMES_TEST_FILE_RETRIES=0 \
`--confcutdir` keeps pytest from importing the plugin as a test package before
Hermes loads it under its own namespace. The tests use temporary profile homes
and remove bundled-provider discovery.
-They check external loading across profiles, HTTP tool dispatch, and cancelled
-setup without changing existing configuration. Gateway tests use mock events
-through Hermes's turn hooks and memory manager. They cover sender changes,
-capture retries, commits, recall scopes, compression fallback, and missing
-sender metadata. Setup tests cover both presets, confirmation, cancellation,
-profile-local persistence, connection routes, and actual Hermes session keys.
-Run the upstream OpenViking
-provider tests in Hermes as well when changing provider behavior:
+They cover external loading, profile isolation, setup, tools, session commits,
+and native memory mirroring. The mirror suite includes ordered writes, restart
+continuity, registry failures, connection isolation, and concurrent workers.
+Gateway tests use mock events through Hermes's turn hooks and memory manager.
+They cover sender changes, capture retries, commits, recall scopes, compression
+fallback, and missing sender metadata. Setup tests cover both presets,
+confirmation, cancellation, profile-local persistence, connection routes, and
+actual Hermes session keys.
+Provider-specific regression tests belong here and must use the shared external
+loader fixture. Generic Hermes framework tests remain in Hermes.
+
+For compatibility checks while Hermes still bundles OpenViking, also run its
+provider tests. These load the bundled copy unless explicitly routed through the
+external loader; they do not replace this directory's tests:
```bash
HERMES_TEST_FILE_RETRIES=0 scripts/run_tests.sh \
diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.md
index 2580163c0..28f74b407 100644
--- a/examples/hermes-plugin/README.md
+++ b/examples/hermes-plugin/README.md
@@ -275,17 +275,55 @@ OpenViking server auto-commit is disabled by default, so an accepted message
whose explicit commit fails normally remains live and unextracted until it is
manually committed.
-Hermes built-in `memory` tool additions are mirrored to OpenViking after the
-local memory operation succeeds:
+Successful Hermes built-in `memory` mutations are mirrored to OpenViking in
+order. The active profile records each mirrored entry's exact URI in
+`$HERMES_HOME/openviking/memory_mirror_registry.json`:
| Hermes action | OpenViking operation |
|---------------|----------------------|
-| `add` | `content/write` with `mode=create` under user memory, or the configured peer memory directory |
-
-Built-in `replace` and `remove` operations are not mirrored because Hermes
-native memory entries do not yet carry stable OpenViking file URIs. Use
-`viking_forget` when the user explicitly asks to delete a specific OpenViking
-memory URI.
+| `add` | Create a file under user memory or the configured peer, then record its URI |
+| `replace` | Match the committed event's full previous content and target, update the same URI, and wait for semantic/vector refresh |
+| `remove` | Match the committed event's full previous content and target, delete that exact URI, and wait for semantic cleanup |
+
+Replacing a mapped entry recreates its file if it was deleted directly in
+OpenViking, for example with `viking_forget`.
+
+The registry stores the current entry text and a connection fingerprint, not
+the raw API key. Endpoint, credentials, user, account, and peer changes isolate
+the new connection from earlier mappings. New files require a server-confirmed
+user identity. Missing or ambiguous mappings block replacement and deletion
+with a warning; the plugin never selects a target by semantic similarity.
+
+Replacement and deletion require Hermes to provide authoritative
+`previous_content` metadata from the native-store commit. Older Hermes versions
+without this event contract skip those mirror operations with a warning; native
+local memory still changes. The plugin never falls back to matching the caller's
+`old_text` against its partial registry.
+The required event contract was merged in
+[Hermes PR #120003](https://github.com/NousResearch/hermes-agent/pull/120003)
+(commit `5908e1aaa83e82aaf12541d7a9d90762d0b46a64`), which landed
+[#118903](https://github.com/NousResearch/hermes-agent/pull/118903).
+
+Only entries created by this mirror have mappings. Session-extracted memories,
+explicit `viking_remember` results, and copies created before this registry are
+outside its scope. Use `viking_forget` with an exact URI to remove those copies.
+
+The mirror is asynchronous. Hermes saves its local memory first. Rejected remote
+writes leave the registry unchanged and produce a warning. Additions do not wait
+for indexing, so the mirror does not report later indexing failures. For `replace`,
+if the server reports that the file changed but indexing failed, the registry
+retains the new content and exact URI; a warning reports the indexing failure
+because search results may be stale. There is no durable replay. A remote mutation
+followed by a failed registry save can also cause drift. Operations are ordered
+per provider; registry updates are serialized across instances sharing a profile
+in one process, not across processes.
+
+Registry files use mode `0600` on POSIX. Protect the profile with normal account
+and filesystem permissions on Windows. An unreadable, invalid, or unsupported
+registry blocks all mirror writes. Stop Hermes before restoring a valid backup.
+For an unsupported version, use a plugin version that supports it. Renaming a
+damaged registry starts a new registry but leaves earlier remote copies without
+mappings; those copies need manual cleanup by exact URI.
`viking_forget` is intentionally narrow. It only accepts concrete user memory
file URIs, such as
diff --git a/examples/hermes-plugin/__init__.py b/examples/hermes-plugin/__init__.py
index e3d286f0f..710980b0f 100644
--- a/examples/hermes-plugin/__init__.py
+++ b/examples/hermes-plugin/__init__.py
@@ -69,6 +69,7 @@ _REMOTE_RESOURCE_PREFIXES = ("http://", "https://", "git@", "ssh://", "git://")
_SYNC_TRACE_ENV = "HERMES_OPENVIKING_SYNC_TRACE"
_RECALL_QUERY_MIN_CHARS = 5
_RECALL_MIN_TIMEOUT_SECONDS = 0.05
+_DEFAULT_RECALL_REQUEST_TIMEOUT_SECONDS = 3.0
_READ_BATCH_LIMIT = 3
_READ_BATCH_FULL_LIMIT = 2500
_LEVEL_ENDPOINTS = {"abstract": "/api/v1/content/abstract", "overview": "/api/v1/content/overview", "full": "/api/v1/content/read"}
@@ -105,7 +106,7 @@ _CONFIG_SCHEMA = [
_cfg_field("recall_max_injected_chars", "Maximum total characters injected by recall", type="integer", minimum=100, maximum=50000, default=4000),
_cfg_field("profile_token_budget", "Maximum session-start memory tokens injected", type="integer", minimum=500, maximum=50000, default=6000),
_cfg_field("recall_timeout_seconds", "Total timeout for recall (seconds)", **_NUM, default=4.0),
- _cfg_field("recall_request_timeout_seconds", "Per-request timeout for recall (seconds)", **_NUM, default=3.0),
+ _cfg_field("recall_request_timeout_seconds", "Per-request timeout for recall (seconds)", **_NUM, default=_DEFAULT_RECALL_REQUEST_TIMEOUT_SECONDS),
_cfg_field("recall_full_read_limit", "Max full L2 content reads per recall", type="integer", minimum=0, maximum=100, default=2),
_cfg_field("recall_prefer_abstract", "Use abstracts instead of full L2 reads", type="boolean", default=False),
_cfg_field("recall_resources", "Include resources in recall", type="boolean", default=False),
@@ -1295,7 +1296,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
# _failed_refresh = (settings key, monotonic ts) of the last failure -> cooldown gate.
self._session_state_lock = threading.RLock()
(self._inflight_lock, self._deferred_commit_lock, self._committed_session_lock,
- self._client_refresh_lock, self._runtime_start_lock, self._memory_write_lock,
+ self._client_refresh_lock, self._runtime_start_lock, self._native_memory_mirror_lock,
self._writer_commit_lock) = (threading.Lock() for _ in range(7))
# Writers keyed by the sid they POST under so a commit can drain all of them.
# Guards the (_session_id, _turn_count) pair. sync_turn runs on the MemoryManager's background sync
@@ -1305,7 +1306,6 @@ class OpenVikingMemoryProvider(MemoryProvider):
self._inflight_writers: Dict[str, Set[threading.Thread]] = {}
self._deferred_commit_threads: Set[threading.Thread] = set()
self._commit_scope: Optional[_CommitScope] = None
- self._memory_write_threads: Set[threading.Thread] = set()
self._profile_prefetched_sessions: Set[str] = set()
self._conn_snapshot: Optional[tuple] = None
self._failed_refresh: Optional[tuple] = None
@@ -1949,7 +1949,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
tail = cls._take_tokens("\n".join(lines[8:]), remaining - cls._token_units(head), from_end=True).lstrip()
return f"{head}{marker}{tail}" if tail else _head_only()
- def _user_space(self, client=None, *, timeout: Optional[float] = None) -> str:
+ def _user_space(self, client=None, *, timeout: Optional[float] = None, require_confirmed: bool = False) -> str:
"""Resolve the user space, caching only a confirmed connection identity.
Use the client's snapshot even when a reload has replaced the active connection.
@@ -1964,6 +1964,11 @@ class OpenVikingMemoryProvider(MemoryProvider):
if snapshot is not None:
self._user_space_cache = (snapshot, resolved)
return resolved
+ if require_confirmed:
+ raise RuntimeError(
+ "OpenViking server did not confirm the current user identity; "
+ "leaving OpenViking unchanged"
+ )
return str(getattr(active, "_user", "") or getattr(self, "_user", "") or "default").strip() or "default"
@staticmethod
@@ -2690,7 +2695,14 @@ class OpenVikingMemoryProvider(MemoryProvider):
# -- memory mirroring -----------------------------------------------------
- def _build_memory_uri(self, subdir: str, *, client=None, timeout: Optional[float] = None) -> str:
+ def _build_memory_uri(
+ self,
+ subdir: str,
+ *,
+ client=None,
+ timeout: Optional[float] = None,
+ require_confirmed_user: bool = False,
+ ) -> str:
"""Explicit-uid user memory URI, under the configured peer when one is set.
The peer is read from the captured client (not the provider) so a config
@@ -2702,11 +2714,27 @@ class OpenVikingMemoryProvider(MemoryProvider):
active_client = client if client is not None else getattr(self, "_client", None)
agent = str(getattr(active_client, "_agent", getattr(self, "_agent", "")) or "").strip()
peer_prefix = f"peers/{agent}/" if agent else ""
- return f"viking://user/{self._user_space(active_client, timeout=timeout)}/{peer_prefix}memories/{subdir}/mem_{uuid.uuid4().hex[:12]}.md"
-
- def on_memory_write(self, action: str, target: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> None:
- """Mirror successful built-in memory additions to OpenViking."""
- if action != "add" or not content or not self._ensure_client():
+ identity_timeout = timeout
+ if require_confirmed_user and identity_timeout is None:
+ identity_timeout = _DEFAULT_RECALL_REQUEST_TIMEOUT_SECONDS
+ user_space = self._user_space(
+ active_client,
+ timeout=identity_timeout,
+ require_confirmed=require_confirmed_user,
+ )
+ return f"viking://user/{user_space}/{peer_prefix}memories/{subdir}/mem_{uuid.uuid4().hex[:12]}.md"
+
+ def on_memory_write(
+ self,
+ action: str,
+ target: str,
+ content: str,
+ metadata: Optional[Dict[str, Any]] = None,
+ ) -> None:
+ """Mirror successful built-in memory mutations to OpenViking."""
+ if action not in {"add", "replace", "remove"} or not self._ensure_client():
+ return
+ if action in {"add", "replace"} and not content:
return
subdir = _MEMORY_WRITE_TARGET_SUBDIR_MAP.get(target, "preferences")
try:
@@ -2715,15 +2743,17 @@ class OpenVikingMemoryProvider(MemoryProvider):
logger.debug("OpenViking memory mirror client creation failed: %s", e)
return
- def _write():
- try:
- uri = self._build_memory_uri(subdir, client=client, timeout=_RECALL_MIN_TIMEOUT_SECONDS)
- client.post("/api/v1/content/write", {"uri": uri, "content": content, "mode": "create"})
- except Exception as e:
- logger.debug("OpenViking memory mirror failed: %s", e)
+ from .native_memory_mirror import enqueue_native_memory_write
- self._spawn_tracked("openviking-memwrite", _write, self._memory_write_lock, lambda: self._memory_write_threads,
- skip_if=lambda: self._shutting_down)
+ enqueue_native_memory_write(
+ self,
+ action,
+ target,
+ content,
+ metadata=metadata,
+ subdir=subdir,
+ client=client,
+ )
# -- tools ------------------------------------------------------------------
@@ -2746,10 +2776,12 @@ class OpenVikingMemoryProvider(MemoryProvider):
# the autostart waiter (a daemon blocked on health probes would SIGABRT CPython at
# Py_FinalizeEx); _shutting_down makes its wait loop bail so the join lands.
self._shutting_down = True
+ from .native_memory_mirror import shutdown_native_memory_mirror
+
+ shutdown_native_memory_mirror(self, timeout=5.0)
workers: List[threading.Thread] = []
for lock, group in ((self._inflight_lock, lambda: [t for g in self._inflight_writers.values() for t in g]),
(self._deferred_commit_lock, lambda: list(self._deferred_commit_threads)),
- (self._memory_write_lock, lambda: list(self._memory_write_threads)),
(self._runtime_start_lock, lambda: [self._runtime_start_thread] if self._runtime_start_thread is not None else [])):
with lock:
workers += group()
diff --git a/examples/hermes-plugin/native_memory_mirror.py b/examples/hermes-plugin/native_memory_mirror.py
new file mode 100644
index 000000000..e5b9ec38e
--- /dev/null
+++ b/examples/hermes-plugin/native_memory_mirror.py
@@ -0,0 +1,387 @@
+"""Stable mirroring for Hermes native MEMORY.md / USER.md entries.
+
+Hermes' built-in memory tool selects entries by text and reports their full
+previous content after a committed write. OpenViking needs an exact ``viking://``
+file URI to update or delete a memory safely. This module keeps the identity map
+in a small profile-scoped registry and serializes mirror operations through one
+FIFO worker.
+
+The registry is intentionally narrow: it tracks only memories created through
+the built-in-memory mirror. Session-extracted memories and explicit
+``viking_remember`` writes are outside its ownership and are never guessed at or
+deleted by similarity.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import queue
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from agent.memory_provider import spawn_context_thread
+from utils import atomic_json_write
+
+logger = logging.getLogger("plugins.memory.openviking")
+
+_REGISTRY_VERSION = 2
+_REGISTRY_RELATIVE_PATH = Path("openviking") / "memory_mirror_registry.json"
+_SUPPORTED_ACTIONS = frozenset({"add", "replace", "remove"})
+_POLL_SECONDS = 0.05
+_REGISTRY_LOCKS_GUARD = threading.Lock()
+_REGISTRY_LOCKS: Dict[Path, threading.Lock] = {}
+
+
+class _MappingError(RuntimeError):
+ """A destructive mirror operation could not resolve one exact URI."""
+
+
+def _registry_lock(path: Path) -> threading.Lock:
+ """Return one process-wide lock for a profile mirror registry."""
+ key = path.resolve(strict=False)
+ with _REGISTRY_LOCKS_GUARD:
+ lock = _REGISTRY_LOCKS.get(key)
+ if lock is None:
+ lock = threading.Lock()
+ _REGISTRY_LOCKS[key] = lock
+ return lock
+
+
+def _connection_fingerprint(client: Any) -> str:
+ """Identify the captured OpenViking connection without storing its key."""
+ identity = [
+ str(getattr(client, "_endpoint", "") or "").rstrip("/"),
+ str(getattr(client, "_api_key", "") or ""),
+ str(getattr(client, "_account", "") or ""),
+ str(getattr(client, "_user", "") or ""),
+ str(getattr(client, "_agent", "") or ""),
+ ]
+ encoded = json.dumps(identity, ensure_ascii=True, separators=(",", ":")).encode()
+ return hashlib.sha256(encoded).hexdigest()
+
+
+class NativeMemoryMirror:
+ """FIFO, profile-scoped mirror of Hermes native memory into OpenViking."""
+
+ def __init__(self, provider: Any):
+ self._provider = provider
+ self._queue: queue.Queue[Dict[str, Any]] = queue.Queue()
+ self._state_lock = threading.Lock()
+ self._worker: Optional[threading.Thread] = None
+ self._shutting_down = False
+
+ def enqueue(
+ self,
+ action: str,
+ target: str,
+ content: str,
+ *,
+ metadata: Optional[Dict[str, Any]] = None,
+ subdir: str,
+ client: Any,
+ ) -> None:
+ """Queue one committed built-in-memory mutation in call order."""
+ if action not in _SUPPORTED_ACTIONS:
+ return
+ normalized_content = str(content or "").strip()
+ if action in {"add", "replace"} and not normalized_content:
+ return
+
+ event = {
+ "action": action,
+ "target": str(target or "memory"),
+ # The native MemoryStore strips content before it commits. Mirror
+ # the committed value rather than the raw tool argument.
+ "content": normalized_content,
+ "metadata": dict(metadata or {}),
+ "subdir": str(subdir),
+ "client": client,
+ "connection": _connection_fingerprint(client),
+ }
+
+ with self._state_lock:
+ if self._shutting_down:
+ logger.warning(
+ "OpenViking memory mirror skipped %s during provider shutdown",
+ action,
+ )
+ return
+ self._queue.put(event)
+ if self._worker is None or not self._worker.is_alive():
+ self._worker = spawn_context_thread(
+ self._run,
+ daemon=True,
+ name="openviking-memory-mirror",
+ )
+ self._worker.start()
+
+ def shutdown(self, timeout: float = 5.0) -> None:
+ """Drain queued mirror operations, then stop the FIFO worker."""
+ with self._state_lock:
+ self._shutting_down = True
+ worker = self._worker
+
+ if worker is None:
+ return
+
+ deadline = time.monotonic() + max(0.0, timeout)
+ while self._queue.unfinished_tasks and time.monotonic() < deadline:
+ time.sleep(0.01)
+
+ remaining = max(0.0, deadline - time.monotonic())
+ if worker.is_alive() and remaining:
+ worker.join(timeout=remaining)
+ if worker.is_alive():
+ logger.warning("OpenViking memory mirror worker did not drain before shutdown")
+
+ def _run(self) -> None:
+ while True:
+ with self._state_lock:
+ stopping = self._shutting_down
+ if stopping and self._queue.empty():
+ return
+
+ try:
+ event = self._queue.get(timeout=_POLL_SECONDS)
+ except queue.Empty:
+ continue
+
+ try:
+ self._apply(event)
+ except _MappingError as exc:
+ logger.warning("OpenViking memory mirror skipped: %s", exc)
+ except Exception as exc:
+ logger.warning("OpenViking memory mirror failed: %s", exc)
+ finally:
+ self._queue.task_done()
+
+ def _registry_path(self) -> Path:
+ root = str(getattr(self._provider, "_hermes_home", "") or "").strip()
+ if not root:
+ from hermes_constants import get_hermes_home
+
+ root = str(get_hermes_home())
+ return Path(root) / _REGISTRY_RELATIVE_PATH
+
+ def _load_registry(self, path: Path) -> Dict[str, Any]:
+ if not path.exists():
+ return {"version": _REGISTRY_VERSION, "entries": []}
+
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except Exception as exc:
+ raise RuntimeError(f"cannot read mirror registry {path}: {exc}") from exc
+
+ if not isinstance(payload, dict):
+ raise RuntimeError(f"invalid mirror registry format: expected a JSON object: {path}")
+
+ if "version" not in payload:
+ raise RuntimeError(f"invalid mirror registry format: missing version: {path}")
+ found_version = payload["version"]
+ if found_version != _REGISTRY_VERSION:
+ raise RuntimeError(
+ "unsupported mirror registry version "
+ f"{found_version!r}: expected {_REGISTRY_VERSION}: {path}"
+ )
+ entries = payload.get("entries")
+ if not isinstance(entries, list):
+ raise RuntimeError(f"invalid mirror registry entries: {path}")
+
+ for entry in entries:
+ if not isinstance(entry, dict):
+ raise RuntimeError(f"invalid mirror registry entry: {path}")
+ if not all(
+ isinstance(entry.get(key), str)
+ for key in ("connection", "target", "uri", "content")
+ ):
+ raise RuntimeError(f"invalid mirror registry entry fields: {path}")
+ return payload
+
+ @staticmethod
+ def _save_registry(path: Path, registry: Dict[str, Any]) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ atomic_json_write(path, registry, mode=0o600)
+
+ @staticmethod
+ def _resolve_mapping(
+ registry: Dict[str, Any],
+ *,
+ connection: str,
+ target: str,
+ previous_content: Any,
+ action: str,
+ ) -> tuple[int, Dict[str, str]]:
+ if not isinstance(previous_content, str) or not previous_content:
+ raise _MappingError(
+ f"{action} requires authoritative previous_content from Hermes; "
+ "upgrade Hermes to a version with committed-entry metadata; "
+ "leaving OpenViking unchanged"
+ )
+
+ matches = [
+ (index, entry)
+ for index, entry in enumerate(registry["entries"])
+ if entry["connection"] == connection
+ and entry["target"] == target
+ and previous_content == entry["content"]
+ ]
+ if not matches:
+ raise _MappingError(
+ f"{action} has no stable OpenViking URI mapping for target={target!r}; "
+ "leaving OpenViking unchanged"
+ )
+ if len(matches) != 1:
+ raise _MappingError(
+ f"{action} matched {len(matches)} OpenViking URI mappings for "
+ f"target={target!r}; leaving OpenViking unchanged"
+ )
+ return matches[0]
+
+ @staticmethod
+ def _warn_failed_indexing(result: Dict[str, Any], uri: str) -> None:
+ failed = [
+ name for name in ("semantic_status", "vector_status") if result.get(name) == "failed"
+ ]
+ if failed:
+ logger.warning(
+ "OpenViking memory file updated at %s, but indexing failed (%s); "
+ "search results may be stale. The URI mapping was retained.",
+ uri,
+ ", ".join(failed),
+ )
+
+ def _apply(self, event: Dict[str, Any]) -> None:
+ path = self._registry_path()
+ # Provider instances can share one profile and registry. Keep the
+ # complete remote-mutation + registry-update sequence atomic in this
+ # process so concurrent read-modify-write cycles cannot lose mappings.
+ with _registry_lock(path):
+ self._apply_locked(path, event)
+
+ def _apply_locked(self, path: Path, event: Dict[str, Any]) -> None:
+ action = event["action"]
+ target = event["target"]
+ content = event["content"]
+ metadata = event["metadata"]
+ connection = event["connection"]
+ registry = self._load_registry(path)
+ client = event["client"]
+
+ if action == "add":
+ # The native store treats exact duplicate adds as idempotent. Mirror
+ # the same way if a duplicate notification ever reaches us.
+ if any(
+ entry["connection"] == connection
+ and entry["target"] == target
+ and entry["content"] == content
+ for entry in registry["entries"]
+ ):
+ return
+
+ requested_uri = self._provider._build_memory_uri(
+ event["subdir"],
+ client=client,
+ require_confirmed_user=True,
+ )
+ response = client.post(
+ "/api/v1/content/write",
+ {"uri": requested_uri, "content": content, "mode": "create"},
+ )
+ result = response.get("result", {}) if isinstance(response, dict) else {}
+ if isinstance(result, dict) and result.get("content_updated") is False:
+ raise RuntimeError("OpenViking memory file was not updated")
+ canonical_uri = (
+ str(result.get("uri") or "").strip() if isinstance(result, dict) else ""
+ ) or requested_uri
+ registry["entries"].append(
+ {
+ "connection": connection,
+ "target": target,
+ "uri": canonical_uri,
+ "content": content,
+ }
+ )
+ self._save_registry(path, registry)
+ return
+
+ index, mapping = self._resolve_mapping(
+ registry,
+ connection=connection,
+ target=target,
+ previous_content=metadata.get("previous_content"),
+ action=action,
+ )
+ uri = mapping["uri"]
+
+ if action == "replace":
+ response = client.post(
+ "/api/v1/content/write",
+ {"uri": uri, "content": content, "mode": "replace", "wait": True},
+ )
+ result = response.get("result", {}) if isinstance(response, dict) else {}
+ if isinstance(result, dict) and result.get("content_updated") is False:
+ raise RuntimeError("OpenViking memory file was not updated")
+ registry["entries"][index] = {
+ "connection": connection,
+ "target": target,
+ "uri": uri,
+ "content": content,
+ }
+ self._save_registry(path, registry)
+ if isinstance(result, dict):
+ self._warn_failed_indexing(result, uri)
+ return
+
+ client.delete(
+ "/api/v1/fs",
+ params={"uri": uri, "recursive": False, "wait": True},
+ )
+ registry["entries"].pop(index)
+ self._save_registry(path, registry)
+
+
+_MIRROR_ATTR = "_native_memory_mirror"
+
+
+def enqueue_native_memory_write(
+ provider: Any,
+ action: str,
+ target: str,
+ content: str,
+ *,
+ metadata: Optional[Dict[str, Any]] = None,
+ subdir: str,
+ client: Any,
+) -> None:
+ """Lazily create the provider's FIFO mirror and enqueue one operation."""
+ with provider._native_memory_mirror_lock:
+ if provider._shutting_down:
+ logger.warning(
+ "OpenViking memory mirror skipped %s during provider shutdown",
+ action,
+ )
+ return
+ mirror = getattr(provider, _MIRROR_ATTR, None)
+ if mirror is None:
+ mirror = NativeMemoryMirror(provider)
+ setattr(provider, _MIRROR_ATTR, mirror)
+ mirror.enqueue(
+ action,
+ target,
+ content,
+ metadata=metadata,
+ subdir=subdir,
+ client=client,
+ )
+
+
+def shutdown_native_memory_mirror(provider: Any, timeout: float = 5.0) -> None:
+ """Drain the provider's native-memory mirror if it was ever used."""
+ with provider._native_memory_mirror_lock:
+ mirror = getattr(provider, _MIRROR_ATTR, None)
+ if mirror is not None:
+ mirror.shutdown(timeout=timeout)
diff --git a/examples/hermes-plugin/tests/test_native_memory_bridge.py b/examples/hermes-plugin/tests/test_native_memory_bridge.py
new file mode 100644
index 000000000..dc1f652f9
--- /dev/null
+++ b/examples/hermes-plugin/tests/test_native_memory_bridge.py
@@ -0,0 +1,207 @@
+"""Native store commits reach the external plugin with exact entry identity."""
+
+import json
+import time
+from contextlib import contextmanager
+
+import pytest
+
+
+class _Client:
+ _endpoint, _api_key, _account, _user, _agent = "http://test", "", "test", "alice", ""
+
+ def __init__(self):
+ self.files = {}
+ self.requests = []
+ self.refresh_failure = None
+
+ def get(self, path, **kwargs):
+ return {"result": {"user": self._user}}
+
+ def post(self, path, payload):
+ self.requests.append(("write", dict(payload)))
+ self.files[payload["uri"]] = payload["content"]
+ result = {
+ "uri": payload["uri"],
+ "content_updated": True,
+ "semantic_status": "skipped",
+ "vector_status": "complete",
+ }
+ if self.refresh_failure:
+ result[self.refresh_failure] = "failed"
+ return {"status": "ok", "result": result}
+
+ def delete(self, path, *, params):
+ self.requests.append(("delete", dict(params)))
+ del self.files[params["uri"]]
+ return {"status": "ok", "result": {"uri": params["uri"]}}
+
+
+def _drain(provider):
+ mirror = getattr(provider, "_native_memory_mirror", None)
+ deadline = time.monotonic() + 3
+ while mirror and mirror._queue.unfinished_tasks:
+ assert time.monotonic() < deadline, "Mirror worker did not drain"
+ time.sleep(0.01)
+
+
+@contextmanager
+def _bridge(external_provider):
+ from agent.memory_manager import MemoryManager
+ from hermes_constants import reset_hermes_home_override, set_hermes_home_override
+ from tools.memory_tool import MemoryStore, memory_tool
+
+ home, provider, _, _ = external_provider("native-bridge")
+ provider._hermes_home = str(home)
+ client = _Client()
+ provider._ensure_client = provider._new_client = lambda: client
+ token = set_hermes_home_override(home)
+ store = MemoryStore()
+ store.load_from_disk()
+ manager = MemoryManager()
+ manager.add_provider(provider)
+
+ def invoke(*operations, batch=False, mirror=True):
+ args = {"target": "user", **({"operations": list(operations)} if batch else operations[0])}
+ result = memory_tool(store=store, **args)
+ if mirror:
+ manager.notify_memory_tool_write(result, args)
+ _drain(provider)
+ return json.loads(result)
+
+ try:
+ yield home, provider, client, store, invoke
+ finally:
+ provider.shutdown()
+ reset_hermes_home_override(token)
+
+
[email protected]("mapped", [False, True])
[email protected]("batch", [False, True])
[email protected]("action", ["remove", "replace"])
+def test_native_exact_entry_does_not_mutate_its_longer_sibling(
+ external_provider, mapped, batch, action
+):
+ with _bridge(external_provider) as (_, _, client, store, invoke):
+ assert invoke({"action": "add", "content": "Prefers tea"}, mirror=mapped)["success"]
+ exact_uri = next(iter(client.files), None)
+ assert invoke({"action": "add", "content": "Prefers tea with milk"})["success"]
+ expected = dict(client.files)
+ operation = {"action": action, "old_text": "Prefers tea"}
+ if action == "replace":
+ operation["new_text"] = "Prefers coffee"
+ if mapped:
+ expected[exact_uri] = "Prefers coffee"
+ elif mapped:
+ del expected[exact_uri]
+ assert invoke(operation, batch=batch)["success"]
+ assert store.user_entries == (
+ ["Prefers coffee", "Prefers tea with milk"]
+ if action == "replace"
+ else ["Prefers tea with milk"]
+ )
+ assert client.files == expected
+
+
+def test_committed_batch_mirrors_each_intermediate_entry_in_order(external_provider):
+ with _bridge(external_provider) as (home, _, client, store, invoke):
+ assert invoke(
+ {"action": "add", "content": "Prefers tea"},
+ {"action": "replace", "old_text": "tea", "new_text": "Prefers coffee"},
+ {"action": "remove", "old_text": "coffee"},
+ batch=True,
+ )["success"]
+ assert store.user_entries == []
+ assert client.files == {}
+ assert [(method, body.get("mode")) for method, body in client.requests] == [
+ ("write", "create"),
+ ("write", "replace"),
+ ("delete", None),
+ ]
+ assert len({body["uri"] for _, body in client.requests}) == 1
+ assert (
+ json.loads((home / "openviking/memory_mirror_registry.json").read_text())["entries"]
+ == []
+ )
+
+
[email protected]("failure", ["missing_entry", "over_budget", "disk_write"])
+def test_uncommitted_batch_has_no_remote_effect(external_provider, monkeypatch, failure):
+ with _bridge(external_provider) as (home, provider, client, store, invoke):
+ assert invoke({"action": "add", "content": "Keep this entry"}, mirror=False)["success"]
+ before = store._path_for("user").read_bytes()
+ operations = [
+ {"action": "add", "content": "Prefers tea"},
+ {"action": "replace", "old_text": "tea", "content": "Prefers coffee"},
+ ]
+ if failure == "missing_entry":
+ operations.append({"action": "remove", "old_text": "Absent entry"})
+ elif failure == "over_budget":
+ operations.append({"action": "add", "content": "x" * 2000})
+ else:
+
+ def fail_write(*_args):
+ raise OSError("disk unavailable")
+
+ monkeypatch.setattr(store, "_write_file", fail_write)
+ if failure == "disk_write":
+ with pytest.raises(OSError, match="disk unavailable"):
+ invoke(*operations, batch=True)
+ else:
+ assert not invoke(*operations, batch=True)["success"]
+ assert client.requests == []
+ assert not getattr(provider, "_native_memory_mirror", None)
+ assert not (home / "openviking/memory_mirror_registry.json").exists()
+ assert store._path_for("user").read_bytes() == before
+
+
[email protected]("action", ["replace", "remove"])
[email protected]("old_text", ["Prefers tea", "tea"])
+def test_legacy_notifications_never_guess_entry_identity(
+ external_provider, caplog, action, old_text
+):
+ with _bridge(external_provider) as (home, provider, client, _, invoke):
+ assert invoke({"action": "add", "content": "Prefers tea"})["success"]
+ path = home / "openviking/memory_mirror_registry.json"
+ before = path.read_bytes()
+ remote_before = dict(client.files)
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write(
+ action, "user", "Prefers coffee", metadata={"old_text": old_text}
+ )
+ _drain(provider)
+ assert client.files == remote_before
+ assert path.read_bytes() == before
+ assert any("authoritative previous_content" in record.message for record in caplog.records)
+
+
[email protected]("failed_status", ["vector_status", "semantic_status"])
+def test_index_failure_preserves_mapping_for_next_replace_and_remove(
+ external_provider, caplog, failed_status
+):
+ with _bridge(external_provider) as (home, _, client, _, invoke):
+ assert invoke({"action": "add", "content": "Prefers tea"})["success"]
+ uri = next(iter(client.files))
+ client.refresh_failure = failed_status
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ assert invoke({"action": "replace", "old_text": "tea", "content": "Prefers coffee"})[
+ "success"
+ ]
+ path = home / "openviking/memory_mirror_registry.json"
+ entry = json.loads(path.read_text())["entries"][0]
+ assert entry["uri"] == uri
+ assert entry["content"] == client.files[uri] == "Prefers coffee"
+ assert any(
+ uri in record.message
+ and "indexing failed" in record.message
+ and failed_status in record.message
+ for record in caplog.records
+ )
+ client.refresh_failure = None
+ assert invoke({"action": "replace", "old_text": "coffee", "content": "Prefers water"})[
+ "success"
+ ]
+ assert client.files == {uri: "Prefers water"}
+ assert invoke({"action": "remove", "old_text": "water"})["success"]
+ assert client.files == {}
+ assert json.loads(path.read_text())["entries"] == []
diff --git a/examples/hermes-plugin/tests/test_native_memory_mirror.py b/examples/hermes-plugin/tests/test_native_memory_mirror.py
new file mode 100644
index 000000000..ae2f69c1e
--- /dev/null
+++ b/examples/hermes-plugin/tests/test_native_memory_mirror.py
@@ -0,0 +1,610 @@
+"""Native memory mirror regressions ported from Hermes PR #100187.
+
+Providers and sibling modules are loaded from the external plugin directory.
+"""
+
+import importlib
+import json
+import threading
+import time
+from types import SimpleNamespace
+
+import pytest
+
+
+class _FakeVikingClient:
+ def __init__(
+ self,
+ *,
+ endpoint: str = "http://openviking.test",
+ api_key: str = "test-key",
+ account: str = "default",
+ user: str = "default",
+ agent: str = "hermes",
+ fail_post: bool = False,
+ fail_delete: bool = False,
+ ):
+ self._lock = threading.Lock()
+ self.calls = []
+ self.fail_post = fail_post
+ self.fail_delete = fail_delete
+ self._endpoint = endpoint
+ self._api_key = api_key
+ self._account = account
+ self._user = user
+ self._agent = agent
+
+ def post(self, path, payload=None, **kwargs):
+ with self._lock:
+ self.calls.append(("post", path, dict(payload or {}), dict(kwargs)))
+ if self.fail_post:
+ raise RuntimeError("mirror write failed")
+ if path == "/api/v1/content/write":
+ return {
+ "status": "ok",
+ "result": {
+ "uri": (payload or {}).get("uri", ""),
+ "written_bytes": len((payload or {}).get("content", "")),
+ },
+ }
+ return {"status": "ok", "result": {}}
+
+ def get(self, path, params=None, **kwargs):
+ if path == "/api/v1/system/status":
+ return {"status": "ok", "result": {"user": "default"}}
+ return {"status": "ok", "result": {}}
+
+ def delete(self, path, **kwargs):
+ with self._lock:
+ self.calls.append(("delete", path, None, dict(kwargs)))
+ if self.fail_delete:
+ raise RuntimeError("mirror delete failed")
+ return {
+ "status": "ok",
+ "result": {"uri": kwargs.get("params", {}).get("uri", "")},
+ }
+
+ def snapshot(self):
+ with self._lock:
+ return list(self.calls)
+
+
+def mirror(external_provider):
+ home, _, module, _ = external_provider("mirror")
+ mirror_type = importlib.import_module(
+ module.__name__ + ".native_memory_mirror"
+ ).NativeMemoryMirror
+
+ def provider(client):
+ _, instance, _, _ = external_provider("mirror")
+ instance._hermes_home = str(home)
+ instance._agent = "hermes"
+ instance._client = client
+ instance._ensure_client = lambda: client
+ instance._new_client = lambda: client
+ return instance
+
+ return SimpleNamespace(home=home, provider=provider, mirror_type=mirror_type)
+
+
+def _wait_for(predicate, *, timeout=2.0):
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ if predicate():
+ return
+ time.sleep(0.01)
+ pytest.fail("timed out waiting for OpenViking mirror worker")
+
+
+def _registry_path(home):
+ return home / "openviking" / "memory_mirror_registry.json"
+
+
+def test_replace_updates_the_same_openviking_uri_and_registry(mirror):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ provider.on_memory_write("add", "user", " Preferred provider is DeepInfra ")
+ _wait_for(lambda: len(client.snapshot()) == 1)
+ create = client.snapshot()[0]
+ uri = create[2]["uri"]
+ assert create[2]["content"] == "Preferred provider is DeepInfra"
+
+ provider.on_memory_write(
+ "replace",
+ "user",
+ "Preferred provider is OpenRouter",
+ metadata={"old_text": "DeepInfra", "previous_content": "Preferred provider is DeepInfra"},
+ )
+ _wait_for(lambda: len(client.snapshot()) == 2)
+
+ replace = client.snapshot()[1]
+ assert replace[0:2] == ("post", "/api/v1/content/write")
+ assert replace[2]["uri"] == uri
+ assert replace[2]["content"] == "Preferred provider is OpenRouter"
+ assert replace[2]["mode"] == "replace"
+ assert replace[2]["wait"] is True
+
+ _wait_for(
+ lambda: (
+ json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))["entries"][0][
+ "content"
+ ]
+ == "Preferred provider is OpenRouter"
+ )
+ )
+ registry = json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))
+ connection = registry["entries"][0]["connection"]
+ assert len(connection) == 64
+ assert registry == {
+ "version": 2,
+ "entries": [
+ {
+ "connection": connection,
+ "target": "user",
+ "uri": uri,
+ "content": "Preferred provider is OpenRouter",
+ }
+ ],
+ }
+ provider.shutdown()
+
+
+def test_add_requires_server_confirmed_user_without_fallback(mirror, caplog):
+ client = _FakeVikingClient(user="configured-fallback")
+
+ def fail_identity_probe(path, params=None, **kwargs):
+ assert path == "/api/v1/system/status"
+ raise TimeoutError("identity probe timed out")
+
+ client.get = fail_identity_probe
+ provider = mirror.provider(client)
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write("add", "user", "Do not misroute this memory")
+ provider.shutdown()
+
+ assert client.snapshot() == []
+ assert not _registry_path(mirror.home).exists()
+ assert any(
+ "did not confirm the current user identity" in record.message for record in caplog.records
+ )
+
+
+def test_add_identity_probe_uses_normal_request_timeout(mirror):
+ client = _FakeVikingClient()
+ identity_probe_kwargs = []
+
+ def record_identity_probe(path, params=None, **kwargs):
+ assert path == "/api/v1/system/status"
+ identity_probe_kwargs.append(dict(kwargs))
+ return {"status": "ok", "result": {"user": "default"}}
+
+ client.get = record_identity_probe
+ provider = mirror.provider(client)
+
+ provider.on_memory_write("add", "user", "Use the normal identity timeout")
+ _wait_for(lambda: len(client.snapshot()) == 1)
+
+ assert identity_probe_kwargs == [{"timeout": 3.0}]
+ provider.shutdown()
+
+
+def test_remove_deletes_exact_mapped_uri_and_registry_entry(mirror):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ provider.on_memory_write("add", "memory", "Project alpha is active")
+ _wait_for(lambda: len(client.snapshot()) == 1)
+ uri = client.snapshot()[0][2]["uri"]
+
+ provider.on_memory_write(
+ "remove",
+ "memory",
+ "",
+ metadata={"old_text": "alpha is active", "previous_content": "Project alpha is active"},
+ )
+ _wait_for(lambda: len(client.snapshot()) == 2)
+
+ delete = client.snapshot()[1]
+ assert delete[0:2] == ("delete", "/api/v1/fs")
+ assert delete[3]["params"] == {"uri": uri, "recursive": False, "wait": True}
+
+ _wait_for(
+ lambda: json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))["entries"] == []
+ )
+ registry = json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))
+ assert registry == {"version": 2, "entries": []}
+ provider.shutdown()
+
+
+def test_mapping_survives_provider_restart_for_true_replace(mirror):
+ client = _FakeVikingClient()
+ first = mirror.provider(client)
+
+ first.on_memory_write("add", "user", "Employment status is job seeking")
+ _wait_for(lambda: len(client.snapshot()) == 1)
+ uri = client.snapshot()[0][2]["uri"]
+ first.shutdown()
+
+ second = mirror.provider(client)
+ second.on_memory_write(
+ "replace",
+ "user",
+ "Employment status is employed",
+ metadata={
+ "old_text": "job seeking",
+ "previous_content": "Employment status is job seeking",
+ },
+ )
+ _wait_for(lambda: len(client.snapshot()) == 2)
+
+ replace = client.snapshot()[1]
+ assert replace[2]["uri"] == uri
+ assert replace[2]["mode"] == "replace"
+ assert replace[2]["wait"] is True
+ assert replace[2]["content"] == "Employment status is employed"
+ second.shutdown()
+
+
+def test_rapid_add_replace_remove_is_processed_in_fifo_order(mirror):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ provider.on_memory_write("add", "user", "Device owned: Tablet A")
+ provider.on_memory_write(
+ "replace",
+ "user",
+ "Device owned: Tablet B",
+ metadata={"old_text": "Tablet A", "previous_content": "Device owned: Tablet A"},
+ )
+ provider.on_memory_write(
+ "remove",
+ "user",
+ "",
+ metadata={"old_text": "Tablet B", "previous_content": "Device owned: Tablet B"},
+ )
+
+ _wait_for(lambda: len(client.snapshot()) == 3)
+ calls = client.snapshot()
+ uri = calls[0][2]["uri"]
+
+ assert [(call[0], call[1]) for call in calls] == [
+ ("post", "/api/v1/content/write"),
+ ("post", "/api/v1/content/write"),
+ ("delete", "/api/v1/fs"),
+ ]
+ assert calls[0][2]["mode"] == "create"
+ assert calls[1][2]["mode"] == "replace"
+ assert calls[1][2]["wait"] is True
+ assert calls[1][2]["uri"] == uri
+ assert calls[2][3]["params"] == {"uri": uri, "recursive": False, "wait": True}
+
+ provider.shutdown()
+ registry = json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))
+ assert registry == {"version": 2, "entries": []}
+
+
+def test_unmapped_replace_fails_closed_with_warning(mirror, caplog):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write(
+ "replace",
+ "user",
+ "Employment status is employed",
+ metadata={
+ "old_text": "job seeking",
+ "previous_content": "Employment status is job seeking",
+ },
+ )
+ provider.shutdown()
+
+ assert client.snapshot() == []
+ assert any("no stable OpenViking URI mapping" in record.message for record in caplog.records)
+
+
+def test_ambiguous_replace_fails_closed_without_guessing(mirror, caplog):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ provider.on_memory_write("add", "user", "Device owned: Tablet A")
+ provider.on_memory_write("add", "user", "Device owned: Tablet B")
+ _wait_for(lambda: len(client.snapshot()) == 2)
+
+ provider.on_memory_write(
+ "replace",
+ "user",
+ "Device owned: Tablet B",
+ metadata={"previous_content": "Device owned: Tablet A"},
+ )
+ _wait_for(lambda: len(client.snapshot()) == 3)
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write(
+ "replace",
+ "user",
+ "Device owned: Tablet C",
+ metadata={"old_text": "Tablet", "previous_content": "Device owned: Tablet B"},
+ )
+ provider.shutdown()
+
+ assert len(client.snapshot()) == 3
+ assert any("matched 2 OpenViking URI mappings" in record.message for record in caplog.records)
+
+
+def test_final_mirror_failure_is_visible_at_warning_level(mirror, caplog):
+ client = _FakeVikingClient(fail_post=True)
+ provider = mirror.provider(client)
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write("add", "user", "Visible failure")
+ _wait_for(lambda: len(client.snapshot()) == 1)
+ _wait_for(
+ lambda: any(
+ record.levelname == "WARNING"
+ and "OpenViking memory mirror failed" in record.message
+ for record in caplog.records
+ )
+ )
+
+ assert not _registry_path(mirror.home).exists()
+ provider.shutdown()
+
+
+ ("registry_text", "expected_warning"),
+ [
+ ("{not valid JSON", "cannot read mirror registry"),
+ ("[]", "invalid mirror registry format: expected a JSON object"),
+ (
+ json.dumps({"entries": []}),
+ "invalid mirror registry format: missing version",
+ ),
+ (
+ json.dumps({"version": 3, "entries": []}),
+ "unsupported mirror registry version 3: expected 2",
+ ),
+ ],
+)
+def test_invalid_registry_blocks_add_without_overwriting_it(
+ mirror, caplog, registry_text, expected_warning
+):
+ path = _registry_path(mirror.home)
+ path.parent.mkdir(parents=True)
+ path.write_text(registry_text, encoding="utf-8")
+ original = path.read_bytes()
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write("add", "user", "Do not orphan this memory")
+ provider.shutdown()
+
+ assert client.snapshot() == []
+ assert path.read_bytes() == original
+ assert any(expected_warning in record.message for record in caplog.records)
+
+
+def test_failed_replace_keeps_previous_registry_mapping(mirror, caplog):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+ provider.on_memory_write("add", "user", "Preferred shell is zsh")
+ _wait_for(lambda: _registry_path(mirror.home).exists())
+ previous = json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))
+ client.fail_post = True
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write(
+ "replace",
+ "user",
+ "Preferred shell is fish",
+ metadata={"old_text": "zsh", "previous_content": "Preferred shell is zsh"},
+ )
+ _wait_for(lambda: len(client.snapshot()) == 2)
+ provider.shutdown()
+
+ assert json.loads(_registry_path(mirror.home).read_text(encoding="utf-8")) == previous
+ assert any("OpenViking memory mirror failed" in record.message for record in caplog.records)
+
+
+def test_failed_remove_keeps_registry_mapping(mirror, caplog):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+ provider.on_memory_write("add", "memory", "Project delta is active")
+ _wait_for(lambda: _registry_path(mirror.home).exists())
+ previous = json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))
+ client.fail_delete = True
+
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write(
+ "remove",
+ "memory",
+ "",
+ metadata={"old_text": "delta is active", "previous_content": "Project delta is active"},
+ )
+ _wait_for(lambda: len(client.snapshot()) == 2)
+ provider.shutdown()
+
+ assert json.loads(_registry_path(mirror.home).read_text(encoding="utf-8")) == previous
+ assert any("OpenViking memory mirror failed" in record.message for record in caplog.records)
+
+
+def test_registry_save_failure_is_reported_after_remote_acceptance(mirror, caplog, monkeypatch):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+
+ def fail_save(_path, _registry):
+ raise OSError("registry disk full")
+
+ monkeypatch.setattr(
+ mirror.mirror_type,
+ "_save_registry",
+ staticmethod(fail_save),
+ )
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write("add", "user", "Remote write without mapping")
+ _wait_for(lambda: len(client.snapshot()) == 1)
+ _wait_for(lambda: any("registry disk full" in record.message for record in caplog.records))
+ provider.shutdown()
+
+ assert not _registry_path(mirror.home).exists()
+ assert client.snapshot()[0][1] == "/api/v1/content/write"
+
+
+def test_registry_mapping_is_isolated_by_connection(mirror):
+ first_client = _FakeVikingClient(api_key="key-a")
+ second_client = _FakeVikingClient(api_key="key-b")
+ first = mirror.provider(first_client)
+ second = mirror.provider(second_client)
+
+ first.on_memory_write("add", "user", "Preferred editor is Helix")
+ second.on_memory_write("add", "user", "Preferred editor is Helix")
+ _wait_for(lambda: len(first_client.snapshot()) == 1)
+ _wait_for(lambda: len(second_client.snapshot()) == 1)
+ _wait_for(
+ lambda: (
+ _registry_path(mirror.home).exists()
+ and len(json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))["entries"])
+ == 2
+ )
+ )
+
+ first_uri = first_client.snapshot()[0][2]["uri"]
+ second_uri = second_client.snapshot()[0][2]["uri"]
+ registry_text = _registry_path(mirror.home).read_text(encoding="utf-8")
+ registry = json.loads(registry_text)
+ assert len(registry["entries"]) == 2
+ assert len({entry["connection"] for entry in registry["entries"]}) == 2
+ assert "key-a" not in registry_text
+ assert "key-b" not in registry_text
+
+ first.on_memory_write(
+ "replace",
+ "user",
+ "Preferred editor is Neovim",
+ metadata={"old_text": "Helix", "previous_content": "Preferred editor is Helix"},
+ )
+ _wait_for(lambda: len(first_client.snapshot()) == 2)
+
+ replace = first_client.snapshot()[1]
+ assert replace[2]["uri"] == first_uri
+ assert replace[2]["uri"] != second_uri
+ assert len(second_client.snapshot()) == 1
+ first.shutdown()
+ second.shutdown()
+
+
+def test_provider_instances_serialize_shared_registry_updates(mirror, monkeypatch):
+ first_client = _FakeVikingClient(api_key="key-a")
+ second_client = _FakeVikingClient(api_key="key-b")
+ first = mirror.provider(first_client)
+ second = mirror.provider(second_client)
+ first_save_started = threading.Event()
+ release_first_save = threading.Event()
+ save_count = 0
+ save_count_lock = threading.Lock()
+ original_save = mirror.mirror_type._save_registry
+
+ def blocking_save(path, registry):
+ nonlocal save_count
+ with save_count_lock:
+ save_count += 1
+ is_first = save_count == 1
+ if is_first:
+ first_save_started.set()
+ assert release_first_save.wait(timeout=2.0)
+ original_save(path, registry)
+
+ monkeypatch.setattr(
+ mirror.mirror_type,
+ "_save_registry",
+ staticmethod(blocking_save),
+ )
+
+ try:
+ first.on_memory_write("add", "user", "First profile fact")
+ assert first_save_started.wait(timeout=2.0)
+
+ second.on_memory_write("add", "user", "Second profile fact")
+ time.sleep(0.05)
+ assert second_client.snapshot() == []
+
+ release_first_save.set()
+ _wait_for(lambda: len(second_client.snapshot()) == 1)
+ _wait_for(
+ lambda: (
+ len(json.loads(_registry_path(mirror.home).read_text(encoding="utf-8"))["entries"])
+ == 2
+ )
+ )
+ finally:
+ release_first_save.set()
+ first.shutdown()
+ second.shutdown()
+
+
+def test_concurrent_first_writes_share_one_mirror_worker(mirror, monkeypatch):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+ constructor_started = threading.Event()
+ release_constructor = threading.Event()
+ constructed = 0
+ constructed_lock = threading.Lock()
+ original_init = mirror.mirror_type.__init__
+
+ def blocking_init(self, owner):
+ nonlocal constructed
+ with constructed_lock:
+ constructed += 1
+ is_first = constructed == 1
+ if is_first:
+ constructor_started.set()
+ assert release_constructor.wait(timeout=2.0)
+ original_init(self, owner)
+
+ monkeypatch.setattr(mirror.mirror_type, "__init__", blocking_init)
+ first = threading.Thread(
+ target=provider.on_memory_write,
+ args=("add", "user", "First concurrent fact"),
+ )
+ second = threading.Thread(
+ target=provider.on_memory_write,
+ args=("add", "user", "Second concurrent fact"),
+ )
+
+ first.start()
+ assert constructor_started.wait(timeout=2.0)
+ second.start()
+ release_constructor.set()
+ first.join(timeout=2.0)
+ second.join(timeout=2.0)
+ _wait_for(lambda: len(client.snapshot()) == 2)
+
+ assert constructed == 1
+ provider.shutdown()
+
+
[email protected]("action", ["add", "replace"])
+def test_explicitly_unwritten_content_does_not_advance_registry(mirror, caplog, action):
+ client = _FakeVikingClient()
+ provider = mirror.provider(client)
+ path = _registry_path(mirror.home)
+ if action == "replace":
+ provider.on_memory_write("add", "user", "Prefers tea")
+ _wait_for(path.exists)
+ before = path.read_bytes() if path.exists() else None
+
+ def no_write(path, payload):
+ return {"status": "ok", "result": {"uri": payload["uri"], "content_updated": False}}
+
+ client.post = no_write
+ with caplog.at_level("WARNING", logger="plugins.memory.openviking"):
+ provider.on_memory_write(
+ action, "user", "Prefers coffee", metadata={"previous_content": "Prefers tea"}
+ )
+ provider.shutdown()
+ assert (path.read_bytes() if path.exists() else None) == before
+ assert any("file was not updated" in record.message for record in caplog.records)
diff --git a/examples/hermes-plugin/tests/test_standalone.py b/examples/hermes-plugin/tests/test_standalone.py
index ba160ac21..09cbd4ce9 100644
--- a/examples/hermes-plugin/tests/test_standalone.py
+++ b/examples/hermes-plugin/tests/test_standalone.py
@@ -24,6 +24,63 @@ def test_external_discovery_preserves_profile_config_and_relative_setup(external
assert (home_a / "config.yaml").read_bytes() == before
[email protected]("target", ["memory", "user"])
+def test_external_native_memory_lifecycle_survives_restart(external_provider, target):
+ from agent.memory_manager import MemoryManager
+
+ files, requests = {}, []
+
+ class Client:
+ _endpoint, _api_key, _account, _user, _agent = "http://test", "", "test", "alice", ""
+
+ def get(self, path, **kwargs):
+ return {"result": {"user": self._user}}
+
+ def post(self, path, payload):
+ requests.append(("write", dict(payload)))
+ files[payload["uri"]] = payload["content"]
+ return {"result": {"uri": payload["uri"]}}
+
+ def delete(self, path, *, params):
+ requests.append(("delete", dict(params)))
+ del files[params["uri"]]
+ return {"result": {"uri": params["uri"]}}
+
+ client = Client()
+ operations = [
+ {"action": "add", "new_text": "Preferred shell is zsh"},
+ {"action": "replace", "old_text": "zsh", "new_text": "Preferred shell is fish"},
+ {"action": "remove", "old_text": "fish"},
+ ]
+ uri = None
+ for index, operation in enumerate(operations):
+ home, provider, _, _ = external_provider("mirror-restart")
+ provider._hermes_home = str(home)
+ provider._ensure_client = provider._new_client = lambda: client
+ manager = MemoryManager()
+ manager.add_provider(provider)
+ result = {"success": True}
+ if index == 1:
+ result["replaced_entries"] = {1: "Preferred shell is zsh"}
+ elif index == 2:
+ result["removed_entries"] = {1: "Preferred shell is fish"}
+ manager.notify_memory_tool_write(result, {"target": target, "operations": [operation]})
+ provider.shutdown()
+ registry = json.loads((home / "openviking/memory_mirror_registry.json").read_text())
+ if index == 0:
+ uri = next(iter(files))
+ assert files == {uri: "Preferred shell is zsh"}
+ elif index == 1:
+ assert files == {uri: "Preferred shell is fish"}
+ else:
+ assert files == {}
+ assert [entry["uri"] for entry in registry["entries"]] == ([uri] if files else [])
+
+ assert [payload["uri"] for _, payload in requests] == [uri, uri, uri]
+ assert requests[1][1]["wait"] is True
+ assert requests[2][1] == {"uri": uri, "recursive": False, "wait": True}
+
+
def test_external_provider_dispatches_search_over_http(external_provider):
_, provider, module, _ = external_provider("search")
requests = []
@@ -337,7 +394,8 @@ def test_external_provider_keeps_user_identity_across_reload(
resume.set()
worker.join(timeout=10)
assert not worker.is_alive()
- assert provider._join_all(lambda: list(provider._memory_write_threads), 10)
+ if operation == "mirror":
+ provider._native_memory_mirror.shutdown(timeout=10)
block = provider.prefetch("", session_id="bob-session")
assert "viking://user/bob/memories/profile.md" in block
assert "viking://user/alice/" not in block