local-memory

dsh（DeepSeek Harness）插件。文件系统级本地资料检索层：持续索引你磁盘上指定的真实文件夹，增量更新，关键词检索返回 文件路径:行号 引用，全程本地、零网络、零 native 依赖。

状态：developer preview。尚未在真实 dsh 运行时中验证，手动验证步骤见下文。

定位与差异化

生态中已有 Recall（索引会话日志）、dsh-mnemon（agent 记忆库）、nowledge-mem（依赖外部服务）、mindspace-dsh-local-rag（上传语料 + 407MB ONNX 模型做语义检索）。本插件补的是它们没覆盖的场景：直接索引用户磁盘上的真实文件夹——免上传、免外部服务、自动增量、敏感目录默认排除、存储只是一个 JSON 文件。它不拼检索质量（v1 无 embedding 语义检索），拼的是轻量与自动。

工具

| 工具 | 作用 | | --- | --- | | memory_index | 索引指定文件夹（递归）。扩展名白名单只收文本类文件；.git/node_modules/.ssh/.aws/.gnupg 等敏感目录默认排除（extraExcludes 可追加）；超 maxFileBytes 的文件与二进制文件（NUL 字节探测）自动跳过。重复调用即增量更新：按 mtime+size 比对，只重建变化文件，删除的文件自动清理索引。 | | memory_search | 关键词检索。纯本地打分（IDF × 词频 + 短语加权），中文按二元组匹配无需分词器。每个命中带 路径:起始行-结束行 引用和上下文片段。省略 path 时搜索全部已索引文件夹。 | | memory_get_source | 按引用取原文片段（文件 + 行范围）。只允许读取已索引文件夹内的文件。 | | memory_remove | 删除指定文件夹的索引。只删索引目录中的数据，绝不改动原始文件（索引库存放在独立目录，物理隔离）。 | | memory_status | 索引状态：文件夹数、文件数、文本块数、最后更新时间、索引占用的磁盘空间。 |

安装与配置

# dsh 配置示例
- id: local-memory
  name: dsh-daily-local-memory
  config:
    enabled: true
    # indexDir: D:/data/dsh-index   # 索引存储目录，默认 ~/.dsh/local-memory
    # maxFileBytes: 1048576         # 单文件大小上限，超出跳过
    # chunkLines: 40                # 每块行数（引用按块给出行区间）
    # chunkOverlap: 5               # 相邻块重叠行数，防止跨块命中丢失
    # extraExcludes: ['family-photos']   # 追加排除的目录名
    # extraExtensions: ['.weird']        # 追加按文本索引的扩展名
    # searchMaxResults: 20
    # contextChars: 80

权限透明

本插件对宿主环境的影响面，逐条交代清楚：

• 读写位置：读——memory_index 指定的文件夹（递归、只读）；写——仅索引目录（默认 ~/.dsh/local-memory，可配）。memory_remove 只删除索引目录下的数据，源码上有物理隔离，不可能碰到原始文件。
• 网络域名：无。本插件不发起任何网络请求。
• 凭证：不持有任何凭证。敏感目录（.ssh/.aws/.gnupg/.kube 等）默认被排除，不会进入索引。
• 确认点：无新增确认点；工具均为只读或只写索引目录。
• 日志内容：仅在加载时写一行启动日志（含索引目录路径），不写文件内容。

检索方案说明

v1 采用自研倒排索引（terms.ts 分词 + search.ts 打分 + store.ts JSON 持久化），未使用 Node 内置 node:sqlite FTS5，原因：

1. 本仓库 engines 覆盖 Node ^22.19，而 node:sqlite 在 Node 22.x 各小版本中可用性/实验标志状态不一致（22.12 实测无 flag 抛 ERR_UNKNOWN_BUILTIN_MODULE），插件无法要求宿主运行时加启动 flag；
2. FTS5 的 unicode61 分词器不切分中文，自研分词（拉丁词 + CJK 二元组）对中英文混合资料开箱即用；
3. 保持零 native 依赖、存储格式透明（一个 JSON 文件，可直接查看/备份）。

v2 可选方向：接入 embedding 语义检索（本地模型或远端 API），在现有关键词索引之外加一层向量召回。

已知限制

• 无语义检索：v1 只有关键词匹配，同义词/近义表达搜不到（v2 计划）。
• 以文本类文件为主：PDF/DOCX/XLSX/PPTX 等二进制办公文档不在索引范围内；如需检索这类文件，建议先用 dsh-daily-documents 提取为文本/Markdown 后再索引。
• 二进制探测是启发式：按前 8KB 是否含 NUL 字节判断，极少数无 NUL 的二进制文件可能被当文本索引（会产生乱码块，不影响其他文件）。
• 整个文件夹索引加载进内存检索：适合 GB 级以下文本资料；超大语料建议分文件夹索引并用 path 参数限定搜索范围。

手动验证

本仓库的 CI 只覆盖类型检查与纯函数/集成单测（node:test + 临时目录）。接入真实 dsh 后请手动验证：

1. 在 dsh 配置中启用本插件，确认启动日志出现 local-memory: loaded（索引目录 …）。
2. 调用 memory_index 索引一个包含 Markdown/代码的测试文件夹，确认返回新增文件数与块数。
3. 调用 memory_search 搜一个文件中出现过的关键词，确认命中带 路径:行号 与上下文片段；再调用 memory_get_source 按命中路径与行号取原文，确认内容一致。
4. 修改/删除/新增一个文件后重新 memory_index，确认返回的 changed/removed/added 计数正确，且删除文件的内容不再被搜到。
5. 在测试文件夹中放入 .git/、含 NUL 字节的假 .txt、超过 maxFileBytes 的大文件，重新索引确认它们都被跳过。
6. 调用 memory_remove，确认 memory_status 中该文件夹消失且原始文件完好。

许可

MIT