Scope Recall 3.7 autonomous memory

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

This checkout is 3.9.0, which is 3.8.2 with one format for the whole tree, a quality check in CI, and the hook clients (adapters/clients) and the Hermes adapter split into smaller modules, with no change in behaviour; since 3.8.2 a Hermes agent on Gemini can use its memory tools; since 3.8.1 a worker stays up until the candidates of a conversation's last messages settle, the doctor names work that has waited a day in any partition, and outside Windows autostart prints the wake for a timer of your own; since 3.8.0 an operator can re-embed a store into a new embedding space (respace-embeddings) and the doctor says when embeddings have waited a day; since 3.7.2 Hermes keeps what a failed tool call printed, an automatic recall reads its evidence in about 470 statements where it ran 16,000, a capture's write no longer grows with its words, its episode or the store's scopes in a busy Hermes gateway (a long tool output held the shared store's writer lease for up to 43 s), a claim's vector work comes back after a provider failed it (retry-failures reopens what earlier releases dropped), a withheld tool output's placeholder is indexed by the tool's own error text alone, and what Hermes writes into a conversation itself is stored as the host's, not the owner's, also when a compression folded its summary or a to-do list into it; since 3.7.0 DeepSeek Harness (dsh) joins the shared store too: a dsh plugin recalls before each turn and stores each turn's messages, and dsh's upload of its session logs is switched off (docs/install.md, section 13). 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). Hermes agents could share a store from 3.2.0; Codex and Claude Code join in 3.3.0. An agent that is not attached keeps its own store. A tool's output is still kept and found, but no longer turned into facts. The notes are the [3.7.x], [3.6.x], [3.5.x] and [3.4.x] sections of CHANGELOG.md, newest first; upgrading from 3.4.x, 3.3.x or 3.2.x is pip install -U, apply-install and a host restart, and the store's schema does not change; on a shared store in the shipped embedding space, set vector_threshold from 0.653 to 0.70 by hand (docs/configuration.md). From 3.1.x the store moves to schema 1110 the first time it is opened, after which a 3.1 process cannot open it. 3.1 is a rebuild rather than a patch on 2.0: production code went from 141,044 lines to 48,289, memory now accumulates evidence before a fact is written rather than judging one sentence on sight, and hosts sit behind adapters instead of the core being shaped around Hermes. The notes for the rebuild are the [3.1.0] section of CHANGELOG.md, and section 9 there is the migration procedure for a 2.0.1 memory database. SQLite remains the only fact authority; host adapters share the same contracts.

What is not verified. scripts/check.py --tier release runs about 2,300 tests with none failing. They check contracts, storage and the hosts' wiring; none of them measures recall quality. Every accuracy figure in the notes was measured by us, on our own corpora, by hand, and there is no regression suite you or we can re-run automatically -- that is the first item in What is not finished.

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. 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 it into the same isolated Python environment the host uses:

python -m pip install hermes-scope-recall==3.7.0
python -m pip install "hermes-scope-recall[codex]==3.7.0"

The same wheel and sdist are attached to the GitHub Release alongside SHA256SUMS and RELEASE-PROVENANCE.json, for an offline install (python -m pip install "<path-to-wheel>"). 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 CHANGELOG.md 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; 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>. Hermes Desktop also 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 even after a rebuild dropped the core (section 1 of docs/install.md).

scope-recall plan-install --host hermes --target-plugin-dir <absolute-plugin-dir> --instance-root <absolute-instance-root> --project-root <absolute-project-root> --agent-id <agent-id> --python <absolute-python>
scope-recall apply-install --host hermes --target-plugin-dir <absolute-plugin-dir> --instance-root <absolute-instance-root> --project-root <absolute-project-root> --agent-id <agent-id> --python <absolute-python>
scope-recall doctor --host hermes --instance-root <absolute-instance-root> --python <absolute-python>

Codex uses the same commands with --host codex, plus --env-file <absolute-file> so the Codex-launched MCP server and hooks can read the credential names the runtime config declares (Codex does not pass them in the environment). The installer writes only its own wrapper and installation records and preserves foreign host files. Its receipt records host registration and applicable hook trust as pending at installation time; use doctor and actual host loading to verify the current state. Uninstall keeps Core data by default; explicit purge is bounded to verified installation-owned data and refuses uncertain ownership or active writers.

Uninstall (default: retain memory)

Uninstall is receipt-driven. By default it removes only plugin wrapper files and retains Core data. Inspect the plan before applying:

scope-recall plan-uninstall --instance-root <absolute-instance-root>
scope-recall apply-uninstall --instance-root <absolute-instance-root>

--target-plugin-dir may be omitted when the install receipt records it. Purge of installation-owned Core data requires a separate plan-uninstall --purge inspection and matching apply-uninstall --purge; see docs/install.md. Do not treat purge as a normal uninstall step.

Data and host boundaries

SQLite truth lives in the verified Core data directory. Vector indexes are companions and may be rebuilt only through an explicit configured space. The Hermes and Codex adapters bind host identity, installation identity, scopes, and project roots before opening Core. After that binding is verified, an omitted runtime-config argument checks only <data_directory>/runtime-config.json; a missing file stays basic plus an explicit capability gap. The file is never generated or discovered from the current directory, parent directories, or credential locations. Optional host wiring must report a capability gap instead of creating or repairing a database.

The codex extra adds the MCP SDK. Without that extra, the Core and Hermes paths remain importable. The lancedb extra enables the tested LanceDB companion path. PostgreSQL/pgvector is outside this v3 distribution; an explicit configuration error directs operators to retain the old installation and use the migration guide.

On Windows, choose a short data directory such as C:\ScopeRecall\my-agent. LanceDB appends index, table, and temporary file names to that path. If the resulting native path is too long, the worker reports native_vector_path_too_long before starting LanceDB or calling the embedding API. Use a short target directory for a new installation or an offline migration.

Profile and entity read views

3.1.0 adds two shared read-only Core methods, profile and entity, and exposes them on both Hermes tools and Codex MCP. They return a deterministic categorized current-fact view, or an exact one-hop statement view, over admitted consolidated claims only. Raw chat is never silently turned into a profile. Incoming relations match the full scalar value_text only and keep recorded conditions and validity. Explicit project-name aliases may resolve when they are already admitted and still live; person aliases are not generalized. A budget_tokens value too small for even the minimal truthful envelope is a validation error, not an oversized view. See docs/profile-entity.zh-CN.md. An older installed wheel does not gain these tools until 3.1.0 is installed.

Bounded multi-hop evidence paths

Use trace when a question needs two or three recorded relationships joined together. It is read-only, shared by Hermes and Codex, and reuses existing SQLite fact/evidence/visibility checks. It does not invoke another model or persist inferred facts. Cross-scope names and conditional relations are not silently joined. Node, path, time and explicit byte budgets bound its cost. See the trace contract and boundaries.

One store for several agents

Several agents can share one store instead of each keeping its own: each attaches as an entry, every memory is marked with the agent it came in through, and a deletion through any of them applies to all. Moving the memory to another machine is copying one directory. Hermes homes attach as entries, and from 3.3.0 so do Codex and Claude Code (attach --host codex|claude-code). See docs/shared-store.md. WorkBuddy and dsh attach the same way (attach --host workbuddy|dsh).

Agent-operated migration

Users ask their agent to upgrade. The bundled scope-recall-setup skill routes fresh installs directly to installation and existing Core databases to ordinary updates. Only legacy SQLite uses a durable migration job. The agent reads scope-recall setup --workflow and performs discovery, verified audience mapping, backup, conversion, indexing and actual host checks. See the agent upgrade guide.

Migration composes the existing converter, backup helper and worker. It preserves original source/history/deletion semantics and never re-extracts the whole old journal. Unsupported formats or unresolved permissions block cutover and preserve the old installation. Index scheduling and actual live readiness remain separate.

Tree layout

The package root holds only the entry (__init__.py), the version and the protocol contracts. core/ is the host-independent memory core over SQLite truth; vector/ the rebuildable vector companions; adapters/ the Hermes plugin, the clients that use hooks and an MCP server (Codex, Claude Code, WorkBuddy, dsh; adapters/clients, with the entry module names installed configurations run kept in adapters/codex) and model transport; runtime/ the background worker, budgets and scheduling; maintenance/ install, doctor, upgrade and migration behind the operator CLI. Every shipped module is reachable by import from an entry point named in packaging_hooks/module_inventory.py; the wheel allowlist is derived from that, not typed.

Development checks

The clean wheel must be tested outside the source checkout. At minimum, verify both CLI aliases, a read-only doctor result, Core capture and recall against a temporary installation, and the stdlib HTTP helper's bounded invalid-input response. Host registration, real gateway lifecycle, and production data are separate acceptance boundaries.

Historical release notes and the former v2 packaging contract remain available in the repository history at the v2.0.1 tag. They are not current v3 usage instructions.