前言¶
在 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 插件頁。
