Scope Recall for Hermes

Hermes current-turn memory provider with journal-first semantic capture, durable recall, SQLite truth storage, and optional vector companions

Give Hermes durable memory that can follow the same user across windows/chats while keeping local scratch context from bleeding into the wrong place.

Current-turn recall · Journal-first capture · Durable shared memory · Background digest · Local scratch scopes · SQLite truth · LanceDB/SQLite companion · Hybrid RRF retrieval

scope-recall is a Hermes local memory provider built for current-turn recall and durable semantic memory. Durable user/project/ops/memory facts are shared across windows/chats for the same user + agent identity; raw general turn captures stay local to the current chat/thread/session.

This repository, scope-recall-hermes, is the Hermes implementation. The Python distribution package is hermes-scope-recall, the Python import/package spelling is scope_recall, and the Hermes plugin ID/provider name remains scope-recall for runtime compatibility. The OpenClaw sibling implementation lives at scope-recall-openclaw.

Benchmark: LoCoMo long-conversation memory

In August 2026 we ran Scope Recall's 1.9.2 development line end-to-end on the LoCoMo long-conversation benchmark: all 1,540 questions across the four non-adversarial categories, with 100% coverage and zero invalid results — a full run, not a sample.

• Overall accuracy: 70.58% (1,087 / 1,540)
• Single-hop factual memory: 84.78%
• Temporal reasoning: 54.83%
• Multi-hop reasoning: 54.61%
• Open-domain inference: 45.83%
• Retrieval side: Top-50 evidence any-hit recall 97.66%, all-hit recall 90.63%

The run used gemini-embedding-001 for retrieval and gpt-5.4-mini as answerer, judge, and query planner. Every per-question result and the run manifest are hash-pinned, and the final score was recomputed independently from the raw rows; the public, path-free receipt is docs/benchmarks/locomo-2026-08.md. The benchmark harness (scripts/benchmark.locomo.py) is part of the 1.9.2 development line so the evaluation stays reproducible.

The August run predates the harness's secret-free model-route receipt and stricter official-comparability checklist. It is therefore legacy local evidence, not a run for which the current official_comparable_categories_1_to_4 flag may be asserted.

The runner has no machine-specific dataset, source-tree, or auth defaults. Supply the external paths explicitly, keep the run directory outside the source checkout, and add --auth-path only for model-backed phases:

python scripts/benchmark.locomo.py \
  --dataset /path/to/locomo.json \
  --run-dir /path/outside/the/checkout/locomo-run \
  --hermes-agent-root /path/to/hermes-agent \
  --phase retrieve

The three categories near 50% remain the clearest future improvement areas: multi-hop evidence completeness, temporal evidence presentation, and open-domain synthesis. We do not claim a cross-vendor ranking, because public LoCoMo evaluations use materially different models, judges, prompts, and dataset variants.

Version 2.0.1 is the managed-upgrade and retrieval-hygiene patch on the last packaged 2.0.0 line. It preserves SQLite truth and the stable V1 provider/tool identities while making strict Fact authority with legacy projection compatibility, finite relation generation, the Recall Packet current-truth compiler, deny-first Purge, governed tool profiles, optional extension boundaries, and the read-only Recall Inspector the coherent 2.0 product contract. All schema work remains additive, and the N-1/N/N-1 rollback window remains open throughout 2.0.x.

Scope Recall 2.0 does not ship the retired standalone visual-console writer or any separate truth-database mutation endpoint. Every durable mutation remains behind the production command application, writer authority, lifecycle fence, and audit boundaries.

Automatic upgrade from 1.10.3 or later

Upgrade the Python package in the same environment as Hermes, then run one decision-free command:

python -m pip install --upgrade hermes-scope-recall
hermes-scope-recall update --json

When invoked by the active plugin, the updater proves the exact home from the plugin location. The standalone command uses the inherited HERMES_HOME. If neither authority is present it refuses to run instead of guessing a platform-default or stale home. An external maintainer shell may supply an explicit --hermes-home; ordinary agents never need to choose among profiles.

Automation must report completion only when the JSON says "upgrade_complete": true. A successful detached launch instead reports "outcome": "upgrade_in_progress", "upgrade_complete": false, and "next_action_code": "wait_for_automatic_restart"; it is accepted work, not a completed upgrade. Retryable release-network failures are retried three times automatically and then return the single fixed action rerun_same_update_command, never a database or rollback decision. When next_action_code is submit_support_receipt, the same JSON contains a content-free support_receipt object that can be forwarded unchanged; users must not inspect or attach the memory database.

The updater accepts no repository, URL, archive, candidate, checksum, memory cleanup, embedding, or rollback policy from the user. It downloads only the latest stable Release from 410979729/scope-recall-hermes, verifies the fixed manifest, archive hash, canonical source tree, package identity, and version, then stops and restarts only that Hermes home. A failed activation automatically restores N-1 when the saved evidence proves that rollback is safe. An ambiguous state remains stopped instead of risking a partial writer. Rerun the same command after a process crash, reboot, or transient network failure; it resumes the sole incomplete frozen operation before contacting GitHub.

Once 2.0.1 or later is active, the equivalent plugin command is:

hermes scope-recall update

Legacy vector metadata or companion debt never causes memory rows to be sent to an embedding provider during upgrade. The updater preserves the companion, temporarily disables unsafe vector use, and keeps SQLite truth plus lexical recall available; vector rebuilding remains optional later maintenance.

The 1.8.6 patch hardened legacy fact-freshness maintenance, Unicode secret filtering, operator portability, truth-connection ownership, lifecycle relation restore, and semantic deduplication. It preserves the 1.8.5 Windows activation-lease PID fix and includes the 1.8.4 deep-audit closure for deterministic freshness, validator, truth-store permission, operator recovery, secret scanning, and cross-platform release gates. Its 1.8.3 predecessor hardened current-state recall, canonical chat identity boundaries, Windows repair and rollback, bounded vector-outbox history, and model-calibrated vector-only filtering. The 1.8.2 release made memory startup honest and local-model tool use reliable. If a configured local embedding model cannot actually load, Scope Recall now reports the degradation and uses a compatible fallback only for a fresh generation; it never opens an existing generation with a different embedding space. It also adds light, balanced, and full semantic retention profiles and fixes LM Studio/llama.cpp grammar initialization without deleting structured claim, freshness, or evolution capabilities. Durable user, memory, project, and ops fact actions resolve to shared durable scope, while general remains local scratch on every integration path. Existing ordinary-memory behavior remains the default because the new evolution, temporal-query, and Reflection surfaces are opt-in. The 1.7.2 release published a compatibility-preserving storage and governance hardening patch: ordinary recall uses one lifecycle policy across journal, nightly, deduplication, and vector paths; vector rebuilds support immutable generations and explicit compare-and-swap activation; metadata and import provenance are sanitized before durable or operator-visible sinks; candidate, freshness, and config mutations fail closed; and folded inline data URLs are removed without losing surrounding prose. It builds on version 1.7.1's runtime-config, candidate-browser, external-bridge, and release-gate fixes. Version 1.7.0 published the productization feature set on the stable V1 release line: event-digest evidence packets, reviewable candidate extraction, read-only memory browsing, candidate governance commands, Experience-to-skill bridge helpers, optional PGVector companion support, external shared-memory bridge contracts, explicit sensitivity governance, release-gate progress output, and same-process peer-provider SQLite lock recovery for scope_recall_store. Version 1.6.3 closed issue #25 with conservative SQLite lock recovery and a single safe retry for scope_recall_store while keeping non-SQLite business errors non-retryable. Version 1.6.2 added graph-relation backfill/benchmark visibility and hardened Experience review and journal-digest bookkeeping without changing the stable V1 runtime contract. Version 1.6.1 published documentation, packaging, and release-provenance