1. 為什么要做 claude-mem從一個反復踩過的坑聊起如果你用 Claude 寫代碼或者做 Agent一定遇到過這種情況同一個項目頭一天還聊得好好的第二天打開新會話它完全不記得你昨天給過它的架構約束。每次都要把需求重新復述一遍遇到復雜的業(yè)務規(guī)則復述過程中漏掉一兩句后續(xù)回答就完全跑偏。claude-mem 這個項目就是為了解決這個問題用本地記憶庫給 Claude 補上一個“長期記憶”讓它在多個會話之間記住關鍵信息而不是每次都從零開始。這套思路技術上不算復雜核心就三步把過去對話里的關鍵內容抽取出來分塊存儲把當前問題向量化再從記憶庫里檢索最相關的內容作為提示補充給 Claude。但實際做下來我發(fā)現真正的難點根本不在“調 API”而在記憶的寫入時機、分塊粒度、相似度閾值這些不起眼的設計點上。差一點效果就是天壤之別。我的目標讀者分兩類一類是做 Claude 深度應用的開發(fā)者想把長期記憶接進自己的項目里另一類是玩?zhèn)€人助手、跑本地服務的進階用戶希望 Claude 能記住自己的偏好和習慣。這篇文章我把整個思路、代碼、參數調節(jié)和踩坑實錄都放出來你可以直接照著抄也可以按自己的場景改。提示本文涉及到的代碼都是我在本地小范圍驗證過的方案不是生產級工業(yè)系統(tǒng)但足夠你跑通一個完整的記憶閉環(huán)。生產環(huán)境要加并發(fā)鎖、連接池和更嚴格的數據隔離這個后面會單獨說。2. 記憶系統(tǒng)設計的三層結構與選型邏輯2.1 短期上下文窗口與長期記憶的邊界開始寫代碼之前我先想清楚了一個問題Claude 本身不是沒有記憶它的上下文窗口就是短期記憶你把內容放在系統(tǒng)提示和對話歷史里它都能看到。但窗口有限而且一旦會話關閉下一輪對話就全部清空。所以要做“長期記憶”本質上是把信息從上下文窗口里挪出去存到外部用的時候再挑一部分放回窗口。我一開始想著把所有歷史都塞回去結果第一次實驗就發(fā)現不行。放了二十多輪的聊天記錄進去Claude 的表現反而變差了因為無關信息太多把注意力全帶偏了。后來我才意識到長期記憶應該扮演的是“筆記”角色而不是“錄像回放”。每個會話結束時整理出幾條關鍵結論存起來比原封不動地存聊天記錄要干凈得多。這也引出了一個核心設計記憶分兩層一層是工作記憶當前上下文窗口一層是長期記憶外部存儲兩者之間靠“寫入摘要”和“請求觸發(fā)讀取”來同步。體現到項目里就是每次對話進行到一定階段我把對話歷史交給 Claude讓它自己總結出不超過 200 字的要點然后把要點向量化后保存。到下一次用戶提問時先把問題向量化再從庫里找出相關的舊要點拼裝進上下文。這樣短期窗口負責深度推理長期記憶負責提供背景各司其職。2.2 向量化、存儲和檢索三個核心選型記憶要能被搜索最省事的方案就是向量檢索。把文本映射成一組浮點數相近語義的文本在向量空間里距離也接近。日常說“幫我找一下上次討論過的緩存策略”向量檢索能匹配到一個大意相似的舊總結而關鍵詞搜索大概率會失敗因為字面上可能一個詞都對不上。選嵌入模型的時候我在兩個方向之間猶豫云 API 還是本地模型。云 API 效果好、省內存但會把對話文本發(fā)到外部服務本地模型多占一點內存但隱私能兜住。對這個項目我最后選了本地方案用 sentence-transformers 加載一個輕量的中文模型。理由很簡單claude-mem 本身定位是本地記憶庫如果嵌入也走云 API就要多維護一套鑒權而且長期運行成本更高。實測下來輕量模型的準確率夠用關鍵是延遲低單條文本十幾毫秒就能出向量。存儲方面我沒有引入重型向量數據庫。因為單機場景、幾千條記憶SQLite 完全夠用。數據量小的時候直接在內存里算余弦相似度也很穩(wěn)。只有當記憶條目超過幾萬條才需要考慮 HNSW 這類近似最近鄰索引。我的經驗是先跑通 SQLite 加線性掃描滿足不了性能了再遷移到真正的向量庫不要一上來就為不存在的規(guī)模買單。2.3 為什么不用現成的記憶 SDK做記憶系統(tǒng)的時候市場上已經有幾個商業(yè)化的記憶 SDK能幫應用記住用戶畫像、聊天記錄。我認真看過功能確實全面接入成本也不高。但最終沒有用原因是這類 SDK 把記憶管理的邏輯封裝成了黑盒我控制不了“什么該記”“什么不該記”。而很多 Agent 場景恰恰需要細粒度控制比如某些對話內容完全不能寫入記憶庫某些記憶只能保留 24 小時這些定制需求在黑盒里做起來很別扭。另外商業(yè) SDK 的數據通常存儲在對方的服務端雖然方便了多端同步但對本地部署和純內網項目來講反而是減分項。數據留在自己手里這個需求比我預想的要硬得多。所以 claude-mem 從立項起就決定本地存儲、邏輯可讀、代碼可改。哪怕犧牲掉一部分開箱即用的便利也值得。這套取舍思路我覺得比具體技術選型更有參考價值。3. 核心實現細節(jié)記憶的寫入、組織與讀取3.1 寫入時機什么時候該把東西沉淀下來記憶寫入是整個系統(tǒng)里最容易做砸的環(huán)節(jié)。最早的版本我圖省事每收到一條用戶消息就先存進數據庫結果庫里垃圾信息一堆。比如用戶說“等一下”這種話也被當成記憶存了下來。后來我改成兩個觸發(fā)條件一個是會話結束或者長時間停頓后讓 Claude 對整個會話做總結另一個是每輪回答結束后根據信息量決定要不要更新記憶。實際操作中我會重點判斷三個點這段對話里有沒有明確的事實性約定比如端口號、存儲路徑、接口返回格式有沒有提出過可復用的方法論比如“這個模塊建議用事件驅動而非輪詢”有沒有涉及用戶偏好比如“輸出盡量簡短”“不要用專業(yè)術語”這三個判斷如果寫成規(guī)則會非常死板。我的做法是直接在總結提示詞里告訴 Claude只記錄事實、決策、偏好和待辦事項忽略寒暄、過程性討論和明顯過時的信息。實測下來這個做法比單純存聊天記錄干凈 80% 以上。壞處是多一次模型調用但相比換回來的記憶質量這點成本完全可以接受。3.2 分塊策略與嵌入模型選擇先過語言關把文本向量化之前要先切塊這是最容易忽略的細節(jié)。我試過整段文本一次性嵌入效果很糟糕因為一段千字內容里包含多個主題向量會被平均成一個誰都不像的中間態(tài)。檢索的時候常常匹配到無關的內容。最后我把單條記憶控制在 150 到 500 字之間超過 500 字就拆成多個小塊每塊盡量保持一個完整主題。這里有個語言層面的坑。Claude 的中文能力很強但中文文本做向量化的模型選擇不太一樣。我對比過幾個通用英文嵌入模型在英文場景下表現很好一換成中文長文就開始出現“詞不達意”的匹配。后來換成了針對中文優(yōu)化的輕量模型匹配準確性明顯提升。做這個項目的一個直觀感受是嵌入模型和主模型是兩回事主模型要智能嵌入模型要貼語言兩者不能混為一談。注意中文文本分塊不要按字符數硬切盡量按句子或者語義段落切。用句號、感嘆號、問號作為切分邊界再根據字數量做合并。否則很容易把一句話從中間截斷向量語義會受損。3.3 檢索策略相似度閾值和 top-k 怎么調檢索環(huán)節(jié)有三個參數需要調相似度閾值、返回條數 top-k、以及時間衰減。相似度閾值的作用是把明顯無關的記憶擋在外面。我一開始閾值設得很低導致很多雜音記憶被塞進上下文。后來把閾值從 0.4 一路往上調到 0.55 左右才穩(wěn)定低于這個值的記憶即使返回了Claude 用起來也只會添亂。top-k 決定最多返回幾條記憶。我試過 3、5、8、10 幾個值發(fā)現 5 條左右效果最好。太少信息量不夠太多又擠占了上下文空間。而且 top-k 不是固定的在長任務場景里我會把它降到 3只保留最核心的背景在閑聊場景里會提到 8讓上下文顯得豐富一點。時間衰減是后加的。因為記憶庫里既有昨天的討論也有上個月的方案如果不加限制很可能檢索出來的全是老舊的過期信息。我的策略是給每條記憶打上時間戳計算相關度時把時間的衰減系數乘上去。簡單做法是最終得分 余弦相似度 - 時間衰減懲罰值。這樣昨天的筆記會比三個月前的優(yōu)先被選中。這個調整非常關鍵尤其在做持續(xù)迭代的項目時舊方案和新需求往往語義相近但方案內容已經完全不同。4. 實操過程從零搭一個可用的 claude-mem4.1 環(huán)境準備與依賴安裝我建議直接在虛擬環(huán)境里操作避免污染系統(tǒng) Python。項目用到的主要依賴有這幾項pip install anthropic sentence-transformers numpysentence-transformers 會自動拉取 PyTorch安裝包體積比較大但一次裝完以后本地推理就很方便。如果機器配置比較低可以換用更小的嵌入模型。我這里用的是中文場景下常見的輕量模型比如 BAAI/bge-small-zh-v1.5量化后占用內存不到 1GB普通筆記本都能帶得動。如果你只是想在命令行里快速體驗不需要自己做接入也可以直接 pip 安裝社區(qū)版本。但我個人建議項目初期自己動手寫一遍核心邏輯這樣出了問題自己心里有數后面好排查。4.2 核心代碼骨架記憶庫的讀寫與檢索下面是 claude-mem 最簡版本的核心邏輯。我不會貼一個超大工程而是把記憶庫的讀寫、向量化和檢索拆成三個邏輯塊方便你對照理解。import sqlite3 import numpy as np from datetime import datetime def get_embedding(text: str) - list: from sentence_transformers import SentenceTransformer model SentenceTransformer(BAAI/bge-small-zh-v1.5) return model.encode(text).tolist() def cosine_similarity(a: list, b: list) - float: a np.array(a) b np.array(b) return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) 1e-8)) class ClaudeMem: def __init__(self, db_pathclaude_mem.db): self.conn sqlite3.connect(db_path) self._init_table() def _init_table(self): self.conn.execute( CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, embedding TEXT NOT NULL, session_id TEXT, created_at TEXT NOT NULL ) ) self.conn.commit() def save_memory(self, content: str, session_id: str): embedding get_embedding(content) created_at datetime.now().isoformat() self.conn.execute( INSERT INTO memories (content, embedding, session_id, created_at) VALUES (?, ?, ?, ?), (content, str(embedding), session_id, created_at) ) self.conn.commit() def search_memories(self, query: str, top_k: int 5, threshold: float 0.55): query_emb get_embedding(query) rows self.conn.execute( SELECT id, content, embedding, session_id, created_at FROM memories ).fetchall() scored [] for row in rows: emb np.array(eval(row[2])) score cosine_similarity(query_emb, emb) if score threshold: scored.append({id: row[0], content: row[1], score: score, created_at: row[4]}) scored.sort(keylambda x: x[score], reverseTrue) return scored[:top_k]這個實現刻意簡化了時間衰減和會話隔離但基本閉環(huán)已經有了“保存記憶”和“檢索記憶”兩個接口都可用。實際用下來SQLite 表里幾千條記錄時線性掃描性能完全能接受返回時間在幾十毫秒級別不會成為瓶頸。4.3 接入 Claude API如何把記憶注入對話記憶庫和 Claude 的銜接是另一個關鍵環(huán)節(jié)。我采用的是“系統(tǒng)提示注入法”每次請求前先拿用戶當前的 query 去檢索相關記憶再把記憶內容拼進 system prompt 里。這樣 Claude 相當于一邊看舊筆記一邊回答新問題不會前后矛盾。import anthropic client anthropic.Anthropic() def ask_with_memory(query: str, mem: ClaudeMem, session_id: str): results mem.search_memories(query, top_k5) memory_lines \n.join([f- {r[content]} for r in results]) system_prompt 你是用戶的項目助理。以下是與當前問題相關的過往記憶\n memory_lines response client.messages.create( modelclaude-sonnet-4-5-20250929, max_tokens1024, systemsystem_prompt, messages[{role: user, content: query}] ) return response.content[0].text上面這段代碼是最小的接入示例但我強烈建議你在實際項目中加一層“來源標注”。比如每條記憶前面標注“來自 3 月 14 日的會議討論”這樣 Claude 既能參考也知道記憶可能存在有效期不會盲目采信。這個細節(jié)看起來簡單實際效果卻很明顯。不加來源時Claude 經常把舊記憶當成確定事實加了來源后回答措辭會更加謹慎比如“根據上周記錄你傾向于這種方式”。4.4 對話結束后的記憶沉淀我還做了一個比較關鍵的功能對話結束后自動沉淀記憶。流程是先統(tǒng)計這輪對話中是否有值得記憶的內容再單獨調用一次 Claude讓它用規(guī)定格式輸出結構化記憶。相比直接保存原始聊天記錄這種做法可以顯著減少噪聲。def summarize_and_save(history: list, mem: ClaudeMem, session_id: str): summary_prompt ( 請根據以下對話歷史提取需要長期記住的事實、決策、偏好和待辦事項。 每條不超過200字只輸出要點列表不要輸出寒暄和過程性討論。\n\n \n.join(history) ) response client.messages.create( modelclaude-sonnet-4-5-20250929, max_tokens512, messages[{role: user, content: summary_prompt}] ) points response.content[0].text.strip().split(\n) for point in points: if point.strip(): mem.save_memory(point.strip().lstrip(- ), session_id)這段代碼跑了很久之后我意識到一個問題summary 的輸出格式不穩(wěn)定。有時候輸出“- 事實……”這種帶前綴的格式有時候是純文本。我在保存前會把行首的多余符號清掉但更穩(wěn)妥的做法是讓模型輸出 JSON 數組然后用 json.loads 解析。這樣做可以避免格式兼容性問題也為后面做記憶合并和去重提供方便。5. 常見問題與排查技巧實錄5.1 記憶被污染檢索到大量無關內容這是我最常被問到的問題?，F象是 Claude 回答問題時突然引入一些和當前話題毫無關聯的背景導致答案變亂。排查下來十有八九是分塊策略出了問題或者相似度閾值設得太低。我后來在項目里加了一個“記憶審計”入口把庫里所有記憶按 id 和內容導出人工看一眼有沒有壞數據。這個方法笨但有用。另一個有效的辦法是給每條記憶加“來源會話”和“類型”字段在檢索時按類型過濾比如當前是技術提問時只檢索類型為“技術決策”的記憶。字段維度越多過濾越精準。5.2 記憶過多擠占上下文窗口隨著時間推移記憶庫越來越龐大檢索返回的 top-k 條記憶拼接進上下文后可能導致總 token 數超標。我遇到過一次在極端情況下 error 提示上下文窗口溢出的情況。解決方案有三個方向限制 top-k、壓縮記憶長度、以及在拼入 system prompt 前做一個總體 token 估算。我實現了一個很實用的函數把當前對話的整體 token 數估算出來再用預算上限減去已用 token剩余配額優(yōu)先滿足 Claude 的回答長度記憶部分只占剩下的 30% 左右。這個比例是我反復試出來的如果記憶占比太大Claude 會過度依賴舊信息回答顯得僵硬如果太小又起不到記憶的作用。5.3 舊知識與新需求沖突另一個典型問題是舊知識和新需求打架。比如周一約定用 A 方案周五又決定改成 B 方案但庫里兩條記錄都存在。檢索時可能同時返回兩條Claude 就出現了自我矛盾。我最終的解決辦法是“記憶覆蓋機制”寫入新方案時給相關舊方案打上 deprecated 標記檢索時默認排除已經廢棄的記錄。不過這個操作有個難點判斷兩條記憶是否相關在簡單規(guī)則下很難做到準確。我現在的做法是在保存新記憶時先用新記憶本身去檢索一次舊記憶把相似度高的舊記憶標記為“被替代”。這個方法不能說完全可靠但能解決大部分方案迭代引發(fā)的矛盾配合時間衰減使用效果更好。5.4 表格速查常見問題與排查方向我把實際碰到的幾個問題整理成了一個速查表方便你在日常使用中快速定位?，F象原因排查方向檢索結果明顯跑題分塊太大或閾值過低檢查文本是否被硬切上調閾值至 0.5 以上Claude 回答矛盾新舊記憶同時存在為記憶加版本或廢棄標記回答太“背課文”記憶比重過高降低 top-k限制記憶 token 配額記憶庫增長極快無篩選地保存一切改用 Claude 總結并結構化后再寫入中文匹配不準嵌入模型不貼合中文換用中文優(yōu)化的嵌入模型會話間記憶串味缺少 session_id 隔離給每條記憶加數據源字段檢索時過濾5.5 存儲安全與隱私隔離本地存儲雖然有隱私優(yōu)勢但沒有做權限控制的本地存儲依然是隱患。我在項目里加了幾條硬規(guī)則數據庫文件默認放到用戶目錄下權限設為 700記憶內容不允許包含明文密鑰和密碼涉敏感的信息在寫入前做脫敏。你可以通過一個簡單的前置過濾列表把像“密鑰”“密碼”這類高危詞直接攔截提示用戶不要寫入記憶庫?？紤]到多人共用一個服務端的情況我建議給每條記憶添加 owner 字段在檢索時強制帶上這個條件避免不同用戶的數據互相污染。這個設計雖然只加一個 WHERE 條件但能避免大量線上事故。6. 寫在最后的實踐體會claude-mem 做下來我最深的感受是“記憶系統(tǒng)本質上是一個代碼之外的工程問題”。模型的選擇、參數的調整、存儲方案的取舍這些都有規(guī)律可循但真正讓一個記憶工具變得好用的是對數據質量的持續(xù)管理。如果你只寫代碼不沉淀記憶那它只是一個普通問答接口如果你把每一輪對話都無腦存下來它就會變成一個越來越大但越來越難用的垃圾場。這幾周踩坑下來我形成了一個很穩(wěn)定的工作流會話開始先檢索緩存會話中先判斷有無值得記錄的決策會話結束后統(tǒng)一總結入庫隔一段時間手動清理失效條目。這樣整個系統(tǒng)的記憶質量始終保持在可用線之上。最后分享一個實用技巧定期給記憶庫做一次壓縮合并把當時拆分成多個 200 字小塊的舊記錄重新匯總成一條完整的階段性總結。壓縮后不僅檢索更快Claude 讀起來也會流暢很多。哪怕你完全復用我的代碼這個習慣也值得先養(yǎng)起來。