Skip to content

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

fix(hermes): commit active memory sessions by token threshold (#5278)

z1gon6b067ca8015c
diff --git a/examples/hermes-plugin/DEVELOPMENT.md b/examples/hermes-plugin/DEVELOPMENT.md
index a9c178eb4..1e40cbb15 100644
--- a/examples/hermes-plugin/DEVELOPMENT.md
+++ b/examples/hermes-plugin/DEVELOPMENT.md
@@ -4,8 +4,8 @@ This directory imports the OpenViking provider from
[`NousResearch/hermes-plugin-openviking`](https://github.com/NousResearch/hermes-plugin-openviking/tree/5dca75f4d3dcef9467ce2ff32e170d84c679de5f),
commit `5dca75f4d3dcef9467ce2ff32e170d84c679de5f`.
-`__init__.py`, `_setup.py`, and `plugin.yaml` are unchanged from that handoff.
-They also match `plugins/memory/openviking/` in Hermes Agent commit
+At the initial import, `__init__.py`, `_setup.py`, and `plugin.yaml` matched that
+handoff and `plugins/memory/openviking/` in Hermes Agent commit
`d177b119e9c56c9ddc0b7379ffce52341ec06584`. The original MIT license is retained
in this directory. Original contributor history is available in
[Hermes Agent](https://github.com/NousResearch/hermes-agent/commits/d177b119e9c56c9ddc0b7379ffce52341ec06584/plugins/memory/openviking).
@@ -18,6 +18,11 @@ future Hermes catalog key remain `openviking`. Existing `memory.openviking`
settings, environment variables, linked `ovcli.conf` files, data paths, and
`viking_*` tools keep their current behavior.
+The active-session commit lifecycle was ported from
+[KoNit-K's Hermes PR #112533](https://github.com/NousResearch/hermes-agent/pull/112533),
+with the original author retained. The OpenViking adaptation uses a configurable
+pending-token threshold instead of the original six-turn trigger.
+
## Migration coordination
After this directory is merged, submit a Hermes catalog entry with:
diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.md
index f2936f44f..f9e5248c8 100644
--- a/examples/hermes-plugin/README.md
+++ b/examples/hermes-plugin/README.md
@@ -245,3 +245,31 @@ The Hermes config equivalent is `memory.openviking.recall_compress: server`.
When enabled, the default request and total recall deadlines become 55 seconds;
explicit recall timeout settings still take precedence. Older servers fall back
to the existing search path within that deadline.
+
+### Active-session commits
+
+The standalone provider checks OpenViking's `pending_tokens` after each successful
+turn upload. At **20,000 tokens** by default, it requests a background commit
+without ending the Hermes session. Memory extraction then runs on the server.
+Session-end and session-switch commits still flush messages below this threshold.
+
+Set a different threshold in the active Hermes profile's `config.yaml`:
+
+```yaml
+memory:
+ openviking:
+ commit_token_threshold: 8000
+```
+
+`OPENVIKING_COMMIT_TOKEN_THRESHOLD` overrides the YAML value. The setting accepts
+integers from 1,000 to 1,000,000; values outside this range are clamped. Invalid
+values use the 20,000-token default. The provider also exposes this setting through
+its configuration schema.
+
+This is a client-side commit trigger. It does not set or replace the server's
+`auto_commit_policy`. If a server policy is enabled, both triggers operate
+independently. Server locking serializes their archive operations, but explicit
+client commits do not use the server scheduler's interval or retention settings.
+The plugin retains the existing `keep_recent_count: 0` commit behavior.
+The threshold is not a hard limit on extraction input: one turn can
+exceed it, and the server may include other context during extraction.
diff --git a/examples/hermes-plugin/__init__.py b/examples/hermes-plugin/__init__.py
index 0c38076f1..c1482bb21 100644
--- a/examples/hermes-plugin/__init__.py
+++ b/examples/hermes-plugin/__init__.py
@@ -11,6 +11,7 @@ from __future__ import annotations
import atexit
import errno
+import hashlib
import json
import logging
import math
@@ -27,7 +28,7 @@ import time
import uuid
import zipfile
from contextlib import suppress
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
from functools import lru_cache
from pathlib import Path
from typing import Any, Callable, Dict, List, Optional, Set
@@ -94,6 +95,8 @@ _CONFIG_SCHEMA = [
type="string",
default="off",
),
+ _cfg_field("commit_token_threshold", "Pending session tokens that trigger a background memory commit",
+ type="integer", minimum=1000, maximum=1000000, default=20000),
_cfg_field("recall_limit", "Maximum memories injected by automatic recall", type="integer", minimum=1, maximum=100, default=6),
_cfg_field("recall_score_threshold", "Minimum relevance score for automatic recall", type="number", minimum=0.0, maximum=1.0, step=0.01, default=0.15),
_cfg_field("recall_max_injected_chars", "Maximum total characters injected by recall", type="integer", minimum=100, maximum=50000, default=4000),
@@ -1145,16 +1148,29 @@ def _index_tool_calls(messages: List[Dict[str, Any]]) -> tuple[Dict[str, Dict[st
return tool_calls_by_id, completed_tool_ids, skipped_tool_ids
+@dataclass
+class _CommitScope:
+ """One connection generation. Workers retain it across a config reload."""
+
+ client: Any
+ connection_key: str
+ marker_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+ committed: Set[str] = field(default_factory=set)
+ pending: Set[str] = field(default_factory=set)
+ finalizing: Set[str] = field(default_factory=set)
+
+
@dataclass
class _TurnUpload:
"""One turn's OpenViking upload: structured batches first, falling back to plain text
on a first-batch failure, and to individual messages after a failed retry."""
- provider: "OpenVikingMemoryProvider"
+ client: _VikingClient
sid: str
batch_messages: List[Dict[str, Any]]
user_content: str
assistant_content: str
+ assistant_peer_id: str
next_index: int = 0
def _trace(self, fmt: str, *args) -> None:
@@ -1179,22 +1195,25 @@ class _TurnUpload:
return
# Plain-text fallback: one user + one assistant message.
assistant_message: Dict[str, Any] = {"role": "assistant", "parts": [{"type": "text", "text": _message_text(self.assistant_content)[:4000]}]}
- if self.provider._agent:
- assistant_message["peer_id"] = self.provider._agent
+ if self.assistant_peer_id:
+ assistant_message["peer_id"] = self.assistant_peer_id
client.post(f"/api/v1/sessions/{self.sid}/messages/batch",
{"messages": [{"role": "user", "parts": [{"type": "text", "text": self.user_content[:4000]}]}, assistant_message]})
- def run(self) -> None:
+ def run(self) -> Optional[_VikingClient]:
try:
- self.post(self.provider._new_client())
- return
+ client = self.client
+ self.post(client)
+ return client
except Exception as e:
- logger.debug("OpenViking sync_turn failed, reconnecting: %s", e)
+ logger.debug("OpenViking sync_turn failed, retrying: %s", e)
retry_client = None
try:
- retry_client = self.provider._new_client()
+ # The HTTP wrapper opens a new connection for every request. Keep
+ # the original identity even if /reload happens during the retry.
+ retry_client = self.client
self.post(retry_client)
- return
+ return retry_client
except Exception as retry_error:
if retry_client is None or self.next_index >= len(self.batch_messages):
logger.warning("OpenViking sync_turn failed: %s", retry_error)
@@ -1207,6 +1226,7 @@ class _TurnUpload:
self._trace("POST %s message_index=%d payload=%s", path, self.next_index, json.dumps(payload, ensure_ascii=False))
retry_client.post(path, payload)
self.next_index += 1
+ return retry_client
except Exception as fallback_error:
logger.warning("OpenViking sync_turn failed during individual-message fallback: %s", fallback_error)
@@ -1245,18 +1265,18 @@ class OpenVikingMemoryProvider(MemoryProvider):
# serialized. _conn_snapshot is the last identity that passed health, published as ONE
# tuple so lock-free background writers never see torn fields or a failed endpoint;
# _failed_refresh = (settings key, monotonic ts) of the last failure -> cooldown gate.
- (self._session_state_lock, self._inflight_lock, self._deferred_commit_lock, self._committed_session_lock,
- self._client_refresh_lock, self._runtime_start_lock, self._memory_write_lock) = (threading.Lock() for _ in range(7))
+ 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._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
# executor while on_session_end / on_session_switch run on the caller's thread, so the
# snapshot+reset of the turn counter and the session-id rotation must be atomic against a concurrent
# increment. See hermes-agent#28296 review.
self._inflight_writers: Dict[str, Set[threading.Thread]] = {}
- self._deferred_commit_sids: Set[str] = set()
self._deferred_commit_threads: Set[threading.Thread] = set()
- self._committed_session_ids: Set[str] = set()
- self._pending_marked_sids: Set[str] = 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
@@ -1349,9 +1369,24 @@ class OpenVikingMemoryProvider(MemoryProvider):
return _VikingClient(endpoint, api_key, account=account, user=user, agent=agent)
def _publish_client(self, client: _VikingClient, endpoint: str) -> None:
- self._client = client
- self._conn_snapshot = self._settings_tuple(endpoint)
- self._failed_refresh = None
+ with self._session_state_lock:
+ self._client = client
+ self._conn_snapshot = self._settings_tuple(endpoint)
+ self._failed_refresh = None
+
+ def _capture_commit_scope(self) -> _CommitScope:
+ with self._session_state_lock:
+ if self._commit_scope is None or self._commit_scope.client is not self._client:
+ snapshot = getattr(self._client, "_conn_snapshot", None)
+ if not isinstance(snapshot, tuple):
+ snapshot = self._conn_snapshot or self._settings_tuple()
+ # Recovery may use only the matching endpoint and identity. Do
+ # not persist credentials, or use the same marker after A -> B -> A.
+ key = hashlib.sha256(json.dumps(snapshot).encode()).hexdigest()
+ if self._commit_scope is not None:
+ self._turn_count = 0
+ self._commit_scope = _CommitScope(self._client, key)
+ return self._commit_scope
def _finish_runtime_openviking_start(self, *, endpoint: Optional[str] = None, status_callback=None, warning_callback=None) -> None:
endpoint = endpoint or self._endpoint
@@ -1528,10 +1563,15 @@ class OpenVikingMemoryProvider(MemoryProvider):
return None
def _new_client(self) -> _VikingClient:
- """Client from the published snapshot (one tuple load: background writers run
- without _client_refresh_lock and must not see torn fields); falls back to the
- raw fields for legacy/hand-wired paths with no snapshot."""
- endpoint, api_key, account, user, agent = self._conn_snapshot or self._settings_tuple()
+ """Clone the published identity, including defaults resolved by the client.
+
+ Re-reading empty account/user defaults from the environment could borrow
+ the next connection's identity before that connection is published.
+ """
+ snapshot = getattr(self._client, "_conn_snapshot", None)
+ if not isinstance(snapshot, tuple):
+ snapshot = self._conn_snapshot or self._settings_tuple()
+ endpoint, api_key, account, user, agent = snapshot
return _VikingClient(endpoint, api_key, account=account, user=user, agent=agent)
# -- prompt / prefetch ---------------------------------------------------
@@ -1715,7 +1755,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
an invalid value falls back to the default with one warning per (source, value)."""
spec = _SETTING_SPECS[key]
default = spec["default"]
- env_value = os.environ.get(spec["env_var"])
+ env_value = get_secret(spec["env_var"])
if env_value is not None and env_value.strip():
value, source = env_value, spec["env_var"]
else:
@@ -2105,12 +2145,21 @@ class OpenVikingMemoryProvider(MemoryProvider):
if not user_content:
return
+ # Capture the client, commit generation and peer together. Neither a
+ # queued upload nor its retry may borrow a later connection's identity.
+ with self._client_refresh_lock:
+ scope = self._capture_commit_scope()
+ if scope.client is None:
+ return
+ client = self._new_client()
+ assistant_peer_id = self._agent
+
turn_messages = [dict(m) for m in (self._extract_current_turn_messages(messages, user_content, assistant_content) if messages is not None else [])]
for message in turn_messages:
if message.get("role") == "user":
message["content"] = user_content # first user message carries the skill-stripped text
break
- batch_messages = self._messages_to_openviking_batch(turn_messages, assistant_peer_id=self._agent)
+ batch_messages = self._messages_to_openviking_batch(turn_messages, assistant_peer_id=assistant_peer_id)
if env_var_enabled(_SYNC_TRACE_ENV):
logger.info(
"OpenViking sync_turn trace: session_arg=%r cached_session=%r messages_param_supported=true messages_present=%s "
@@ -2121,22 +2170,34 @@ class OpenVikingMemoryProvider(MemoryProvider):
_preview(user_content), _preview(assistant_content),
)
- # Snapshot sid + bump the counter atomically so a concurrent switch/end can't
- # interleave its snapshot+reset (lost turn / misattributed session).
- with self._session_state_lock:
- sid = str(session_id or self._session_id).strip()
- if not sid:
- return
- self._turn_count += 1
- self._mark_session_pending(sid)
- upload = _TurnUpload(self, sid, batch_messages, user_content, assistant_content)
-
def drop_empty() -> None:
if not self._inflight_writers.get(sid):
self._inflight_writers.pop(sid, None)
- # Tracked in _inflight_writers[sid] so commits can drain every writer for that sid.
- self._spawn_tracked("openviking-sync", upload.run, self._inflight_lock, lambda: self._inflight_writers.setdefault(sid, set()),
+ threshold = self._setting("commit_token_threshold", _load_hermes_openviking_config())
+
+ def upload_and_check() -> None:
+ # Serialize writes with commits on the workers, so a slow commit never
+ # blocks sync_turn. A write after a commit re-arms its recovery marker.
+ with self._writer_commit_lock:
+ with self._session_state_lock:
+ if self._session_id == sid and self._commit_scope is scope and self._client is scope.client:
+ self._turn_count += 1
+ turn_count = self._turn_count
+ else:
+ turn_count = 1
+ self._mark_session_committed(sid, committed=False, scope=scope)
+ self._mark_session_pending(sid, scope=scope)
+ client = upload.run()
+ if client is not None:
+ self._maybe_commit_live_session(sid, turn_count, threshold, client, scope)
+
+ with self._session_state_lock:
+ sid = str(session_id or self._session_id).strip()
+ if not sid:
+ return
+ upload = _TurnUpload(client, sid, batch_messages, user_content, assistant_content, assistant_peer_id)
+ self._spawn_tracked("openviking-sync", upload_and_check, self._inflight_lock, lambda: self._inflight_writers.setdefault(sid, set()),
after_discard=drop_empty)
# -- tracked worker threads ---------------------------------------------
@@ -2202,24 +2263,27 @@ class OpenVikingMemoryProvider(MemoryProvider):
# -- session commit / pending-session recovery --------------------------
- def _has_committed_session(self, sid: str) -> bool:
+ def _has_committed_session(self, sid: str, *, scope: Optional[_CommitScope] = None) -> bool:
+ scope = scope or self._capture_commit_scope()
with self._committed_session_lock:
- return sid in self._committed_session_ids
+ return sid in scope.committed
- def _mark_session_committed(self, sid: str, committed: bool = True) -> None:
+ def _mark_session_committed(self, sid: str, committed: bool = True, *, scope: Optional[_CommitScope] = None) -> None:
"""Latch (or, with ``committed=False``, re-arm) the per-sid commit guard. Re-arming is
for in-place compression: it keeps the same live id, which would otherwise reject every later commit."""
+ scope = scope or self._capture_commit_scope()
with self._committed_session_lock:
- (self._committed_session_ids.add if committed else self._committed_session_ids.discard)(sid)
+ (scope.committed.add if committed else scope.committed.discard)(sid)
- def _state_path(self, kind: str, name: str) -> Optional[Path]:
- """Marker/lock file under HERMES_HOME: ``pending`` -> pending_sessions/<sid>.json,
+ def _state_path(self, kind: str, name: str, *, scope: Optional[_CommitScope] = None) -> Optional[Path]:
+ """Marker/lock file under HERMES_HOME: ``pending`` -> pending_sessions/<sid>.<generation>.json,
``lock`` -> runs/<run_id>.lock; an empty run id maps to the legacy recovery lock."""
name = str(name or "").strip()
if not self._hermes_home or (not name and kind != "lock"):
return None
if kind == "pending":
- return Path(self._hermes_home) / _PENDING_SESSIONS_RELATIVE_DIR / f"{quote(name, safe='')}.json"
+ scope = scope or self._capture_commit_scope()
+ return Path(self._hermes_home) / _PENDING_SESSIONS_RELATIVE_DIR / f"{quote(name, safe='')}.{scope.marker_id}.json"
return Path(self._hermes_home) / _RUN_LOCKS_RELATIVE_DIR / (f"{quote(name, safe='')}.lock" if name else _LEGACY_RECOVERY_LOCK_FILENAME)
@staticmethod
@@ -2291,10 +2355,11 @@ class OpenVikingMemoryProvider(MemoryProvider):
logger.debug("Skipping OpenViking pending-session recovery for owner %s; could not check run lock %s: %s", owner_run_id, path, e)
return False, None
- def _mark_session_pending(self, sid: str) -> None:
- if not sid or self._has_committed_session(sid) or sid in self._pending_marked_sids:
+ def _mark_session_pending(self, sid: str, *, scope: Optional[_CommitScope] = None) -> None:
+ scope = scope or self._capture_commit_scope()
+ if not sid or self._has_committed_session(sid, scope=scope) or sid in scope.pending:
return
- path = self._state_path("pending", sid)
+ path = self._state_path("pending", sid, scope=scope)
if path is None:
return
if self._run_lock_path is None:
@@ -2303,26 +2368,29 @@ class OpenVikingMemoryProvider(MemoryProvider):
try:
from hermes_constants import mkdir_under_hermes_home
mkdir_under_hermes_home(path.parent)
- atomic_json_write(path, {"session_id": sid, "owner_run_id": self._run_id}, mode=0o600)
- self._pending_marked_sids.add(sid)
+ atomic_json_write(path, {"session_id": sid, "owner_run_id": self._run_id,
+ "connection_key": scope.connection_key}, mode=0o600)
+ scope.pending.add(sid)
except Exception as e:
logger.debug("Could not mark OpenViking session %s pending: %s", sid, e)
- def _clear_pending_session(self, sid: str) -> None:
- self._pending_marked_sids.discard(sid)
- path = self._state_path("pending", sid)
+ def _clear_pending_session(self, sid: str, *, scope: Optional[_CommitScope] = None,
+ pending_path: Optional[Path] = None) -> None:
+ scope = scope or self._capture_commit_scope()
+ scope.pending.discard(sid)
+ path = pending_path or self._state_path("pending", sid, scope=scope)
try:
if path is not None:
path.unlink(missing_ok=True)
except Exception as e:
logger.debug("Could not clear OpenViking pending session %s: %s", sid, e)
- def _pending_sessions(self) -> List[tuple[str, str]]:
- """(sid, owner_run_id) for every marker file; sid falls back to the file name."""
+ def _pending_sessions(self) -> List[tuple[str, str, Path, str]]:
+ """Read both scoped markers and legacy <sid>.json recovery markers."""
directory = Path(self._hermes_home) / _PENDING_SESSIONS_RELATIVE_DIR if self._hermes_home else None
if directory is None or not directory.is_dir():
return []
- sessions: List[tuple[str, str]] = []
+ sessions: List[tuple[str, str, Path, str]] = []
for path in sorted(directory.glob("*.json")):
try:
raw = json.loads(path.read_text(encoding="utf-8"))
@@ -2331,27 +2399,32 @@ class OpenVikingMemoryProvider(MemoryProvider):
raw = raw if isinstance(raw, dict) else {}
sid = str(raw.get("session_id") or "").strip() or unquote(path.stem).strip()
if sid:
- sessions.append((sid, str(raw.get("owner_run_id") or "").strip()))
+ sessions.append((sid, str(raw.get("owner_run_id") or "").strip(), path,
+ str(raw.get("connection_key") or "")))
return sessions
- def _claim_deferred_sid(self, sid: str, *, release: bool = False) -> bool:
- """Dedupe: one finalizer per sid at a time; never claim after shutdown began."""
+ def _claim_deferred_sid(self, sid: str, *, release: bool = False, scope: Optional[_CommitScope] = None) -> bool:
+ """One finalizer per sid and connection generation; none after shutdown."""
+ scope = scope or self._capture_commit_scope()
with self._deferred_commit_lock:
if release:
- self._deferred_commit_sids.discard(sid)
+ scope.finalizing.discard(sid)
return True
- if self._shutting_down or sid in self._deferred_commit_sids:
+ if self._shutting_down or sid in scope.finalizing:
return False
- self._deferred_commit_sids.add(sid)
+ scope.finalizing.add(sid)
return True
def _recover_pending_sessions(self) -> None:
"""Commit sessions left pending by dead runs, one thread per former owner."""
- if not self._client:
+ scope = self._capture_commit_scope()
+ if not scope.client:
return
- pending_by_owner: Dict[str, List[str]] = {}
- for sid, owner_run_id in self._pending_sessions():
- pending_by_owner.setdefault(owner_run_id, []).append(sid)
+ pending_by_owner: Dict[str, List[tuple[str, Path]]] = {}
+ for sid, owner_run_id, path, connection_key in self._pending_sessions():
+ if connection_key and connection_key != scope.connection_key:
+ continue
+ pending_by_owner.setdefault(owner_run_id, []).append((sid, path))
for owner_run_id, sids in pending_by_owner.items():
recoverable, owner_lock_file = self._claim_owner_run_for_recovery(owner_run_id)
@@ -2360,67 +2433,93 @@ class OpenVikingMemoryProvider(MemoryProvider):
def _recover_owner(pending_sids=tuple(sids), owner=owner_run_id, lock_file=owner_lock_file) -> None:
try:
- for pending_sid in pending_sids:
- if not self._claim_deferred_sid(pending_sid):
+ for pending_sid, pending_path in pending_sids:
+ if not self._claim_deferred_sid(pending_sid, scope=scope):
continue
try:
- if self._has_committed_session(pending_sid):
- self._clear_pending_session(pending_sid)
- elif not self._shutting_down:
- self._commit_session(pending_sid, 0, context="during startup recovery", clear_missing=True)
+ with self._writer_commit_lock:
+ if self._has_committed_session(pending_sid, scope=scope):
+ self._clear_pending_session(pending_sid, scope=scope, pending_path=pending_path)
+ elif not self._shutting_down:
+ self._commit_session(pending_sid, 0, context="during startup recovery", clear_missing=True,
+ scope=scope, pending_path=pending_path)
finally:
- self._claim_deferred_sid(pending_sid, release=True)
+ self._claim_deferred_sid(pending_sid, release=True, scope=scope)
finally:
self._flock_close(lock_file, None if owner == self._run_id else self._state_path("lock", owner), "owner run lock")
self._spawn_tracked(f"openviking-recover-owner-{owner_run_id or 'legacy'}", _recover_owner, self._deferred_commit_lock, lambda: self._deferred_commit_threads)
- def _session_needs_commit(self, sid: str, turn_count: int) -> bool:
+ def _maybe_commit_live_session(self, sid: str, turn_count: int, threshold: int, client: _VikingClient,
+ scope: _CommitScope) -> None:
+ """Check after a successful upload; metadata failures must not replay the turn."""
+ if self._shutting_down:
+ return
+ try:
+ session = self._unwrap_result(client.get(f"/api/v1/sessions/{sid}"))
+ if int(session.get("pending_tokens") or 0) >= threshold:
+ self._finalize_session_async(sid, turn_count, context="after live token threshold", client=client, scope=scope)
+ except Exception as e:
+ logger.warning("OpenViking live commit check failed for %s: %s", sid, e)
+
+ def _session_needs_commit(self, sid: str, turn_count: int, *, scope: Optional[_CommitScope] = None) -> bool:
# The committed-guard wins over turn_count: a racing sync_turn can re-increment
# _turn_count after a commit+reset.
- if self._has_committed_session(sid):
+ scope = scope or self._capture_commit_scope()
+ if self._has_committed_session(sid, scope=scope):
return False
if turn_count > 0:
return True
try:
- session = self._unwrap_result(self._client.get(f"/api/v1/sessions/{sid}"))
+ session = self._unwrap_result(scope.client.get(f"/api/v1/sessions/{sid}"))
return isinstance(session, dict) and int(session.get("pending_tokens") or 0) > 0
except Exception:
return False
- def _commit_session(self, sid: str, turn_count: int, *, context: str, clear_missing: bool = False) -> bool:
+ def _commit_session(self, sid: str, turn_count: int, *, context: str, clear_missing: bool = False,
+ client: Optional[_VikingClient] = None, scope: Optional[_CommitScope] = None,
+ pending_path: Optional[Path] = None) -> bool:
+ scope = scope or self._capture_commit_scope()
try:
- self._client.post(f"/api/v1/sessions/{sid}/commit", {"keep_recent_count": 0})
- self._mark_session_committed(sid)
- self._clear_pending_session(sid)
+ (client or scope.client).post(f"/api/v1/sessions/{sid}/commit", {"keep_recent_count": 0})
+ self._mark_session_committed(sid, scope=scope)
+ self._clear_pending_session(sid, scope=scope, pending_path=pending_path)
+ with self._session_state_lock:
+ if self._session_id == sid and self._commit_scope is scope and self._client is scope.client:
+ self._turn_count = 0
logger.info("OpenViking session %s committed %s (%d turns)", sid, context, turn_count)
return True
except Exception as e:
if clear_missing and _status_code_from_error(e) == 404:
- self._clear_pending_session(sid)
+ self._clear_pending_session(sid, scope=scope, pending_path=pending_path)
logger.debug("OpenViking pending session %s no longer exists; dropped marker", sid)
else:
logger.warning("OpenViking session commit failed for %s: %s", sid, e)
return False
- def _finalize_session_async(self, sid: str, turn_count: int, *, context: str) -> None:
+ def _finalize_session_async(self, sid: str, turn_count: int, *, context: str,
+ client: Optional[_VikingClient] = None, scope: Optional[_CommitScope] = None) -> None:
"""Drain the old session's writers and commit it on a daemon thread, so the
multi-second drain + pending-token GET + commit POST never runs on the
- caller's command thread (on_session_switch). Deduped per sid; no-op after shutdown."""
- if not sid or not self._claim_deferred_sid(sid):
+ caller's command thread (on_session_switch). Deduped per sid and connection; no-op after shutdown."""
+ scope = scope or self._capture_commit_scope()
+ if not sid or not self._claim_deferred_sid(sid, scope=scope):
return
def _finalize() -> None:
try:
if self._shutting_down:
return
+ # Drain before taking the write lock: queued uploads need that
+ # lock to finish. A later writer re-arms the guard after this commit.
if not self._drain_writers(sid, timeout=_DEFERRED_COMMIT_TIMEOUT):
logger.warning("OpenViking writer for %s still alive after drain — leaving session uncommitted", sid)
return
- if not self._shutting_down and self._session_needs_commit(sid, turn_count):
- self._commit_session(sid, turn_count, context=context)
+ with self._writer_commit_lock:
+ if not self._shutting_down and self._session_needs_commit(sid, turn_count, scope=scope):
+ self._commit_session(sid, turn_count, context=context, client=client, scope=scope)
finally:
- self._claim_deferred_sid(sid, release=True)
+ self._claim_deferred_sid(sid, release=True, scope=scope)
self._spawn_tracked(f"openviking-finalize-{sid}", _finalize, self._deferred_commit_lock, lambda: self._deferred_commit_threads)
@@ -2430,18 +2529,17 @@ class OpenVikingMemoryProvider(MemoryProvider):
if not self._ensure_client():
return
with self._session_state_lock:
+ scope = self._capture_commit_scope()
sid = self._session_id
- turn_count = self._turn_count
if not self._drain_writers(sid, timeout=_SESSION_DRAIN_TIMEOUT):
logger.warning("OpenViking writer for %s still alive after drain — skipping commit", sid)
return
- if not self._session_needs_commit(sid, turn_count):
- return
- if self._commit_session(sid, turn_count, context="on session end"):
- # Mark clean so a follow-up on_session_switch skips its own commit.
+ with self._writer_commit_lock:
with self._session_state_lock:
- if self._session_id == sid:
- self._turn_count = 0
+ turn_count = self._turn_count if self._session_id == sid and self._commit_scope is scope else 0
+ if not self._session_needs_commit(sid, turn_count, scope=scope):
+ return
+ self._commit_session(sid, turn_count, context="on session end", scope=scope)
def on_session_switch(self, new_session_id: str, *, parent_session_id: str = "", reset: bool = False, **kwargs) -> None:
"""Commit the old session and rotate cached state to the new session_id.
@@ -2462,6 +2560,7 @@ class OpenVikingMemoryProvider(MemoryProvider):
# Rotate under the lock so a concurrent sync_turn lands fully under old or new.
with self._session_state_lock:
+ scope = self._capture_commit_scope()
# Rotate cached session state synchronously (cheap, in-memory) and snapshot the old session
# under the lock so a concurrent sync_turn either lands fully before the rotation (counted under
# old) or fully after (counted under new) — never split. The OLD session's commit (drain +
@@ -2487,13 +2586,13 @@ class OpenVikingMemoryProvider(MemoryProvider):
# In-place compression keeps the same (still live) sid, which compress_context()
# just committed and latched. Re-arm so later commits aren't rejected. Rotation
# mode is untouched: the old id stays latched to dedupe its async finalizer.
- self._mark_session_committed(old_session_id, committed=False)
+ self._mark_session_committed(old_session_id, committed=False, scope=scope)
if not rotate:
logger.debug("OpenViking on_session_switch skipped rotation: session=%s rewound=%s", old_session_id, rewound)
return
if old_session_id:
- self._finalize_session_async(old_session_id, old_turn_count, context="on switch")
+ self._finalize_session_async(old_session_id, old_turn_count, context="on switch", scope=scope)
logger.debug("OpenViking on_session_switch: old=%s new=%s parent=%s reset=%s", old_session_id, new_id, parent_session_id, reset)
# -- memory mirroring -----------------------------------------------------
diff --git a/examples/hermes-plugin/tests/test_standalone.py b/examples/hermes-plugin/tests/test_standalone.py
index 0ab1caa9b..b5d3d2e45 100644
--- a/examples/hermes-plugin/tests/test_standalone.py
+++ b/examples/hermes-plugin/tests/test_standalone.py
@@ -484,3 +484,415 @@ def test_save_config_preserves_profiles_and_scope_when_target_is_invalid(externa
assert (target / "config.yaml").read_text() == invalid
finally:
reset_hermes_home_override(token)
+
+
+def _live_provider(external_provider, monkeypatch, name="live-commit"):
+ from unittest.mock import Mock
+
+ home, provider, module, _ = external_provider(name)
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ provider._hermes_home = str(home)
+ provider._session_id = "live-sid"
+ provider._client = Mock()
+ provider._client.get.return_value = {"pending_tokens": 20000}
+ provider._ensure_client = lambda: True
+ provider._new_client = lambda: provider._client
+ provider._acquire_run_lock()
+ return home, provider, module
+
+
+def _finish_turn(provider, user="one", sid="live-sid"):
+ provider.sync_turn(user, "reply", session_id=sid)
+ assert provider._drain_writers(sid, timeout=5)
+ assert provider._drain_finalizers(timeout=5)
+
+
+def test_live_session_commits_at_token_threshold_and_rearms(external_provider, monkeypatch):
+ """Small turns do not trigger a commit; crossing the token limit does, repeatedly."""
+ home, provider, _ = _live_provider(external_provider, monkeypatch)
+ client = provider._client
+ client.get.return_value = {"pending_tokens": 19999}
+ for _ in range(7):
+ _finish_turn(provider)
+ assert not [c for c in client.post.call_args_list if c.args[0].endswith("/commit")]
+ marker = provider._state_path("pending", "live-sid")
+ assert marker.exists()
+ client.get.return_value = {"result": {"pending_tokens": 20000}}
+ _finish_turn(provider)
+ assert provider._turn_count == 0
+ assert provider._has_committed_session("live-sid")
+ assert not marker.exists()
+ client.get.return_value = {"pending_tokens": 100}
+ _finish_turn(provider, "new turn")
+ assert not provider._has_committed_session("live-sid")
+ assert marker.exists()
+ client.get.return_value = {"pending_tokens": 25000}
+ _finish_turn(provider)
+ commits = [c for c in client.post.call_args_list if c.args[0].endswith("/commit")]
+ assert len(commits) == 2
+ assert commits[0].args == ("/api/v1/sessions/live-sid/commit", {"keep_recent_count": 0})
+ provider.on_session_end([])
+ assert len([c for c in client.post.call_args_list if c.args[0].endswith("/commit")]) == 2
+
+
+def test_live_commit_waits_for_registered_writer_before_committing(external_provider, monkeypatch):
+ """A live threshold commit must not cross an upload that is still running."""
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ upload_started = threading.Event()
+ release_upload = threading.Event()
+ commit_paths = []
+
+ def post(path, payload=None, **kwargs):
+ if path.endswith("/messages/batch"):
+ upload_started.set()
+ assert release_upload.wait(timeout=5)
+ elif path.endswith("/commit"):
+ commit_paths.append(path)
+ return {}
+
+ provider._client.post.side_effect = post
+ provider.sync_turn("one", "reply", session_id="live-sid")
+ try:
+ assert upload_started.wait(timeout=5)
+ assert commit_paths == []
+ finally:
+ release_upload.set()
+ assert provider._drain_writers("live-sid", timeout=5)
+ assert provider._drain_finalizers(timeout=5)
+ assert commit_paths == ["/api/v1/sessions/live-sid/commit"]
+
+
+def test_failed_live_commit_stays_pending_and_retries_on_next_turn(external_provider, monkeypatch):
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ commit_attempts = []
+
+ def post(path, payload=None, **kwargs):
+ if path.endswith("/commit"):
+ commit_attempts.append(path)
+ if len(commit_attempts) == 1:
+ raise RuntimeError("temporary failure")
+ return {}
+
+ provider._client.post.side_effect = post
+ _finish_turn(provider)
+ assert provider._turn_count == 1
+ assert not provider._has_committed_session("live-sid")
+ assert provider._state_path("pending", "live-sid").exists()
+ _finish_turn(provider, "two")
+ assert len(commit_attempts) == 2
+ assert provider._turn_count == 0
+ assert not provider._state_path("pending", "live-sid").exists()
+
+
[email protected]("metadata", [{}, {"pending_tokens": "invalid"}, RuntimeError("unavailable")])
+def test_live_metadata_failure_does_not_replay_uploaded_turn(external_provider, monkeypatch, metadata):
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ if isinstance(metadata, Exception):
+ provider._client.get.side_effect = metadata
+ else:
+ provider._client.get.return_value = metadata
+ _finish_turn(provider)
+ assert provider._client.post.call_count == 1
+ assert provider._state_path("pending", "live-sid").exists()
+ provider._client.get.side_effect = None
+ provider._client.get.return_value = {"pending_tokens": 20000}
+ _finish_turn(provider)
+ assert provider._has_committed_session("live-sid")
+
+
+def test_live_failed_upload_does_not_commit_partial_turn(external_provider, monkeypatch):
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ provider._client.post.side_effect = RuntimeError("upload unavailable")
+ _finish_turn(provider)
+ assert not provider._client.get.called
+ assert provider._state_path("pending", "live-sid").exists()
+ provider._client.post.side_effect = None
+ _finish_turn(provider)
+ assert provider._has_committed_session("live-sid")
+
+
+def test_live_config_schema_save_and_profile_overrides(external_provider, monkeypatch):
+ from agent.secret_scope import build_profile_secret_scope, reset_secret_scope, set_secret_scope
+ from hermes_constants import reset_hermes_home_override, set_hermes_home_override
+
+ home_a, provider, module, _ = external_provider("threshold-a")
+ home_b, _, _, _ = external_provider("threshold-b")
+ provider.save_config({"commit_token_threshold": 8000}, str(home_a))
+ provider.save_config({"commit_token_threshold": 12000}, str(home_b))
+ (home_b / ".env").write_text("OPENVIKING_COMMIT_TOKEN_THRESHOLD=4000\n")
+ monkeypatch.setenv("OPENVIKING_COMMIT_TOKEN_THRESHOLD", "99000")
+ schema = next(f for f in provider.get_config_schema() if f["key"] == "commit_token_threshold")
+ assert schema["default"] == 20000
+ assert schema["env_var"] == "OPENVIKING_COMMIT_TOKEN_THRESHOLD"
+ monkeypatch.setattr("agent.secret_scope._MULTIPLEX_ACTIVE", True)
+ for home, expected in [(home_a, 8000), (home_b, 4000), (home_a, 8000)]:
+ token = set_hermes_home_override(home)
+ scope = set_secret_scope(build_profile_secret_scope(home))
+ try:
+ cfg = module._load_hermes_openviking_config()
+ assert provider._setting("commit_token_threshold", cfg) == expected
+ finally:
+ reset_secret_scope(scope)
+ reset_hermes_home_override(token)
+
+
[email protected]("value,expected", [("bad", 20000), (True, 20000), ("nan", 20000), (999, 1000), (1000001, 1000000)])
+def test_live_threshold_validation(external_provider, value, expected):
+ _, provider, _, _ = external_provider("threshold-validation")
+ assert provider._setting("commit_token_threshold", {"commit_token_threshold": value}) == expected
+
+
+def test_live_commit_uses_upload_client_after_connection_change(external_provider, monkeypatch):
+ from unittest.mock import Mock
+
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ original = provider._client
+ replacement = Mock()
+
+ def get(*_args, **_kwargs):
+ provider._client = replacement
+ return {"pending_tokens": 20000}
+
+ original.get.side_effect = get
+ _finish_turn(provider)
+ assert original.post.call_args.args[0].endswith("/commit")
+ replacement.post.assert_not_called()
+
+
+def test_session_switch_commits_below_live_threshold(external_provider, monkeypatch):
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ provider._client.get.return_value = {"pending_tokens": 1}
+ _finish_turn(provider)
+ provider.on_session_switch("new-sid")
+ assert provider._drain_finalizers(timeout=5)
+ assert provider._client.post.call_args.args[0] == "/api/v1/sessions/live-sid/commit"
+ assert provider._session_id == "new-sid"
+
+
+def test_live_commit_does_not_block_next_turn_or_lose_its_pending_marker(external_provider, monkeypatch):
+ from concurrent.futures import ThreadPoolExecutor
+
+ _, provider, _ = _live_provider(external_provider, monkeypatch)
+ started = threading.Event()
+ release = threading.Event()
+ commits = []
+
+ def post(path, payload=None, **kwargs):
+ if path.endswith('/commit'):
+ commits.append(path)
+ started.set()
+ assert release.wait(timeout=5)
+ return {}
+
+ provider._client.post.side_effect = post
+ provider.sync_turn('first', 'reply', session_id='live-sid')
+ assert started.wait(timeout=5)
+ provider._client.get.return_value = {'pending_tokens': 100}
+ with ThreadPoolExecutor(max_workers=1) as executor:
+ try:
+ submitted = executor.submit(provider.sync_turn, 'second', 'reply', session_id='live-sid')
+ submitted.result(timeout=2)
+ finally:
+ release.set()
+ assert provider._drain_writers('live-sid', timeout=5)
+ assert provider._drain_finalizers(timeout=5)
+ assert not provider._has_committed_session('live-sid')
+ assert provider._state_path('pending', 'live-sid').exists()
+ provider.on_session_end([])
+ assert len(commits) == 2
+
+
+def reload_provider(external_provider, monkeypatch):
+ from unittest.mock import Mock
+
+ home, provider, module, _ = external_provider("connection-reload")
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ backends = {name: Mock() for name in ("alice", "bob")}
+ for backend in backends.values():
+ backend.get.return_value = {"result": {"pending_tokens": 20}}
+ backend.post.return_value = {"result": {}}
+
+ class Client:
+ def __init__(self, endpoint, api_key="", *, account="", user="", agent=""):
+ self._conn_snapshot = (endpoint, api_key, account, user, agent)
+ self.get = backends[user].get
+ self.post = backends[user].post
+
+ monkeypatch.setattr(module, "_VikingClient", Client)
+ monkeypatch.setattr(module, "_classify_runtime_openviking_health", lambda *_: ("healthy", ""))
+
+ def reload(user, endpoint="http://127.0.0.1:19531"):
+ monkeypatch.setenv("OPENVIKING_USER", user)
+ monkeypatch.setenv("OPENVIKING_ENDPOINT", endpoint)
+ monkeypatch.setenv("OPENVIKING_API_KEY", "private-test-key")
+ if not provider._env_refresh_enabled:
+ provider.initialize("same-sid", hermes_home=str(home))
+ else:
+ assert provider._ensure_client() is not None
+
+ reload("alice")
+ return home, provider, module, backends, reload
+
+
+def test_upload_client_keeps_published_defaults_until_reload(external_provider, monkeypatch):
+ _, provider, module, _ = external_provider("published-defaults")
+ monkeypatch.setenv("OPENVIKING_USER", "alice")
+ provider._endpoint = "http://127.0.0.1:19531"
+ provider._client = module._VikingClient(provider._endpoint)
+ provider._conn_snapshot = provider._settings_tuple()
+ # /reload can update the environment before the provider sees the change.
+ monkeypatch.setenv("OPENVIKING_USER", "bob")
+ upload_client = provider._new_client()
+ assert upload_client._headers()["X-OpenViking-User"] == "alice"
+
+
[email protected]("bob_tokens", [20, 20000])
[email protected]("endpoint", ["http://127.0.0.1:19531", "http://127.0.0.1:19532"])
+def test_reload_keeps_new_connection_pending_after_old_commit(reload_provider, monkeypatch, bob_tokens, endpoint):
+ """A's finalizer must neither clear B's work nor suppress B's finalizer."""
+ _, provider, _, backends, reload = reload_provider
+ sid = "same-sid"
+ alice_get = threading.Event()
+ bob_get = threading.Event()
+ release_alice = threading.Event()
+ release_bob = threading.Event()
+ alice_claimed = threading.Event()
+ claim = provider._claim_deferred_sid
+
+ def observe_claim(*args, **kwargs):
+ claimed = claim(*args, **kwargs)
+ if claimed and not kwargs.get("release"):
+ alice_claimed.set()
+ return claimed
+
+ def metadata(started, release, tokens):
+ started.set()
+ assert release.wait(timeout=10)
+ return {"result": {"pending_tokens": tokens}}
+
+ monkeypatch.setattr(provider, "_claim_deferred_sid", observe_claim)
+ backends["alice"].get.side_effect = lambda *_: metadata(alice_get, release_alice, 20000)
+ backends["bob"].get.side_effect = lambda *_: metadata(bob_get, release_bob, bob_tokens)
+ provider.sync_turn("Alice's pending turn", "reply", session_id=sid)
+ try:
+ assert alice_get.wait(timeout=5)
+ alice_marker = provider._state_path("pending", sid)
+ reload("bob", endpoint)
+ provider.sync_turn("Bob's pending turn", "reply", session_id=sid)
+ assert bob_get.wait(timeout=5)
+ bob_marker = provider._state_path("pending", sid)
+ assert bob_marker.exists()
+ # A claims the finalizer while B's metadata request is still pending.
+ release_alice.set()
+ assert alice_claimed.wait(timeout=5)
+ finally:
+ release_alice.set()
+ release_bob.set()
+ assert provider._drain_writers(sid, timeout=5)
+ assert provider._drain_finalizers(timeout=5)
+ assert not alice_marker.exists()
+ if bob_tokens < 20000:
+ assert bob_marker.exists()
+ assert not provider._has_committed_session(sid)
+ assert provider._turn_count == 1
+ else:
+ # B must get its own threshold finalizer while A already owns one.
+ assert provider._has_committed_session(sid)
+ assert not bob_marker.exists()
+ provider.on_session_end([])
+ assert not bob_marker.exists()
+ for backend in backends.values():
+ commits = [c for c in backend.post.call_args_list if c.args[0].endswith("/commit")]
+ assert len(commits) == 1
+ assert commits[0].args == (f"/api/v1/sessions/{sid}/commit", {"keep_recent_count": 0})
+
+
+def test_reload_recovery_preserves_markers_for_other_connections(reload_provider, monkeypatch):
+ """Failed commits survive restart and recover only with matching credentials."""
+ home, provider, module, backends, reload = reload_provider
+ sid = "same-sid"
+ markers = {}
+
+ def fail_commit(path, *_args, **_kwargs):
+ if path.endswith("/commit"):
+ raise RuntimeError("temporary failure")
+ return {}
+
+ for user in ("alice", "bob"):
+ reload(user)
+ backends[user].post.side_effect = fail_commit
+ _finish_turn(provider, user, sid=sid)
+ markers[user] = provider._state_path("pending", sid)
+ provider.on_session_end([])
+ assert markers[user].exists()
+ assert not provider._has_committed_session(sid)
+ assert "private-test-key" not in markers[user].read_text()
+ assert markers["alice"] != markers["bob"]
+ provider.shutdown()
+
+ for backend in backends.values():
+ backend.post.side_effect = None
+ backend.post.reset_mock()
+ for user in ("bob", "alice"):
+ monkeypatch.setenv("OPENVIKING_USER", user)
+ recovered = module.OpenVikingMemoryProvider()
+ try:
+ recovered.initialize("new-sid", hermes_home=str(home))
+ assert recovered._drain_finalizers(timeout=5)
+ assert not markers[user].exists()
+ backends[user].post.assert_called_once_with(f"/api/v1/sessions/{sid}/commit", {"keep_recent_count": 0})
+ if user == "bob":
+ assert markers["alice"].exists()
+ backends["alice"].post.assert_not_called()
+ finally:
+ recovered.shutdown()
+
+
+def test_reload_back_to_original_identity_keeps_new_generation_pending(reload_provider):
+ _, provider, _, backends, reload = reload_provider
+ sid = "same-sid"
+ first_get = threading.Event()
+ release_first = threading.Event()
+ later_get = threading.Event()
+ bob_get = threading.Event()
+
+ def alice_metadata(*_args):
+ if not first_get.is_set():
+ first_get.set()
+ assert release_first.wait(timeout=10)
+ return {"pending_tokens": 20000}
+ later_get.set()
+ return {"pending_tokens": 20}
+
+ def bob_metadata(*_args):
+ bob_get.set()
+ return {"pending_tokens": 20}
+
+ backends["alice"].get.side_effect = alice_metadata
+ backends["bob"].get.side_effect = bob_metadata
+ provider.sync_turn("old Alice turn", "reply", session_id=sid)
+ try:
+ assert first_get.wait(timeout=5)
+ old_marker = provider._state_path("pending", sid)
+ reload("bob")
+ provider.sync_turn("Bob turn", "reply", session_id=sid)
+ assert bob_get.wait(timeout=5)
+ bob_marker = provider._state_path("pending", sid)
+ reload("alice")
+ provider.sync_turn("new Alice turn", "reply", session_id=sid)
+ assert later_get.wait(timeout=5)
+ new_marker = provider._state_path("pending", sid)
+ finally:
+ release_first.set()
+ assert provider._drain_writers(sid, timeout=5)
+ assert provider._drain_finalizers(timeout=5)
+ assert not old_marker.exists()
+ assert new_marker.exists() and bob_marker.exists()
+ assert not provider._has_committed_session(sid)
+ assert provider._turn_count == 1
+ provider.on_session_end([])
+ assert not new_marker.exists()
+ assert bob_marker.exists()
+ commits = [c for c in backends["alice"].post.call_args_list if c.args[0].endswith("/commit")]
+ assert len(commits) == 2