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