KokoroMemo / 心憶項目機制介紹

之前已經發過 KokoroMemo / 心憶的項目介紹，這次就不重複聊“它是什麼”，主要介紹一下工作原理

https://api.xiaoheihe.cn/v3/bbs/app/api/web/share?h_camp=link&h_src=YXBwX3NoYXJl&link_id=79e071d5b933

https://api.xiaoheihe.cn/v3/bbs/app/api/web/share?h_camp=link&h_src=YXBwX3NoYXJl&link_id=359571da85fb

前排提示，本篇爲技術介紹文檔，僅供有興趣的盒友參考（現在退出還來得及

一、項目定位

KokoroMemo 不是一個聊天前端，而是一箇中間件。

也就是夾在 AI 客戶端和大模型 API 之間的本地代理，用來存儲相關記憶信息。

（一）核心工作流程

KokoroMemo 配置好相關 AI 模型後，客戶端直接用 OpenAI 兼容協議請求本地 14514 端口。

當請求經過 KokoroMemo 時，它會在中間做幾件事：保存對話、維護當前會話狀態、判斷是否需要召回長期記憶、把必要的記憶注入上下文，然後再把請求轉發給雲端 AI 。

KokoroMemo 不是“再做一個聊天軟件”，而是給現有 AI 角色扮演、AI 遊戲、桌寵、類 SillyTavern 輕量客戶端補上一層本地長期記憶系統。

（二）常見問題

1.跟酒館啥區別？

壓根就不是一個東西，酒館是聊天前端，KokoroMemo 是中間件。

2.爲什麼不做酒館插件？

酒館插件無法脫離酒館環境運行，也就無法應用到其他遊戲上。

KokoroMemo 想做的是把長期記憶這個功能進行擴展，做成一個能夠適配多種平臺的功能。

而且實話說酒館插件維護，本身就是個喫💩的過程，之前做這個插件踩的坑讓我完全不想嘗試第二次了

3.爲什麼不做 AstrBot 插件？

和上面問題一樣，插件無法脫離本體運行，而且會受到本體的功能限制。

二、記憶分層

（一）全量處理的弊端

記憶處理不是大雜燴，並不能直接把聊天記錄塞進上下文。

如果完全不做篩選直接全量處理，短期看很簡單，但是長期必然會遇到如下問題：

1.上下文變髒

角色可能把玩笑、誤會、過期設定甚至是幻覺都當成穩定記憶。

比如你發了一句“你是能當我媽媽的女人啊！”，然後這個玩笑寫入了聊天記憶。

剛開始的時候可能 AI 還能意識到這是個玩笑，但是在幾輪對話之後，AI 注意力降低，它只注意到了要“當媽媽”，然後開始勸你好好學習

2.召回不穩定

隨口說一句話，也可能觸發一堆不相關歷史內容。

比如正在衝刺的時候發了一句“你這個🔥福瑞”，然後向量庫把你們之前聊過的貓娘犬娘蜘蛛娘之類的話題全都召回了，接下來 AI 立馬開始跟你討論福瑞這個話題

3.內容不可控

AI 到底記住了什麼，用戶不一定看得見，也不一定能改。

簡單來說就是變成黑箱了，很難針對性地進行改動，即使手動修改上下文也會很麻煩，你需要從一大堆聊天記錄裏面找出來特定內容

4.token爆炸

這個不用多說了，全量塞的話每一輪都會造成 token膨脹，最後會發現你一輪對話提示詞裏面90%都是聊天曆史。而且上下文過多會導致注意力混亂，越往後面幻覺越嚴重。

（二）分層方案

KokoroMemo 會採用 3 層記憶分層方案來處理聊天記錄。

1.熱記憶：當前會話狀態板

類似於酒館記憶表格，可以理解成角色當前狀態，它記錄的是當前會話里正在發生的事情

比如：當前場景、角色情緒、正在進行的任務、短期承諾、當前關係狀態、重要物品、用戶剛剛強調的邊界

舉個例子，當前劇情是你們現在在雨夜的車站，青梅手裏拿着一封沒拆開的信。她發現了隔壁大姐姐給你的情書，所以她現在要去跟隔壁大姐姐對線。

這些信息對當前幾輪對話很重要，但是不值得永久保存。

所以 KokoroMemo 會把這類內容放進“會話狀態板”，在每輪請求前注入給模型。

這樣模型下一輪迴復時就知道：現在在哪裏、角色是什麼狀態、當前任務是什麼、剛纔發生了什麼，不用每次都靠完整聊天記錄硬灌。

會話狀態板

2.溫記憶：長期記憶卡片圖譜

這是提煉出來的記憶卡片，負責“長期穩定的事實”。

也就是說，真正需要跨會話保存的內容，會被整理成記憶卡片。

比如：用戶希望角色稱呼自己爲“BAKA”、用戶不喜歡過度病嬌或威脅式表達、角色曾經答應下次一起去看煙花某條劇情線已經推進到某個階段用戶喜歡輕鬆撒嬌型互動

這些內容不是一整段聊天記錄，而是被整理成比較清晰的卡片。

比如一張記憶卡片可能長這樣：

稱呼：哥哥
類型：偏好
內容：用戶希望 Yuki 在親密場景中稱呼自己爲“BAKA”
標籤：稱呼、用戶偏好、親密互動
狀態：approved

也就是把聊天記錄提煉成可視化卡片，可以一眼看懂 AI 到底記住了什麼，也能手動修改或拒絕。

記憶卡片

當然，記憶之間也有關係，不只是“相似”

KokoroMemo 裏的記憶卡片不只是孤立保存，還可以有關係。

比如：A 支持 B、A 約束 B、A 與 B 衝突、A 替代 B、A 延續 B、A 屬於 B……

舉個例子，系統記住了：用戶喜歡角色輕微喫醋。

但同時也記住了：用戶不喜歡威脅、自傷、病態控制。

這兩條就不是簡單的“相似關係”，第二條應該約束第一條。

也就是說，當角色想表現“輕微喫醋”時，提示詞彙提醒模型：可以喫醋，但不要演變成病嬌式威脅、自傷或病態控制。

這就是記憶圖譜的意義，不只是幫角色“想起來”，還要幫角色“想對”。

記憶圖譜

3.冷記憶：語義向量索引

這是語義索引，負責“需要時去找舊事”，主要用於檢索。

比如用戶說：你還記得我們X月X日約好的事嗎？

這句話本身沒有說明“約好的事”是什麼，這時候 KokoroMemo 就需要去長期記憶裏找相關內容。

它會根據當前發言、角色、會話和已有狀態，去檢索相關記憶卡片、摘要、標籤和圖關係。

比如可能召回：之前約定，等穹妹長大就結婚……然後再把這條記憶注入提示詞。

這樣模型回覆時就能接上：當然記得，我們現在去領證吧！

這裏有個重點，語義索引的 LanceDB 向量庫其實不是記憶本體，真正可信的長期數據保存在本地 SQLite 裏。

語義索引只是爲了方便搜索，即使壞了也可以通過 SQLite 數據庫進行完整重建。

同樣重建向量庫這個功能也可以用在不同模型上，比如更換其他 Embedding 模型。

三、風控機制

Retrieval Gate：不是每輪都翻舊賬

KokoroMemo 裏有一個比較關鍵的機制叫 Retrieval Gate，也就是“召回門控”。

它負責判斷：這一輪到底需不需要查長期記憶？

因爲不是每句話都值得召回。

比如用戶只是說：嗯、繼續、好、抱抱……這種時候，當前狀態板通常已經足夠了。

沒必要每輪都查向量庫，也沒必要把一堆舊記憶塞進上下文。

但如果用戶說：你還記得我們第一次見面嗎？上次你答應我的事情呢？之前我說過我不喜歡什麼？那個角色後來怎麼樣了？這種就明顯需要長期召回。

所以 KokoroMemo 的流程大致是：

接收聊天請求 ➡ 識別用戶、角色和會話 ➡ 讀取當前會話狀態板 ➡ 先注入當前狀態 ➡ Retrieval Gate 判斷是否需要長期召回 ➡ 如果需要，就檢索記憶卡片、圖關係和語義索引 ➡ 篩選、去重、排序 ➡ 把少量高相關記憶注入上下文 ➡ 轉發給真實大模型 ➡ 返回回覆 ➡ 後臺更新狀態板並提煉候選記憶

這樣可以減少兩個問題：不必要的檢索開銷、不必要的上下文污染

角色要記得你，但不能每句話都翻舊賬。

本項目含人量約10%，核心代碼均由AI貢獻

除核心方案工作流全程人工製作，其餘均由 AI 參與。

截至 v0.10.0 版本，項目代碼量約 3 萬行，其中古法編程約 500 行

項目 LOGO 及 GUI 設計由 Gemini 3.1 Pro 實現，後端架構設計、審覈由 GPT 5.5 實現，核心功能由 Claude Opus 4.7 實現，部分 BUG 檢修由 MiMo V2.5 Pro 及 DeepSeek V4 Pro 執行，累計消耗 token 約 12 億……token 燃燒器

關於視頻教程，因目前的測試版功能變動較快，所以會當 v1.0 穩定版發佈的時候製作