mem recall "..." 丟進去一個查詢字串,回來八行路徑。這八行是怎麼排出來的?中間有沒有哪一步偷偷叫了模型?

tigerless-labs/agent-memory 的 README 說沒有:「nothing in the read path calls a model or crosses a network」。這句話我不想只收下,所以讀了原始碼,從 recall 的入口一路拆到排序公式。先講清楚界線:我只讀了程式碼,沒有安裝、沒有跑過任何一個指令,下面每一個機制都是讀出來的,不是跑出來的。讀的版本是 HEAD commit 2648ba0(committer date 2026-11-12)。

專案本身很年輕。2026-11-20 用 gh api 取的數字:4,323 顆星、MIT、22 位貢獻者、2026-09-01 建立、沒有 GitHub release。README 也自己寫了 “There is no release on PyPI yet, so install from a checkout”,badge 是 0.1.0。所以下面講的是這個 HEAD 的行為,不是哪個穩定版的承諾。

查詢字串變成什麼

最底層從這裡開始。search_index.py 把查詢字串切成 token,每個 token 加上雙引號,去重但保留順序,再用 OR 串起來,交給 SQLite 的 FTS5 當 MATCH 運算式。

1
2
tokens = query_tokens(...)
" OR ".join(f'"{token}"' for token in dict.fromkeys(tokens))

(摘自 search_index.py:31–33。)切 token 的規則在 tokenization.py:13:[0-9A-Za-z_]+,而且一律轉小寫。

OR 這個選擇值得停一下。查詢裡有五個詞,只要記憶裡出現其中一個就進候選,不要求全部命中。要多命中幾個詞才排得前面,交給 BM25 去算。把「有沒有資格」和「有多相關」拆開,是整個 recall 的第一個設計,後面會一直看到同一個切法。

資格不看分數,只看這筆記憶現在算不算數

recall.py 的檔頭只有一行:「Eligibility before relevance, then relevance × weight × recency. Zero LLM (ADR-002).」先資格,再相關度。

資格這一關不看分數,只看這筆記憶現在算不算數。沒帶 as_of 的預設呼叫,只查 active 那一組索引(索引裡有 active 和 history 兩個 surface,寫入時依記憶是否仍有效分流),而且 invalid_at 不是空的就直接跳過(recall.py:148–150)。帶了 as_of,history 也會被查進來,改用「在那個時間點有沒有效」判斷:valid_from 晚於那個時間點的排除,invalid_at 早於或等於那個時間點的也排除(recall.py:161–165)。

scope 的比對有個小地方:它比的是路徑分段前綴,path_parts[: len(scope_parts)] == scope_parts(recall.py:156–159),不是字串前綴。我的讀法是,這樣 a/b 不會誤吃到 a/bc,但這是看程式碼推的,我沒有造一個目錄去驗證。

但「先資格、後相關」講的是語意,不是函式呼叫的先後。recall() 的實際順序是:先用 FTS5 對 active surface 取回候選(recall.py:100),再呼叫 _eligible 建出合格名單(recall.py:105),最後在 _rank 裡把不在名單上的候選丟掉(recall.py:175–176)。資格判斷本身不看分數,這一點成立;但 BM25 取回發生在它前面。預設路徑下,失效的記憶因為根本沒進 active surface,所以擠不進候選;帶 as_of 時,要等候選取回之後才靠 _eligible 過濾,被濾掉的名額不會補撈。

BM25 的負號、兩倍的摘要、和每筆記憶只留一個 chunk

候選是這樣向 FTS5 取的(search_index.py:113–117、135):

1
2
3
SELECT name, kind, anchor, heading, bm25({surface}) AS rank
FROM {surface} WHERE {surface} MATCH ?
ORDER BY rank LIMIT ?

轉成相關度時,程式碼寫的是 relevance=-float(row["rank"])。SQLite 的 bm25() 回傳值越小代表越相關,所以前面要補一個負號,讓「越大越好」。讀到這裡我才注意到,這個 relevance 是原始 BM25 的尺度,沒有歸一化。

候選池的大小由 pool = limit * candidate_pool_multiplier 決定,預設 default_limit = 8、倍數 10。我的算術是每次先撈 80 個 chunk 候選,再縮成 8 筆。

一則記憶會被切成多個 chunk 建索引,有 abstract chunk 也有 body chunk。加權在這裡發生(recall.py:177、210–215):

1
weighted = candidate.relevance * self._kind_weight(candidate.kind)

abstract 乘 bm25_abstract_weight = 2.0,body 乘 bm25_body_weight = 1.0。同一則記憶有好幾個 chunk 命中時,只留加權後最大的那一個(recall.py:179–180)。所以同樣的 BM25 原始值,落在摘要 chunk 上,加權後是落在正文 chunk 上的兩倍。寫記憶的人最好把摘要寫成「別人會拿來搜的那句話」,這個加權是在獎勵這種寫法。

三個數字連乘

最後一步是最終分數(recall.py:201、207):

1
2
score = relevance * weight * recency
hits.sort(key=lambda hit: (-hit.score, hit.name))

同分時用 name 的字典序排,結果是穩定的。三個因子各自來自哪裡,整理成表:

因子 從哪來 預設值 原始碼
relevance BM25 取負號後,乘 abstract/body 加權 abstract 2.0、body 1.0 recall.py:177、210–215;config.py:61–62
weight 記憶 frontmatter 的 weight 欄 initial 1.0、floor 0.05、ceiling 5.0 recall.py:187;config.py:75–82
recency 以 updated 欄算的時間衰減 base 0.5、half-life 180 天、floor 0.25 recall.py:217–222;config.py:89–91

recency 的公式是 decayed = recency_decay_base ** (age_days / recency_half_life_days),回傳 max(recency_floor, decayed)。我照這個公式代入預設值,算了幾個年齡(只是算公式,不是跑專案):

記憶的年齡 recency
0 天 1.0
90 天 約 0.707
180 天 0.5
360 天 0.25
720 天、3650 天 0.25

360 天以後再老,都被地板釘在 0.25。一則十年前的記憶和一則一年前的記憶,在時間這個因子上拿到一樣的分數。

讓我意外的是地板的位置。recency 的地板是 0.25,weight 的地板是 0.05,差了五倍。連乘的結構下,三個因子裡任何一個很小,整個分數就很小。我的算術是,一則很舊(0.25)、weight 掉到下限(0.05)、但字面完全命中的記憶,relevance 之外還會被乘上 0.0125。這是我從預設值算出來的最壞情況,沒有拿真實資料驗證過。

weight 怎麼被加減,是 Manage 層(睡眠期整理)的工作。設定裡有 boost_step 0.5、decay_step 0.1、decay_after_days 30,但 manage.py 我沒有讀,所以那個流程我不知道。recall 本身只是讀它。

我的立場是:連乘是對的選擇,而且 weight 的地板訂得比 recency 低很多,看起來是有意的。時間是機械算出來的,不該一個人說了算,所以地板只墊在 0.25;weight 是整理層下的判斷,下到 0.05 就等於「幾乎不要再出現」。這句話有一半是推測,因為我沒看到 weight 被壓到下限的條件。如果讀了 manage.py 發現 weight 會被機械地、無差別地往下壓,我就會收回「有意」這個說法,改說這是一個需要小心的副作用。

選配的 RRF:把兩份名單合成一份

預設只有 BM25。IndexConfig.vector_enabled 預設是 False,開了之後 recall.py:106–112 會把 BM25 候選和向量候選交給 fuse_candidates,預設向量模型是 BAAI/bge-small-en-v1.5。

融合用的是 RRF(recall.py:22–49):RRF_K = 60,每個來源內某個 chunk 的貢獻是 1.0 / (RRF_K + rank),rank 從 1 起算。兩個來源加起來之後,再除以 RRF_SOURCE_COUNT / (RRF_K + 1) 歸一化,所以 relevance 落在 0 到 1。算兩個極端:兩邊都排第 1,是 (1/61 + 1/61) ÷ (2/61) = 1.0;只有一邊排第 1,是 0.5。

這裡有一個我沒有驗證的推論:純 BM25 時 relevance 是原始尺度,開了 RRF 之後是 0 到 1,兩種模式下 score 的絕對大小不同。因為最後只用來排序,我猜影響只在它和 weight、recency 相乘時的相對比重。這是讀碼的推測,沒有實際比較過兩種模式的排名差異。

中文使用者要留意預設的 tokenizer。config.py 預設 tokenizer = "ascii",而 ASCII 的 regex 抓不到中文字,我讀 query_tokens 與 to_match_query 推出來的結果是:中文查詢會得到空的 MATCH 運算式,if not expression: return [](search_index.py:110–111)。這是推論,我沒有執行驗證。設成 "cjk" 之後,索引端會用 jieba 先斷詞,查詢端 ASCII 一律保留、中文只收長度至少 2 的詞(tokenization.py:14、56);jieba 是選配依賴,安裝提示是 pip install 'agent-memory-core[cjk]'。

索引是可以整個丟掉的快取

前面講的 FTS5 索引,README 的開頭就說它是可以隨時刪掉的快取:「rm -rf .index/ && mem rebuild loses zero knowledge」,還補了一句有測試強制。那個測試我沒有去跑,這句話是 README 的說法,我只驗證了「機制上做得到」這一半。

機制上做得到的原因很樸素,在 manifest.py 和 indexer.py。每個檔案的內容算一個 sha256,取前 16 個字元(hash_prefix_length 預設 16)。同步時拿磁碟上的檔案和索引裡記的 digest 做三向比對:磁碟有、索引沒記的是 added;兩邊都有但 digest 不同的是 changed;索引有、磁碟沒有的是 removed。只有 added 加 changed 會被重新載入、重新索引,removed 的從索引移除。

最有意思的是 rebuild。indexer.py 的 docstring 寫:「Incremental by content hash; a full rebuild is the same code path.」rebuild() 的實作就是先 self._database.drop(),再呼叫 self.sync()。重建不是另一套邏輯,只是把索引清空,讓「索引什麼都沒有」這個狀態走一遍平常的增量同步。我自己讀到這裡的感覺是,這個寫法等於每次增量同步都在替重建背書,兩條路徑沒有分岔的機會。

有一個細節我自己覺得要留意:recall 的存取紀錄(access_log 表)建在同一個 SQLite 索引檔裡(database.py:83–89),而 drop() 的做法是直接把整個索引檔 unlink(database.py:124–125)。照字面讀,rebuild 之後存取紀錄會跟著歸零。這份紀錄算不算 README 所說的 knowledge,我沒查,也沒有實際重建驗證過。

換 tokenizer 也靠同一條路:tokenizer 設定變了,index 會被判定漂移(_tokenizer_drifted,indexer.py:46–47、102–110),整個丟掉重建。

拆完,反過來看它為什麼這樣設計

把五道關卡排起來:查詢變 OR 運算式、資格過濾、BM25 取負加權並每記憶留一個 chunk、(選配)RRF、三因子連乘。我讀的 recall.py、search_index.py、tokenization.py 裡,預設路徑沒有任何一步呼叫 LLM,每一步都是一個可以單獨讀、單獨改的小函式。
這也解釋了回傳形狀。README 說 recall 不會把文字貼進你的 context,它回的是 L0 list:一行摘要、檔案路徑、anchor、分數,agent 再用 mem read <name> --level outline(或 abstract、full)決定要開多深。排序只負責「哪八筆值得打開」,不負責替你讀。另外 recall 在 log=True 時,會把每個命中連同查詢寫進 AccessLog(recall.py:115–129),這份紀錄有沒有餵回 weight 的調整,我沒查,不知道。

README 的「Proof it works」有一張評測表,我只轉述,沒有重跑:在 LongMemEval-S、bounded haystack、120 個 episode 的設定下,agent-memory 是 127/240 = 52.9%,另一個對照系統 MemCore 是 86/240 = 35.8%,沒有記憶是 7/120 = 5.8%。作者自己的但書要一起帶走:haystack 限制在每個 episode 12 個 session,絕對數字不能和公開的 LongMemEval 分數比;系統對系統那一列是寫入加讀取的端到端比較,不能拆開歸功給任何一半。換句話說,這張表說不出「排序公式有多好」。

這種拆法還能拿去拆什麼

這個結構不只解 agent 的記憶。任何「查詢進來、排序出去」的系統,都可以用同一個問題拆:哪些東西是資格,哪些是相關,哪些是人或時間加進來的偏好。搜尋引擎、推薦清單、你自己寫的 RAG,把它們攤開,我猜不少也是「先篩,再算,再乘上幾個係數」的形狀(這是推測,我只拆了這一個專案),差別只在每一格填什麼。

最小的練習是用五十行 Python 把這條管線自己寫一遍:幾則帶 weight 和 updated 的 markdown、一個 FTS5 表、三個函式。寫完你會很清楚每個係數該放在哪一格,也會看到自己想偷懶時最想砍掉的是哪一步。我還沒寫,所以這裡不放結果。

我讀完還沒答案的有三件:weight 究竟在什麼條件下被壓到 0.05;log=True 寫下的紀錄有沒有被用;預設 ascii 的中文查詢,實際上是不是真的回空。這三個都得靠安裝後的實測,或讀 manage.py。

原文來源:tigerless-labs/agent-memory(README,HEAD 2648ba0,2026-11-20 取證)、packages/core/src/agent_memory/core/ 下的 recall.py、search_index.py、tokenization.py、config.py、indexer.py、manifest.py(行號依 2026-11-12 的 HEAD)