Metadata-Version: 2.4
Name: hermes-scope-recall
Version: 3.12.0
Summary: Local long-term memory for Hermes, Codex, Claude Code, WorkBuddy and dsh agents: SQLite truth, source-backed recall and rebuildable vector companions.
Author: scope-recall contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/410979729/scope-recall-hermes
Project-URL: Documentation, https://github.com/410979729/scope-recall-hermes#readme
Project-URL: Issues, https://github.com/410979729/scope-recall-hermes/issues
Project-URL: Source, https://github.com/410979729/scope-recall-hermes
Project-URL: Changelog, https://github.com/410979729/scope-recall-hermes/blob/main/CHANGELOG.md
Keywords: hermes,codex,claude-code,mcp,memory,sqlite,lancedb,vector
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0
Requires-Dist: jsonschema<5,>=4.22
Requires-Dist: packaging<27,>=24
Requires-Dist: tzdata<2027,>=2025.3; sys_platform == "win32"
Provides-Extra: lancedb
Requires-Dist: lancedb<=0.37.1,>=0.30.2; extra == "lancedb"
Requires-Dist: pyarrow<25,>=24; extra == "lancedb"
Provides-Extra: codex
Requires-Dist: mcp<=2.1.0,>=2.0.0; extra == "codex"
Requires-Dist: pydantic<3,>=2; extra == "codex"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: PyYAML<7,>=6; extra == "dev"
Requires-Dist: setuptools<82,>=69; extra == "dev"
Requires-Dist: wheel<1,>=0.45; extra == "dev"
Requires-Dist: ruff==0.16.10; extra == "dev"
Requires-Dist: pyright==1.1.414; extra == "dev"
Dynamic: license-file

# 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.12.0`. 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](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](CHANGELOG.md) and in full on its
[GitHub release](https://github.com/410979729/scope-recall-hermes/releases). Upgrading from `3.2.x` or later is
`pip install -U`, `apply-install` and a host restart; the first store open adds the local management audit table. Back up
before upgrading and follow the [management migration and rollback guide](docs/manage.md#migration-and-rollback).
On a shared store in
the shipped embedding space, set `vector_threshold` from 0.653 to 0.70 by hand
([docs/configuration.md](docs/configuration.md#vector_threshold)). Older supported stores migrate in order to schema 1111;
an earlier release cannot open the upgraded store. Section 9 of the
[3.1.0 release notes](https://github.com/410979729/scope-recall-hermes/releases/tag/v3.1.0) 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.

**Recall-quality checks.** The [synthetic recall benchmark](CONTRIBUTING.md#the-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 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.
[The management guide](docs/manage.md) covers store selection, filters, version checks and receipts; the
[export guide](docs/export.md) covers package layout, hashes and filtering.

## 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](maintenance/AGENT_WORKFLOW.md). 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](docs/install.md). Claude Code
installs only as an entry of a shared store, and Codex can join one too:
[docs/shared-store.md](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](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](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):

```text
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](https://github.com/410979729/scope-recall-hermes/releases/latest)
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:

```text
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](https://github.com/410979729/scope-recall-hermes/releases/tag/v3.1.0) 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](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 Hermes sync that environment and restart it
(sections 1 and 4 of [docs/install.md](docs/install.md)).

```text
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:

```text
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](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 adds the LanceDB vector companion, the default `vector.backend`; without it, configure `sqlite-bruteforce` or recall stays lexical. 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

Two shared read-only Core methods, `profile` and `entity`, are exposed as Hermes tools and on 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](docs/profile-entity.zh-CN.md).

## 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](docs/trace.zh-CN.md).

## 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 so do Codex and Claude Code
(`attach --host codex|claude-code`). See [docs/shared-store.md](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](docs/upgrade-guide.zh-CN.md).

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.
