Scoped Memory
做项目时,真正麻烦的往往不是忘了一句聊天内容,而是忘了当时为什么这样决定、哪些办法已经试过、下一步该从哪里接着做。
Scoped Memory 是一个可供 Codex 和 DeepSeek Harness 使用的本地工程记忆工具。它把值得长期保留的内容按照“使用者、项目、当前任务”分开放置,并用脚本把工程转换成紧凑的结构化事实。换一个会话或代理继续工作时,可以直接读取已有结论和工程关系,不必重新翻完整聊天记录,也不必先把代码改写成自然语言摘要。
为什么不让大模型每次重新读工程
一般的工作方式是:大模型打开很多文件,把代码、日志和测试重新解释成一段自然语言,然后再依靠这段解释继续工作。项目一大,这个过程会反复消耗上下文;压缩以后还可能丢失文件路径、符号名称、依赖方向和证据位置。
Scoped Memory 把工作分成两层:
- 工程脚本负责整理事实。 脚本直接扫描文件树,读取语言结构和项目清单,记录文件指纹、顶层符号、导入关系、测试位置、依赖名称和 Git 状态。这个过程可重复、可比较,不需要调用大模型。
- 大模型负责判断和工作。 Codex 或 DeepSeek Harness 先查询一小段与当前任务有关的工程事实,再按需打开少数源码文件。它不用先把整个工程翻译成文章,最后向人交付结果时才组织自然语言。
实际流程是:
代码、测试、配置和 Git 状态
↓
确定性工程扫描脚本
↓
按项目隔离的 EIR/1 工程索引
↓
按问题和长度预算选出相关事实
↓
Codex / DeepSeek Harness 继续分析、修改和验证
↓
最终结果才转换成人类自然语言
例如,模型不需要先阅读一段“认证模块依赖数据库模块”的说明。它可以直接得到:认证文件包含哪些符号、导入了哪个模块、对应测试在哪里、这些文件当前是否发生变化。需要确认实现细节时,它再打开准确的文件,而不是重新遍历整个仓库。
这样做带来的变化:
- 减少重复读取和重复总结,给实际推理、编码和测试留下更多上下文。
- 文件、符号、依赖和版本都有稳定标识,不依赖某次聊天的措辞。
- Codex 与 DeepSeek Harness 可以读取同一份工程地图,不需要分别建立两套自然语言摘要。
- 工程发生变化后重新运行脚本,就能用文件指纹和 Git 状态识别新旧差异。
- 索引只是导航和记忆,不替代源码、测试或运行结果;需要下结论时仍以真实工程证据为准。
第一版有意保持简单和可检查。它能提取 Python、JavaScript、TypeScript 等常见源码的顶层符号与导入关系,也能识别测试和常见依赖清单;它不会假装已经理解所有业务含义,也不会凭索引自动证明调用链正确。更深的语义分析、增量差异和语言服务器接入可以在后续版本继续扩展。
它适合记住什么
- 长期有效的工作习惯,例如代码风格和交付偏好。
- 只属于当前项目的架构决定、限制条件和已经验证的事实。
- 当前任务做到哪里、还有什么没完成、哪些方法已经失败。
它不应该保存密码、密钥、个人资料、完整聊天记录或大段命令输出。这里保存的是帮助继续工作的摘要,不是另一个聊天档案库。
不同项目不会混在一起
每个项目都有独立身份。默认情况下,一个项目看不到另一个项目的记忆。跨项目读取必须明确指定来源项目,并持有通过本机命令行创建、仍在有效期内的继承授权;撤销后下次召回立即拒绝。记忆事实和任务检查点本身不授予权限。
同一个 Git 仓库的工作树共享项目身份,因此在不同工作树之间切换不会失忆。普通复制或重新克隆的仓库不会自动继承原项目记忆,避免把不相关的工程误认成同一个项目。
记忆怎样保存
所有内容默认留在本机,不需要云端服务,也不需要额外密钥。记录先进入 SQLite 数据库,同时生成一份便于检查和迁移的 JSONL 审计日志。
旧记录不会被偷偷改写。更新一条结论时,系统会追加一条新记录并注明它取代了哪一条;忘记某项内容时,也会追加一条删除标记。这样可以追溯发生过什么,也可以检查日志是否完整。
在 Codex 中怎样工作
插件会在任务开始、恢复以及上下文压缩后,自动取回当前项目最相关的一小段记忆。内容有严格的长度限制,不会把整个历史重新塞回会话。
也可以通过命令行或 MCP 工具主动保存决定、建立任务检查点、查找记录或忘记某个主题。读取类工具不会改动数据;写入和忘记操作有明确的权限标记。
工程中间层 EIR/1
memory_ingest_project 使用确定性脚本扫描工程,生成 EIR/1:文件指纹、语言、符号、导入关系、测试角色、依赖清单和 Git 状态。它不调用大模型,不保存源码正文,并跳过密钥、环境变量文件、二进制文件和超大文件。
memory_engineering_context 再按查询和 token 预算返回一小段紧凑 JSON。大模型直接消费这些符号和关系;只有最终交付给人时才需要整理成自然语言。
scripts/scoped-memory --home /tmp/scoped-memory-demo ingest .
scripts/scoped-memory --home /tmp/scoped-memory-demo engineering-context . --query memory --token-budget 1200
0.4:紧凑记忆、独立任务与重复任务表
memory_recall_compact 使用固定的 SMC/1 码表,每条事实只返回一次,不再同时传 context 和重复的 items。预算针对返回的紧凑包;token 数仍是本地估算,节省量需在目标模型上实测。原 memory_recall 保留给现有客户端。
memory_open_task 为每个新任务生成独立 ID。memory_task_checkpoint、memory_task_context 和 memory_close_task 只操作该任务;新任务不会自动读到旧任务检查点。任务上下文只附加当前使用者/项目显式标记 durable-rule 的长期提醒,不能把旧任务授权保存为记忆。跨项目记忆继承还需要本机 CLI 创建有期限的授权;撤销后下一次召回立即拒绝。
重复任务可以先把经过人工检查的脚本作为候选登记到本机预测表,记录两份不同的成功证据引用后,通过本机 CLI 显式提升。memory_pattern_predict 仅在任务特征完全匹配、脚本指纹不变且未过期时返回建议。证据引用是使用者报告,工具不核验其正文;预测工具不会生成或执行脚本,也不会批准读取、修改、实验或外传。
# 本机演示,使用合成工程;不要把真实研究目录传给示例
mkdir -p /tmp/demo-project/scripts
printf 'print("demo")\n' > /tmp/demo-project/scripts/repeat.py
scripts/scoped-memory --home /tmp/scoped-memory-demo init /tmp/demo-project
scripts/scoped-memory --home /tmp/scoped-memory-demo task-open /tmp/demo-project
scripts/scoped-memory --home /tmp/scoped-memory-demo recall-compact /tmp/demo-project --token-budget 512
scripts/scoped-memory --home /tmp/scoped-memory-demo pattern-propose /tmp/demo-project repeat '{"schema":1}' scripts/repeat.py
当前插件是本机 stdio MCP。不要将全量工具原样暴露给云端;远程接入需要独立的本机授权与输出过滤层。此版本不改变任何外部任务执行权限。
DeepSeek Harness
DeepSeek Harness 原生支持本地 stdio MCP,因此可以直接使用同一个服务:
先使用隔离环境安装命令行服务:pipx install git+https://github.com/lixuanfan567-png/scoped-memory.git。
- insert:
- id: mcp-scoped-memory
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: scoped_memory
transport: stdio
command: scoped-memory-mcp
cwd: !!js process.cwd()
env:
SCOPED_MEMORY_HOME: /absolute/path/to/scoped-memory-data
连接后,Harness 会看到 mcp__scoped_memory__memory_ingest_project、mcp__scoped_memory__memory_engineering_context 以及原有记忆工具。Codex 与 DeepSeek Harness 可以共享同一个本地记忆库,同时继续遵守项目隔离规则。
本地开发
需要 Python 3.10 或更高版本。运行测试:
python3 -m unittest discover -s tests -v
构建安装包:
python3 -m pip wheel . --no-deps
初始化一个项目并查看状态:
scripts/scoped-memory --home /tmp/scoped-memory-demo init .
scripts/scoped-memory --home /tmp/scoped-memory-demo status .
测试覆盖项目隔离、任务隔离、显式继承、Git 工作树、独立克隆、并发写入、更新与忘记、中文长度预算、EIR 工程提取、敏感文件排除、启动注入、MCP 调用和审计恢复。
当前状态
项目目前处于早期版本。核心存储、隔离规则、Codex 启动注入和 MCP 调用已经通过自动化测试及真实运行验证,但在稳定版发布前仍可能调整接口。
参与方式见 CONTRIBUTING.md,安全边界和漏洞报告方式见 SECURITY.md。
本项目使用 MIT 许可证,详见 LICENSE。
Metadata
Release files for codex-scoped-memory 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| codex_scoped_memory-0.4.0.tar.gz | 33.2 kB | With provenance | Details for codex_scoped_memory-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| codex_scoped_memory-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for codex_scoped_memory-0.4.0-py3-none-any.whl |
Total release size: 62.5 kB
Release files / codex_scoped_memory-0.4.0.tar.gz
| Download URL | codex_scoped_memory-0.4.0.tar.gz |
|---|---|
| Size | 33.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c5604b8ecdc792feed3ea388ddfaddf2d10a92e437c18e1975c5328ef69ea75e
|
|
BLAKE2b-256 checksum How to use checksums |
c19fe9015c48d7cb19264243dc93cede09d61383f9872589d656c790dd7de0a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / codex_scoped_memory-0.4.0-py3-none-any.whl
| Download URL | codex_scoped_memory-0.4.0-py3-none-any.whl |
|---|---|
| Size | 29.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36c5740cb5185682e4023029261983d8f92c52e92511baf202e376f4115c059a
|
|
BLAKE2b-256 checksum How to use checksums |
4ab22cbfb8fd51a925f7495e6ac54ff38ff3cadd2b5c1673fbd4890b613449fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for codex-scoped-memory 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for codex_scoped_memory-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.