twoyoung91/dsh-memoknow

MemoKnow：DeepSeek Harness 的本地记忆与知识插件

MemoKnow 是一款面向个人记忆和用户导入知识的本地 DeepSeek Harness（DSH）插件。它在 SQLite 中保存结构化记录，以 SHA-256 为原始文档生成快照，结合 FTS5 全文检索和可选的 sqlite-vec 语义检索，提供 Agent 工具，并在 DSH 内置界面中管理数据。

MemoKnow 是独立的社区插件，并非 DeepSeek Harness 官方组件。它面向单人使用的本地 DSH 配置，不是多用户服务，也不提供云端同步。

功能概览

- 从符合条件的已完成聊天轮次中提炼可长期使用的事实、偏好和决定；明确提出“请记住”的请求会更快处理。
- 在 DSH 的 Settings → MemoKnow 中查看、编辑或永久遗忘单条记忆。
- 将文本/Markdown、Word、PDF、CSV 和 Excel 文档导入为不可变的本地知识快照，并检索其中的文字；忽略文档内嵌图片。
- 默认使用 Local FTS，不需要嵌入模型或 API 密钥；可选的本地 CPU 嵌入或 OpenAI 兼容嵌入可改善知识检索。

界面一览

以下截图来自 MemoKnow 的真实管理界面，但使用的是虚构示例记录，不包含私人聊天内容或导入文档。

写入、搜索、编辑或遗忘单条记忆：

包含三条示例记忆和写入表单的 MemoKnow 记忆库

导入文档或粘贴 Markdown，再查看可搜索的知识库：

包含导入表单和两份示例文档快照的 MemoKnow 知识库

从默认的 Local FTS 开始，按需调整检索设置：

使用默认 Local FTS 模式的 MemoKnow 检索设置

安装步骤、日常使用、备份和故障排查请参阅英文用户手册。贡献者请阅读 CONTRIBUTING.md；版本变更见 CHANGELOG.md。

从源码目录快速安装

需要 Node.js ^22.19.0 || >=24.0.0、pnpm 11.7，以及兼容的 DSH 安装。在 MemoKnow 源码目录运行：

pnpm install --frozen-lockfile
pnpm run check
dsh plugin --profile web add .

如果 DSH 也是源码克隆，且 dsh 不在 PATH 中，请在 DSH 仓库根目录改用 pnpm dsh plugin --profile web add 。如果安装的是预构建的 GitHub Release 压缩包，使用 dsh plugin --profile web add 。安装后重启 web 配置。暂不支持直接用 github: 安装：这种方式会获取源码，而插件目前不会在 Git 安装过程中自动构建。上述命令参照 DSH 的插件打包指南和 CLI 参考文档。

安装并重启 DSH 后，打开 Settings → MemoKnow，选择 Setup & settings。Local FTS 是默认模式，无需模型。首次启用 Local CPU embedding 时，会下载固定版本的 INT8 Xenova/multilingual-e5-small 模型（含分词器文件约 140 MiB）。OpenAI-compatible 模式会在启用前验证接口地址和模型。如果嵌入服务之后不可用，仍可使用 FTS 检索。

如果选择 API 模式，请将密钥放入指定的环境变量（默认为 MEMOKNOW_EMBEDDING_API_KEY）。MemoKnow 只保存环境变量名，不保存密钥值。

托管嵌入策略

集成 MemoKnow 的产品可以通过标准 Cordis 插件配置固定一个 OpenAI 兼容嵌入服务，无需修改公开的插件源码：

- id: dsh-memoknow
name: '@dsh-external/dsh-memoknow'
config:
embedding:
source: managed-api
baseUrl: https://managed.example/v1
model: managed-embedding-model
apiKeyEnv: MEMOKNOW_EMBEDDING_API_KEY

托管模式会将这些值映射到运行时设置，并在管理界面中禁用相应控件；通过设置 API 更新也不能覆盖该策略。接口地址必须使用 HTTPS，但本机回环地址可用于开发。配置中只能写环境变量名；密钥值必须由进程环境提供，MemoKnow 不会返回密钥。

本地数据

默认数据目录为 $DSH_HOME/memoknow；如果未设置 DSH_HOME，则使用 ~/.dsh/memoknow：

memoknow.sqlite3
objects/sha256/aa/bb/[.txt]
models/                         # 仅启用 Local CPU 后创建

可以在 Cordis patch 中设置插件的 dataDir，选择其他目录。SQLite 是元数据和生命周期状态的权威数据源；原始文档快照是不可变文件；FTS 和 sqlite-vec 索引都属于可派生的数据。

导入知识

管理界面支持粘贴文本/Markdown，或导入不超过 25 MiB 的文件：

- Word .doc、.docx
- 带可提取文本层的 PDF
- UTF-8 编码的 CSV
- Excel .xlsx

插件会保留原始文件的完整字节。内嵌图片不会被提取、嵌入或索引。因此，只有扫描图片、没有文字层的 PDF 需要先经过 OCR；本版本不提供 OCR。暂不支持旧版 Excel .xls。

Agent 工具

- memoknow_remember
- memoknow_search
- memoknow_memory_list
- memoknow_memory_update
- memoknow_memory_forget
- memoknow_knowledge_import
- memoknow_knowledge_remove

记忆会随时间降低检索排名，但不会因年龄自动删除。遗忘操作会删除记忆记录及其搜索索引，不创建墓碑记录。将过时记忆自动移入墓碑区仍是设计目标，并非本版本功能。遗忘由聊天提炼出的记忆不会删除原始 DSH 聊天会话或其他备份。移除知识会删除文档记录和索引；只有当内容寻址的原始文件不再被任何记录引用时，才会删除该文件。

记忆半衰期默认为 180 天，自动召回最多返回 12 条记忆。知识检索没有用户可配置的结果上限，但仍有内部安全上限，以保护 Agent 上下文和 SQLite 进程。

自动更新记忆

每次根 Agent 完成一个轮次后，MemoKnow 只记录新增的用户直接发言和可见的助手文本。它会排除失败的轮次、子 Agent、工具或插件上下文、推理内容、简单应答，以及疑似凭证的内容。这一步在本地完成，不调用模型，并推进每个会话的持久化检查点。

符合条件的轮次使用该 DSH 会话已配置的模型提炼。普通更新按两分钟或五个符合条件的轮次批量处理；“请记住”之类的明确请求会跳过等待。模型只看到待处理的新增内容及少量通过词汇检索找到的相关记忆，不能使用工具；输出上限为 700 token，调用超时为 45 秒，并且必须返回经验证的 JSON。推断得出的记忆以 candidate 状态进入；用户明确要求记住的内容可以以 active 状态进入。

捕获和处理分别使用独立事务。重启、超时、模型故障、版本冲突或 token 预算不足时，已捕获的轮次会保留待处理，以便稍后重试。成功处理时，记忆变更、用量统计和检查点推进会原子提交。自动提炼默认每个会话最多使用 8,000 token，每个 UTC 日最多使用 30,000 token。

安全提示

管理 API 与 DSH 页面同源，拒绝跨站修改请求，将 JSON 请求体限制为 1 MiB、文件请求限制为 26 MiB，验证文件签名，使用参数化 SQL，设置严格的浏览器响应头，且不会返回敏感设置。除非另行部署带身份验证的反向代理，否则请让 DSH web 服务仅监听本机回环地址。

请通过 SECURITY.md 报告安全问题，不要公开提交 issue。

当前限制

- 自动提炼使用当前 DSH 会话的模型；MemoKnow 设置页尚无独立的模型或预算控制。
- 导入 PDF 时不会对扫描页面进行 OCR，并且会忽略图片。
- Local CPU embedding 通过 Transformers.js 在 CPU 上运行；网络较慢或知识库较大时，首次下载和建立索引可能耗时较长。
- 不导入 Excel .xls、受密码保护的文件、宏或内嵌图片。
- 管理界面目前使用简单的 prompt/confirm 对话框完成编辑与删除。