共享记忆检索 Juna9969/dsh-pi-billion-memory

Pi Billion Memory · DeepSeek Harness 原生版

1.0.0 · 移植自 pi-billion-memory 0.5.3，针对 Harness 0.1.7-rc.2 / billion-context 0.1.166 的原生持久化格式适配。

把 Pi / OpenCode ACP / DSH billion-context 的压缩摘要放入同一个本地 SQLite 记忆索引。不是把 Pi 扩展直接塞进 Harness，也不是完整会话搜索器。

快速使用

- 模型工具 memory_search：跨项目检索历史压缩摘要；可传 project 精确筛选项目标签，默认 6 条、最多 20 条。中英文空格分词，多个词为 AND；少于 3 字符的词走 LIKE，其余走 FTS5 trigram。
- 人工命令 /memory status：共享索引数量、最近扫描、跳过原因和当前写权限。
- /memory sources：查看实际生效的来源白名单。
- /memory scan：增量扫描。
- /memory rescan：重新解析；不会覆盖已存摘要文字，只补入新块、刷新来源信息和消息引用。
- /memory prune 30：只提示确认语法。实际删除须 /memory prune 30 --confirm；仅删除有时间戳、超过保留期的摘要，记录 tombstone，源文件不删。此操作影响 Pi 与 DSH 共享索引，不能在插件内撤销。

没有自动剪枝，没有网络请求，没有自动向提示词注入记忆。检索结果是历史资料，不是当前指令。命令不触发模型轮次；Harness 仍会记录命令执行事件。

与现有 Pi 共享什么

默认以运行 Harness 的操作系统用户 HOME 为基准：

| 路径 | 用途 |
| ~/.pi/pi-billion-memory.db | 与 Pi 共用的摘要、FTS 索引、来源水位和剪枝墓碑 |
| ~/.pi/pi-billion-memory.json | 共用配置；只读入，不自动重写 |
| ~/.pi/pi-billion-memory.sources.jsonl | 共用来源白名单；只读入，不自动重写 |
| ~/.pi/pi-billion-memory.dsh-attribution.db | 本插件额外建立的 DSH 会话 ID → cwd 归属缓存；不改共享数据库结构 |

保留 Pi 0.5.x 的 UNIQUE(source_file,block_id)、不可变摘要、mtime/size 水位、消息引用及 tombstone 语义。当前 Pi 0.5.2 可以继续使用同一兼容索引，不会被隐式升级。未知/旧版/不兼容数据库结构会拒绝打开并提示迁移，绝不删除重建。

读写连接使用 WAL、busy_timeout=5000、synchronous=NORMAL 和 BEGIN IMMEDIATE，扫描有水位比较与有界重试。支持同一台机器的多进程；不要把活动数据库放到 NFS/SMB 等网络文件系统。保持各进程使用同一规范路径，避免硬链接或别名重复索引。

检索和状态查询使用 SQLite readOnly:true / query_only，不创建索引数据库、不迁移、不扫描、不写日志。注意：SQLite 活动 WAL 数据库的只读连接仍可能需要创建或更新 -shm / -wal 辅助文件，不是逐字节文件系统只读承诺；不能对活动共享库使用 immutable=1 忽略 WAL。参见 SQLite 官方说明。

来源与 DSH 适配

共享白名单不存在时，默认扫描 Pi sidecar 与 OpenCode ACP 目录；另外添加一个不写回共享白名单的 DSH-only Bili 来源。已有白名单中的同根 Bili 条目优先，包括 enabled:false 和更窄的 pattern；Windows 大小写及可解析目录别名会归一化比较。白名单损坏/不可读时整个扫描失败关闭，而非退回宽泛默认值。空白名单仍可能有独立的 DSH 默认来源；要全部禁用，同时设置 dshEnabled:false。

原生 DSH 根目录按以下顺序确定：

1. 插件配置 dshSessionsRoot；
2. Harness Host 进程的 BILI_SESSIONS_DIR；
3. $XDG_DATA_HOME/billion-context/sessions；
4. ~/.local/share/billion-context/sessions。

默认 DSH 来源仅接纳 pluginAgent:'dsh' 的 Bili 文件。读取 v3 envelope 的 payload.state.blocks，也兼容旧版平铺 state；不索引 messages、blockContents 或 content-store。只接受 hash24 会话文件名，跳过临时文件、内容库和恢复 .fb.json。如果代理部署在另一个进程/主机、使用另一个根目录，请显式设置 dshSessionsRoot；不从路由提示猜测。

当前格式没有持久化 cwd。本插件监听/引导加载当前 Harness agent 的精确 session ID 与 header.cwd，核对文件 ID 的 SHA-256 后才归属项目；未知历史不会套用当前工作目录。之后发现精确归属时，即使摘要文件未变化也会刷新元数据。归属缓存只保留首个精确映射，避免冲突覆盖。

BILI_PERSIST=false 时没有可扫描文件。BILIENC1 加密和 BILIZSTD1 压缩文件跳过并计数；不会读取密钥、解密或额外导出明文。

白名单示例（JSONL，每行一个对象；Windows 反斜杠须按 JSON 转义，也可用 /）：

{"id":"pi","adapter":"pi-sidecar","root":"~/.pi/agent/sessions","pattern":"/.jsonl.acp.json","enabled":true}
{"id":"dsh-off","adapter":"bili-session","root":"~/.local/share/billion-context/sessions","pattern":"/.json","enabled":false}

仅显式 adapter:'bili-session' 的自定义条目可以扫描非 DSH 的 Bili 摘要。支持的 glob 是 和 ，不是完整 minimatch 语法；不要使用 ..。

配置与权限

共用 JSON 配置示例（无需为默认值创建文件）：

{
"scanOnStartup": true,
"maxSummaryChars": 20000,
"expandEnabled": false,
"expandMaxChars": 40000,
"expandMaxMessages": 200,
"expandMaxReadBytes": 33554432,
"excludeDirs": [],
"debug": false
}

也兼容 dbPath、sourcesPath、logPath；路径必须绝对或以 ~/ 开头。诊断仅保存在本插件内存中的有界、脱敏环形记录，不写共用日志文件。共享配置在 worker 启动时载入，改后需停用/启用插件；白名单每次维护或展开都会重新验证。

插件组合包中的 native-only 配置：

- insert:
- id: pi-billion-memory-native
name: dsh-pi-billion-memory
config:
scanIntervalSeconds: 60
dshEnabled: true
dshSessionsRoot: C:/absolute/path/to/billion-context/sessions
scanOnStartup: false

插件选项覆盖共享配置。scanIntervalSeconds:0 关闭定时扫描；正值范围 10–2147483 秒。启动和定时扫描服从全局 sandbox policy；人工维护服从明确发起命令的会话 policy。

任何索引/归属缓存写入和剪枝都要求实际 policy 为 danger-full-access。 插件不会偷偷覆盖模式，也不会用 --confirm 绕过沙箱。workspace-write / read-only 下仍可检索已有共享索引，维护命令会明确拒绝。Native 插件是受信任的 Host 代码，其直接文件/SQLite 访问不是 shell 沙箱代理；安装本插件即信任其限域实现。

隐私边界与可选展开

- 插入前完整脱敏，再截断摘要/主题；读旧索引结果时再次脱敏，避免把早期未脱敏数据直接回显。脱敏是启发式规则，不能保证识别所有秘密。旧行本身不会因此被改写。
- 扫描不跟随白名单根目录下的 symlink/junction 子项；允许根目录本身是 junction（兼容 Pi 安装布局）。同一文件句柄在读前/读后校验身份、大小和时间。Node 没有跨平台父目录句柄 openat API，因此这不是对恶意本地并发写入者的强安全边界；只允许可信用户写入来源目录。
- 单文件最多 128 MiB；Bili 流式投影丢弃原文对象，不构造原文对象树。额外有嵌套、字符串、块数量和选中数据大小限制，超限会跳过，不记录成功水位。
- Pi 入库只读 sidecar 摘要和原始 JSONL 第一行 cwd 头；OpenCode 归属库仅只读访问。
- memory_expand 默认完全不注册。显式 expandEnabled:true 后只支持 Pi 原始 JSONL：先 mode:'list' 获取索引清单，再 mode:'full',select:[1,3] 选择具体消息。每次重新验证当前白名单、文件边界和字符/消息/读取上限，输出再脱敏。没有消息引用或源文件已删时会说明缺失。不支持 DSH/Bili 原文展开。
- 取消扫描/展开采用共享取消标记；工具请求等 worker 确认静止或退出才结束。SQLite 原子操作不能立即中断，已提交的早先文件不会回滚；当前未提交事务回滚。关闭插件会排空/终止其 worker，单个 agent 结束不关闭共享 worker。

安装、备份和回滚

要求支持 native bundle 的 Harness，以及提供 node:sqlite 的 Node ≥22.19.0。本机测试使用 Node 24.21.0 / SQLite 3.53.4；多个写入者应使用包含 SQLite WAL-reset 修复的版本（3.51.3 或相应维护分支回补版以上）。

1. 首次写入前做一致性备份。包内脚本使用 SQLite online backup API，不直接复制活动主库：

node scripts/backup.mjs "C:\Users\you\.pi\pi-billion-memory.db" "C:\private-backups\pi-memory-before-dsh.db"

目标必须不存在，且脚本不会输出摘要。备份仍包含全部私人记忆，请放在受限本地目录，勿上传或混入发行包。
2. Desktop 从 Harness 插件管理入口安装本地发行 .tgz 的绝对路径，启用 dsh-pi-billion-memory 组合包。不要执行 dsh plugin --profile desktop ...，Desktop profile 由 Electron 管理。
3. 在原来的 Harness 页面刷新工具/命令列表；无需替换 Web 服务。先 /memory sources、/memory status，确认根目录和权限；需要写入时再执行 /memory scan。
4. 独立 CLI 管理的 Web profile 可用 dsh plugin --profile web add "C:\path\dsh-pi-billion-memory-1.0.0.tgz"。不要为了本插件启动第二个 GUI。

停用：在插件管理中关闭此组合包。取消未完成扫描并关闭 worker 后，共享数据保留，Pi 继续可用。卸载只移除这个包/组合包，不要删除整个 .pi，不要恢复旧的整个 profile manifest。更换同名 Host 源码版本可能受到模块缓存影响，必要时等现有任务结束再重启，而非重启正在工作的 Host。

如确实要恢复备份，先停止 Pi 与 DSH 所有连接/写入者，单独保留当前主库及 WAL/SHM，再在离线状态恢复一致性备份；不要用旧备份覆盖活动主库。恢复会丢失备份后的记忆与墓碑，不能作为普通卸载步骤。

开发与验证

无构建步骤或网络依赖；Host 的 @deepseek-ai/dsh-tools 由 Harness 原生加载器提供，且声明为 optional peer，因此普通 pnpm/npm 安装不会尝试从公共源拉取该包（它不在 npm 上）。发行包本身可在隔离目录内直接 pnpm add 安装。

node --check src/host.js
node --check src/memory-worker.js
node --test test/.test.mjs

36 项隔离 fixture 测试覆盖在线 WAL 一致性备份及：三种来源、仅摘要/原文哨兵、UTF-8 投影、拒绝损坏/编码文件、同根禁用及 Windows junction、schema/trigger/FTS 拒绝、不可变文字/引用更新/水位/CAS 重试、WAL 多 worker、tombstone、完整主题脱敏、归属合并与迟到刷新、可选展开、取消回滚、worker 致命退出/排空、原生 API 注册/权限和 150 个已有 agent 引导。测试只使用临时 HOME，不扫描真实 .pi。

正式机器的结构验证仅输出版本与计数，不输出记忆正文。最新本机安装/运行结果另见发行附带的验证记录；离线 mock 通过不等于所有外部版本均已验证。