Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(hermes): align setup and capability guidance (#5423)
z1gon9ed69c5ab55c
diff --git a/docs/en/agent-integrations/05-hermes.md b/docs/en/agent-integrations/05-hermes.mdindex c1794816e..f646dba04 100644--- a/docs/en/agent-integrations/05-hermes.md+++ b/docs/en/agent-integrations/05-hermes.md@@ -29,6 +29,9 @@ hermes memory setup openvikinghermes memory status```+`available` means that the provider is configured. It does not check server+connectivity or confirm memory extraction.+## See also- [Capability Reference](./16-capability-reference.md)diff --git a/docs/en/agent-integrations/16-capability-reference.md b/docs/en/agent-integrations/16-capability-reference.mdindex 382be00fd..2b0731c2f 100644--- a/docs/en/agent-integrations/16-capability-reference.md+++ b/docs/en/agent-integrations/16-capability-reference.md@@ -1,5 +1,10 @@# Integration Capability Reference+**Hermes scope:** The Hermes rows describe its [bundled provider](https://github.com/NousResearch/hermes-agent/tree/989798cd5e691230b54b2ea72e5937b68133014c/plugins/memory/openviking),+checked against Hermes main `989798cd5e`. The [OpenViking-maintained external plugin](https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin)+has additional commit, recall, and mirroring behavior. The bundled copy takes+precedence while present; use the [normal setup guide](./05-hermes.md) for it.+## Reading guide| What you want to know | Where to look |@@ -37,7 +42,7 @@| dsh | MCP passthrough (`@deepseek-ai/dsh-mcp-client` → the shared stdio proxy; host adds an `mcp__openviking__` prefix) | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² || pi | MCP mirror (official client; extension adds an `openviking_` prefix) | 16, i.e. whatever `tools/list` returns (registration has preconditions³) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | no type distinction² || openclaw | native registration (15 × `memory_*`/`ov_*` and friends) | 15 (14 on by default⁴) | ✅ `memory_recall` | ✅ `ov_search` (both scopes by default) | ✅ `ov_search` | ✅ `memory_store` | off by default⁴ | ✅ `add_skill` | memory-only allowlist + auto-delete only for a single candidate with score≥0.85 |-| hermes | native registration (6 × `viking_*`) | 6 (all on once the provider is active) | ✅ | ✅ | ✅ | ✅ `viking_remember` (writes the file directly, no extraction) | ✅ multi-protocol ingest (HTTP/Git/SSH/local file/directory zip) | ❌ | memory-only + `.md` leaf check |+| hermes | native registration (6 × `viking_*`) | 6 (all on once the provider is active) | ✅ | ✅ | ✅ | ✅ `viking_remember` (dedicated session and asynchronous extraction) | ✅ multi-protocol ingest (HTTP/Git/SSH/local file/directory zip) | ❌ | memory-only + `.md` leaf check || ov CLI | CLI commands | ~40 command groups | ✅ `ov find` | ✅ `ov find` | ✅ `ov find` | ✅ `ov add-memory` | ✅ `ov add-resource` | ✅ `ov add-skill` | `ov rm` executes directly (TUI deletion asks for confirmation and blocks root/scope deletes) |¹ MCP `write` rejects the user's own `skills/` subtree; under `viking://agent/skills` it writes a plain file that skips skill installation (no frontmatter abstract, no privacy extraction), so use `add_skill` there too. Skills are created, installed, and replaced through the MCP `add_skill` tool (inline SKILL.md text, a Git URL, or a signed upload of a local directory or zip), which shares one install implementation with REST `POST /api/v1/skills`.@@ -61,7 +66,7 @@| dsh | native Cordis plugin (same process) + MCP proxy + skill | ✅ | ✅ | ❌ | ✅ (10000) + `<available-skills>` (1200), once per session | ❌ | ✅ | ❌ || pi | native extension (9 events) | ✅ | ✅ | ❌ | ✅ (10000) + `<available-skills>` (1200), rebuilt into systemPrompt every turn | ✅ **takeover** (on by default) | ✅ | ✅ || openclaw | context-engine plugin (`ownsCompaction:true`) | ✅ | ❌ (goes through `/find`, which has no session_id field) | ❌ | ❌ | ✅ **full ContextEngine takeover** | ❌ failed turns are not replayed | ❌ |-| hermes | native MemoryProvider plugin | ✅ | partial (preferred `search/search` path only; the degraded `/find` path drops it) | ❌ | ❌ (static tool-guidance block) | ❌ | ✅ in-process queue (never written to disk) | ❌ |+| hermes | native MemoryProvider plugin | ✅ | partial (preferred `search/search` path only; the degraded `/find` path drops it) | ❌ | ✅ (6000-token session-start memory budget) | ❌ | ✅ in-process uploads; durable pending-commit markers | ❌ || ov CLI | one-shot commands | ❌ (`ov find/search` are explicit commands) | — (`ov search --session-id` is an explicit argument) | ❌ | ❌ | ❌ | ❌ | ❌ |\* This column indicates whether the client performs its own local compression of recall results. On the server side, the context retrieval API provides digest capabilities equally to all callers via the `rewrite` parameter (see [§3.2.5](#_3-2-5-recall-digest)).@@ -179,7 +184,7 @@ Core modules at a glance (detailed further in the per-dimension sections):| dsh | In-process Cordis plugin (`cordis.patch.yml` entry) | Unified installer (asks for the profile, default `web`), or `dsh plugin --profile web add @openviking/dsh-memory-plugin` | `dsh-<session.id as-is>`; each subagent is assigned its own session | env + ovcli.conf `plugin.dsh` + the cordis patch config, which is the lowest behavior layer (credentials still come from the patch first) | ❌ || pi | Native pi extension (loaded from a directory, with TypeScript transpiled on the fly via jiti) | One-line `--harness pi` (copied into the auto-discovery directory, no `pi install` needed) | `pi-<piSessionId>` | env + ovcli.conf `plugin.pi` (credential fields are resolved via the shared credential chain) | ✅ || openclaw | context-engine plugin (`ownsCompaction:true`) + 15 tools + 5 slash + 4 hooks + HTTP routes | ClawHub: run `openclaw plugins install clawhub:@openviking/openclaw-plugin` alongside `openclaw openviking setup` / npm installer / TOS offline bundle | A UUID is lowercased as-is, otherwise `sha256(sessionKey)`; `memory_store` temporary sessions use `memory-store-<ts>-<rand>` | `plugins.entries.openviking.config` in `openclaw.json` (strictly validated: unknown keys or invalid values force the plugin into setup-only mode) + a few env vars | ✅ `openclaw openviking setup` (interactive/non-interactive + key role probing + version compatibility check) |-| hermes | Hermes bundled MemoryProvider (ships with Hermes; no plugin installation required) | Run `hermes memory setup openviking` (interactive curses wizard), or manually run `config set memory.provider openviking` + `.env` | Hermes generates `%Y%m%d_%H%M%S_<hex6>`; the plugin uses it verbatim | `.env` (`OPENVIKING_*`) or linked ovcli.conf (`use_ovcli_config` mode clears the 5 corresponding variables from .env) + config.yaml | ✅ (multi-level menu) |+| hermes | Hermes bundled MemoryProvider (ships with Hermes; no plugin installation required) | Run `hermes memory setup openviking` (interactive curses wizard), or manually run `hermes config set memory.provider openviking` + `.env` | Generated by Hermes and used unchanged | `.env` (`OPENVIKING_*`) or linked ovcli.conf (`use_ovcli_config` mode clears the 5 corresponding variables from .env) + config.yaml | ✅ (multi-level menu) || ov CLI | Native Rust binary | npm `@openviking/cli` / `uv tool install openviking` / cargo / GitHub Releases | Does not manage its own session (`ov chat` defaults to the machine-uid) | `ovcli.conf` (multiple profiles) + a few env vars | ✅ `ov config` (TUI wizard) |### 3.1.2 Unified installer@@ -238,7 +243,7 @@ To give a directory that is not a repository its own peer, create `.openviking/c**Migration** (no user action required): The pre-git peer id is a pure function of the cwd, so the client can always recompute it locally and recall still reaches memories written under it. Under the default `peer_scope: "all"`, the server's existing cross-peer sweep already covers it at zero cost; under `peer_scope: "actor"`, the plugin asks that peer separately and appends whatever it returns. There is no deadline on this.-For `openclaw`, the peer is derived from `peer_role`/`peer_prefix` (note that if `peer_role=sender`, sender information must be available, otherwise tool calls will fail; legacy `person` is accepted as an alias). The `hermes` peer defaults to `OPENVIKING_AGENT` (defaulting to `hermes`).+For `openclaw`, the peer is derived from `peer_role`/`peer_prefix` (note that if `peer_role=sender`, sender information must be available, otherwise tool calls will fail; legacy `person` is accepted as an alias). The Hermes assistant peer is optional: `OPENVIKING_AGENT`, a linked OpenViking peer, or YAML `agent`; no peer is set by default.### 3.1.4 Configuration layers@@ -303,8 +308,8 @@ On the server side, `session_id` handling diverges into two distinct execution p- **opencode**: Once per session on the first `chat.message` (10000 budget, deduplicated by an in-process `Set`, subagent sessions skipped). Note that opening injection is attempted only once per session and does not retry in-process after a failure.- **dsh**: Posts `profileDelivered` once per session (10000 budget; not re-posted after compaction).- **pi**: Injected into the `systemPrompt`, re-assembled for every prompt (10000 budget, always resident).- - *Note:* `openclaw` and `hermes` do not perform profile injection.-- **Skill catalog** (`<available-skills>`): `buildProfileBlock()` appends it inside the same `<openviking-context>` envelope, after `<user-profile>` and `<available-memories>`, so every harness above injects it together with the profile (codex covers trae-cli). One `GET /api/v1/skills?node_limit=200` returns the user's own skills and the account-shared `viking://agent/skills`. Own skills are listed first, and a shared skill whose name the user also owns is omitted. Each description is cut to about 40 tokens by the same CJK-aware estimate, and envelope tags inside a description are escaped.+ - *Note:* `openclaw` does not perform profile injection. Hermes uses its own session-start reader for the user profile and preferences/entities listings, with a default `profile_token_budget` of 6000.+- **Skill catalog** (`<available-skills>`): `buildProfileBlock()` appends it inside the same `<openviking-context>` envelope, after `<user-profile>` and `<available-memories>`, so each harness using the shared profile loader injects it together with the profile (codex covers trae-cli). One `GET /api/v1/skills?node_limit=200` returns the user's own skills and the account-shared `viking://agent/skills`. Own skills are listed first, and a shared skill whose name the user also owns is omitted. Each description is cut to about 40 tokens by the same CJK-aware estimate, and envelope tags inside a description are escaped.- **Budget and switch**: `skillCatalogTokenBudget` (default 1200 tokens, range 0-20000, env `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`) is the block's own budget and is not taken from `profileTokenBudget`. `skillCatalog` (default true, env `OPENVIKING_SKILL_CATALOG`) turns the block on or off, and a budget of 0 also turns it off. Both are declared in `config-schema.mjs`, so the ovcli.conf `plugin` / `plugin.<harness>` sections set them like any other knob.- **Degradation**: Every entry is listed with its description when that fits. Otherwise the block lists names only, and if even the names do not all fit, it ends with `... +N more, search OpenViking skills to find the rest`. When not even one name fits, it shrinks to a single line, `<available-skills>N OpenViking skills; search OpenViking skills to find them.</available-skills>`. With no skills, or on a server without `GET /api/v1/skills`, the block is omitted.- **Size cap**: `sessionStartMaxBytes` (env `OPENVIKING_SESSION_START_MAX_BYTES`) caps the whole session-start context in UTF-8 bytes: 9500 for claude-code and codex, whose hosts save hook context over about 10,000 characters or bytes to a file and show only a preview, 20000 for zcode, which drops stdout over 32 KB, and no cap elsewhere. Under it the budgets shrink; if the block still does not fit, the memory index is dropped first, then the skill catalog. On resume/compact the session archive takes up to half, truncated with a pointer to `viking://~/sessions/<id>/history/`, and on resume claude-code and codex skip a profile block identical to the one the session already received.@@ -404,14 +409,14 @@ Legend: **C** = commits; **C\*** = commits, with a precondition (see notes); **| pi (takeover default) | **—** (`session_shutdown` fires on every shutdown path and is awaited, but the handler persists local takeover state and does not commit) | **—** | **—** | **—** | **—** | The next run accumulating 30000, or a manual `/viking commit` || pi (takeover off) | **C** (`await sync.commit()`, failures go to the pending queue) | **C** | **C** | **C** | **—** | — || openclaw | **—** (upstream sends an awaited `session_end(reason=shutdown\|restart)`; the handler caches agentId and returns without triggering a commit; `gateway_stop` is not registered; no signal handling) | **—** | **—** | **—** | **—** | Explicit `/new` `/reset` and the ~50% threshold; sessions below the threshold rely on these two paths for archiving |-| hermes | **C** (atexit `_run_cleanup` → 10s flush → on_session_end) | **C** (both interactive and non-interactive trigger atexit) | **C** (`_signal_handler`, grace period defaults to 1.5s → clean exit → atexit) | **C** (SIGHUP follows the same path as SIGTERM) | **—** (atexit does not run) | If the drain does not finish, this round aborts the commit (avoiding a half-written commit); an exit watchdog kills slow commits at 30s |+| hermes | **C\*** (atexit `_run_cleanup` → 10s flush → on_session_end) | **C\*** (both interactive and non-interactive trigger atexit) | **C\*** (`_signal_handler`, grace period defaults to 1.5s → clean exit → atexit) | **C\*** (SIGHUP follows the same path as SIGTERM) | **—** (atexit does not run) | If the drain does not finish, this round aborts the commit (avoiding a half-written commit); the Hermes exit watchdog can interrupt a slow commit || ov CLI | n/a (one-shot command) | n/a | n/a | n/a | n/a | No pending queue; just re-run a failed command |-| ingest | **C** (`finally _flush_all`) | **C** (SIGINT → stop) | **C** | **—** (no SIGHUP handler) | **—** | The only write path offering crash recovery: `needs_commit` is persisted in the cursor store, and the subsequent run's reconciliation completes the commit |+| ingest | **C** (`finally _flush_all`) | **C** (SIGINT → stop) | **C** | **—** (no SIGHUP handler) | **—** | Crash recovery through the cursor store: `needs_commit` is persisted in the cursor store, and the subsequent run's reconciliation completes the commit || LangChain / Open WebUI / Agent Plugins / generic MCP | **—** (no session lifecycle hooks; the `DELETE /mcp` sent by an MCP proxy on exit only releases the protocol session and does not trigger memory commits) | — | — | — | — | LangChain relies on the caller's `close()`; the in-process pending-commit set disappears alongside the process |**Three reading notes**:-1. Five integrations commit on a normal exit: `claude-code`, `opencode` (≥1.15.11), `dsh`, `pi` (takeover off), and `hermes`. The rest rely on the recovery mechanisms detailed in the "recovery path" column.+1. Five integrations attempt a commit on a normal exit: `claude-code`, `opencode` (≥1.15.11), `dsh`, `pi` (takeover off), and `hermes`. The rest rely on the recovery mechanisms detailed in the "recovery path" column.2. No integration commits under `kill -9` — messages already submitted remain in the server's live area and are archived the next time the same session triggers a commit. The server offers a per-session idle fallback ([§2.3](#_2-3-server-side-session-and-commit-semantics)), which the current plugins do not utilize by default.3. `trae×2` and `zcode`, which commit on every turn, offer the simplest shutdown semantics (the maximum data left to archive equals the last round that never reached Stop), at the cost of a full archive and memory extraction on every Stop (keep 0).@@ -421,9 +426,9 @@ Legend: **C** = commits; **C\*** = commits, with a precondition (see notes); **|---|---|---|| cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi | On-disk queue `~/.openviking/pending` (0700/0600) | Only retryable failures are queued (4xx errors, including 401/403, are considered non-retryable and are not queued, though they appear in debug logs); replay runs at session start: ≤50 entries per run, ≤3 attempts per entry, TTL 7 days; `.processing` claims entries atomically, with a 10min stale reclaim; an addMessage failure breaks execution immediately to preserve order || openclaw | No local queue | An addSessionMessage failure is caught, and that turn's messages are not replayed |-| hermes | In-process daemon-thread queue | The drain operates on a strict budget (10s/65s); nothing is written to disk |+| hermes | In-process upload threads; pending-commit markers under `$HERMES_HOME/openviking/pending_sessions/` | On POSIX, startup recovery commits sessions left pending by dead runs. Unsent messages are not replayed from disk. || LangChain | In-process `_pending_commit_sessions` set | A failed commit is retried automatically during the next record; nothing is written to disk. On partial success, it raises an `OpenVikingPartialWriteError` (carrying `messages_written`, `input_messages_consumed`, and `context_attached`, allowing the caller to slice by position and retry the suffix) — making this the only protocol across all integrations that reports partial success |-| ingest | SQLite cursor store + single-instance lock | The intent is persisted before appending. After a crash, a reconciliation process checks the server's message count to determine if the batch landed—making this the only write path with true crash-recovery semantics |+| ingest | SQLite cursor store + single-instance lock | The intent is persisted before appending. After a crash, a reconciliation process checks the server's message count to determine if the batch landed—providing recovery of partially delivered batches |### 3.3.5 subagent session comparison@@ -492,7 +497,7 @@ There are three primary guards on MCP `write` and REST `content/write` (`content**Tier 3: The two memory-only delete surfaces.**- In openclaw's `memory_forget`, three regex whitelists restrict deletions strictly to `viking://user/[…/]memories`, `viking://user/<u>/peers/<p>/memories`, and `viking://agent/[…/]memories`. Explicit URIs failing to match these are refused outright. Search-path candidates must pass this same guard first; automatic deletion only proceeds if a candidate is unique and scores ≥ 0.85. Otherwise, candidates are listed so the agent can explicitly select one. The underlying URL always pins `recursive=false`.-- In hermes' `viking_forget`, there are six sequential validations: non-string or empty inputs are refused; a scheme other than `viking://` is refused; queries or fragments are refused; directories or any files not ending in `.md` are refused; the path must match one of four permitted memory path structures and contain at least two additional segments after the `memories` segment (ensuring `memories/` and its category directories are never deleted); finally, the filename must not be `.abstract.md` or `.overview.md`.+- Hermes `viking_forget` rejects empty inputs, non-`viking://` URIs, query/fragment suffixes, directories, non-`.md` files, and generated `.abstract.md`/`.overview.md` summaries. The bundled validator accepts user-memory layouts, including files directly under `memories/`; `memories/profile.md` is allowed. Use the server-returned URI with an explicit user ID. The external plugin also supports `viking://~/...`, rejects deprecated UID-less layouts, and verifies ownership before sending an explicit-user deletion.**Tier 4: No deletion offered by default (LangChain / Open WebUI).** LangChain's `viking_forget` is only exposed as a tool when configured with `profile="admin"` or `allow_forget=True`. Open WebUI does not offer any deletion tools.@@ -510,7 +515,7 @@ There are three primary guards on MCP `write` and REST `content/write` (`content| dsh | The client swallows all exceptions; `ensureState` failures are not cached (when the server is unreachable, each pre-step makes two 5s health calls) | context-face 6h + an in-process user-space cache that never expires | None; pending queue replays 3 times across processes | Yes (pre-step runs profile+recall serially; session/flush blocks) || pi | On health failure, `start()` returns early and registers no tools; subsequent prompts silently retry the connection. A `/mcp` handshake that fails on its own (401/403, timeout, no `/mcp`) never fails startup: recall, sync and takeover carry on, the status line shows `tools ✗`, and `/viking` prints the full error | context-face 6h; the handshake has none, so a still-failing bridge is retried once per turn and can spend its 5s budget before recall is queued | Hooks: none, pending queue only. A failed MCP transport is discarded and the next invocation reconnects; the failed call is never replayed | Partly (`session_shutdown` is awaited: ~0s with takeover, max 30s without, plus closing the MCP client; on a `turn_end` network error, each message waits 10s) || openclaw | Client construction never fails; health checks swallow exceptions; recall is skipped if the 500ms precheck fails | No negative cache (one 500ms health precheck per turn) | None (a single fetch); Phase2 polling in commit/afterTurn | No (except when `memory_store` re-raises; `compact()` blocks for up to 5 minutes) |-| hermes | `_client=None` acts as the runtime negative cache (stops retrying in the current process, except for the local auto-start waiter) | No separate structure (`_client=None` handles this) | One retry with a trusted identity, one retry with a fresh sync client, multi-tier degradation; failed commits are not retried | No (a single background worker + per-provider try/except) |+| hermes | 30s cooldown for unchanged failed connection settings; changed settings trigger a new probe | `_failed_refresh` tracks the failed settings | Trusted-identity and sync-client retries; dead-run pending commits recovered on startup (POSIX) | No || ov CLI | Mostly exits with 1; `ov status` in table mode always exits with 0; `ov health` exits with 0 even when unhealthy | None | Only one retry on a gateway 401 challenge | n/a (no host) |### 3.6.2 Common timeouts@@ -530,7 +535,7 @@ General HTTP timeouts are 15000ms (with a 1000ms floor). MCP proxy requests time| dsh | ❌ | ❌ | 2 skills, `openviking-memory` and `openviking-skills` (own isolated `ctx.skills` provider) | ❌ | `ctx.provide("openvikingMemory")` allows other Cordis plugins to build upon it || pi | ✅ `ctx.ui.setStatus` | ✅ `/viking` `/viking commit` | None | ✅ | `e2e-live.sh` || openclaw | ❌ | ✅ 5 commands (`/add-resource`, `/add-skill`, `/ov-search`, `/ov-query-config`, `/ov-recall-trace`) | 3 skills shipped with the plugin | ✅ (Key role detection, version compatibility checks, and a `status` command) | Gateway HTTP routes for visualizing recall traces; feature-gated RPCs; health-check script |-| hermes | ❌ | ❌ | None | ✅ Multi-level curses menus | `hermes memory status` (includes env override lists); `hermes backup` covers `ovcli.conf` |+| hermes | ❌ | ❌ | None | ✅ Multi-level curses menus | `hermes memory status` (includes env override lists); `hermes backup` includes the default or env-selected `ovcli.conf` under `$HOME`; back up YAML-linked named files separately || ov CLI | ❌ | ❌ (The CLI itself acts as the command) | None | ✅ TUI wizard | Comprehensive help system (63 curated entries); language gating; `ov tui` full-screen file browser (includes in-terminal image previews) |---@@ -638,10 +643,11 @@ Each card serves as a quick-reference entry point. It records only the facts and## hermes (Nous Research)- **Integration docs**: [Hermes Agent](./05-hermes.md)-- **Form**: Implemented as a MemoryProvider bundled directly with Hermes (a single-file Python implementation of 3725 lines, shipped alongside Hermes). It connects directly via `httpx`, eliminating the need for additional plugin installations. It provides 6 tools and over 10 lifecycle hooks (including `prefetch`, `sync_turn`, `on_session_end`, `on_session_switch`, and `on_memory_write`). The baseline is release `e12626b3` (equivalent to brew 2026.7.7.2).-- **Highlights**: Boasts the most comprehensive resource-ingestion surface: `viking_add_resource` supports HTTP, Git, SSH, `file://`, temporary uploads of local files, and zip-packing local directories for upload (automatically skipping symlinks and out-of-tree files). The `viking_remember` tool writes memory files directly, bypassing session commits or extractions. A local server can be initialized on demand; if the configured local endpoint is unreachable, it is automatically launched via `subprocess.Popen openviking-server`. It supports retries with an injected trusted identity. Commits are guaranteed to complete whether triggered by a normal exit, Ctrl+C, SIGTERM, or SIGHUP ([§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)).-- **Behavior**: During recall, only the preferred `search/search` path carries a session ID and routes to path B (`mode="deep"`). Conversely, the `auto` and `fast` modes call `/find` without a session ID ([§3.2.2](#_3-2-2-decision-matrix)). The `queue_prefetch` hook is implemented synchronously without warm-up. Subagents configured with `skip_memory=True` will not interact with OpenViking ([§3.3.5](#_3-3-5-subagent-session-comparison)). This integration lacks profile injection, a status line, and slash commands. Commits strictly follow a "keep 0" policy; if the queue drain does not finish cleanly, the commit is skipped for that round. Additionally, the in-process queue is never written to disk. Session IDs follow the `%Y%m%d_%H%M%S_<hex6>` format. Recall parameters are strictly defined: 6 results, a 0.15 threshold, a 4000-character budget, and a 4-second total timeout. Memory URIs are formatted as `viking://~/peers/{agent}/memories/{subdir}/mem_<uuid12>.md`. The shutdown sequence incorporates a 1.5-second SIGTERM grace period alongside a 30-second exit watchdog. Finally, a complementary path (`openviking-server ingest hermes`) enables offline replays, though this is disabled by default ([§7](#_7-appendix-non-coding-integrations-at-a-glance) E).-- **Config**: Configured through `OPENVIKING_ENDPOINT` (not `_URL`), 8 `OPENVIKING_RECALL_*` environment variables, and `config.yaml`. In `use_ovcli_config` mode, the corresponding variables in `.env` are cleared.+- **Form**: A bundled `MemoryProvider` using HTTP, with six `viking_*` tools. OpenViking runs in a separate server environment. The external plugin is maintained separately; see the scope note above.+- **Memory writes**: `viking_remember` submits an unchanged fact through a dedicated session and commits it for asynchronous extraction. It returns `status: submitted`; extraction may add, merge, or skip the fact. The bundled provider mirrors native memory additions only. The external plugin adds mapped replacement and deletion; see its README.+- **Recall**: Synchronous query recall uses session-aware `search/search`, then `/find` as a fallback. `queue_prefetch` is a no-op. Session-start injection reads the user profile and preferences/entities listings (6000-token default). Query recall defaults to 6 results, score threshold 0.15, 4000 characters, and a 4s total / 3s per-request timeout. These values are configurable.+- **Lifecycle**: Commits keep 0 messages. Upload threads are not durable, but pending-commit markers support dead-run recovery on POSIX. Normal exits and signals attempt to drain and commit; network failures or forced termination can interrupt this. Delegated agents with `skip_memory=True` do not load the provider. No status line or provider slash commands are added.+- **Paths and config**: Memory writes use `viking://user/<uid>/memories/...`, or `viking://user/<uid>/peers/<peer>/memories/...` when a peer is configured. No assistant peer is set by default. Connection settings use `OPENVIKING_ENDPOINT`, profile secrets, linked `ovcli.conf`, and Hermes YAML. Linking an OpenViking profile clears the five connection variables from the Hermes `.env`.- **Dimension index**: tool surface [§1.1](#_1-1-active-tool-surface-agentic-calls) | recall [§3.2](#_3-2-automatic-recall-and-injection) | commit [§3.3.2](#_3-3-2-regular-commit-triggers)/[§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix) | deletion [§3.5](#_3-5-type-boundaries-for-writes-and-deletes).## ov CLI@@ -752,7 +758,7 @@ If you need the full spectrum of automation—recall, capture, commit, and pendi| **B. [LangChain/LangGraph](./07-langchain-langgraph.md)** | Python SDK adapter layer (retriever/tools/store/middleware/recorder) | `create_openviking_tools()` provides 12 StructuredTools (`viking_forget` is not in the agent profile by default) | `thread_id`/`session_id` come from the caller; `CommitPolicy` defaults to `never` | Most robust in this group: read-only methods automatically retry once, writes never retry (to prevent duplicates), and partial successes raise a structured exception that can be retried as a slice. | Requires explicit construction before taking effect. || **C. [Agent Plugins 1.0](./15-agent-plugins.md)** | Portable package: `plugin.json` + `skills/` + `mcp.json` (stdio→HTTP proxy) | MCP passthrough for all 16 tools; intentionally excludes hooks (recall relies on a skill instructing the model). | Only `remember` creates a temporary session | Retries handled at the MCP proxy layer (401/403 triggers credential swap, 400/404 triggers re-initialization; max 1 retry each). | Active as soon as loaded by the client. || **D. [Direct MCP Connection](./06-mcp-clients.md)** | No local components, connects straight to `/mcp` | Same as C (16 tools) | Same as C | Depends entirely on the client. | `/mcp` is always on. |-| **E. [Log Ingestion](./09-log-ingestion.md)** | `openviking-server ingest` CLI (runs on the machine hosting the logs, importing them in reverse) | None (write-only, no recall) | Session ID `{prefix}__{harness}__{sanitized native id}`; commit token 6000 / idle 5s / keep 0 | The only integration featuring crash recovery: utilizes a SQLite cursor store, single-instance locking, and a reconciliation process to verify batch delivery. | Disabled by default on two levels (`ingest.enabled` and each harness's individual `enabled` flag are both false); adapters available for claude_code, codex, hermes, opencode, openclaw, and cursor. |+| **E. [Log Ingestion](./09-log-ingestion.md)** | `openviking-server ingest` CLI (runs on the machine hosting the logs, importing them in reverse) | None (write-only, no recall) | Session ID `{prefix}__{harness}__{sanitized native id}`; commit token 6000 / idle 5s / keep 0 | Crash recovery: utilizes a SQLite cursor store, single-instance locking, and a reconciliation process to verify batch delivery. | Disabled by default on two levels (`ingest.enabled` and each harness's individual `enabled` flag are both false); adapters available for claude_code, codex, hermes, opencode, openclaw, and cursor. || **F. [OpenViking Helper](./14-openviking-helper.md)** | Closed-source desktop app | — | — | — | Outside the scope of this codebase. |---diff --git a/docs/images/agents/en/hermes.md b/docs/images/agents/en/hermes.mdindex 46ce743c3..2b2b1f13d 100644--- a/docs/images/agents/en/hermes.md+++ b/docs/images/agents/en/hermes.md@@ -6,7 +6,8 @@hermes memory setup openviking```-2. The wizard first asks for the configuration source:+2. If local `ovcli.conf` profiles exist, the wizard asks for the configuration+ source. Otherwise, it starts creating a new configuration:```textOpenViking config source@@ -36,8 +37,7 @@{{OPENVIKING_API_KEY}}```-5. Fill in **Hermes peer ID in OpenViking**. This identifies the Hermes Agent in OpenViking so memories produced by different Agents can be separated. Press Enter to use the default `hermes`, or enter a custom value.-6. Choose how to save the configuration. We recommend **Mirror to OpenViking store**:+5. Choose how to save the configuration. We recommend **Mirror to OpenViking store**:```textSave OpenViking config@@ -46,8 +46,8 @@→ (●) Mirror to OpenViking store - write ~/.openviking/ovcli.conf.<name> and link it```-7. Fill in **OpenViking profile name**. Hermes' multi-tenant capabilities can isolate models, memories, configuration, and credentials across Profiles. We recommend configuring an independent OpenViking environment or identity for each Hermes Profile, and using an easy-to-recognize local name here. This name is local only; it does not create a new user or change account identity or permissions.-8. When setup completes, Hermes shows:+6. Fill in **OpenViking profile name**, for example `hermes`. Hermes' multi-tenant capabilities can isolate models, memories, configuration, and credentials across Profiles. We recommend configuring an independent OpenViking environment or identity for each Hermes Profile, and using an easy-to-recognize local name here. This name is local only; it does not create a new user or change account identity or permissions.+7. When setup completes, Hermes shows:```textOpenViking memory is ready@@ -56,6 +56,10 @@Start a new Hermes session to activate.```+New connections use user memory without an assistant peer. Setup does not ask+for a peer ID. To separate assistant context, set `memory.openviking.agent` in+the active Hermes profile's `config.yaml`. Existing peer memories are not moved.+## Step 2: Verify1. Check the memory plugin status:@@ -64,7 +68,8 @@hermes memory status```-2. A result similar to the following means the integration is successful:+2. Confirm that OpenViking is selected and configured. `available` does not+ check server connectivity or confirm memory extraction:```textMemory status@@ -78,21 +83,11 @@openviking config:use_ovcli_config: Trueovcli_config_path: ~/.openviking/ovcli.conf.hermes- endpoint: `https://api.vikingdb.cn-beijing.volces.com/openviking`- agent: hermes+ endpoint: https://api.vikingdb.cn-beijing.volces.com/openvikingPlugin: installed ✓Status: available ✓- Installed plugins:- • byterover (API key / local)- • hindsight (API key / local)- • holographic (local)- • honcho (API key / local)- • mem0 (API key / local)- • openviking (API key / local) ← active- • retaindb (API key / local)- • supermemory (requires API key)```## Troubleshoot@@ -100,7 +95,7 @@| Problem | Fix ||---|---|| Provider is not openviking | Re-run `hermes memory setup openviking` |-| Status is not available | Check the API key |+| Status is not available | Check the configured endpoint and linked OpenViking config file |## Referencediff --git a/docs/images/agents/zh/hermes.md b/docs/images/agents/zh/hermes.mdindex f8dc58ba9..e2b996577 100644--- a/docs/images/agents/zh/hermes.md+++ b/docs/images/agents/zh/hermes.md@@ -6,7 +6,7 @@hermes memory setup openviking```-2. 执行后将出现配置来源选择界面:+2. 如果本地已有 `ovcli.conf` 配置,向导会询问配置来源;否则会直接开始创建新配置:```textOpenViking config source@@ -36,8 +36,7 @@{{OPENVIKING_API_KEY}}```-5. 填写「Hermes peer ID in OpenViking」:该字段为 Hermes 在 OpenViking 中的 Agent 身份标识,用于区分不同 Agent 产生的记忆。可直接按 Enter 使用默认值「hermes」,也可自定义填写。-6. 选择配置保存方式,建议选择「Mirror to OpenViking store」:+5. 选择配置保存方式,建议选择「Mirror to OpenViking store」:```textSave OpenViking config@@ -46,8 +45,8 @@→ (●) Mirror to OpenViking store - write ~/.openviking/ovcli.conf.<name> and link it```-7. 填写「OpenViking profile name」:Hermes 的多租户能力可隔离不同 Profile 的模型、记忆、配置及凭据。建议为每个 Hermes Profile 配置独立的 OpenViking 环境或身份,并在此填写一个便于识别的本地配置名称,以区分对应的 OpenViking 配置。该名称仅用于本地标识,不会创建新用户,也不会改变账号身份或权限。-8. 配置完成后将显示如下确认信息:+6. 填写「OpenViking profile name」,例如 `hermes`:Hermes 的多租户能力可隔离不同 Profile 的模型、记忆、配置及凭据。建议为每个 Hermes Profile 配置独立的 OpenViking 环境或身份,并在此填写一个便于识别的本地配置名称,以区分对应的 OpenViking 配置。该名称仅用于本地标识,不会创建新用户,也不会改变账号身份或权限。+7. 配置完成后将显示如下确认信息:```textOpenViking memory is ready@@ -56,6 +55,10 @@Start a new Hermes session to activate.```+新连接默认使用用户记忆,不设置助手 peer;向导不再询问 peer ID。如需隔离助手+上下文,可在当前 Hermes profile 的 `config.yaml` 中设置 `memory.openviking.agent`。+已有的 peer 记忆不会迁移。+## 步骤2:验证1. 执行以下命令验证记忆插件状态:@@ -64,7 +67,7 @@hermes memory status```-2. 返回如下结果即表示接入成功:+2. 确认已选择并配置 OpenViking。`available` 不会检查服务端连通性,也不代表记忆已完成抽取:```textMemory status@@ -78,21 +81,11 @@openviking config:use_ovcli_config: Trueovcli_config_path: ~/.openviking/ovcli.conf.hermes- endpoint: `https://api.vikingdb.cn-beijing.volces.com/openviking`- agent: hermes+ endpoint: https://api.vikingdb.cn-beijing.volces.com/openvikingPlugin: installed ✓Status: available ✓- Installed plugins:- • byterover (API key / local)- • hindsight (API key / local)- • holographic (local)- • honcho (API key / local)- • mem0 (API key / local)- • openviking (API key / local) ← active- • retaindb (API key / local)- • supermemory (requires API key)```## 故障排查@@ -100,7 +93,7 @@| 问题 | 处理 ||---|---|| Provider 不是 openviking | 重跑 `hermes memory setup openviking` |-| Status 不是 available | 检查 API Key |+| Status 不是 available | 检查 endpoint 配置和关联的 OpenViking 配置文件 |## 参考diff --git a/docs/zh/agent-integrations/05-hermes.md b/docs/zh/agent-integrations/05-hermes.mdindex f40a96bb2..25b7219dd 100644--- a/docs/zh/agent-integrations/05-hermes.md+++ b/docs/zh/agent-integrations/05-hermes.md@@ -27,6 +27,8 @@ hermes memory setup openvikinghermes memory status```+`available` 表示 provider 已配置,不会检查服务端连通性,也不代表记忆已完成抽取。+## 参见- [集成能力参考](./16-capability-reference.md)diff --git a/docs/zh/agent-integrations/16-capability-reference.md b/docs/zh/agent-integrations/16-capability-reference.mdindex 0a2806bdf..7f4a2c15d 100644--- a/docs/zh/agent-integrations/16-capability-reference.md+++ b/docs/zh/agent-integrations/16-capability-reference.md@@ -1,5 +1,10 @@# 集成能力参考+**Hermes 范围**:表中的 Hermes 描述其[内置 provider](https://github.com/NousResearch/hermes-agent/tree/989798cd5e691230b54b2ea72e5937b68133014c/plugins/memory/openviking),+核对版本为 Hermes main `989798cd5e`。[OpenViking 维护的外部插件](https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin)+另有提交、召回和镜像改进。内置副本仍在时优先加载;正常使用请按+[配置指南](./05-hermes.md)操作。+## 导读| 你想知道 | 去哪里 |@@ -37,7 +42,7 @@| dsh | MCP 透传 | 16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² || pi | MCP 镜像(官方客户端;扩展加 `openviking_` 前缀) | 16,即 `tools/list` 返回什么就是什么(注册有前置条件³) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ `add_skill`¹ | 无类型区分² || openclaw | 原生注册(15 个 `memory_*`/`ov_*` 等) | 15(默认开 14⁴) | ✅ `memory_recall` | ✅ `ov_search`(默认双 scope) | ✅ `ov_search` | ✅ `memory_store` | 默认关⁴ | ✅ `add_skill` | memory-only 白名单 + 单候选 score≥0.85 才自动删 |-| hermes | 原生注册(6 个 `viking_*`) | 6(provider 激活即全开) | ✅ | ✅ | ✅ | ✅ `viking_remember`(直写文件,不走抽取) | ✅ 多协议摄取(HTTP/Git/SSH/本地文件/目录 zip) | ❌ | memory-only + `.md` 叶子校验 |+| hermes | 原生注册(6 个 `viking_*`) | 6(provider 激活即全开) | ✅ | ✅ | ✅ | ✅ `viking_remember`(独立会话提交,异步抽取) | ✅ 多协议摄取(HTTP/Git/SSH/本地文件/目录 zip) | ❌ | memory-only + `.md` 叶子校验 || ov CLI | CLI 命令 | ~40 命令组 | ✅ `ov find` | ✅ `ov find` | ✅ `ov find` | ✅ `ov add-memory` | ✅ `ov add-resource` | ✅ `ov add-skill` | `ov rm` 直接执行(TUI 删除有确认 + root/scope 禁删) |¹ MCP `write` 拒绝写用户自己的 `skills/` 子树;写 `viking://agent/skills` 时会生成一个绕过 skill 安装流程的普通文件(没有 frontmatter abstract,也不做 privacy 抽取),所以共享 skill 同样要走 `add_skill`。skill 的新建、安装和替换走 MCP `add_skill` 工具(内联 SKILL.md 文本、Git URL,或本地目录/zip 的签名上传),它和 REST `POST /api/v1/skills` 共用同一套安装实现。@@ -61,7 +66,7 @@| dsh | Cordis 原生插件(同进程)+ MCP 代理 + skill | ✅ | ✅ | ❌ | ✅(10000)+ `<available-skills>`(1200),每 session 一次 | ❌ | ✅ | ❌ || pi | 原生扩展(9 事件) | ✅ | ✅ | ❌ | ✅(10000)+ `<available-skills>`(1200),进 systemPrompt 每轮重拼 | ✅ **takeover**(默认开) | ✅ | ✅ || openclaw | context-engine 插件(`ownsCompaction:true`) | ✅ | ❌(走 `/find`,该接口无 session_id 字段) | ❌ | ❌ | ✅ **ContextEngine 全接管** | ❌ 失败轮次不重放 | ❌ |-| hermes | MemoryProvider 原生插件 | ✅ | 部分(仅 `search/search` 首选路径;降级 `/find` 不带) | ❌ | ❌(静态工具指引块) | ❌ | ✅ 进程内队列(不落盘) | ❌ |+| hermes | MemoryProvider 原生插件 | ✅ | 部分(仅 `search/search` 首选路径;降级 `/find` 不带) | ❌ | ✅(会话开场记忆预算默认 6000 token) | ❌ | ✅ 进程内上传;待提交标记落盘 | ❌ || ov CLI | 一次性命令 | ❌(`ov find/search` 是显式命令) | —(`ov search --session-id` 为显式参数) | ❌ | ❌ | ❌ | ❌ | ❌ |\* 此列指客户端是否内建了针对召回结果的本地压缩;服务端则在 context 检索面上,统一为所有调用方提供 digest 能力(`rewrite` 参数,[§3.2.5](#_3-2-5-召回再摘要))。@@ -181,7 +186,7 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章| dsh | Cordis 同进程插件(`cordis.patch.yml` 条目) | 统一安装器(会询问 profile,默认 `web`),或执行 `dsh plugin --profile web add @openviking/dsh-memory-plugin` | `dsh-<session.id 原样>`;subagent 各自独立会话 | env + ovcli.conf `plugin.dsh` + cordis patch config(行为旋钮的最低层;凭据仍以 patch 优先) | ❌ || pi | pi 原生扩展(目录装载,jiti 直译 TS) | 一键 `--harness pi`(复制到自动发现目录,无需 `pi install`) | `pi-<piSessionId>` | env + ovcli.conf `plugin.pi`(凭据字段由凭据链统一解析) | ✅ || openclaw | context-engine 插件(`ownsCompaction:true`)+ 15 工具 + 5 slash + 4 hook + HTTP 路由 | ClawHub 执行 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 搭配 `openclaw openviking setup` / npm 安装器 / TOS 离线包 | UUID 原样小写,否则 `sha256(sessionKey)`;`memory_store` 临时会话 `memory-store-<ts>-<rand>` | `openclaw.json` 的 `plugins.entries.openviking.config`(严格校验:存在未知键/非法值时插件进入 setup-only 模式)+ 少量 env | ✅ `openclaw openviking setup`(交互/非交互 + key 角色探测 + 版本兼容检查) |-| hermes | Hermes bundled MemoryProvider(随 Hermes 发布,无需装插件) | 执行 `hermes memory setup openviking`(curses 向导)或手动 `config set memory.provider openviking` + `.env` | 由 Hermes 生成 `%Y%m%d_%H%M%S_<hex6>`,插件原样使用 | `.env`(`OPENVIKING_*`)或 ovcli.conf 联动(`use_ovcli_config` 模式会清空 .env 里的 5 个对应变量)+ config.yaml | ✅(多层菜单) |+| hermes | Hermes bundled MemoryProvider(随 Hermes 发布,无需装插件) | 执行 `hermes memory setup openviking`(curses 向导)或手动 `hermes config set memory.provider openviking` + `.env` | 由 Hermes 生成,插件原样使用 | `.env`(`OPENVIKING_*`)或 ovcli.conf 联动(`use_ovcli_config` 模式会清空 .env 里的 5 个对应变量)+ config.yaml | ✅(多层菜单) || ov CLI | Rust 原生二进制 | npm `@openviking/cli` / `uv tool install openviking` / cargo / GitHub Releases | 无自有会话(`ov chat` 默认使用 machine-uid) | `ovcli.conf`(多 profile)+ 少量 env | ✅ `ov config`(TUI 向导) |### 3.1.2 统一安装器@@ -240,7 +245,7 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章**迁移**(无需用户操作):旧 peer id 是 cwd 的纯函数,客户端随时可以本地重算,召回仍能覆盖到写在它名下的记忆。默认 `peer_scope: "all"` 下,服务端本就有的跨 peer 扫描零成本地把它包含在内;`peer_scope: "actor"` 下插件会另外向该 peer 发一次召回并拼接结果。此事没有截止期限。-openclaw 的 peer 由 `peer_role`/`peer_prefix` 推导(`peer_role=sender` 时需保证 sender 信息可用,否则工具调用报错;旧值 `person` 作为别名兼容);hermes 的 peer 就是 `OPENVIKING_AGENT`(默认 `hermes`)。+openclaw 的 peer 由 `peer_role`/`peer_prefix` 推导(`peer_role=sender` 时需保证 sender 信息可用,否则工具调用报错;旧值 `person` 作为别名兼容);Hermes 的助手 peer 可由 `OPENVIKING_AGENT`、关联的 OpenViking 配置或 YAML `agent` 指定;默认不设置。### 3.1.4 配置体系分层@@ -296,8 +301,8 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处### 3.2.3 profile / 开场注入- **实现**:`profile-inject.mjs`——读 `viking://user/<space>/memories/profile.md` 全文 + `preferences/`、`entities/` 递归清单(abs_limit=512)。预算估算引入 CJK 感知(≥U+3000 记 1.5 token/字,其余 chars/4);profile 占一半预算,超限则采用"头 8 行 + 尾部"的中段省略;清单超限时会再撤掉几条,直到放得下 `... +N more` 提示。-- **谁注入、何时、预算**:claude-code(SessionStart 全部 source,10000);codex(SessionStart startup/clear/resume,10000);cursor/trae×2/zcode(SessionStart,10000,2s 去抖);opencode(每会话首条 chat.message 一次,10000,进程内 Set 去重,subagent 会话跳过;注意开场注入每会话只尝试一次,失败后本进程内不重试);dsh(每 session 投一次 `profileDelivered`,10000;compaction 之后不重投);pi(进 systemPrompt,每个 prompt 重拼,10000 常驻)。openclaw、hermes 无 profile 注入。-- **skill 清单**(`<available-skills>`):由 `buildProfileBlock()` 追加在同一个 `<openviking-context>` 信封里,排在 `<user-profile>` 和 `<available-memories>` 之后,所以上面每个 harness 都会随 profile 一起注入它(codex 覆盖 trae-cli)。数据来自一次 `GET /api/v1/skills?node_limit=200`,包含用户自己的 skill 和账户共享的 `viking://agent/skills`:自己的排在前面,和自己某个 skill 同名的共享 skill 不再列出。每条描述按同一套 CJK 感知估算截到约 40 token,描述里出现的信封标签会被转义。+- **谁注入、何时、预算**:claude-code(SessionStart 全部 source,10000);codex(SessionStart startup/clear/resume,10000);cursor/trae×2/zcode(SessionStart,10000,2s 去抖);opencode(每会话首条 chat.message 一次,10000,进程内 Set 去重,subagent 会话跳过;注意开场注入每会话只尝试一次,失败后本进程内不重试);dsh(每 session 投一次 `profileDelivered`,10000;compaction 之后不重投);pi(进 systemPrompt,每个 prompt 重拼,10000 常驻)。openclaw 无 profile 注入。Hermes 使用独立的开场读取逻辑,注入用户 profile 及 preferences/entities 清单,`profile_token_budget` 默认 6000。+- **skill 清单**(`<available-skills>`):由 `buildProfileBlock()` 追加在同一个 `<openviking-context>` 信封里,排在 `<user-profile>` 和 `<available-memories>` 之后,所以上述使用共享 profile 加载器的 harness 都会随 profile 一起注入它(codex 覆盖 trae-cli)。数据来自一次 `GET /api/v1/skills?node_limit=200`,包含用户自己的 skill 和账户共享的 `viking://agent/skills`:自己的排在前面,和自己某个 skill 同名的共享 skill 不再列出。每条描述按同一套 CJK 感知估算截到约 40 token,描述里出现的信封标签会被转义。- **预算与开关**:`skillCatalogTokenBudget`(默认 1200 token,取值 0-20000,env `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`)是这一块自己的预算,不占 `profileTokenBudget`。`skillCatalog`(默认 true,env `OPENVIKING_SKILL_CATALOG`)控制开关,预算设为 0 同样关闭。两者都在 `config-schema.mjs` 中声明,因此和其他旋钮一样,也能在 ovcli.conf 的 `plugin` / `plugin.<harness>` 段里设置。- **降级**:放得下时每条都带描述;放不下就只列名称,名称也列不全时以 `... +N more, search OpenViking skills to find the rest` 收尾;连一个名称都放不下时,只剩一行 `<available-skills>N OpenViking skills; search OpenViking skills to find them.</available-skills>`。没有任何 skill,或服务端没有 `GET /api/v1/skills` 时,整块省略。- **总量上限**:`sessionStartMaxBytes`(env `OPENVIKING_SESSION_START_MAX_BYTES`)按 UTF-8 字节限制整个会话开场注入:claude-code 和 codex 为 9500,因为这两个宿主会把超过约 10,000 字符或字节的 hook 上下文存成文件、只给模型看预览;zcode 为 20000,因为它会丢弃超过 32 KB 的 stdout;其余不设上限。在上限内各项预算相应收缩,仍放不下时先去掉记忆索引,再去掉 skill 清单。resume/compact 时会话归档最多占一半,截断处附 `viking://~/sessions/<id>/history/` 指针;resume 时 claude-code 和 codex 若 profile 块与本会话上次注入的相同就不再重复注入。@@ -383,14 +388,14 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处| pi(takeover 默认) | **—**(`session_shutdown` 全关闭方式都触发且被 await,handler 持久化本地 takeover 状态,不 commit) | **—** | **—** | **—** | **—** | 下次续跑攒满 30000,或手动 `/viking commit` || pi(takeover off) | **C**(`await sync.commit()`,失败入 pending 队列) | **C** | **C** | **C** | **—** | — || openclaw | **—**(上游发 awaited `session_end(reason=shutdown\|restart)`,handler 缓存 agentId 后返回,不触发 commit;`gateway_stop` 未注册;无信号处理) | **—** | **—** | **—** | **—** | 显式 `/new` `/reset` 与 ~50% 阈值;低于阈值的会话依赖这两条路径归档 |-| hermes | **C**(atexit `_run_cleanup` → flush 10s → on_session_end) | **C**(交互与非交互最终都走 atexit) | **C**(`_signal_handler`,grace 默认 1.5s → 干净退出 → atexit) | **C**(SIGHUP 同 SIGTERM 路径) | **—**(atexit 不执行) | drain 不净时本次不 commit(避免提交半截数据);退出看门狗 30s 终止慢 commit |+| hermes | **C\***(atexit `_run_cleanup` → flush 10s → on_session_end) | **C\***(交互与非交互最终都走 atexit) | **C\***(`_signal_handler`,grace 默认 1.5s → 干净退出 → atexit) | **C\***(SIGHUP 同 SIGTERM 路径) | **—**(atexit 不执行) | drain 不净时本次不 commit(避免提交半截数据);Hermes 退出看门狗可能中断慢 commit || ov CLI | n/a(一次性命令) | n/a | n/a | n/a | n/a | 无 pending queue;命令失败重跑即可 |-| ingest | **C**(`finally _flush_all`) | **C**(SIGINT → stop) | **C** | **—**(无 SIGHUP handler) | **—** | 唯一有崩溃恢复的写路径:`needs_commit` 持久化在游标库,下次运行 reconcile 补 commit |+| ingest | **C**(`finally _flush_all`) | **C**(SIGINT → stop) | **C** | **—**(无 SIGHUP handler) | **—** | 通过游标库恢复:`needs_commit` 持久化在游标库,下次运行 reconcile 补 commit || LangChain / Open WebUI / Agent Plugins / 通用 MCP | **—**(无会话生命周期挂钩;MCP 代理退出时的 `DELETE /mcp` 只释放协议会话,与记忆 commit 无关) | — | — | — | — | LangChain 靠调用方 `close()`;进程内 pending-commit 集合随进程消失 |**三点阅读提示**:-1. 正常退出即 commit 的有五家:claude-code、opencode(≥1.15.11)、dsh、pi(takeover off)、hermes;其余各家均依赖表中"补救路径"列的回收机制。+1. 正常退出时尝试 commit 的有五家:claude-code、opencode(≥1.15.11)、dsh、pi(takeover off)、hermes;其余各家均依赖表中"补救路径"列的回收机制。2. kill -9 场景所有集成都不触发 commit——已提交的消息保留在服务端 live 区,后续同一会话再触发 commit 时一并归档;服务端提供 per-session idle 兜底能力([§2.3](#_2-3-服务端会话与-commit-语义)),当前插件默认不下发该 policy。3. 每轮必 commit 的 trae×2 / zcode 关闭语义最简单(即最大待归档量 = 最后一个未走到 Stop 的回合),代价是每个 Stop 都触发一次全量归档 + 记忆抽取(keep 0)。@@ -400,9 +405,9 @@ JS 系 harness 的召回逻辑均由 `recall-core.mjs` 中的三级降级链处|---|---|---|| cc / codex / cursor / trae×2 / zcode / opencode / dsh / pi | 磁盘队列 `~/.openviking/pending`(0700/0600) | 仅可重试的失败入队(4xx 含 401/403 判为不可重试,不入队,debug 日志可见);重放在会话启动时执行:≤50 条/次、≤3 次/条、TTL 7 天;`.processing` 原子认领,10min 陈旧回收;addMessage 失败即 break 保序 || openclaw | 无本地队列 | addSessionMessage 失败被 catch,该轮消息不重放 |-| hermes | 进程内 daemon 线程队列 | drain 有预算(10s/65s);不落盘 |+| hermes | 进程内上传线程;`$HERMES_HOME/openviking/pending_sessions/` 保存待提交标记 | POSIX 上启动时可提交已退出进程遗留的待提交会话;未上传消息不会从磁盘重放。 || LangChain | 进程内 `_pending_commit_sessions` 集合 | commit 失败下次 record 自动重试;不落盘。部分成功时抛 `OpenVikingPartialWriteError`(携带 `messages_written`、`input_messages_consumed`、`context_attached`,调用方可按位置切片重试后缀)——全部集成里唯一的部分成功上报协议 |-| ingest | SQLite 游标库 + 单实例锁 | append 前持久化意图,崩溃后 reconcile 按服务端消息数判定该批是否落地——唯一有崩溃恢复语义的写路径 |+| ingest | SQLite 游标库 + 单实例锁 | append 前持久化意图,崩溃后 reconcile 按服务端消息数判定该批是否落地——可恢复部分落地的批次 |### 3.3.5 subagent 会话对照@@ -472,7 +477,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可**第三档:memory-only 的两个删除面**。- openclaw `memory_forget`:三条白名单正则只放行 `viking://user/[…/]memories`、`viking://user/<u>/peers/<p>/memories`、`viking://agent/[…/]memories`;显式 uri 不匹配直接拒绝;搜索路径候选先过同一 guard,且只有在候选唯一且 score≥0.85 时才自动删,否则列出候选让 agent 指名;底层 URL 固定 `recursive=false`。-- hermes `viking_forget`:六道顺序校验——非 str / 空拒;scheme≠viking 拒;带 query/fragment 拒;目录或非 `.md` 结尾拒;必须命中 4 种 memories 路径形状之一,且 `memories` 段后至少还有 2 段(不删除 `memories/` 与分类目录本身);文件名不能是 `.abstract.md/.overview.md`。+- Hermes `viking_forget` 拒绝空输入、非 `viking://` URI、query/fragment、目录、非 `.md` 文件及 `.abstract.md`/`.overview.md` 摘要。内置校验器允许用户记忆路径,包括直接位于 `memories/` 下的 `profile.md`。请使用服务端返回的、带明确用户 ID 的 URI。外部插件还支持 `viking://~/...`,拒绝已废弃的无用户 ID 路径,并在删除明确用户路径前验证归属。**第四档:默认不提供删除(LangChain / Open WebUI)**。LangChain `viking_forget` 需配置 `profile="admin"` 或 `allow_forget=True` 才加入工具面;Open WebUI 则完全不提供删除工具。@@ -491,7 +496,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可| dsh | client 全吞异常;`ensureState` 失败不缓存(服务端不可达时每 pre-step 两次 health 各 5s) | context-face 6h + user-space 缓存进程内不过期 | 无;pending 跨进程重放 3 次 | 是(pre-step 串行 profile+recall;session/flush 阻塞) || pi | health 失败时 start() 提前返回,本轮也不注册工具,此后每 prompt 静默重试连接;`/mcp` 握手单独失败(401/403、超时、server 无 `/mcp`)不影响启动:召回、同步、takeover 照常,状态栏显示 `tools ✗`,`/viking` 打印完整错误 | context-face 6h;握手没有负缓存,一直失败就每轮重试一次,最多占满 5s 握手预算才轮到排队召回 | hook 侧无,只有 pending queue;传输失败后丢弃当前 MCP 连接,下次调用重新连接;失败的工具调用不会自动重放 | 部分(session_shutdown 被 await:takeover 近 0、非 takeover 最坏 30s,外加关闭 MCP 客户端;turn_end 网络异常时逐条各等 10s) || openclaw | client 构造永不失败;health 吞异常;召回 500ms precheck 失败跳过 | 无负缓存(每轮一次 500ms health 预检) | 无(单次 fetch);commit/afterTurn 的 Phase2 轮询 | 否(`memory_store` 重抛例外;`compact()` 最长阻塞 5 分钟) |-| hermes | `_client=None` 即运行期负缓存(本进程不再重试,除本地自启 waiter 外) | 无独立结构(`_client=None` 承担) | trusted 补身份 1 次、sync 全新 client 1 次、多档降级;commit 失败不重试 | 否(后台单 worker + 逐 provider try/except) |+| hermes | 未变化的失败连接配置冷却 30s;配置变化触发新探测 | `_failed_refresh` 记录失败配置 | trusted 身份补发及 sync client 重试;启动时恢复已退出进程的待提交会话(POSIX) | 否 || ov CLI | 多数 exit 1;`ov status` 表格模式始终退 0;`ov health` 即使 unhealthy 也退 0 | 无 | 仅网关 401 挑战重试 1 次 | n/a(无宿主) |### 3.6.2 通用超时@@ -511,7 +516,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可| dsh | ❌ | ❌ | 2 个 skill:`openviking-memory` 与 `openviking-skills`(独立的 `ctx.skills` provider) | ❌ | `ctx.provide("openvikingMemory")` 供其他 Cordis 插件二次开发 || pi | ✅ `ctx.ui.setStatus` | ✅ `/viking` `/viking commit` | 无 | ✅ | e2e-live.sh || openclaw | ❌ | ✅ 5 个(/add-resource /add-skill /ov-search /ov-query-config /ov-recall-trace) | 3 skill 随插件分发 | ✅(key 角色探测 + 版本兼容检查 + `status` 命令) | Gateway HTTP 路由做 recall trace 可视化;feature-gate RPC;健康检查脚本 |-| hermes | ❌ | ❌ | 无 | ✅ curses 多层菜单 | `hermes memory status`(含 env 覆盖列表);`hermes backup` 带 ovcli.conf |+| hermes | ❌ | ❌ | 无 | ✅ curses 多层菜单 | `hermes memory status`(含 env 覆盖列表);`hermes backup` 收集 `$HOME` 下默认或环境变量指定的 `ovcli.conf`;YAML 关联的命名文件需单独备份 || ov CLI | ❌ | ❌(自身即命令) | 无 | ✅ TUI 向导 | 完整 help 系统(63 条 curated);语言门禁;`ov tui` 全屏文件浏览器(含终端内图片预览) |---@@ -620,10 +625,11 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可## hermes(Nous Research)- **集成文档**:[Hermes Agent](./05-hermes.md)-- **形态**:Hermes bundled MemoryProvider(Python 单文件实现,共 3725 行,随 Hermes 一同发布)。通过 `httpx` 直连,无需额外安装插件。提供 6 工具及 10+ 生命周期 hook(prefetch/sync_turn/on_session_end/on_session_switch/on_memory_write/…)。基线为发行版 `e12626b3`(= brew 2026.7.7.2)。-- **能力亮点**:具备最全面的资源摄取面——`viking_add_resource` 支持 HTTP、Git、SSH、`file://`、本地文件 temp_upload 以及本地目录 zip 打包上传(跳过 symlink + 越界文件);`viking_remember` 直写记忆文件(不依赖 session commit/抽取);支持本地服务端自启(当 endpoint 位于本地且不可达时,通过 `subprocess.Popen openviking-server` 拉起);支持 trusted 补身份重试;无论正常退出还是接收到 Ctrl+C、SIGTERM、SIGHUP 信号,均能保证完成 commit(详见 [§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵))。-- **行为要点**:在召回上,仅有 `search/search` 的首选路径携带 session_id 并落到路径 B(`mode="deep"`;而 `auto`/`fast` 走 `/find` 且不带 session_id,详见 [§3.2.2](#_3-2-2-判定矩阵))。`queue_prefetch` 为同步实现,无预热;subagent 传入 `skip_memory=True` 时不接 OV(详见 [§3.3.5](#_3-3-5-subagent-会话对照))。无 profile 注入/statusline/slash;commit 恒 keep 0,drain 不净则本次不 commit;进程内队列不落盘。session id 格式为 `%Y%m%d_%H%M%S_<hex6>`。召回参数:6 条/阈值 0.15/字符预算 4000/总超时 4s。记忆 URI 为 `viking://~/peers/{agent}/memories/{subdir}/mem_<uuid12>.md`。退出机制包含 SIGTERM grace 1.5s 与退出看门狗 30s。互补路径支持 `openviking-server ingest hermes`(离线重放,默认关,详见 [§7](#_7-附录-非-coding-集成速览) E)。-- **配置**:通过 `OPENVIKING_ENDPOINT`(非 `_URL`)、8 个 `OPENVIKING_RECALL_*` env 以及 `config.yaml` 进行配置。在 `use_ovcli_config` 模式下,系统会清空 `.env` 里的对应变量。+- **形态**:通过 HTTP 连接的内置 `MemoryProvider`,提供 6 个 `viking_*` 工具。OpenViking 运行于独立服务端环境。外部插件独立维护;范围区别见本文开头。+- **记忆写入**:`viking_remember` 将原始事实送入独立会话并提交,触发异步抽取;返回 `status: submitted`,最终可能新增、合并或跳过。内置 provider 只镜像原生记忆新增;外部插件还支持按 URI 映射替换和删除,详见其 README。+- **召回**:同步 query 召回优先使用带 session_id 的 `search/search`,降级至 `/find`。`queue_prefetch` 不做预热。会话开场注入用户 profile 和 preferences/entities 清单,默认预算 6000 token。Query 召回默认 6 条、阈值 0.15、4000 字符、总超时 4s/单请求 3s,均可配置。+- **生命周期**:commit 保留 0 条消息。上传线程不落盘,但待提交标记支持 POSIX 上的崩溃恢复。正常退出和信号会尝试 drain 与 commit,网络故障或强制终止仍可中断。`skip_memory=True` 的委派子代理不加载 provider;无 statusline 或 provider slash 命令。+- **路径与配置**:记忆写入 `viking://user/<uid>/memories/...`,设置 peer 时写入 `viking://user/<uid>/peers/<peer>/memories/...`。默认不设置助手 peer。连接读取 `OPENVIKING_ENDPOINT`、profile 凭据、关联的 `ovcli.conf` 和 Hermes YAML;关联 OpenViking profile 时会清除 Hermes `.env` 中的 5 个连接变量。- **维度索引**:工具面 [§1.1](#_1-1-主动工具面-agentic-调用能力) |召回 [§3.2](#_3-2-自动召回与注入) |commit [§3.3.2](#_3-3-2-常规-commit-触发条件)/[§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵) |删除 [§3.5](#_3-5-写入与删除的类型边界)。## ov CLI@@ -735,7 +741,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可| **B. [LangChain/LangGraph](./07-langchain-langgraph.md)** | Python SDK 适配层(retriever/tools/store/middleware/recorder) | `create_openviking_tools()` 提供 12 个 StructuredTool(`viking_forget` 默认不在 agent profile 中) | `thread_id`/`session_id` 由调用方给;`CommitPolicy` 默认 `never` | 本组最稳:只读方法自动重试 1 次、写方法不重试(防重复)、部分成功抛结构化异常可切片重试 | 需全部显式构造才生效 || **C. [Agent Plugins 1.0](./15-agent-plugins.md)** | 便携包 `plugin.json` + `skills/` + `mcp.json`(stdio→HTTP 代理) | MCP 透传 16 工具;刻意无 hooks(召回靠 skill 教模型) | 仅 `remember` 建临时会话 | MCP 代理层重试(401/403 换凭据、400/404 重初始化各 1 次) | 客户端加载后工具即用 || **D. [通用 MCP 直连](./06-mcp-clients.md)** | 零本地组件,直连 `/mcp` | 同 C(16 工具) | 同 C | 由客户端自定 | `/mcp` 常驻 |-| **E. [log ingestion](./09-log-ingestion.md)** | `openviking-server ingest` CLI(跑在日志所在机器,反向导入) | 无(只写不召回) | 会话 id `{prefix}__{harness}__{sanitized native id}`;commit token 6000/idle 5s/keep 0 | 唯一有崩溃恢复:SQLite 游标库 + 单实例锁 + reconcile 判定批次落地 | 双重默认关(`ingest.enabled` + 每 harness `enabled` 都 false);支持 claude_code/codex/hermes/opencode/openclaw/cursor 适配器 |+| **E. [log ingestion](./09-log-ingestion.md)** | `openviking-server ingest` CLI(跑在日志所在机器,反向导入) | 无(只写不召回) | 会话 id `{prefix}__{harness}__{sanitized native id}`;commit token 6000/idle 5s/keep 0 | 崩溃恢复:SQLite 游标库 + 单实例锁 + reconcile 判定批次落地 | 双重默认关(`ingest.enabled` + 每 harness `enabled` 都 false);支持 claude_code/codex/hermes/opencode/openclaw/cursor 适配器 || **F. [OpenViking Helper](./14-openviking-helper.md)** | 闭源桌面 App | — | — | — | 不在本文代码基线内 |---diff --git a/examples/hermes-plugin/DEVELOPMENT.md b/examples/hermes-plugin/DEVELOPMENT.mdindex cb45a0ecb..d0d202189 100644--- a/examples/hermes-plugin/DEVELOPMENT.md+++ b/examples/hermes-plugin/DEVELOPMENT.md@@ -49,12 +49,23 @@ accepted by current OpenViking servers.## Migration coordination-After this directory is merged, submit a Hermes catalog entry with:+Before the catalog cutover, submit a Hermes catalog entry with:- `name: openviking`- `repo: https://github.com/volcengine/OpenViking`- `subdir: examples/hermes-plugin`- `sha`: the full reviewed OpenViking commit SHA+- `category: memory`+- `tier: community`++Include the required `capabilities` block for tools, hooks, middleware, and+environment variables. Its declarations must match the plugin at the reviewed+SHA. Follow the [Hermes catalog entry schema](https://github.com/NousResearch/hermes-agent/blob/main/plugin-catalog/README.md#entry-schema)+and validate the pinned installation directory:++```bash+hermes plugins validate /path/to/hermes-profile/plugins/openviking+```Publish the catalog entry and validate migration before Hermes removes itsbundled provider. Hermes PR [#114569](https://github.com/NousResearch/hermes-agent/pull/114569)diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.mdindex 91458c41c..558f5822c 100644--- a/examples/hermes-plugin/README.md+++ b/examples/hermes-plugin/README.md@@ -2,40 +2,41 @@Context database by Volcengine (ByteDance) with filesystem-style knowledge hierarchy, tiered retrieval, and automatic memory extraction.-This directory prepares the standalone OpenViking provider for migration out of-Hermes core. The installation and upgrade steps below are for migration testing-in a separate Hermes profile.+This plugin connects Hermes to OpenViking for long-term memory and knowledge+retrieval. The installation steps below use a reviewed OpenViking commit.-For normal use while Hermes still bundles OpenViking, follow the+For Hermes releases that still bundle OpenViking, follow the[Hermes integration guide](../../docs/en/agent-integrations/05-hermes.md) and run`hermes memory setup openviking`. No external plugin installation is needed.-See [DEVELOPMENT.md](DEVELOPMENT.md) for the source, license, migration contract,-and test commands.+For development and licensing details, see [DEVELOPMENT.md](DEVELOPMENT.md).-## Install for migration testing+## Install-Use a current Hermes version with repository-subdirectory plugin support:+Hermes v2026.9.24 is the tested release baseline.++For a direct installation, replace the placeholder with the reviewed OpenViking+commit's full 40-character SHA:```bash-hermes plugins install 'https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin'+hermes plugins install 'https://github.com/volcengine/OpenViking/tree/main/examples/hermes-plugin' \+ --ref '<full-40-character-commit-SHA>' --no-enablehermes plugins enable openvikinghermes memory setup openvikinghermes memory status```The equivalent shorthand is `volcengine/OpenViking/examples/hermes-plugin`.-Hermes installs this directory as `$HERMES_HOME/plugins/openviking/` and installs-its `pyproject.toml` dependencies under Hermes's dependency constraints.+Hermes installs this directory as `$HERMES_HOME/plugins/openviking/`.+In this two-step flow, Hermes resolves its `pyproject.toml` dependencies under+Hermes's dependency constraints when you enable the plugin.If Hermes still includes the bundled OpenViking provider, that copy takesprecedence. The external copy becomes active after the bundled copy is removed.Keep `memory.provider: openviking` and your existing configuration. No memory-data needs to move. Automatic installation after core removal also requires a-published `openviking` entry in the Hermes catalog; this directory alone does-not register one.+data needs to move.-## Upgrade a test installation+## UpgradeFor a direct subdirectory installation, use force-reinstallation instead of`hermes plugins update openviking`. Hermes does not retain the repository's@@ -50,8 +51,8 @@ hermes plugins install 'volcengine/OpenViking/examples/hermes-plugin' \```Existing connection settings and server data are retained. Restart Hermes or-the gateway after the upgrade. Once the plugin is registered in the Hermes-catalog, copies installed through the catalog use `hermes plugins update openviking`.+the gateway after the upgrade. For catalog installations, use+`hermes plugins update openviking`.## Requirements@@ -135,7 +136,10 @@ OpenViking's server config is separate from Hermes:`account`, and `user`. It is read from `OPENVIKING_CLI_CONFIG_FILE` or`~/.openviking/ovcli.conf`.-Hermes-side provider config is read from the initialized profile's `.env`.+Hermes reads provider settings from the initialized profile's `config.yaml`,+profile secrets, and linked `ovcli.conf`. Connection values resolve in this order:+profile environment, linked OpenViking config, Hermes YAML, then defaults. API keys+come from profile secrets or the linked OpenViking config, not Hermes YAML.After initialization, the provider keeps that profile for connection, identity,and recall settings, including when another profile is active in the sameprocess. For the launch profile, process-level `OPENVIKING_*` values fill missing@@ -151,8 +155,8 @@ Routed profiles never inherit the launch profile's process values.| `OPENVIKING_USER` | `default` | Tenant user for local/trusted mode || `OPENVIKING_AGENT` | (none) | Optional peer ID for separate assistant context |-When `OPENVIKING_API_KEY` is set, Hermes lets OpenViking derive account/user-identity from the key. In local or trusted deployments without an API key,+User and admin API keys let OpenViking derive account/user identity from the key.+In local or trusted deployments without an API key,Hermes sends `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` as identity headers.Hermes also sends `User-Agent: openviking-memory-hermes/<version>` onOpenViking requests. This standard harness identifier contains the Hermes@@ -299,15 +303,10 @@ the new connection from earlier mappings. New files require a server-confirmeduser identity. Missing or ambiguous mappings block replacement and deletionwith 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).+Replacement and deletion require Hermes to provide the full previous entry+content after its local memory write succeeds. If this data is unavailable,+the plugin skips those mirror operations with a warning; local memory still+changes. It does not guess which remote entry to change.Only entries created by this mirror have mappings. Session-extracted memories,explicit `viking_remember` results, and copies created before this registry are@@ -386,9 +385,10 @@ exceed it, and the server may include other context during extraction.### Non-primary contexts-Hermes passes an `agent_context` to `initialize()`. Sessions started for scheduled-cron jobs, delegated subagents, or flush forks (`cron`, `subagent`, `flush`) are-non-primary: recall and profile reads keep working, but the provider skips turn-uploads, session commits, and memory mirroring, so fixed-prompt job output neither-lands in the memory bank nor spends server-side extraction budget. Interactive-sessions (and hosts that predate `agent_context`) keep the previous write behavior.+When Hermes initializes the provider with `agent_context` set to `cron`, `subagent`,+or `flush`, recall and profile reads keep working. Automatic turn uploads,+session-end/switch commits, and native memory mirroring are skipped for that+context. Startup recovery can still commit pending messages from earlier sessions.+Explicit `viking_*` tools keep their normal behavior, including writes and deletes.+Interactive sessions (and hosts that predate `agent_context`) keep the previous+automatic write behavior.