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.3.0 continues the stable V1 release line for the documented interfaces and adds scope_recall_profile, a compact high-level profile/context surface for durable user/memory/project/ops rows, optional local general scratch, and live Hermes curated memory files. It keeps compression-boundary journal staging through Hermes' on_pre_compress() memory-provider hook, preserves surrounding user text when gateway image attachment markers appear inline, keeps the supported standalone install shape added in v1.1.0, and retains 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.

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:8176453077": "joy",
      "cli:local": "joy",
      "feishu:ou_xxx": "joy"
    }
  }
}

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 does not contaminate another group
• current-turn recall searches only for memories relevant to the active query, avoiding stale previous-turn injection
• the SQLite truth store remains auditable, and vector stores are only rebuildable semantic companions

scope-recall is built around a simple rule:

Recall the relevant durable memory for the current query, while keeping local scratch context inside the current runtime scope.

Without scoped durable recall

You: "For this memory-provider project, SQLite is the source of truth."

(later, in another window/chat)

Agent: "I don't have that context here." ❌

With scope-recall

You: "What did we decide for this Hermes memory provider?"

Agent: recalls the durable project memory from SQLite truth/vector companion and answers from the relevant context. ✅

Without local scratch boundaries

Group A: "Temporary note: restart this group's test bot only."

(later, in Group B)

Agent: applies Group A's temporary note in Group B. ❌

scope-recall keeps that temporary general scratch row local while still sharing durable user/memory/project/ops facts.

What you get

Optional companion: turn-closure-audit

scope-recall works as a standalone Hermes memory provider. You can install only this plugin and get scoped current-turn recall, SQLite truth storage, configured vector companion retrieval, and local scratch isolation.

For stric