不配置模型路由和预算时只有原文检索可用，完整记忆功能需用 --configure-models 或 --models 配置；向量索引只是伴生数据，换嵌入模型必须显式重跑重嵌入，打开存储不会自动重建；卸载默认只删插件包装文件并保留 Core 数据，清除数据需单独执行 --purge 计划
scope-recall-hermes
410979729MIT活跃维护给 Hermes、Claude Code、Codex 等编码 Agent 提供本地长期记忆，用单个 SQLite 库存储，支持带来源回溯的混合检索，并能查看、纠正或删除记忆内容。
Local long-term memory for Hermes, Codex, Claude Code, WorkBuddy and dsh agents: one SQLite store, source-backed recall, and tools to inspect, correct or delete what is remembered.
v4.0.3发布于 2026-11-07 08:02 UTC540star +6 / 7 天50fork同步于 2026-11-10 23:56 UTC
python -m pip install -U "hermes-scope-recall[codex]"
scope-recall setup 硬件要求按 README 说明
README 未说明显存或 GPU 要求；检索依赖 NumPy 做映射检索与全向量打分，未提及 GPU 厂商或型号
给多个编码 Agent 共用的本地长期记忆库，用 SQLite 存原始对话，记忆可溯源、可修正、可删除
给 Hermes、Claude Code、Codex 等编码 Agent 提供本地长期记忆，用单个 SQLite 库存储，支持带来源回溯的混合检索，并能查看、纠正或删除记忆内容。
核心能力
- 用 SQLite 保存原始对话，事实与向量可溯源、可重建
- 自动召回按词法覆盖或向量相似度阈值注入 0~6 条记忆
- 提供 profile 与 entity 只读视图，输出分类后的当前事实
- trace 支持两到三跳关系证据路径，不调用模型也不写入推断
- 多个 Agent 可共享同一存储，删除操作对所有 Agent 生效
容易踩的坑
内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README
- v4.0.3scope-recall v4.0.3最新正式版2026-11-07 · 2026-11-07 08:02 UTC
hermes memory setupandscope-recall setup --host hermesnow give a new Hermes entry's memory to Hermes Desktop on the same machine as well as to the CLI: the entry gets the owner principal(desktop, local)and itsowner_privaterow on the CLI row's scope, so a Desktop chat recalls and captures without ascope-recall grantsedit.hermes --tuistill needs the owner's approval, because the browser dashboard's chat tab runs the TUI and a dashboard on loopback can serve it without a login. Running setup again keeps an existing entry's grants; add Desktop to an entry made by an earlier release asdocs/install/hermes.mddescribes.No schema change is needed: stores from 4.0.0 through 4.0.2 work directly with this release.
- v4.0.2scope-recall v4.0.22026-11-06 · 2026-11-06 10:43 UTC
查看更新说明
A Hermes that installs Scope Recall from its plugin catalog can now use it.
hermes memory setupwithscope-recallselected runs the ordinary setup through the provider's setup hook, using the plugin environment's interpreter, and reports a refusal in one line. Hermes entries in a shared store carry the Hermes profile's identity instead of a fixed agent id, so a fresh installation's sessions no longer fail with anagent_identityconflict; an unused entry recorded with the old id is repaired. Setup leaves a catalog-installed plugin directory under Hermes's control, treats a home that selects the provider but holds no database, manifest or receipt as a fresh installation, and changes onlymemory.providerinconfig.yaml. The provider reports itself unavailable until it is bound, and unbound turns no longer raise. A named Hermes profile attaches to a shared store ashermes-<profile>, so another agent recalling its items can say which profile heard them.plugin.yamldeclaresprovides_hooks,requires_hermesand the pinned core package.Inside Hermes, model and embedding credentials come from Hermes's own secret source for the active profile; the plugin does not read
.envor other credential files. Background workers receive only the declared credential names, and work that needs a missing credential is held and rechecked every minute instead of being claimed and returned (#354). On Windows, copying a file's access control no longer needs permission to change its owner when the owner stays the same, and a failed backup leaves no empty file. On macOS, a store no longer repeats its structure check after every write: the check's cache key leaves out the inode change time, which macOS advances on each transaction. Therevisetool's guidance says that original messages cannot be revised and that a value stated in conversation needs no tool call.No schema change is needed: stores from 4.0.0 and 4.0.1 work directly with this release. Before release, a pre-release build was taken through the catalog installation on Windows, Linux and macOS with Hermes v0.23.0: install, setup, recall in a new session, and a correction. The test suites now also run on macOS.
- v4.0.1scope-recall v4.0.12026-11-06 · 2026-11-06 10:24 UTC
查看更新说明
Empty or whitespace-only HTTP 200 responses now get bounded recovery as unfinished upstream responses, while uncertain billing reservations and duplicate-execution safeguards remain in place. Hermes notices retain their trusted host origin across display timestamps and later human messages; those messages keep their own origin and are captured once. Scheduled Hermes sessions without a user no longer participate in memory and report
capability_gap:unbound_sessionin diagnostics. After more than 60 seconds idle, binding a Hermes session warms the query embedding route in the background using the auxiliary budget; private mode skips the warm-up.Only first-hand human messages, external documents and imports originally from either can start consolidation. Assistant messages, tool output and host notices can still be embedded; old ineligible consolidation work is marked obsolete without a model call. After two automatic decisions, only a first-hand human restatement can reopen a candidate; after five undecided evaluations, retries and other paths also observe the limit of one question per day. OpenAI-compatible embedding routes can settle usage reported only as
total_tokens, while unknown or invalid usage keeps its reservation. Configuration lines that name a credential environment variable, such ascredential_env: OPENROUTER_API_KEY, are no longer refused as credentials. The documentation explains that model and embedding routes use the worker process's proxy environment and that local network routes belong inno_proxy.No schema change is needed: stores from 4.0.0 work directly with this release. The optional
vector.tool_output_embeddingsetting defaults totrue, preserving existing behavior; set it tofalseto keep new tool output searchable by keyword without embedding it. The changes in this release have not been verified on a real host; validation was limited to automated tests using synthetic data. - v4.0.0scope-recall v4.0.02026-11-04 · 2026-11-04 09:47 UTC
查看更新说明
Source-backed summaries, reviewed facts, entity links and task handoffs improve shared memory across five hosts, with local review, private mode and recall history. The store structure moves from 1112 to 1134 and upgrades itself on first open after taking a snapshot. Upgrade with all store users stopped and keep the pre-upgrade snapshot: older releases cannot open the upgraded store. Remote 3.16 clients keep working against a 4.0 server.
A new session starts with the tasks in progress, recent decisions and preferences, and work left half done in one host reaches the next session of another host in the same project. After the owner corrects or withdraws a fact, current and automatic reads stop returning the old value and the sources that only supported it, and a session that already received it gets one short correction notice. Recall history records what each turn injected and why; an optional review list holds memories before storage, one entry can be paused without the others, and
scope-recall pause/resumework inside a conversation. The same person or thing under different names resolves to one entity, "go with option two" resolves to that option, and facts spread over several sessions are summarised, with original words ranked ahead of restatements. Text that tries to instruct the agent is held back. Injection has a per-turn token cap, an optional session total andjson,compactandoutlinerenderings. Memory files of Claude Code, Codex and Hermes, ChatGPT and Claude exports, and mem0 and claude-mem data import after a preview. Vectors move into SQLite: the per-session LanceDB helper is gone and existing vectors import in the background.scope-recall replay-sessionsrecovers host sessions an entry missed while its hooks were off.On LongMemEval-S, with one answering model for every method, the sealed split scores 0.553 against 3.16.1's 0.557 (paired p = 1.0) with median recall time 188 ms against 1,269 ms; naive RAG scores 0.657 on the same split, a gap in recall coverage. Retrieval p95 is 0.3-0.8 s on stores of 350,000 and 1,000,000 records, and the prompt hook takes about 100 ms more than in 3.16.1. A signed-in real-host run for Claude Code, promotion time with real models, Linux hosts and the Docker install were not verified for this release.
- v3.17.0scope-recall v3.17.02026-10-31 · 2026-10-31 10:20 UTC
查看更新说明
Capture masks a detected credential instead of refusing the whole message. The value after a credential label, and a key-shaped token, becomes
[REDACTED_SECRET]; the label and the text outside the value are kept. An unquoted value is masked to the end of its line or its item in a structure; a quoted one to its closing quote, or to the end of the line when anything after the quote could extend it; a three-quote literal to its closing quotes. Capture still refuses a credential in an identity or reference field, a message that would be left as the marker alone, a private-key block and a value that may continue on the next line. Receipts, hook diagnostics and the remote server's hook log report how many values were masked (masked_secret_count). What counts as a credential is unchanged, and recall, model requests and corrections keep their checks.A remote
UserPromptSubmithook no longer makes its recall wait for the prompt's capture: once the prompt is durably queued, the server commits it on its own thread, and the hook reports a capture still being written as queued. A prompt sent again with only a later time is answered as the message already stored instead ofcapture_failed (VERSION_CONFLICT); a different message under the same key stays queued ascapture_conflict_pending. The Codex client's background sender no longer sends a spooled hook that its own request is still sending; this part takes effect once the machine that runs the hooks is upgraded. The server's hook log adds the capture's outcome and, for each recall, where a vector search or query embedding stopped.
用户点评
登录用户的真实使用记录，可按版本和硬件筛选共 0 条
还没有人点评。第一个说出真实体验的人最有价值。
Scope Recall
This checkout is 4.0.3. Local, source-backed memory shared by Claude Code, Codex, Hermes, WorkBuddy and DeepSeek Harness.
SQLite keeps the original conversations; model-derived facts and vectors remain traceable and rebuildable.
Quick start
- In the Python environment you want the hooks to use, run
python -m pip install -U "hermes-scope-recall[codex]". - Run
scope-recall setup. Review the detected hosts, store, scopes, zero model budget and worker plan, then confirm. - Start a new host session. Approve the plugin hooks or MCP server when the host asks.
For this development checkout, install from the repository root with python -m pip install -U ".[codex]";
the package-index command above selects a published release. An unpublished wheel can be installed directly with its codex extra.
| Host | Setup and host-specific approval |
|---|---|
| Claude Code | Setup |
| Codex | Setup and hook review |
| Hermes | Setup and local identity |
| WorkBuddy | Setup and MCP approval |
| DeepSeek Harness | Setup and plugin check |
Without model routes or budget, setup reports 原文检索可用 (original-text search available).
Use scope-recall setup --configure-models for guided routes and budget configuration, or
--models <route-file.json> for automation. Successful model checks report 完整记忆功能可用
(full memory features available). Model keys are environment references; setup never asks for a key value.
Installation covers shared stores, reruns, worker commands and verification boundaries.
For a shared store on a Linux Docker host, see Docker deployment.
Agents can hand off a task across entries, with one receiving entry and a bounded session-start report.
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. Retrieval reserves time for compilation and fresh SQLite release checks, so slow optional channels can leave a partial packet with their cutoff reason. Unverified items never ship. The thresholds and diagnostic counts are described in the recall configuration.
Current and automatic recall preserve the ordinary complete items and can append a neutral list when remaining matching records span at least three sessions. Each session contributes its highest-ranked remaining visible record. The list does not assert that records describe the same event or count how often something occurred. Every row labels its excerpt, full text length, source time and versioned reference; use inspect to expand the source. At most twelve rows share at most 1024 budget units and one quarter of the packet budget, using only space left after the complete items. Rows that do not fit are omitted without displacing full evidence. Visibility, privacy, suppression, current versions and retelling checks apply before publication. Historical reads keep their ordinary items. Existing packet fields and the shared host renderer carry the list; no migration or configuration change is required.
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.
Extraction can normalize fact wording while keeping exact source character intervals. A separate model judgement handles support that literal checks cannot establish; unavailable or uncertain support remains a labelled candidate. Claim contracts describe promotion, merging and source authority.
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, held-content review, private rules, export and backup status in your browser.
Capture screens text for embedded instructions, exfiltration links and hidden Unicode before indexing. Held sources
are excluded from recall and processing; explicit inspection returns a reason without their words. The owner can
review and release them on the local management page. External and unattributed sources await an explicit review result.
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 import --source <kind> --from <path> --source-id <stable account> previews external
memory files and conversation exports without opening the store. Review the original actors, projects and time range,
then repeat with the same store selection, --yes --preview-id <shown hash>. Approval permits import; it does not
confirm the content as fact. Importing memories describes supported formats and retry behavior.
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 with one of --session <id>, --project <path> or --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.
Install or upgrade with an assistant
Run scope-recall setup --dry-run --plan-json to inspect the complete plan, then
scope-recall setup --yes after the owner has approved it. Existing installations reuse their store and grants.
Legacy conversion and live process coordination use the migration workflow.
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. NumPy provides mapped retrieval and exact full-vector
scoring without SQLite extensions. The lancedb extra is only a reader for existing
LanceDB embeddings. Legacy vector.backend values map to the SQLite companion automatically.
The worker imports existing vectors without embedding calls and retains the original files.
Until all visible identities are verified, recall uses lexical channels and reports an import gap.
Missing or unreadable input remains a reported gap. Changing the embedding model still requires
an explicit re-embedding run; opening a store never authorizes paid reconstruction.
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. Admitted aliases can identify people, objects, places, organizations and projects. A worker compares bounded spelling/vector candidates with source evidence before recording a reversible identity relation. Different scopes, projects and branches remain separate; ambiguous names stay unresolved. Entity, trace and recall recheck these relations when reading. 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.
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 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). Full backup bundles
and disaster recovery restore to fresh destinations are in docs/backup-restore.md.
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 operator follows the migration workflow for 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
Contributor checks cover clean-wheel installation, both CLI aliases, read-only diagnostics and capture/recall in temporary stores. These checks do not establish that a running host loaded the package.
Queue states, retry limits and recovery actions are described in Background work.