OpenHuman Archivist 后臺(tái)知識(shí)館員會(huì)話歸檔、經(jīng)驗(yàn)提煉與 MEMORY.md 記憶沉淀機(jī)制全解析【免費(fèi)下載鏈接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/op/openhumanOpenHuman 的Archivist知識(shí)館員是一個(gè)在會(huì)話結(jié)束后于后臺(tái)運(yùn)行的專(zhuān)用 Agent負(fù)責(zé)把每一輪對(duì)話沉淀為可檢索的記憶資產(chǎn)回合索引寫(xiě)入 FTS5 情景記憶表、經(jīng)驗(yàn)教訓(xùn)抽取與分類(lèi)、知識(shí)庫(kù)文件 MEMORY.md 增量更新。本文以 Archivist 的系統(tǒng)提示詞prompt.md為骨架結(jié)合其 Agent 配置agent.toml、提示詞裝配器prompt.rs以及后端 Hook 實(shí)現(xiàn)hook_impl.rs、lifecycle.rs深入剖析 OpenHuman 的「會(huì)話 → 記憶」流水線幫助你理解其記憶系統(tǒng)如何做到低開(kāi)銷(xiāo)、可檢索、防泄露、不重復(fù)。一、Archivist 是誰(shuí)后臺(tái)知識(shí)館員的角色定位在 OpenHuman 的 Agent 注冊(cè)表中Archivist 被定義為一個(gè)典型的「后臺(tái) 輕量」Agent。它的when_to_use字段一句話點(diǎn)明使命Background librarian — extracts lessons from a completed session, updates MEMORY.md, and indexes to FTS5. Runs cheap and slow.后臺(tái)知識(shí)館員——從已完成的會(huì)話中提取經(jīng)驗(yàn)更新 MEMORY.md并索引到 FTS5。以低成本、低速度運(yùn)行。這段描述見(jiàn) agent.toml揭示了三個(gè)關(guān)鍵設(shè)計(jì)意圖后臺(tái)觸發(fā)background true不占用前臺(tái)交互路徑低成本temperature 0.4低隨機(jī)性、輸出穩(wěn)定、max_iterations 3最多 3 輪工具循環(huán)防止無(wú)限迭代知識(shí)歸檔產(chǎn)出物橫跨兩類(lèi)存儲(chǔ)——結(jié)構(gòu)化數(shù)據(jù)庫(kù)FTS5 情景記憶與人類(lèi)可讀的 Markdown 知識(shí)庫(kù)MEMORY.md。系統(tǒng)提示詞把 Archivist 的全部職責(zé)收斂為三條明確指令I(lǐng)ndex turns— 將每一輪對(duì)話記錄到情景記憶FTS5中供未來(lái)檢索召回Extract lessons— 識(shí)別可復(fù)用的模式、需要規(guī)避的錯(cuò)誤以及用戶(hù)偏好Update MEMORY.md— 將重要的學(xué)習(xí)成果追加到工作區(qū)知識(shí)庫(kù)。從源碼結(jié)構(gòu)看這三條職責(zé)分別對(duì)應(yīng)了三條獨(dú)立但聯(lián)動(dòng)的實(shí)現(xiàn)路徑回合索引走ArchivistHook::on_turn_completehook_impl.rs經(jīng)驗(yàn)提煉走分段 recap 事件啟發(fā)式提取lifecycle.rs知識(shí)庫(kù)更新則通過(guò)白名單工具update_memory_md完成update_memory_md.rs。二、系統(tǒng)提示詞如何裝配prompt.md → 完整提示詞Archivist 的提示詞并非一段寫(xiě)死的字符串而是由 prompt.rs 中的build()函數(shù)在運(yùn)行時(shí)動(dòng)態(tài)拼裝而成通過(guò)include_str!(prompt.md)把本文的 archetype角色原型嵌入二進(jìn)制依次追加render_user_files(ctx)用戶(hù)可見(jiàn)文件、render_tools(ctx)可用工具清單與render_workspace(ctx)工作區(qū)上下文。這正是 OpenHuman「提示詞即產(chǎn)物」的設(shè)計(jì)理念——build()的輸出就是 LLM 最終看到的內(nèi)容Runner 不做任何二次加工見(jiàn) prompt.rs 模塊注釋。這意味著 prompt.md 中每條規(guī)則都會(huì)原樣生效且工具清單由運(yùn)行時(shí)上下文決定而非硬編碼。對(duì)應(yīng)的單元測(cè)試 prompt_tests.rs 驗(yàn)證了build()在最小上下文空工具集、空工作區(qū)下也能產(chǎn)出非空提示詞保證該 Agent 在任何場(chǎng)景下都能被加載。三、agent.toml 運(yùn)行參數(shù)詳解agent.toml 是 Archivist 的完整運(yùn)行配置理解這些參數(shù)是自定義 Agent 的最佳范本配置項(xiàng)值含義與影響idarchivist注冊(cè)表中的唯一標(biāo)識(shí)delegate_namearchive_session編排器調(diào)用該子 Agent 時(shí)使用的委托名temperature0.4低隨機(jī)性保證歸檔內(nèi)容穩(wěn)定、可復(fù)現(xiàn)max_iterations3最多 3 輪工具調(diào)用循環(huán)防止后臺(tái)任務(wù)失控max_result_chars8000歸檔摘要回流到編排器的字?jǐn)?shù)上限約 2000 tokens與普通子 Agent 上限一致防止冗長(zhǎng)的「記憶寫(xiě)入確認(rèn)」撐爆編排器上下文issue #4099sandbox_modenone無(wú)需沙箱因?yàn)槠涔ぞ呒瘜?xiě) MEMORY.md / 寫(xiě)數(shù)據(jù)庫(kù)本就受白名單約束backgroundtrue后臺(tái)運(yùn)行不阻塞主會(huì)話omit_identity/omit_memory_context/omit_safety_preambletrue跳過(guò)身份、記憶上下文與安全前言進(jìn)一步壓縮上下文開(kāi)銷(xiāo)model.hintlocal優(yōu)先使用本地模型契合「便宜、慢速、后臺(tái)」的定位tools.namedupdate_memory_md、insert_sql_record、memory_store僅暴露三個(gè)寫(xiě)工具權(quán)限面最小化值得強(qiáng)調(diào)的是tools.named的最小權(quán)限設(shè)計(jì)Archivist 只能通過(guò)update_memory_md寫(xiě) Markdown 知識(shí)庫(kù)、通過(guò)insert_sql_record寫(xiě) FTS5 表格、通過(guò)memory_store訪問(wèn)記憶存儲(chǔ)——它沒(méi)有文件系統(tǒng)通用讀寫(xiě)權(quán)限從機(jī)制上杜絕了后臺(tái) Agent 越權(quán)操作工作區(qū)。四、職責(zé)一Index turns — 回合索引與情景記憶FTS5Archivist 的后端實(shí)現(xiàn)是一個(gè)PostTurnHook回合后鉤子核心入口是ArchivistHook::on_turn_completehook_impl.rs。每輪對(duì)話結(jié)束后它依次執(zhí)行寫(xiě)入用戶(hù)回合把用戶(hù)消息作為一條EpisodicTurnroleuser插入 FTS5 情景記憶表insert_turn返回?cái)?shù)據(jù)庫(kù)分配的自增 ID寫(xiě)入助手回合把助手回復(fù)作為第二條記錄寫(xiě)入時(shí)間戳加0.001毫秒偏移確保同一輪內(nèi)「用戶(hù)在前、助手在后」的排序穩(wěn)定工具調(diào)用摘要tool_calls_json隨助手記錄一并落庫(kù)輕量教訓(xùn)提取若本輪存在失敗的工具調(diào)用則調(diào)用extract_lesson_from_tools生成一條純啟發(fā)式教訓(xùn)不消耗 LLM格式為T(mén)ools that failed in this turn: xxx, yyyhelpers.rs雙寫(xiě) md 歸檔同時(shí)把回合寫(xiě)入workspace/memory_tree/content/episodic/session_id/seq:06.md的 md 備份存儲(chǔ)最佳努力模式寫(xiě)失敗不阻斷回合為 FTS5 → md 的存儲(chǔ)遷移做并行驗(yàn)證hook_impl.rs。會(huì)話分段把長(zhǎng)對(duì)話切成「知識(shí)單元」原始回合是零散的時(shí)間序列Archivist 通過(guò)**會(huì)話分段conversation segmentation**把同主題的回合聚合成 Segment為后續(xù) recap 提供邊界。分段判定由 boundary.rs 的detect_boundary()完成按「從便宜到昂貴」的順序執(zhí)行四重檢查boundary.rs檢查項(xiàng)判定條件默認(rèn)閾值TurnCountExceeded段內(nèi)回合數(shù)超上限max_turns_per_segment 20TimeGap相鄰回合間隔過(guò)長(zhǎng)max_time_gap_secs 60010 分鐘ExplicitMarker回合以話題切換短語(yǔ)開(kāi)頭如now lets、switching to、by the way,等內(nèi)置 15 個(gè)英文短語(yǔ)表EmbeddingDrift回合向量與段質(zhì)心的余弦相似度低于閾值min_cosine_similarity 0.4邊界判定產(chǎn)出BoundaryDecision::Continue繼續(xù)積累或Boundary::Boundary(reason)關(guān)閉當(dāng)前段、以當(dāng)前回合為起點(diǎn)新建段段 ID 形如seg-{uuid}。這個(gè)設(shè)計(jì)的精妙之處在于「便宜檢查先跑、貴檢查后跑」——一個(gè)回合若命中前三條任一規(guī)則就永遠(yuǎn)不會(huì)支付 embedding 比較的成本。五、職責(zé)二Extract lessons — 經(jīng)驗(yàn)提煉的三層漏斗Archivist 的教訓(xùn)提取不是單一機(jī)制而是「無(wú) LLM 啟發(fā)式 → 啟發(fā)式事件 → LLM recap」的三層漏斗按成本從低到高排列第一層工具失敗教訓(xùn)零成本extract_lesson_from_tools純規(guī)則實(shí)現(xiàn)遍歷本輪工具調(diào)用記錄只要存在success false的調(diào)用就生成一條「哪些工具失敗」的教訓(xùn)。這是唯一逐輪執(zhí)行的教訓(xùn)提取因?yàn)樗幌娜魏瓮评碣Y源。第二層事件啟發(fā)式提取segment 關(guān)閉時(shí)在段關(guān)閉on_segment_closed時(shí)Archivist 對(duì)段內(nèi)所有用戶(hù)消息做句子切分按.!?換行符再與四組模式表做子串匹配events_heuristic.rsDecision決策如i decided、going with等模式Commitment承諾如i will、ill make sure等Preference偏好如i prefer、i like、i dont like等Fact事實(shí)如my name is、i work at、i live in、my timezone等。每個(gè)事件被寫(xiě)入EpisodicEvent表confidence 固定 0.6其中Preference 與 Fact 事件還會(huì)二次寫(xiě)入用戶(hù)畫(huà)像Profile Facets通過(guò)extract_profile_key取內(nèi)容前 4 個(gè)有意義的詞生成鍵與upsert_provider_facet合并置信度低的重復(fù)觀察不會(huì)覆蓋更強(qiáng)的舊記錄lifecycle.rs。第三層LLM 段摘要recap可回退每個(gè)被關(guān)閉的 Segment 都會(huì)產(chǎn)出一段摘要recap默認(rèn)使用summarization角色的推理模型生成見(jiàn) lifecycle.rs 中RECAP_INFERENCE_ROLE常量。整個(gè)流程遵循軟回退契約若with_config階段探測(cè)到無(wú)法構(gòu)建summarization角色的模型則回退到啟發(fā)式摘要on_segment_closed永不返回 Err所有失敗只記日志不中斷回合recap 生成后持久化段摘要 → 調(diào)用 embedder 生成向量并寫(xiě)入segment_embeddings段關(guān)閉時(shí)是唯一寫(xiě)入點(diǎn)空摘要直接跳過(guò)以避免上游 embedding API 400→ 提取事件 → 更新畫(huà)像。這里有一個(gè)重要的**「證據(jù) vs 解讀」數(shù)據(jù)策略**在config.learning.chat_to_tree_enabled true時(shí)Archivist 會(huì)把該段的原始散文回合用戶(hù) 助手消息剝離工具調(diào)用 JSON以source_idconversations:agent整批灌入記憶樹(shù)而絕不把 LLM recap 喂給記憶樹(shù)——樹(shù)必須基于原始證據(jù)自己歸納否則就成了「對(duì)摘要再做摘要」lifecycle.rs。六、職責(zé)三Update MEMORY.md — 知識(shí)庫(kù)的并發(fā)安全寫(xiě)入update_memory_md是 Archivist 更新工作區(qū)知識(shí)庫(kù)的唯一通道update_memory_md.rs其實(shí)現(xiàn)體現(xiàn)了 OpenHuman 對(duì)「后臺(tái)并發(fā)寫(xiě)文件」這一危險(xiǎn)場(chǎng)景的完整防護(hù)白名單約束工具只能修改MEMORY.md與SKILL.mdALLOWED_FILES常量其他工作區(qū)文件一概拒絕進(jìn)程內(nèi)互斥每個(gè)工作區(qū)目錄對(duì)應(yīng)一把全局 async 互斥鎖以 canonicalize 后的路徑為鍵并發(fā)跑并行 fork、cron的歸檔寫(xiě)操作排隊(duì)執(zhí)行而非互相覆蓋issue #4458跨進(jìn)程文件鎖由于 cron 通過(guò)獨(dú)立子進(jìn)程啟動(dòng)進(jìn)程內(nèi)互斥鎖無(wú)法覆蓋因此再對(duì)工作區(qū)下的哨兵文件.memory-write.lock做flock獨(dú)占鎖阻塞式、運(yùn)行在線程池同時(shí)拒絕 symlink 鎖文件并用O_NOFOLLOW關(guān)閉 TOCTOU 窗口防止符號(hào)鏈接把鎖重定向到工作區(qū)之外原子寫(xiě)入臨時(shí)文件 原子重命名進(jìn)程被 kill 也不會(huì)留下截?cái)辔募?。這套機(jī)制與 prompt.md 中的Deduplicate規(guī)則形成「機(jī)制 智能」的雙保險(xiǎn)鎖保證寫(xiě)入不互相破壞LLM 負(fù)責(zé)在追加前比對(duì)已有 MEMORY.md 內(nèi)容、避免重復(fù)條目。七、質(zhì)量規(guī)則五條提示詞紀(jì)律prompt.md 的 Rules 部分是 Archivist 輸出質(zhì)量的靈魂逐條展開(kāi)規(guī)則含義落地方式Be concise教訓(xùn)濃縮為一兩句密集而非啰嗦max_result_chars 8000從物理上限制回流體量Be selective并非每輪都有教訓(xùn)只沉淀真正有用的觀察默認(rèn)只對(duì)工具失敗做逐輪啟發(fā)式提取其余留給段級(jí) recapNever log secrets脫敏 API 密鑰、令牌、密碼與 PII由提示詞紀(jì)律約束配合 log_redaction 等安全機(jī)制Use categories按類(lèi)型打標(biāo)簽pattern模式、mistake錯(cuò)誤、preference偏好、fact事實(shí)與事件啟發(fā)式的 Decision/Commitment/Preference/Fact 分類(lèi)一一呼應(yīng)Deduplicate追加前先查 MEMORY.md避免重復(fù)配合update_memory_md的讀-改-寫(xiě)加鎖流程八、可配置開(kāi)關(guān)learning 配置族Archivist 的行為并非硬編碼而是由 learning.rs 中的學(xué)習(xí)配置族統(tǒng)一開(kāi)關(guān)以下參數(shù)均可通過(guò)learning配置節(jié)或環(huán)境變量覆蓋配置項(xiàng)默認(rèn)值作用環(huán)境變量覆蓋episodic_capture_enabledtrue情景捕獲總開(kāi)關(guān)即使learning.enabled關(guān)閉也保持活動(dòng)情景記憶是對(duì)話回合的系統(tǒng)事實(shí)來(lái)源OPENHUMAN_LEARNING_EPISODIC_CAPTURE_ENABLED0\|1chat_to_tree_enabledtrue是否把對(duì)話原始回合灌入記憶樹(shù)conversations:agent—goals_enrichment_enabledtrue段關(guān)閉后是否后臺(tái)觸發(fā)goals_agent刷新長(zhǎng)期目標(biāo)清單MEMORY_GOALS.mdOPENHUMAN_LEARNING_GOALS_ENRICHMENT_ENABLED0\|1stm_recall_enabledtrue是否在會(huì)話開(kāi)始注入跨會(huì)話的近期情景召回FTS5 關(guān)鍵詞 cosine 段摘要OPENHUMAN_LEARNING_STM_RECALL_ENABLED0\|1explicit_preferences_enabledtrue顯式固定偏好是否注入系統(tǒng)提示詞OPENHUMAN_LEARNING_EXPLICIT_PREFERENCES_ENABLED0\|1注意learning.enabled默認(rèn)是false而episodic_capture_enabled默認(rèn)true——這體現(xiàn)了「情景記憶是獨(dú)立于推理學(xué)習(xí)棧的基礎(chǔ)設(shè)施」這一架構(gòu)判斷即使關(guān)閉反射/穩(wěn)定性檢測(cè)等推理組件對(duì)話歸檔依然持續(xù)運(yùn)轉(zhuǎn)。九、會(huì)話收尾flush 保證最后一段不丟失一個(gè)容易被忽略的邊界情況是會(huì)話結(jié)束時(shí)往往沒(méi)有一個(gè)觸發(fā)邊界的回合導(dǎo)致最后一個(gè) Segment 永遠(yuǎn)處于 open 狀態(tài)、得不到 recap。Archivist 通過(guò)flush_open_segment解決lifecycle.rs在會(huì)話結(jié)束Agent::spawn_session_memory_extraction時(shí)強(qiáng)制關(guān)閉殘留的 open segment并走與正常段關(guān)閉完全相同的路徑——recap embedding 事件提取 樹(shù)灌入。該操作冪等段只會(huì)從open → closed遷移一次可安全重復(fù)調(diào)用。十、小結(jié)一條完整的「會(huì)話 → 知識(shí)」流水線將以上機(jī)制串聯(lián)一次會(huì)話在 OpenHuman 中的記憶沉淀路徑是逐輪on_turn_complete將用戶(hù)/助手回合寫(xiě)入 FTS5 情景表雙寫(xiě) md 歸檔工具失敗生成零成本教訓(xùn)分段detect_boundary按回合數(shù)、時(shí)間間隔、話題短語(yǔ)、向量漂移四重檢查切分 Segment段關(guān)閉LLM recap或啟發(fā)式回退→ 段摘要與 embedding 落庫(kù) → 啟發(fā)式事件提取 → 畫(huà)像 Facet 合并 → 原始散文灌入記憶樹(shù) → 后臺(tái)刷新長(zhǎng)期目標(biāo)知識(shí)庫(kù)update_memory_md以白名單 進(jìn)程內(nèi)鎖 跨進(jìn)程 flock 原子重命名的方式安全追加 MEMORY.md/SKILL.md會(huì)話結(jié)束flush_open_segment兜底收尾最后一個(gè)開(kāi)放段。Archivist 的設(shè)計(jì)核心可以概括為三句話用便宜機(jī)制做逐輪工作用昂貴機(jī)制做段級(jí)工作用并發(fā)安全機(jī)制做文件寫(xiě)入。如果你想在 OpenHuman 中自定義類(lèi)似的后臺(tái)記憶 Agentagent.toml 的「background 最小工具集 低 temperature max_result_chars 限流」組合加上 prompt.md 的「職責(zé) 規(guī)則」雙層結(jié)構(gòu)是一份可以直接復(fù)用的模板?！久赓M(fèi)下載鏈接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/op/openhuman創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考