长期记忆库 aujurd22/dsh-flymemory

dsh-flymemory

给 DeepSeek Harness 加长期记忆。

这是一个 DSH 插件（bundle）：把 FlyMemory 当作本地 MCP 服务跑起来，接进 harness。装完之后模型手里多出 15 个记忆工具，另外还有两个钩子在背后干活——你干活的过程它自己记，下次用得上就自己翻出来。省掉每次开会话都重新交代一遍背景的功夫。

所有东西都在你自己机器上：服务监听 127.0.0.1:8791，记忆就是 DSH home 底下的一个文件，没有任何数据发到外面。

DSH 会话 ──┬── mcp__flymemory__* 模型可调的 15 个工具 └── 钩子 回合前召回，回合后记录 │ ▼ FlyMemory 服务 127.0.0.1:8791 │ ▼ $DSH_HOME/flymemory-data/flymemory_v3.pkl

拿到什么

15 个工具，调用时都带 mcp__flymemory__ 前缀：

| 工具 | 干什么用的 |
| flymemory_remember | 存一条决定或发现。近似重复会自动合并。compartment 按主题分区；state_key/state_value 记「某个东西当前是什么」，旧值自动退场。 |
| flymemory_recall | 搜。向量相似度和关键词匹配融合排序，旧条目随时间衰减，返回结果带 id、年龄和来源。加 include_superseded 能翻历史。 |
| flymemory_auto | 一次调用同时做召回和存储，钩子用的就是它。 |
| flymemory_recall_index / flymemory_get_memory | 先看索引再读正文：先给一行摘要，觉得有用再取全文。 |
| flymemory_supersede | 标明「这条过时了，被那条取代」。 |
| flymemory_state_lookup / flymemory_state_history | 某个实体键当前的值，或者它的全部历史。 |
| flymemory_consolidate | 把几条归纳成一条结论，原始条目留着当证据。 |
| flymemory_find_conflicts / flymemory_insights | 看起来互相矛盾的配对；有价值但快衰减掉的条目。 |
| flymemory_forget / flymemory_cleanup | 删单条，或者按衰减阈值批量清理。 |
| flymemory_session_pack | 近期轨迹 + 最新结论的短包。 |
| flymemory_stats | 条数、年龄、访问次数。 |

另外两个钩子自己跑，不用模型操心：

- 每条提示：把提示存下来，再把匹配得上的记忆附到这一轮里。纯本地检索，不调用模型。
- 会话开始：塞一个近期活动的恢复包，新会话不至于两眼一抹黑。

服务不在线时两个钩子都静默跳过，也绝不会卡住回合。

需要什么

- 带 @deepseek-ai/dsh-mcp-client 的 DeepSeek Harness。在 0.2.0-rc.2 与 44.7.0 上开发验证。
- Node 20 以上（插件本体和 CLI）。
- Python 3.10 以上，装引擎的依赖：

pip install torch sentence-transformers "mcp>=1.30,<2" numpy

解释器不用你指定：插件会依次看 FLYMEMORY_PYTHON、常见安装位置、PATH，而且 先确认这个解释器真能 import sentence_transformers 才选它。机器上装了好几个 Python 的时候，这一步能省掉半小时的「为什么起不来」。

第一次运行会把多语言嵌入模型（约 470MB）下载进 HuggingFace 缓存，之后离线可用。

安装

用 plugin_manager 指向本目录（绝对路径）：

plugin_manager(action: "install_bundle", target: "/absolute/path/to/dsh-flymemory")

或者打开 Web 侧边栏的 Plugins 页面，选这个文件夹。harness 重新加载后会有两行插件起来（flymemory、flymemory-mcp），工具就出现了。

自检：

node bin/flymemory.mjs status # 解析出来的配置 + 当前实际状态
node bin/flymemory.mjs doctor # 解释器、依赖、端点

然后让模型记一条东西再搜一次。工具没出来，doctor 基本能告诉你卡在哪。

卸载就是反过来：

plugin_manager(action: "remove_bundle", target: "dsh-flymemory")

记忆文件不会被删，想清掉自己动手。

运行方式

bundle 插入两行：

| 行 | 模块 | 干的事 |
| flymemory | 本包 | 探端口；没人应答就拉起引擎；记录解析结果；注册召回/捕获钩子 |
| flymemory-mcp | @deepseek-ai/dsh-mcp-client | 把服务端的工具变成 mcp__flymemory__<tool> |

钩子以前挂在 DSH 的 Claude-Code hook bridge 上。44.7 开始的版本不再带那个包，所以同样的逻辑改成跑在插件自己的 agent/pre-step 上，bundle 也不再依赖 hook bridge。

harness 启动时第一行先探 127.0.0.1:8791：已经有 FlyMemory 服务在应答就直接复用，两个 harness 窗口共享同一个引擎和同一份记忆；端口空着就后台把自带引擎拉起来，等它就绪了再让下一行去连；端口被别的程序占着，插件只报一句，不去动它——不是自己起的进程，绝不 kill。

冷启动偏慢：引擎要先 import torch 才能开始监听，大概 15–20 秒。这一行默认最多等 25 秒，没等到的话 mcp-client 会自己重连补上。

引擎彻底起不来（没有解释器、缺依赖、端口冲突）时 harness 照样启动，只是没有这些工具，原因写在日志里。

配置

环境变量，harness 启动前读取：

| 变量 | 默认值 | |
| FLYMEMORY_MCP_PORT | 8791 | 服务端口 |
| FLYMEMORY_MCP_URL | http://127.0.0.1:<port>/mcp | 完整端点 |
| FLYMEMORY_DATA_DIR | $DSH_HOME/flymemory-data | 记忆、日志、钩子配置、pid |
| FLYMEMORY_PYTHON | 自动探测 | 引擎用的解释器 |
| FLYMEMORY_DEVICE / FLYMEMORY_MODEL | cpu / 多语言 MiniLM | 传给引擎 |

其余参数写在你自己 profile 的 cordis.patch.yml 里，挂在对应行上。注意 patch 条目是 整体替换 config 的，需要的字段要写全：

- id: flymemory
name: 'dsh-flymemory'
config:
port: 8791
dataDir: 'D:\dsh-memory'
libraryPath: 'D:\dsh-memory\my-lib.pkl'
pythonExe: 'C:\Python313\python.exe'
device: cpu
readinessTimeoutMs: 25000 # 0 = 不等待，工具晚点自己出来 shutdownOnDispose: true # 退出时关掉本次拉起的引擎 nativeHooks: true # 每条手打提示做召回+捕获 hookTimeoutMs: 6000 # 每次钩子请求的预算 writeHooksConfig: true # 同时给 DSH 之外的客户端写 hooks.json seedFromUpstream: false # 默认不导入别的库 upstreamLibrary: '' # 想导入就同时配这两项 autostart: true

其余字段在 lib/index.js 的 resolveOptions() 里，多余的键会被忽略。

记忆存在哪

$DSH_HOME/flymemory-data/flymemory_v3.pkl，就一个文件，备份和删除都很直接。同目录还有：

- hooks.json — 每次激活重新生成，描述那两个钩子
- state.json — 上次激活实际解析出来的结果（端点、库、解释器、服务是怎么来的）； status 和 doctor 读它，所以有 profile 覆盖时会报真实值而不是默认值
- engine.log — 引擎进程的 stdout/stderr
- server.log — 引擎自己的日志
- server.pid — 给 flymemory stop 用来找进程

不想通过 harness、单独把服务跑起来：

node bin/flymemory.mjs start
node bin/flymemory.mjs stop
node bin/flymemory.mjs log -n 40

装成 bundle 之后，同一个 CLI 会被链接到 profile 里： <profile>/node_modules/.bin/dsh-flymemory。

关于钩子

默认是开着的，毕竟「自动记忆」就是这个插件的意义。钩子跑在插件自己身上（agent/pre-step），不依赖宿主的 hook bridge。它具体做了什么，值得说清楚：

- 只有你真正打出来的消息会被记录和召回。宿主给手打提示打的是 source.kind === "user"；peer 消息、系统提醒、自动化心跳、模型切换通知都带别的 kind，一律忽略。被委派的子 agent 只在任务开始时召回一次，之后不再记录。
- 长得像密钥的文本不会入库，自动化/心跳提示在发往服务之前就被跳过。
- 召回内容附到当前回合，上限约 2.5KB，并明确标注「这是数据、不是指令」。
- 还有一次请求专门取 compartment="lessons" 的前两条，单独注入。踩过的坑因此每轮都在眼前，而不是和普通记忆抢名额。存教训用 flymemory_remember 加 compartment="lessons"，文本开头写清楚「哪个工具/哪个环境」，因为最后是靠词法通道把它捞回来的。

只想要工具、不想要自动化，就把这一行的开关关掉（patch 条目是整体替换 config，需要的字段要写全）：

- id: flymemory
name: 'dsh-flymemory'
config:
port: 8791
nativeHooks: false

导入已有的库

默认什么都不导入。如果你手上已经有一份 FlyMemory 的库想搬进来，指一次就行：

- id: flymemory
name: 'dsh-flymemory'
config:
port: 8791
upstreamLibrary: 'D:\path\to\flymemory_v3.pkl'
seedFromUpstream: true

下次激活时，只要目标文件还不存在就复制过去，源文件保持不动。两边格式一致，以后想搬出去也可以。

分享一个已经在跑的服务

如果这台机器上已经有 FlyMemory 服务在跑，而你希望 DSH 直接用它的记忆、而不是自己另存一份，覆盖这两行即可（写在你自己 profile 的 patch 层）：

- id: flymemory
name: 'dsh-flymemory'
config:
port: 8765
libraryPath: 'D:\path\to\flymemory_v3.pkl'
- id: flymemory-mcp
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: flymemory
transport: streamable-http
url: 'http://127.0.0.1:8765/mcp'

port 是插件去哪找现成的服务；libraryPath 是万一它得自己拉引擎时开哪个文件——两条路通向同一份记忆。钩子那行不用动，它会跟着插件解析出来的端点走。
node bin/flymemory.mjs status 在这种覆盖生效时会标出 "from hooks.json"，一眼能看出用的不是默认值。

想改代码

node --check lib/index.js # 语法
npm test # 单元测试，不需要 Python，约 0.3 秒
node tests/engine_smoke.mjs # 打真引擎的端到端（需要 torch）
python tests/http_smoke.py # 对着运行中的服务做协议检查

npm test 盯的是容易出错的那几块：端口和库的默认值、配置优先级、生成的钩子文件、端点探测。engine smoke test 在临时目录里用真的 Python 引擎跑一遍 apply()——需要 torch 和 sentence-transformers，没装会打印 SKIP。CI 在 Linux、macOS、Windows 上跑 Node 20 / 22 / 24，加上语法检查和单元测试。

lib/index.js Host 端：探端口、管引擎、生成钩子配置 bin/flymemory.mjs CLI，复用同一套函数 cordis.patch.yml 这个 bundle 插入的两行 python/ 随包的 FlyMemory 引擎（服务端、钩子、引擎包）
locale/{en,zh}.json Plugins 页面显示的标题和描述
tests/ 单元测试、引擎冒烟、协议冒烟

不太行的地方

- 第一次启动要 15–20 秒，都是 torch 的加载时间。嫌久就把 readinessTimeoutMs 设成 0，harness 立刻启动，工具几秒后自己出现。
- Python 依赖比较重。插件不会替你装，doctor 会告诉你缺什么。
- DSH 没有 PreCompact 钩子，所以恢复包挂在会话开始，而不是压缩之后。
- 工具名很长。mcp__flymemory__flymemory_recall 是 mcp-client 的命名规则（mcp__<server>__<tool>）决定的，稳定，但不好看。
- 一个端口一个引擎。两个 harness 共用；要第三份实例得显式配独立端口和独立库。
- 库越大召回越慢。上游在 CPU、约 1400 条时测到每查询 ~11ms。

许可

MIT，见 LICENSE。

随包携带的 FlyMemory 引擎同样是 MIT，Copyright (c) 2026 Junrong Du。
具体复制了哪些文件、改了哪些、为什么改，都写在 THIRD_PARTY_NOTICES.md 里。