MemPalace 記憶檢索實操指南Agent 的語義搜索流程、MCP 工具鏈與 CLI 回退方案【免費下載鏈接】mempalaceThe best-benchmarked open-source AI memory system. And its free.項目地址: https://gitcode.com/GitHub_Trending/me/mempalace當你向 MemPalace 提問“我們上次為什么把登錄切到 Clerk”這類問題時真正發(fā)生的是一次結(jié)構(gòu)化的記憶檢索查詢意圖被解析、作用域Wing/Room被收斂、向量語義檢索與關(guān)鍵詞檢索被聯(lián)合打分最后結(jié)果按來源歸組呈現(xiàn)。本篇指南基于 MemPalace 的 search 指令面向 AI Agent 的操作規(guī)程展開并結(jié)合倉庫內(nèi) MCP 服務(wù)端與搜索引擎源碼完整還原一次搜索從“用戶一句話”到“帶出處、帶相似度的記憶清單”的完整鏈路以及沒有 MCP 時的 CLI 兜底打法。讀完本文你將掌握如何解析檢索意圖與過濾器、如何按優(yōu)先級調(diào)用 6 個記憶檢索相關(guān) MCP 工具、如何理解mempalace search命令的全部參數(shù)、如何把結(jié)果以“可引用、可追溯”的形式呈現(xiàn)以及這些能力背后的混合檢索Hybrid Search實現(xiàn)原理。一、先理解要檢索的對象Wing / Room / Drawer 三級結(jié)構(gòu)MemPalace 的記憶不是一坨文本而是被組織成層級化“宮殿”結(jié)構(gòu)。搜索指令中反復出現(xiàn)的過濾器Wing、Room都建立在如下三級分類上層級名稱含義檢索中的作用頂層分類Wing領(lǐng)域 / 項目 / 主題如 work、personal、research在項目挖掘流程中對應(yīng)項目名mempalace_search的wing參數(shù)、CLI 的--wing子分類RoomWing 內(nèi)的子類 / 主題如 auth-migration、costsmempalace_search的room參數(shù)、CLI 的--room記憶單元Drawer一條被原樣保存verbatim的記憶元數(shù)據(jù)攜帶 wing、room、source_file 等歸屬信息檢索返回的正是這些 Drawer 的原文關(guān)于“Wing 到底代表什么”倉庫內(nèi)有兩種具體形態(tài)可以互相印證面向項目的挖掘流程把它當作項目名mcp-tools.md 中mempalace_add_drawer將 wing 描述為 “project name”而日記寫入工具mempalace_diary_write的文檔寫明“each agent gets its own wing”——即多 Agent 共享腦場景下每個 Agent 擁有獨立 Wing。因此把它理解為“最頂層的歸屬分類”即可不必糾結(jié)于單一命名。檢索到的最底層單元是 Drawer其核心特征是原文返回verbatim搜索引擎 searcher.py 的模塊文檔串寫著 “Search the palace. Returns verbatim drawer content.”返回的是當初寫入的確切文字而不是摘要或改寫這正是記憶檢索區(qū)別于普通問答的關(guān)鍵。二、第一步解析搜索查詢Parse the Search Query當用戶提出一個需要回憶的問題時不要把整句話原樣丟給搜索而是先做一次結(jié)構(gòu)化解析從消息中提取語義查詢詞Keywords / semantic query——真正要去匹配的記憶內(nèi)容通常是去掉寒暄后的核心短語例如 “auth migration decision last month”。顯式或隱式的作用域過濾器Wing——用戶提到的領(lǐng)域 / 項目 / 上下文如 “咱們的項目 X 里”、“在我的研究筆記里”Room——用戶提到的具體子主題如 “關(guān)于數(shù)據(jù)庫選型那部分”若用戶沒有給出任何維度線索則這些過濾器缺省見下文“全局檢索”。三、第二步判定并解析 Wing/Room 過濾器解析出候選作用域之后關(guān)鍵一步是把用戶口語化的領(lǐng)域描述映射為倉庫中真實存在的分類名如果用戶明確提到具體域名 / 主題 / 上下文盡量映射到合適的 Wing 或 Room如果不確定寧可不加過濾器進行全局檢索——全局檢索永遠不會因為猜錯了分類而漏掉本該命中的記憶需要時可以先做一次“分類體系探查”即用第 4 節(jié)中的mempalace_list_wings/mempalace_list_rooms/mempalace_get_taxonomy拿到真實存在的分類名后再發(fā)起搜索。這一步的價值在倉庫文檔中有明確論述searching.md 指出當單個 palace 里存放著許多互不相關(guān)的項目或人時Wing或 Wing Room限定能讓向量存儲只在作用域內(nèi)打分從而隨記憶規(guī)模增長保持檢索結(jié)果的可預測性同時它也被如實描述為“向量存儲的元數(shù)據(jù)過濾能力而非新的檢索機制”是任何人都能套用的清晰操作約定。四、第三步優(yōu)先走 MCP 工具鏈搜索指令規(guī)定只要 MCP 工具可用就按下面的優(yōu)先級順序使用它們。這套順序的設(shè)計意圖非常清晰先直接檢索mempalace_search檢索前或檢索后按需做結(jié)構(gòu)探查wings/rooms/taxonomy需要深挖關(guān)聯(lián)時再用圖遍歷traverse、find_tunnels。優(yōu)先級MCP 工具用途關(guān)鍵參數(shù)1首選mempalace_search語義搜索主工具傳入語義查詢 Wing/Room 過濾器query必填、wing、room、limit默認 52mempalace_list_wings列出全部 Wing。當用戶問“有哪些分類”或你需要解析 Wing 名稱時使用無3mempalace_list_rooms(wing)列出某 Wing 內(nèi)的 Rooms用于幫助用戶導航或解析 Room 名wing可選缺省列出全部4mempalace_get_taxonomy取回完整 Wing → Room → Drawer 樹當用戶想縱覽整個記憶結(jié)構(gòu)時使用無5mempalace_traverse(room)從某個 Room 出發(fā)在記憶圖上漫游當用戶想探索關(guān)聯(lián)記憶時使用start_room必填、max_hops默認 26mempalace_find_tunnels(wing1, wing2)尋找兩個 Wing 之間的跨域連接tunnel當用戶關(guān)心不同知識域之間的關(guān)系時使用wing_a、wing_bschema 中的參數(shù)名均可選說明指令文檔寫作層面稱mempalace_traverse(room)、mempalace_find_tunnels(wing1, wing2)在 MCP 服務(wù)端實際暴露的 JSON Schema 中前者參數(shù)為start_room/max_hops后者為wing_a/wing_b見 MCP Tools Reference。4.1 工具在源碼中的對應(yīng)實現(xiàn)這些工具并不是虛構(gòu)的抽象而是 MCP 服務(wù)端 mcp_server.py 中真實注冊的調(diào)用面mempalace_search等讀工具在服務(wù)端的工具清單TOOLS中被聲明其內(nèi)部調(diào)用鏈會導向 searcher.py 的search_memories()——一個“返回 dict 而非打印”的程序化檢索入口專供 MCP 服務(wù)端與其它需要結(jié)構(gòu)化數(shù)據(jù)的調(diào)用方使用mempalace_traverse、mempalace_find_tunnels對應(yīng)的底層邏輯在 palace_graph.py 中traverse、find_tunnels等函數(shù)它們工作在由實體與關(guān)系構(gòu)成的記憶圖譜上服務(wù)端還內(nèi)置了健壯性設(shè)計例如在chroma.sqlite3的啟動完整性探針失敗時會先把狀態(tài)類工具mempalace_status等放入允許名單其余工具被拒絕并提示修復見 mcp_server.py 中 SQLite integrity gate 的實現(xiàn)注釋。4.2 搜索引擎的返回值契約mempalace_search的返回結(jié)構(gòu)是 Agent 呈現(xiàn)結(jié)果的數(shù)據(jù)基礎(chǔ){ query: auth decisions, filters: { wing: myapp, room: auth }, results: [ { text: We decided to migrate auth to Clerk because..., wing: myapp, room: auth-migration, source_file: session_2026-01-15.md, similarity: 0.892 } ] }注意三個細節(jié)text是逐字原文similarity是 [0,1] 區(qū)間上的相似度由底層距離換算而來見第 6 節(jié)source_file在此處暴露的是文件名部分——服務(wù)端刻意把挖掘流程寫入的絕對路徑在返回前降為 basename作為顯示用途詳見 mcp-tools.md。五、第四步CLI 兜底方案搜索指令明確約定如果 MCP 工具不可用回退到命令行?；拘螒B(tài)為mempalace search query [--wing X] [--room Y]在 cli.py 的 search 子命令解析器中實際可用參數(shù)比指令文檔示例更完整參數(shù)說明默認值query位置參數(shù)要搜索的內(nèi)容自然語言語義查詢必填--wing限定到某一個項目 / 領(lǐng)域無全局--room限定到某一個 Room無全局--results返回結(jié)果條數(shù)5--since只檢索歸檔時間 ≥ 該 ISO 日期/時間含端點如2026-04-01的 Drawer一旦設(shè)定日期邊界缺少filed_at的 Drawer 會被排除無--before只檢索歸檔時間嚴格早于該 ISO 日期/時間的 Drawer不含端點無--backend本次搜索使用的存儲后端默認走配置 / 環(huán)境變量 / 自動探測 / chroma自動一個組合示例同時命中主題、來源文件路徑與時間窗的實戰(zhàn)查詢# 全局檢索 mempalace search why did we switch to GraphQL # 限定項目與主題 mempalace search database decision --wing myapp --room db # 限定項目 主題 最近歸檔區(qū)間返回 10 條 mempalace search deploy process --wing driftwood --room infra --results 10 --since 2026-01-015.1 CLI 如何調(diào)用指令內(nèi)容命令插件形態(tài)倉庫把“執(zhí)行 search 指令”做成了可直接觸發(fā)的命令在 Cursor 等宿主里執(zhí)行search命令時commands/mempalace-search.md 會指引插件先運行mempalace instructions search打印出檢索規(guī)程再照章執(zhí)行該會話內(nèi)也直接暴露了mempalace_searchMCP 工具。而mempalace instructions search之所以能工作是因為 cli.py 把init/search/mine/help/status等指令名注冊進了instructions子命令它們對應(yīng) mempalace/instructions/ 目錄下的同名 Markdown 文件——搜索規(guī)程正是 search.md。六、第五步如何向用戶呈現(xiàn)搜索結(jié)果指令文檔對結(jié)果呈現(xiàn)提出了四條硬性要求它們共同保證“可追溯、可深挖、不淹沒重點”始終附帶來源歸屬source attribution每條結(jié)果都要給出 Wing、Room以及有值時給出 Drawer/source_file讓用戶能判斷這條記憶來自哪里給出相關(guān)度 / 相似度分數(shù)如果檢索返回了分數(shù)就展示它similarity/cosine_sim/bm25多條命中時按 Wing/Room 歸組不要平鋪一長串把同一領(lǐng)域的命中原樣歸并展示便于用戶按域瀏覽清晰引用或概括記憶內(nèi)容優(yōu)先直接引用原文MemPalace 的搜索契約就是返回 verbatim 原文確實過長時給出忠實概括而不是夾帶模型推測。6.1 CLI 的結(jié)果排版模板搜索引擎 searcher.py 在 CLI 路徑下使用如下排版可作為呈現(xiàn)層參考——每條命中都帶序號、歸屬路徑、來源文件名、相似度與 BM25 分數(shù)、逐行縮進的原文 Results for: auth decisions Wing: myapp Room: auth [1] myapp / auth-migration Source: session_2026-01-15.md Match: cosine_sim0.892 bm251.7 We decided to migrate auth to Clerk because... --------------------------------------------------------七、第六步給出后續(xù)動作Next Steps搜索往往不是終點。呈現(xiàn)結(jié)果后指令建議向用戶提供這些“深入一層”的選項全部有對應(yīng)的 MCP 工具支撐Drill deeper鉆取——在某個具體 Room 內(nèi)繼續(xù)搜或收窄查詢詞用mempalace_search加wing/room重跑Traverse圖漫游——從相關(guān) Room 出發(fā)探索知識圖譜上的關(guān)聯(lián)記憶mempalace_traverse(start_room, max_hops)默認 2 跳Check tunnels檢查隧道——如果話題跨領(lǐng)域查找兩個 Wing 之間的顯式跨域連接mempalace_find_tunnels例如一個項目的 API 設(shè)計與另一個項目的數(shù)據(jù)庫 schema 在圖上被顯式“打通”Browse taxonomy瀏覽分類樹——展示完整結(jié)構(gòu)供用戶手動瀏覽mempalace_get_taxonomy。這一層設(shè)計把“檢索”升級為“檢索—探索”閉環(huán)純文本命中之外用戶還能順著圖譜關(guān)系發(fā)現(xiàn)原本沒想到的相鄰記憶。八、原理縱深混合檢索如何工作搜索指令是操作層而操作背后的檢索質(zhì)量由 searcher.py 的混合檢索架構(gòu)支撐。以下幾點是“呈現(xiàn)相似度、解釋命中原因”時必須理解的事實8.1 Drawer 檢索是地板Closet 只是排名信號模塊文檔明確寫下設(shè)計原則drawer query直接檢索記憶永遠運行作為兜底地板closet主題抽取文檔命中只是在它們“與 drawer 命中一致”時按排名加分。Closet 是排名信號ranking signal永遠不是門禁never a gate——這避免了“弱 closet 回歸”敘述性內(nèi)容抽取出的低信號 closet 可能掩蓋直接檢索本應(yīng)命中的 Drawer。在search_memories的實現(xiàn)里boost 表按source_file建立命中的 drawer 若來自同一個有 closet 命中的源文件會依據(jù) closet 排名獲得階梯加分源碼中 rank-based boost 序列為[0.40, 0.25, 0.15, 0.08, 0.04]余弦距離超過 1.5 的弱 closet 不會被采信。8.2 向量相似度 BM25 關(guān)鍵詞的聯(lián)合重排即便在“純向量”的默認路徑下最終排序也是混合的_hybrid_rank用向量相似度權(quán)重 0.6與 Okapi-BM25 關(guān)鍵詞得分權(quán)重 0.4的凸組合對候選集重排。BM25 的 IDF 是在當前候選集內(nèi)計算并做 min-max 歸一化因此兩路分數(shù)可比較同分時按authored_at更新的排前。這是為什么 CLI 命中行會同時打印cosine_sim與bm25兩列。8.3 從距離到相似度的換算后端返回的原始字段是“距離”distance語義為越小越近與具體度量無關(guān)這一契約來自 RFC 001 的后端度量聲明相關(guān)規(guī)范可見 docs/rfcs/001-storage-backend-plugin-spec.md。展示給用戶的similarity是換算后的 [0,1] 值cosine默認similarity max(0, 1 - distance)l2歐氏距離1 / (1 distance)ip內(nèi)積logistic 壓縮1 / (1 e^distance)。_distance_to_similarity與_metric_for_collection在 searcher.py 中實現(xiàn)后者會讀取后端集合聲明的distance_metric取不到時回退為cosine。8.4 候選策略與降級路徑search_memories的candidate_strategy參數(shù)默認vector決定混合重排的候選池來源默認取向量索引前n_results × 4行union模式會額外拉取前n_results × 3條詞法候選并入池中按 source_file 去重從而捕獲“與查詢在向量空間很遠、但 BM25 信號極強”的機械性文檔目錄清單、diff、日志片段等。此外若 HNSW 向量段與 SQLite 元數(shù)據(jù)出現(xiàn)分歧會導致原生崩潰服務(wù)端會把vector_disabledTrue傳入讓檢索自動降級為直接讀 chroma.sqlite3 的 BM25-only 路徑經(jīng)由 chromadb 自帶的 FTS5 trigram 索引取候選再套用同一套 BM25 重排并在 CLI 輸出中明確提示運行mempalace repair修復。換言之索引壞了可以降級但絕不能靜默返回與健康索引不同規(guī)則的“空結(jié)果”。九、給 Agent 的最終操作清單速查綜合指令文檔與上述源碼事實一次規(guī)范的記憶檢索可以收斂為以下動作序列解析抽出語義查詢詞 候選 Wing/Room 過濾器確認作用域能確定分類就用--wing/--room或wing/room參數(shù)收窄不確定就全局檢索絕不亂猜分類名主檢索MCP 可用 →mempalace_search(query, wing, room)MCP 不可用 →mempalace search query [--wing X] [--room Y]結(jié)構(gòu)探查按需mempalace_list_wings/mempalace_list_rooms/mempalace_get_taxonomy呈現(xiàn)逐條標注 wing / room / source_file附相似度按域歸組優(yōu)先引用原文延伸根據(jù)用戶意圖提供鉆取、圖漫游traverse、跨域隧道tunnels或分類瀏覽。上述每一步都可以在倉庫中找到對應(yīng)實現(xiàn)或規(guī)程文檔——指令本體在 mempalace/instructions/search.md命令觸發(fā)方式見 commands/mempalace-search.mdMCP 工具的完整參數(shù) schema 見 website/reference/mcp-tools.md檢索與搜索的引擎實現(xiàn)在 mempalace/searcher.py 與 mempalace/mcp_server.py對應(yīng)的回歸測試則集中在 tests/test_searcher.py 等測試文件中。閱讀源碼時建議從search_memories()這個程序化入口入手它串聯(lián)了過濾器構(gòu)建、混合重排、closet 加分與日期窗口過濾的全部邏輯?！久赓M下載鏈接】mempalaceThe best-benchmarked open-source AI memory system. And its free.項目地址: https://gitcode.com/GitHub_Trending/me/mempalace創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考