tr1v3r/dsh-ltm

dsh-ltm

为 DeepSeek Harness（dsh）提供的结构化长期记忆：一个本地 SQLite 存储，具备 CJK 感知的分词搜索、BM25 + 字符 n-gram 混合重排序、近似重复检测、过期审查，以及从 dsh-memory 一键迁移——零强制网络访问。

为什么

- dsh-memory@0.1.0 是纯文本 + 使用默认分词器的 FTS5：中文检索实际上无法工作（整句话变成单个 token）。
- 长期存活的记忆需要超出追加/搜索的生命周期控制：结构化的作用域和标签、重复检测、审查时间戳，以及有界召回。

安装到 profile

使用 @tr1v3r/dsh-ltm 0.1.2 或更新版本，一条命令即可安装并注册捆绑配置：

dsh plugin --profile web add @tr1v3r/dsh-ltm

将 web 替换为你的 profile 名称（例如 dsh-tui），然后重启该 profile。该 bundle 将数据库路径设置为 $DSH_HOME/memory/ltm.db；无需 API key 或 embedding 服务。

替换 dsh-memory 时，请先禁用其现有条目：两个插件都会注册 memory_write、memory_search 和 memory_forget。如果你已经手动插入了 ltm 条目，请在启用 bundle 之前移除该手动插入，以避免重复实例。安装不会自动迁移旧数据库；参见从 dsh-memory 迁移。

对于手动组合（包括 0.1.0–0.1.1 版本，这些版本缺少 bundle manifest），请安装 npm 依赖，并将以下内容插入 profile 的 cordis.patch.yml，而不是启用 bundle：

- insert:
- id: ltm
name: '@tr1v3r/dsh-ltm'
config:
path: !!js dshHomePath('memory/ltm.db')

path 是必填项，代码侧没有默认值。推荐的部署路径 $DSH_HOME 下的 memory/ltm.db 是一个新的、独立的数据库——本插件从不写入旧版 memory/memory.db。

配置

| key | 默认值 | 含义 |
|---|---|---|
| path | （必填） | SQLite 文件，或 :memory: |
| defaultScope | "" | 回退作用域，或在禁用自动检测时作为固定作用域 |
| autoProjectScope | true | 从每个 agent 会话的 cwd/Git 仓库推导当前活动项目 |
| escapeSequences | [] | 可选的输出序列，在提示渲染前用零宽空格打断 |
| promptRecentCount | 10 | 召回区中未固定的近期记忆数量 |
| promptMaxChars | 2000 | 该区的硬性 UTF-16 字符预算；固定项优先保留 |
| promptMaxTokens | （未设置） | 可选的正安全整数硬 token 上限，与字符数并列 |
| promptTokenizerPath | （未设置） | 本地支持的 Hugging Face tokenizer.json；必须与 promptMaxTokens 一起使用 |
| maxTextChars | 2000 | 每条记忆的最大字符数 |
| searchLimitDefault / searchLimitMax | 10 / 50 | 搜索结果限制 |
| promptOrder | 50 | 召回区段顺序 |
| dedupeThreshold | 0.8 | Jaccard 相似度 ≥ 此值即在写入时标记为近似重复 |
| dedupeCosineThreshold | 0.92 | 余弦相似度 ≥ 此值也会标记为近似重复 |
| staleAfterDays | 90 | 超过此天数未确认的记忆将呈现为过期 |

默认情况下，记忆文本在召回提示中会被原样保留。escapeSequences 是部署级别的显式可选启用项，适用于会将渲染后的提示再传递给额外的基于分隔符的解析器的环境；DSH 本身并不需要它。

无效值（空路径、非整数边界、超出 [0,1] 的阈值、短于 2 个字符或包含零宽空格的转义序列）会在插件加载时抛出错误——大声失败，而不是等到第一次工具调用时才失败。

自动项目隔离

当 autoProjectScope: true 时，每个 agent 都会解析自己的 session.header.cwd；绝不会使用共享的 DSH 进程 cwd。Git 检出通过其规范公共 Git 目录来标识，因此子目录和链接工作树共享同一个项目作用域。非 Git 工作区通过其规范目录来标识。Git 作用域名称仅包含一段简短的 SHA-256 摘要，因此每种链接工作树布局都保持完全一致；目录作用域还会包含一个可读的基名。绝对路径绝不会被存储。

面向模型的默认行为有意保持狭窄：

- 写入和近似重复检查使用当前活动项目作用域；
- 搜索和自动提示召回只能看到当前活动项目加上全局记忆（scope=""）；
- update、forget、confirm 和 merge 会拒绝这些可见作用域之外的记录，并且 merge 绝不会跨越作用域边界；
- memory_list 和 CLI 仍然是显式的跨项目聚合/管理界面。

将 autoProjectScope: false 设置为仅使用 defaultScope 作为固定的部署作用域（使用 "" 表示仅全局操作）。作用域是上下文隔离边界，而不是操作系统权限边界；任何能够直接访问 SQLite 文件或 CLI 的人仍然可以管理每一条记录。
可选的离线提示 token 预算

添加到 ltm 条目的 config 中；请自行准备此本地资源。
promptMaxChars: 2000
promptMaxTokens: 512
promptTokenizerPath: /path/to/pinned-model-revision/tokenizer.json

这两个选项默认均未启用：现有的仅字符输出保持不变。
两者必须同时设置。可选的 @huggingface/tokenizers@0.2.0 依赖
仅在配置好的插件启动时加载一次；渲染仍保持同步，
不进行网络请求、下载或文件读取。如果你的包管理器省略了可选依赖，
请自行安装。CLI doctor 可以使用显式提供的 JSON 配置渲染诊断投影
（它绝不会读取正在运行的 profile）。

这支持一个受限的、经过保真度测试的 ByteLevel/BPE 子集：GPT-2 风格的
ByteLevel，或已发布的 DeepSeek-V3 Isolated Split 模式后接 ByteLevel，
在没有规范化器（或空的 Sequence）、完整的字节词汇表和确定性 BPE 的情况下。不支持的管道/选项会在启动时失败，而不是静默地近似任意的 Hugging Face 分词器。缺失的文件、格式错误的 JSON、无效的限制以及缺失的可选依赖项也会在打开存储之前大声失败。

上限计算的是完整的转义召回部分，包括头部、元数据、换行符、截断省略号以及任何省略通知，不添加 BOS/EOS 或聊天模板。固定记录优先；最近记录永远不会为省略通知而取代固定记录。必要时，第一条固定行会在 Unicode 码点边界上被缩短。如果即使其可识别前缀加上头部和省略号也无法同时满足两个上限，则该部分为空。计数不可相加；每个候选项都作为整体进行编码。UTF-16 字符限制仍然是硬上限。

离线计数对于所支持的选定分词器定义是精确的，并非对服务器报告用量的承诺：提供商可能使用另一个修订版/分词器、聊天框架或特殊 token 策略。不执行自动模型路由或服务器用量校准。FTS/搜索/去重分词和模式版本不受影响。有关资产版本/哈希/许可证要求、开销和保真度证据，请参阅配置、兼容性和验证。

面向模型的工具

兼容 dsh-memory 习惯：

- memory_write(text, tags?, pinned?, force?) — 首先进行去重检查；除非 force: true，否则返回近似重复项而不是写入
- memory_search(query, limit?) — 支持 CJK 的分词 + 混合重排序
- memory_forget(id)

新增：

- memory_update(id, text?, tags?, pinned?) — 就地修订，保留 id
- memory_confirm(id | "*") — 刷新审查时间戳，清除过期项
- memory_list(scope?, tags?, stale?, limit?) — 过滤浏览（标签 AND）
- memory_merge(targetId, sourceIds[], text?, tags?) — 合并重复项；标签默认为并集

当其身份尚不已知时，在写入之前优先搜索现有的事实/主题。同一事实的状态变化应放在 memory_update 中，而不是另一次写入或强制的近似重复。相似性并不证明等价或矛盾；请审查候选项。这是指导，而不是强制性的额外搜索调用或新的长度限制。

成功的固定写入和相关更新包含可选的 budget 反馈：实际渲染的字符数、可选的已配置分词器 token 数、来自渲染器本身的已选、已省略和已截断的 ID。该计算使用当前可见范围、最近计数和转义/预算配置——而不是整个数据库的文本长度。被拒绝的重复写入不会声称新的固定预算。成功变更后的渲染失败会单独报告；保存的 ID 仍然成功。

规模和限制
在同一作用域内，每次非强制 memory_write 都会扫描所有记忆以进行近重复检测。此设计面向个人长期事实存储，而非大型文档集合。写入成本随该作用域中记忆的数量和长度增长；目前尚无有基准支持容量限制的文档记录。

同一台个人电脑或服务器上的多个会话可以共享一个本地 WAL 数据库。使用当前 FTS 词元打开一个已初始化且兼容的存储不会获取 schema 写入锁；首次初始化、schema 修复和词元索引重建仍需要写入。SQLite 仍通过 5 秒忙超时来串行化写入者。SQLITE_BUSY 错误提示你稍后重试；应用不会自动重试。去重仍在写事务内进行，因此随着存储增长，其全作用域扫描可能更久地持有写入锁。这不是高并发服务，也不是跨机器数据库同步。

CLI

npx -p @tr1v3r/dsh-ltm dsh-ltm --db /path/to/ltm.db  [--json]

list / search / show / edit / tag / pin / merge / confirm / export / import —— 每个命令都支持 --json 以输出机器可读结果。未知标志、互斥标志和多余的位置参数都会被拒绝。默认数据库：$DSH_HOME/memory/ltm.db。

export 输出 dsh-ltm-export/1；--out 必须指定一个新文件。现有文件（包括符号链接和硬链接）绝不会被覆盖，活动数据库及其 SQLite 附属路径即使不存在也会被保留。每次导出请选择新的备份文件名。不带 --out 时，JSON 输出到 stdout；shell 重定向不受此保护，因此绝不要重定向到数据库或现有备份。

import 会验证完整负载，并恢复 ID、时间戳、规范化标签、作用域、固定状态和过期生命周期。重新导入相同 ID 会被跳过；若某个 ID 的存储值不同，则整个导入会中止，不会进行部分写入。

只读质量医生

dsh-ltm --db /path/to/ltm.db doctor --json
dsh-ltm doctor --config /path/to/ltm-config.json --scope 'git:…' --max-pairs 100000 --json

doctor 以 SQLite readOnly: true 打开一个现有数据库，绝不通过
MemoryStore：不创建、不更改日志模式、不重建 FTS、不迁移、不确认
或清理。缺失的文件/父目录和不兼容的 schema 会明确报错。
它读取一致的基础行快照，包括已提交的 WAL 数据。FTS 健康状况
明确不会被检查或修复；旧词元版本不会妨碍分析。

两种输出模式都会省略所有记忆文本和标签。发现项仅包含 ID、规则名称、
原因、长度/相似度。请有意使用 show/list 检查正文。
规则仅供参考：长条目（报告中会打印 UTF-16 阈值）、疑似
临时状态/路径线索以及可能的项目特定全局条目并非
删除、迁移或缩短任何内容的依据。全局项目线索无法识别
所属项目。任意 #123 文本不会被当作记忆引用：没有可靠语法时不会执行引用检查。

分析和范围分布覆盖整个数据库。提示词核算则单独处理：默认使用 CLI 当前工作目录推导出的项目 + 全局范围，或者当 autoProjectScope: false 时仅使用 defaultScope。--scope S 覆盖的是当前提示词范围，而不是审计总体（在自动模式关闭时，它仍保持仅固定范围）。所有选中的范围都会被打印。选择/排序/最近数量限制和预算与实际提示词渲染器一致，包括元数据、转义、头部、通知和截断；ID 以结构化方式跟踪，而不是从可能多行的记忆文本中解析出来。

CLI 不会加载实时配置。没有 --config 时，报告的预算是包默认值，并不代表已部署的设置。--config 接受一个 JSON 对象，包含与插件配置相同的键（包括 promptMaxChars、成对的 promptMaxTokens/promptTokenizerPath、promptRecentCount、escapeSequences 以及范围/去重设置）；--db 会覆盖其路径。相对路径从 CLI 当前工作目录解析。会打印数据库路径和配置来源，但绝不会打印完整配置。Token 计数具有上文所述的相同离线分词器限制。

同范围近重复分析在记录数量上是二次复杂度（也对文本长度敏感），默认最多进行 100,000 次成对比较。可按需提高 --max-pairs N；总数、已比较、已跳过和 complete 始终显式给出，因此不完整的扫描无法悄悄声称已覆盖。相似性是词汇证据，而不是矛盾检测。不会引入嵌入、自动清理、模式变更或后台 LLM 调用。

从 dsh-memory 迁移

从已退役的 dsh-memory 插件进行的一次性导入位于仓库中，而不是已发布的 CLI 中（scripts/legacy-migration/；参见其 README）。对于 dsh-ltm 数据库之间的备份和传输，请改用 export / import：它们会保留项目范围和审查时间戳，而迁移（旧模式、全局范围映射）不会。

开发

pnpm install
pnpm typecheck && pnpm test && pnpm build

- node:sqlite（Node ^22.19.0 || >=24.0.0）；WAL + busy_timeout。
- 引擎模块：src/store.ts、src/tokenize.ts、src/search.ts、src/dedupe.ts、src/expire.ts、src/migrate.ts；冻结接口位于 src/contracts.ts。
- 表层模块：src/config.ts、src/tools.ts、src/prompt.ts、src/cli.ts、src/index.ts。

发布凭据

发布通过 npm Trusted Publishing（OIDC + provenance）从 .github/workflows/publish.yml 发出，因此 CI 完全不需要存储 npm token。
尽可能将任何其他 npm 发布凭据保存在仓库之外。如果本地发布命令需要项目级配置，请使用被忽略的 .npmrc-publish 路径，并且绝不要强制将其添加到 Git。不要将 npm 令牌放入受跟踪的 .npmrc、源文件、示例、测试夹具、shell 记录或 CI 日志中。

通过平台的加密密钥存储提供 CI 发布凭据。在支持的情况下，使用最小权限、短期或细粒度的令牌。如果令牌可能已进入提交、日志、制品或共享终端历史记录，请立即在 npm 账户中撤销或轮换该令牌，然后再清理暴露的副本；仅重写 Git 历史记录并不能使该凭据失效。

MIT © tr1v3r