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.

Version 1.7.2 publishes a compatibility-preserving storage and governance hardening patch on the stable V1 release line: ordinary recall now 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 updates without changing the stable V1 runtime contract. The 1.6.0 release packages a compatibility-preserving refactor of the doctor, graph-hygiene, maintenance, digest-result, recall-pipeline, and provider-schema internals while keeping the stable V1 commercial-governance line introduced in 1.5.0. The 1.5 line includes promoted-only profile lifecycle safety, candidate-memory promotion planning, graph-hygiene repair, fail-closed vector-repair fallback handling, governance cleanup, journal recovery, an operator dashboard, repository-owned golden benchmarks, stricter release gates, fail-closed hard-delete safety, packaged benchmark fixtures, Recall Funnel observability, synthetic retrieval-regression benchmarking, and default-safe vector fallback behavior. Runtime Experience packet injection is enabled by default through experience.prefetch_enabled=true and can be disabled with experience.prefetch_enabled=false; background automatic promotion remains an explicit operator opt-in through experience.auto_promotion_enabled=true, and low-risk auto-promotion remains a second explicit opt-in through experience.auto_promote_low_risk=true. By default, successful low-risk scans create candidate playbooks, high-risk playbooks stay review-gated, and final-failure or low-signal traces are not promoted. It keeps the scope_recall_profile surface added in v1.3.0, compression-boundary journal staging through Hermes' on_pre_compress() memory-provider hook, inline attachment-marker sanitization, the supported standalone install shape added in v1.1.0, and native-safe LanceDB probing with automatic SQLite vector fallback for non-AVX hosts.

It uses a three-layer design:

• Journal/provenance layer for eligible raw conversation turns and evidence links that are not directly recalled as durable memory
• SQLite truth store for high-density durable local records and deterministic auditing
• Vector companion for semantic retrieval and hybrid ranking: LanceDB by default, or sqlite-bruteforce for native-free/non-AVX hosts

This replaces the old lancepro naming, which was misleading because the earlier implementation was SQLite-only.

Design promises

• Truth stays inspectable: SQLite remains the authoritative store; vectors are rebuildable.
• Recall is current-turn scoped: retrieval is based on the active query, not stale queued context from the previous topic.
• Durable memory travels deliberately: user, memory, project, and ops facts can follow the same user + agent identity across windows/chats, and can cross platforms only when explicit canonical identity mapping is configured.
• Raw turns are provenance, not durable memory: eligible conversation turns are written to a journal/staging layer; only digest-produced high-density user/memory/project/ops rows enter durable recall and vector sync.
• Operator actions fail closed: cross-scope export/dedupe/govern/repair paths require explicit maintenance mode.
• Install remains practical: hosted embeddings are used when configured, while deterministic local-hash keeps no-key bootstrap available.

Deployment boundaries

scope-recall is the local per-Hermes recall layer. In multi-agent deployments that already run a central shared backend such as PostgreSQL, keep that backend as the cross-agent source of truth and connect it to scope-recall through explicit import/export/tool boundaries.

The V1 shape is intentionally simple:

• SQLite remains the local truth store for provider-owned memory records.
• the configured vector backend remains a rebuildable semantic retrieval companion.
• Durable user/memory/project/ops facts can be bridged deliberately across systems.
• Local general scratch, raw system/tool output, and plaintext secret values stay outside durable recall; explicit scope_recall_store_secret_index rows may store only searchable credential indexes such as service/account/purpose/vault references and non-reversible fingerprints.
• Hermes native skills remain the place for procedural knowledge packaging.
• Operational visibility is exposed through doctor, repair, inspect, explain, and benchmark utilities; deployment-specific dashboards can consume those outputs when needed.

For external shared-memory bridge guidance, see docs/external-shared-memory.md. For public JSON report contracts used by doctor, dashboard, golden benchmark, replay, and forgetting outputs, see docs/response-contracts.md. For reviewed procedural playbooks and preflight packets, see docs/experience.kernel.md.

Optional cross-platform identity mapping

By default, durable shared scope remains platform-isolated: platform + agent_workspace + agent_identity + user_id. To let the same human recall durable rows across Telegram, CLI, Feishu, or another gateway, configure an explicit canonical identity map in $HERMES_HOME/scope-recall/config.json:

{
  "identity": {
    "cross_platform_shared_scope": true,
    "cli_user_id_fallback": "local",
    "user_aliases": {
      "telegram:user_123": "canonical_user_123",
      "cli:local": "canonical_user_123",
      "feishu:ou_xxx": "canonical_user_123"
    }
  }
}

Only durable targets (user, memory, project, ops) use the canonical shared scope. general scratch, raw journal evidence, chat/thread/session context, and tool traces remain local. Existing platform-specific durable rows stay readable through query-time aliases before any explicit migration. Newly written rows keep raw_platform, raw_user_id, and mapped canonical_user metadata for auditability.

Provider-specific LLM endpoints

For capture, journal, or nightly digest LLM providers whose chat-completions endpoint is not base_url + /v1/chat/completions, set either a full endpoint or disable /v1 appending:

{
  "journal": {
    "endpoint": "https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions",
    "append_v1": false
  }
}

For scripts/nightly-digest.py, the same behavior is available through --endpoint or --no-append-v1.

Why scope-recall?

Most agent memory pain is not just "wrong memory was recalled". The bigger user-facing failure is often "the agent forgot everything when I opened a new window." scope-recall therefore separates durable facts from local scratch context:

• user preferences, project facts, ops notes, and explicitly stored memories follow the same user + agent identity across chats/windows
• raw/general turn captures remain local to the current chat/thread/session so one group's temporary chatter d