前言¶
在 DSH 里跑智能体时，上下文窗口有限，单靠会话历史很难跨天、跨任务保留「用户偏好、做过的事、稳定事实」。常见做法要么把整段聊天记录塞进 prompt（贵且噪声大），要么接向量库和 embedding 服务（依赖多、数据路径复杂）。feiyu-memory 走另一条路：把记忆落成主机目录下的纯文本与 JSON，用本地规则做召回与抽取，不装 npm 运行时依赖、不向外部发 embedding 请求。下面介绍它是什么、怎么装、怎么用，以及使用时要注意的边界。
这是什么¶
feiyu-memory 是由维护者 wudaoyu65-collab 发布的 DSH 记忆类插件（社区目录：feiyu-memory）。当前 package 版本为 0.2.0，许可证 MIT，要求 Node >= 18。
定位一句话：给 DSH 的本地纯文件长期记忆——热层 / 事件层 / 事实层 / 摘要层，每步按 token 预算注入相关片段；实现只用 Node 内置模块（fs / path / os），没有一行记忆数据需要离开本机（面板数据服务仅绑定 127.0.0.1，见后文）。
四层数据形态（README 原文）：
热层 hot.md 你手写/自动维护的「每次都得知道」的事
事件层 events.jsonl 一行一条经历，带时间、重要度、情绪、存活系数
事实层 facts.json 槽位表：key → value，可失效、可钉住（换人换说法不打架）
摘要层 summary/ 按天压缩过去的事件，省 token
为什么用纯文件¶
资料里强调的设计动机可以概括为四点：
- 可读可改：直接编辑
hot.md，下次注入即生效；删目录即「全忘光」。 - 可审计：召回、衰减、去重在明文 JS（约 500 行量级）里，不藏在 embedding 黑盒。
- 零运行时 API 成本：默认本地规则抽取，闲置时不消耗模型 token。
- 可迁移：数据目录拷走即完整记忆库。
核心功能¶
每步注入与轮次固化¶
插件通过 DSH 宿主钩子工作（README 归纳）：
| 环节 | 接口 |
|---|---|
| 每步注入 | agent.ctx.systemPrompt.context({name, order, text})，宿主按步重算，内容不变则不重复提交 |
| 取当前提问 | agent/pre-step 只读捕获 |
| 轮次收尾 | agent/turn-stopping → 异步规则抽取 → 写 events / facts |
| 挂到 agent | agent/created |
| 工具 | ctx.tools.register 共 4 个 |
记忆注入走动态上下文，而不是往 decision.messages 里塞 user 消息，避免把记忆写进会话日志、越聊越贵。
召回打分¶
src/recall.js 中的规则（资料原文）：
sim = 提问 token 的 idf 加权覆盖率（不是 Jaccard）
decay = 0.5 ^ (天数 / 半衰期) # 情绪浓的事件换更短半衰期
s = sim × decay × importance
C = 1 - e^(-3s)
命中条件：C ≥ minScore
默认 minScore 为 0.35；相似度刻意不用 Jaccard，避免「问句短、事件长」时相关事件被压分。
四个 Agent 工具¶
| 工具 | 作用 |
|---|---|
feiyu_remember |
写一条记忆（event 经历 / fact 长期事实） |
feiyu_recall |
按关键词检索，返回热层/事实/事件片段 |
feiyu_forget |
标记遗忘（markSuperseded，不硬删，可追溯） |
feiyu_stats |
事件数 / 事实数 / 热层字数 / 数据目录 |
侧边栏「记忆」面板¶
同一 bundle 含 client.js：在侧边栏挂「记忆」图标，用 Canvas 2D 力导向图展示 hot / fact / event / summary 节点与边；pre-step 召回命中时有沿边脉冲动画。图数据来自 Host 在回环地址起的小 HTTP 服务（路径含 /graph、/stats、/hits、/forget、/pin），面板每 2 秒轮询。节点过多或帧率过低时会降级关闭辉光等效果。
安装与启用¶
这是 Host-only bundle，无构建步骤。官方说明两种方式：
方式一：DSH 界面
- 把本仓库放到任意目录（建议绝对路径，避免中文与空格）。
- 打开 DSH → 设置 → 插件 → 安装 bundle，目标目录选仓库根目录。
- 重启 DSH（插件代码变更需重启才会加载新模块）。
方式二：命令行写入 profile
在仓库根目录执行：
node tools/install-profile.mjs
# 默认 ~/.dsh/profiles/desktop，可用 DSH_PROFILE_DIR / DSH_PROFILE 覆盖
脚本会幂等写入 link: 依赖、把 feiyu-memory 加入 dsh.profile.bundles、在 node_modules 下建 junction；会先备份 package.json。
注意：部分受限 profile / 会话预设不带 plugin_manager 权限，安装需在桌面 UI 或权限完整的会话里完成。
插件以当前 DSH 进程权限运行；安装前请自行阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全策略。
数据目录与配置¶
默认数据目录：
~/.dsh/feiyu-memory/
├── hot.md
├── facts.json
├── events.jsonl
├── summary/
├── config.json
└── feiyu.log # 出错日志，最多 200 行
换盘可在 cordis.patch.yml 打开 dataDir，或在 config.json 里写 dataDir。彻底清空记忆：删除整个目录，下次启动会重建空库。
配置优先级：行 config（cordis.patch.yml）> data/config.json > 默认值。常用键（默认值来自 README 表格）：
| 键 | 默认 | 含义 |
|---|---|---|
| enabled | true | 关闭后不注入 |
| injectTokenBudget | 1200 | 每步注入预算（按字符 ×4 估算） |
| recallLimit | 3 | 最多命中几条事件 |
| minScore | 0.35 | 证据分门槛 |
| eventHalfLifeDays | 30 | 普通事件半衰期 |
| emotionalHalfLifeDays | 7 | 情绪浓事件半衰期 |
| disableExtract | false | true 时只写不抽（隐私敏感） |
| viewHttp | true | 是否起面板数据服务 |
| viewPort | 17654 | 数据服务起始端口（向后试 10 个） |
完整键列表见仓库 README「配置」一节。
典型用法¶
经过上面的安装与重启，智能体在对话中会自动按预算注入热层、事实与命中事件；轮次结束时默认会做本地规则抽取（可在配置里用 disableExtract: true 关闭）。
需要显式操作时，在 Agent 可用工具里调用（参数形态以仓库实现为准）：
- 主动记下经历或事实：
feiyu_remember - 按关键词查记忆：
feiyu_recall - 标记某条记忆被新信息取代：
feiyu_forget - 查看库规模与路径：
feiyu_stats
热层适合人工维护「每次对话都要知道」的短文本：直接编辑 ~/.dsh/feiyu-memory/hot.md，保存后下次注入生效。
维护者提供的自检（在仓库根目录，使用临时目录，不碰真实记忆库）：
npm test
node test/selftest.mjs
适用场景与注意¶
更适合：希望长期记忆可编辑、可备份、可审计；不想为记忆单独部署向量库或 embedding API；接受基于关键词与规则的召回，而不是语义 embedding 检索。
务必知晓：
- 面板 HTTP 只绑
127.0.0.1，但本机任意进程理论上可访问该端口；介意则设viewHttp: false。 - 插件不发起对外网络请求做记忆；仓库
data/在.gitignore，发布版不含个人记忆。 - DSH 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；生态理念是「一切皆插件」，安装第三方 bundle 前请自行审代码。
结尾¶
feiyu-memory 把 DSH 智能体的长期记忆拆成四层纯文件，用 token 预算注入和本地规则抽取串起「记—召—忘—摘要」闭环，适合看重本机可控与零运行时依赖的开发者。源码与说明见 GitHub：wudaoyu65-collab/feiyu-memory，目录页见 SkillHub 插件页。
