前言¶
DeepSeek Harness (DSH) 的核心哲学是「一切皆插件」。在开发基于 DSH 的智能体时，跨会话的持久化记忆是一个常见痛点。传统的向量检索方案通常依赖外部数据库，或者需要额外的模型调用，这增加了系统的复杂度和延迟。
dsh-long-term-memory 插件旨在解决这个问题。它为 DSH 提供了分层的、确定性的长期记忆能力。它使用 JSONL 文件存储数据，采用 CJK 感知的 BM25 算法进行确定性召回，并在每次请求组装前自动注入记忆摘要。该插件不依赖向量库、不需要额外的模型调用、也不需要自建 SQLite 或外部服务器，完全基于 DSH 已有的接缝进行组合。
核心功能¶
本插件提供以下核心能力：
- 三库分层存储：将记忆分为三个作用域，各占一个 JSONL 文件。
user：用户画像（姓名、角色、偏好）。global：跨项目的事实与决策。workspace：项目专属的记忆。
- 确定性召回：使用 BM25 算法检索。中文按汉字 bigram 匹配，日文韩文同理，英文按单词匹配。结果可解释、可重放。
- 自动注入与校准：每次组装请求前，通过
systemPrompt.context()注入记忆摘要。注入块被<long_term_memory>标签包裹，明确声明来源与不确定性，指引模型判断相关性并忽略无关内容。 - 安全机制：
- 威胁扫描：对写入内容和注入快照进行轻量模式检测，命中则拒绝写入或替换为占位符。
- 写入护栏：采用写临时文件 + rename 的原子方式，配合跨进程文件锁，防止数据损坏。
- 纠正回路：提供
memory_correct工具，用于更正旧事实，将旧记录标记为superseded，并在后续召回与注入中自动排除。
安装与启用¶
在插件目录下执行以下命令：
cd dsh-long-term-memory
dsh plugin --profile web add .
安装完成后需要重启 dsh web。
⚠️ 注意：
dsh plugin add命令曾破坏过link:的相对路径（导致相关插件被移出 bundles）。本插件已使用绝对路径link:/Users/...固化。请勿再对新插件依赖相对路径。
使用方式¶
插件提供两类使用入口：模型工具和斜杠命令。
模型工具¶
模型可以通过注册的工具读写记忆：
memory_write(content, scope?, tags?)：写入一条记忆。scope可选user/global/workspace，默认workspace。memory_recall(query, scope?, limit?)：BM25 检索，返回带分数的命中记录。memory_list(scope?, limit?)：按更新时间列出近期记忆。memory_get(id)：查看单条记忆。memory_forget(id, scope?)：按 ID 删除记忆。memory_correct(claim, truth, evidence?)：记录更正事实。
斜杠命令¶
用户可以直接在输入框使用斜杠命令（不经模型）：
/memory list [user|global|workspace|all]：列出近期记忆。/memory search <query>：BM25 检索。/memory get <id>：查看单条记忆。/memory forget <id>：删除单条记忆。/memory export [|markdown]：导出记忆 bundle。
配置说明¶
通过覆盖 cordis.patch.yml 或 settings.yaml 来控制行为。以下是关键配置项：
- 注入策略 (
injectContext)：recent（默认）：每轮注入每库最近的几条记忆。full：注入全部记忆（受字符预算限制）。off：关闭自动注入。
- 标签过滤 (
injectTags)：在recent模式下，只注入带有指定标签（如decision,constraint）的记忆，过滤琐碎条目。 - 写入审批 (
requireApprovalForWrite)：可选开启，在写入前通过 DSH 的审批接缝进行人工确认。 - 威胁扫描 (
scanThreatsOnWrite)：默认开启，对写入内容进行轻量威胁模式检测。 - 字符预算 (
charLimit)：每个作用域的字符上限，超限时先自动压缩再拒绝。
技术细节与注意事项¶
- 同步注入：DSH 的 prompt 组装器同步调用相关函数。如果注入渲染走异步路径（返回 Promise），会导致崩溃。插件已将注入渲染全部改为同步路径（首个 assembly 前异步预热 store）。
- 零外部依赖：插件内部实现了 BM25 分词器和 JSONL 读写逻辑，不依赖外部向量库。
- 威胁扫描保守：扫描模式刻意收窄（仅检测指令覆盖/系统提示泄露/角色劫持/标记注入），避免误伤正常笔记。注入快照使用占位符而非直接删除原文，保留供用户处理。
- 存储路径：
user:$DSH_HOME/dsh-memory/user.jsonlglobal:$DSH_HOME/dsh-memory/global.jsonlworkspace:<workspaceRoot>/.dsh/memory.jsonl
适用场景¶
适合需要在 DSH 智能体中实现跨会话记忆、用户偏好管理、历史决策追溯以及需要严格数据安全控制的场景。
- 记忆沉淀：模型在对话中通过
memory_write将关键信息沉淀下来。 - 确定性召回：当模型需要查询历史约束或事实时，使用
memory_recall获取高相关性结果。 - 知识库管理：通过
/memory list和标签过滤，整理项目文档或用户画像。
