Scope Recall

Scope Recall v3 is a bounded local memory core with SQLite as the authority and rebuildable vector companions. It provides host adapters for Hermes, and for Codex, Claude Code, WorkBuddy and DeepSeek Harness (dsh), which share one adapter of hooks and an MCP server (the MCP tools need the optional codex extra; dsh runs the hooks through a plugin). The public package is hermes-scope-recall; the Python import is scope_recall; the host wrapper identity remains scope-recall.

This checkout is 3.16.1. Hermes, Codex, Claude Code, WorkBuddy and dsh can keep one memory: each attaches to a shared store as an entry, what the owner tells one of them another can recall, and each memory says which agent it came in through (docs/shared-store.md). An agent that is not attached keeps its own store. A tool's output is kept and found, but not turned into facts. Each release's notes are a line or two in CHANGELOG.md and in full on its GitHub release. Upgrading from 3.2.x or later to 3.16.1 is pip install -U, apply-install and a host restart; the first store open adds the local management audit and private-interval tables. Back up before upgrading and follow the management migration and rollback guide. On a shared store in the shipped embedding space, set vector_threshold from 0.653 to 0.70 by hand (docs/configuration.md). Older supported stores migrate in order to schema 1112; an earlier release cannot open the upgraded store. Section 9 of the 3.1.0 release notes is the migration procedure for a 2.0.1 memory database. Facts are drawn from accumulated evidence rather than judged one sentence on sight; only the owner's explicit correction or confirmation changes a fact as it is captured. SQLite is the only fact authority; host adapters share the same contracts.

Automatic recall injects zero to six items that clear a lexical coverage or vector similarity floor. Background preferences and tasks accompany passing query evidence; a session's first resume request can recover its current task. Acknowledgments, approvals, praise, bare continuation and session status prompts within an existing session start no search or query embedding. Explicit recall keeps its admission behavior. The thresholds and diagnostic counts are described in the recall configuration.

Recall-quality checks. The synthetic recall benchmark provides reproducible development and held-out splits for retrieval, answerability, scope isolation, packet size and latency. It uses proposed claims and a word-hashing embedder without a model or network, so it does not establish consolidation quality, semantic embedding quality or performance on private conversations. The test tiers also check contracts, storage and host integration.

Manage your memories

Use scope-recall ui with the same store selection to open the local management page. It provides Chinese and English browsing, reviewed actions, private rules, export and backup status in your browser.

Use scope-recall memory to browse, search, inspect history, correct a fact, mute it or delete a conversation. It runs as the local store owner and makes no model request. Deletion shows the dependent sources and facts before --yes applies it. scope-recall memory export --out <new directory or .zip> writes the visible store as a portable package with original sources, facts, history, episodes, readable Markdown and optional retained attachments. scope-recall memory secrets lists stored credential matches by reference, provenance, time and pattern names. After upgrading, review its findings, remove them with scope-recall memory forget <refs> and change any credential found. The management guide covers store selection, filters, version checks and receipts; the export guide covers package layout, hashes and filtering.

Use scope-recall private on --session <id> | --project <path> | --all to stop keeping a session, directory or the whole store. --mode full refuses capture, recall and background model work; --mode read-only refuses capture while recall continues; --all --for 2h sets a duration and off closes a rule. Rules are stored as metadata only, overlap takes the stricter mode, and an event is refused by its own occurrence time even when a later retry or transcript read arrives after the rule ends. Undated events are refused when earlier private history could cover them. Directory identity follows junctions and symbolic links on the owning machine; recalls and outbound requests check again before release. The private-mode guide lists every host path, injection notice, migration and what is stored or sent in each mode.

For agents: install or upgrade on the user's behalf

Users only need to ask "install Scope Recall" or "帮我升级一下 scoperecall". Start with scope-recall setup --host <hermes-or-codex> --home <actual-instance-home>. New users go directly to installation; only detected legacy databases go through the agent migration workflow. The installed scope-recall-setup skill makes this routing discoverable in Hermes and Codex. A second installed skill, scope-recall-memory, which Claude Code gets too, is for the owner's everyday questions: what is remembered about me, did I say it or was it worked out, does it still hold, and what correcting, muting or deleting one memory does before it is done. Claude Code, WorkBuddy and dsh only read memory through their tools; the change is made in Codex or a Hermes chat on the same store. Perform path discovery, backup, audience binding, migration, indexing and host checks yourself; do not ask the user to execute commands or govern old memories.

Install

Step-by-step Hermes and Codex instructions: docs/install.md. Claude Code installs only as an entry of a shared store, and Codex can join one too: docs/shared-store.md. WorkBuddy runs the same hooks and MCP server, also only as an entry; its installer adds them to WorkBuddy's own settings.json and mcp.json (docs/install.md, section 12). dsh (DeepSeek Harness) runs them through a plugin the installer writes and names in dsh's home patch, also only as an entry, with dsh's upload of its session logs switched off (docs/install.md, section 13).

The package is hermes-scope-recall on PyPI. Install or upgrade it, with its vector extra, into the same isolated Python environment the host uses. The default vector store is LanceDB: without [lancedb] it cannot open, and recall finds memories by their words alone (the sqlite-bruteforce backend needs no extra):

python -m pip install -U "hermes-scope-recall[lancedb]"
python -m pip install -U "hermes-scope-recall[lancedb,codex]"

The second line is for Codex, Claude Code, WorkBuddy and dsh, whose MCP server needs the codex extra. -U moves an older install to the current release; write ==<version> instead to pin one. A Hermes that builds its own plugin environment installs the core from the declaration the installer writes instead (below). doctor names an environment that lacks the vector extra while a LanceDB store is configured (vector_dependencies_missing).

The same wheel and sdist are attached to each GitHub release alongside SHA256SUMS and RELEASE-PROVENANCE.json, for an offline install (python -m pip install "<path-to-wheel>[lancedb]"). To build it yourself from this checkout instead:

python -m build --wheel

Upgrading from 2.0.x is not an in-place upgrade. Read section 9 of the 3.1.0 release notes before you start; your old database needs a one-time offline migration and there are two errors people commonly hit.

The two console names scope-recall and hermes-scope-recall invoke the same v3 maintenance CLI. They are aliases for the current CLI only; neither is a compatibility promise for an older command set.

Use explicit absolute paths for installation planning. Hermes --agent-id must match the host active profile (get_active_profile_name(), commonly default on an isolated home). Hermes default --agent-workspace is hermes to match the host memory-provider init contract; pass the same value on plan and apply if you override it. Codex does not accept --agent-workspace.

If you talk to Hermes through the Desktop app or hermes --tui rather than the CLI, add --local-platform desktop (or tui) to both commands. Those surfaces name no user unless a dashboard login exists, and a session that names no user is refused everywhere but the CLI until the installer approves the surface; where Hermes's gateway runs those conversations over its local session transport, it names the account the gateway runs as, which binds as the owner on an approved surface and binds nothing on another. docs/install.md says what the approval does and does not cover. If you reach the host through a dashboard login instead (hermes serve with dashboard.basic_auth, the Desktop app on another machine), the session is that login: approve it as yours with --owner-login desktop=basic:<name>. A Hermes with its package manager (Hermes Desktop, and gateways on a Hermes that has one) builds the Python environment it runs plugins in, and builds it again on updates: pass it --target-plugin-dir <home>\plugins\scope-recall, where Hermes finds the plugin and the core it declares, vector dependencies included, then let Herm