05 · 記憶與召回 · AI 程式設計教程中文版

Hermes 的 memory（長期記憶）不是無限日誌，而是精選長期事實。它的目標是讓新 session 一開始就知道關鍵偏好、環境事實和專案約定，同時把歷史細節留給 session_search（會話檢索）按需呼叫。理解這一點比記任何命令都重要——把 memory 當日志寫，結果就是 agent 在錯誤資訊上越用越固執。

官方資料：Persistent Memory、Memory Providers、Sessions、Honcho。

先給結論：MEMORY.md（專案記憶）和 USER.md（使用者偏好）是短、穩、可驗證的長期事實；session_search 是歷史會話檢索（FTS5 全文索引）；外部 memory provider 是進階擴充套件，不是新手必選項——基礎三件套用好，多數任務已經夠。

官方機制補充

Hermes 的 memory 工具只有三個動作：add、replace、remove。沒有 read 動作——因為 memory 會在 session 啟動時直接注入 system prompt（系統提示），agent 在當前上下文裡已經能看到啟動快照，不需要主動讀。這是和"無限日誌型記憶"的根本區別。

replace 和 remove 使用 old_text 的短唯一子串匹配，不要求複製完整條目。如果子串命中多條，工具會要求更具體的匹配。這個設計適合小容量、高密度 memory，但也要求條目不要寫得太相似——否則 replace 時找不到唯一匹配，操作會失敗。

add      -> 新增一条长期事实
replace  -> 用唯一子串定位旧条目并替换
remove   -> 用唯一子串定位旧条目并删除
read     -> 不存在，启动时已注入

系統還會拒絕 exact duplicate entries（完全重複條目），並在寫入前掃描 prompt injection（提示注入：惡意文本偽裝成系統指令）、credential exfiltration（憑據外洩：偷偷把 token / 密碼塞進 memory）、SSH backdoor（SSH 後門：寫入未授權登入入口）、invisible Unicode（不可見 Unicode：用零寬字元隱藏惡意內容）等模式。原因很直接：memory 會進入 system prompt（系統提示），所以它本身就是長期注入面——任何寫進去的內容下次啟動都會被模型當成權威指令讀。

三層記憶機制總覽

Hermes 的記憶並不是單一系統，而是三層各管不同時間尺度，疊在一起才構成"自我改進閉環"的記憶支柱：

flowchart LR
    subgraph S1["啟動注入<br/>每次啟動 system prompt 自帶"]
        M1["MEMORY.md<br/>專案長期事實<br/>~2200 chars"]
        M2["USER.md<br/>使用者偏好畫像<br/>~1375 chars"]
    end
    subgraph S2["當前會話<br/>本輪對話上下文"]
        S3["session 上下文<br/>本次對話的滾動視窗"]
    end
    subgraph S3box["按需檢索<br/>需要時再查"]
        SS["session_search<br/>FTS5 全文索引<br/>歷史所有 session"]
        EXT["External Providers<br/>Honcho / Mem0 等<br/>語義 / 使用者建模"]
    end
    M1 --> S3
    M2 --> S3
    SS -.LLM 摘要.-> S3
    EXT -.外掛式.-> S3

三層使用規則：每次啟動都該帶 → 內建 memory；本次任務用 → 當前對話；歷史回查 → session_search；複雜使用者建模 → 外部 provider。

兩類長期事實

內建記憶在：

~/.hermes/memories/
├── MEMORY.md
└── USER.md

MEMORY.md

Agent 需要記住的環境和工作事實，例如專案約定、工具坑、已驗證修復結論。

USER.md

使用者畫像，例如溝通偏好、常用技術堆疊、明確偏好和反覆糾正過的要求。

預設容量按官方當前 memory 配置文件（截至本文核驗日：MEMORY.md 2200 chars、USER.md 1375 chars）。容量小是有意設計——為了讓記憶保持高密度，而不是把聊天曆史變成永久 prompt。容量小才是優勢：每次啟動這兩個檔案全文都進系統提示，越短模型越能精準記住。

官方配置鍵在 ~/.hermes/config.yaml 的 memory 段：

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

不要為了“多記一點”盲目把限制調大。限制越大，長期 prompt 的噪音和注入面也越大。

凍結快照

兩者會在 session 啟動時注入 system prompt。當前 session 中新增或修改的記憶會寫盤，但不會重新整理當前 system prompt；新 session 才能看到。

這個機制的判斷：

當前任務馬上需要：直接在當前對話說。
以後每次都該知道：寫入 memory。
只是可能要回查：留給 session_search。

不要因為“剛儲存的記憶沒立刻生效”就重複寫入。

儲存標準

適合儲存：

使用者明確偏好。
穩定環境事實。
專案長期規則。
反覆出現的工具問題。
已驗證過的修復結論。

不適合儲存：

一次性任務細節。
大段日誌或程式碼。
臨時檔案路徑。
可以從專案文件直接讀到的內容。
未驗證的猜測。

錯誤記憶比缺少記憶更危險。它會持續影響後續 session，並讓 agent 變得“有依據地錯”。

session_search

session_search 是歷史會話檢索，不是 curated memory。

適合問：

之前怎麼修過類似問題。
某個長期任務上次停在哪裡。
使用者曾經糾正過什麼。
某個專案以前跑過哪些命令。

Hermes 把 CLI 和 messaging sessions 寫入 SQLite，並用 FTS5 全文檢索，再由模型總結相關片段。

官方實現裡歷史會話儲存在 ~/.hermes/state.db。這意味著 session_search 更像“查歷史記錄再摘要”，而 memory 更像“每輪啟動都預設攜帶的長期事實”。前者容量大但按需觸發，後者容量小但每次都會進入上下文。

簡單判斷：

每次都该知道 -> memory
偶尔需要回查 -> session_search
当前临时上下文 -> 当前对话
项目长期规则 -> AGENTS.md / CLAUDE.md / .hermes.md

外部 provider

Hermes 支援多個外部 memory provider（記憶外掛，按官方 Memory Providers 頁當前列表為準）：Honcho（AI 原生使用者建模）、OpenViking、Mem0（流行的 AI 記憶服務）、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等——多數是 AI-native（AI 原生）記憶服務，提供語義搜尋、使用者建模、知識圖譜等能力。

外部 provider 適合更復雜的長期使用者建模、語義搜尋、知識圖譜或自動事實抽取，但不要一開始就接。先把內建 memory 用好，再判斷是否需要外部 provider——多數場景內建 MEMORY.md + USER.md + session_search 已經夠。

hermes memory setup    # 选 provider + 配凭据
hermes memory status   # 查当前激活的 provider 和数据量

它們和內建 memory 並行工作，不替代 MEMORY.md / USER.md——內建層是"啟動快照"，外部 provider 是"按需查詢的語義檢索層"。Honcho 提供官方推薦的 dialectic（辯證式）多代理使用者建模，用 LLM 持續修正使用者畫像，是 Nous Research 自己重點推的能力。

記憶治理

推薦規則：

事实必须可验证
偏好必须来自用户明确表达
临时信息不入库
低密度内容先合并再保存
超过 80% 容量就主动压缩
发现错误立即 replace 或 remove
外部内容先提炼再入库

好的 memory 會讓 Hermes 越用越貼合；壞的 memory 會讓它越來越固執。

何時合併而不是新增

官方建議 memory 超過 80% 容量時先合併。實踐中可以用這組規則判斷：

情況	動作
同一專案有多條環境事實	合併成一條專案畫像
使用者偏好互相沖突	replace 成最新明確偏好
一次性任務已經結束	remove，不要留長期記憶
同一工具坑反覆出現	合併為“症狀 + 原因 + 修復”
條目來自外部網頁或 issue	先提煉事實，再決定是否 add

memory 的目標不是完整，而是穩定。能從專案文件、命令、Git 歷史或官方文件重新讀到的資訊，不應該優先佔用 memory。

安全邊界

記憶會直接進入 system prompt，所以它是長期注入面——任何寫進 memory 的內容會在每次啟動時被模型當成"權威指令"讀取。這意味著兩條鐵律：

來源審查：外部網頁、issue、聊天記錄、PR 評論裡的原文不要直接儲存成 memory。先判斷來源可信度，再提煉成經過驗證的事實——攻擊者可以在 GitHub issue 留下 prompt injection 文本，等你不慎複製進 memory 就長期生效。
不儲存憑據：API key、token、密碼、私鑰路徑、SSH backdoor、可用於攻擊的連線資訊一律不入 memory。需要憑據時走 ~/.hermes/.env 或作業系統級憑據系統（macOS Keychain / 1Password CLI 等）。Hermes 啟動時會掃描 memory 內容裡的 prompt injection、憑據外洩、SSH backdoor、不可見 Unicode 等模式並拒寫——但你也別故意去試它的下限。

官方資料

Persistent Memory（MEMORY.md / USER.md / 容量 / 注入機制）
Memory Providers（外部 provider 完整列表）
Honcho（AI-native dialectic 使用者建模）
Sessions（session_search 來源）
Context Files（專案級 AGENTS.md / CLAUDE.md / .hermes.md / 全域性 SOUL.md）

05 · 記憶與召回