AI Agent 在執(zhí)行復(fù)雜任務(wù)時(shí)真正限制它表現(xiàn)的往往不是單個(gè)模型的能力而是它能不能記住上下文、能不能在關(guān)鍵節(jié)點(diǎn)調(diào)出正確信息。oGMemory 記憶系統(tǒng)要解決的正是 Agent 跨會(huì)話、跨任務(wù)的記憶組織問(wèn)題而數(shù)據(jù)分支又是決定記憶系統(tǒng)能不能“用起來(lái)”的關(guān)鍵設(shè)計(jì)。這一期分集把視線聚焦在記憶系統(tǒng)與數(shù)據(jù)分支上先講清楚數(shù)據(jù)分支為什么存在再給出一套可以落地的最小實(shí)現(xiàn)。很多項(xiàng)目在最初接入記憶能力時(shí)通常的做法是“對(duì)話結(jié)束后把文本塞進(jìn)向量庫(kù)下次檢索再查出來(lái)”。這個(gè)思路在 Demo 階段可行但一旦進(jìn)入真實(shí)業(yè)務(wù)就會(huì)出現(xiàn)一個(gè)典型問(wèn)題所有記憶混在一起用戶偏好、任務(wù)記錄、知識(shí)沉淀、短期上下文全部堆在同一個(gè)集合里。寫(xiě)入越久檢索噪聲越大Agent 越來(lái)越難分辨哪條信息是當(dāng)前任務(wù)該用的。數(shù)據(jù)分支的作用就是按業(yè)務(wù)維度把這些記憶拆開(kāi)讓寫(xiě)入有明確歸屬讓檢索有明確范圍。1. 記憶系統(tǒng)到底在解決什么問(wèn)題1.1 沒(méi)有記憶的 Agent 為什么不夠用沒(méi)有記憶系統(tǒng)的 Agent本質(zhì)上是一個(gè)“每次對(duì)話都從零開(kāi)始”的狀態(tài)機(jī)。模型本身?yè)碛杏?xùn)練階段沉淀的靜態(tài)知識(shí)但它不知道用戶上一次問(wèn)過(guò)什么、當(dāng)前任務(wù)做到哪一步、用戶偏好哪種回答風(fēng)格。對(duì)于一次性的問(wèn)答場(chǎng)景這沒(méi)有問(wèn)題但對(duì)于需要連續(xù)執(zhí)行多步任務(wù)、跨天維護(hù)用戶關(guān)系、持續(xù)沉淀團(tuán)隊(duì)知識(shí)的場(chǎng)景缺記憶就意味著每次都要用戶重新交代背景。oGMemory 這類記憶系統(tǒng)的核心目標(biāo)是給 Agent 增加一個(gè)可持續(xù)讀寫(xiě)的外部狀態(tài)層。模型本身不可變但記憶數(shù)據(jù)可以隨時(shí)間、任務(wù)、用戶不斷更新。Agent 在執(zhí)行任務(wù)前先讀取記憶執(zhí)行過(guò)程中寫(xiě)入新記憶任務(wù)結(jié)束后再整理歸檔這樣它就能形成“越用越懂當(dāng)前場(chǎng)景”的能力。需要注意的是記憶不是簡(jiǎn)單地等于聊天記錄。聊天記錄是原始素材記憶系統(tǒng)要把素材加工成結(jié)構(gòu)化的、可檢索的、能按需過(guò)濾的數(shù)據(jù)。這個(gè)加工過(guò)程包括抽取主題、過(guò)濾噪聲、判定重要性、設(shè)置生命周期、分配數(shù)據(jù)分支。1.2 “能存下來(lái)”和“會(huì)用”之間的差距只把文本存進(jìn)數(shù)據(jù)庫(kù)并不是記憶系統(tǒng)。真正的記憶系統(tǒng)要處理四個(gè)連續(xù)問(wèn)題第一什么值得記。不是每一句對(duì)話都值得寫(xiě)入長(zhǎng)期記憶。寒暄、臨時(shí)計(jì)算過(guò)程、重復(fù)確認(rèn)信息都應(yīng)該被過(guò)濾掉。真正值得記的是用戶偏好、事實(shí)結(jié)論、任務(wù)狀態(tài)、關(guān)鍵約束。第二記到哪里去。這個(gè)問(wèn)題就是數(shù)據(jù)分支要解決的。不同性質(zhì)的記憶需要不同的存儲(chǔ)策略比如短期會(huì)話上下文可以放在快速緩存中用戶長(zhǎng)期偏好需要進(jìn)入穩(wěn)定的關(guān)系型存儲(chǔ)或向量庫(kù)而任務(wù)執(zhí)行記錄可能需要按項(xiàng)目維度隔離。第三如何被找到。寫(xiě)入時(shí)可讀不等于檢索時(shí)可命中。檢索環(huán)節(jié)要處理相似度計(jì)算、過(guò)濾條件、排序策略、時(shí)效衰減。如果沒(méi)有分支約束檢索時(shí)會(huì)把不相關(guān)的記憶也召回導(dǎo)致上下文被污染。第四什么時(shí)候被更新或遺忘。記憶不能只增不減。當(dāng)用戶明確改變偏好、任務(wù)狀態(tài)發(fā)生流轉(zhuǎn)、數(shù)據(jù)超過(guò)保留期限時(shí)系統(tǒng)要具備更新、合并、降級(jí)、刪除能力。這四個(gè)問(wèn)題里存儲(chǔ)和檢索最容易理解但也最容易被低估。很多時(shí)候項(xiàng)目跑不起來(lái)不是因?yàn)槟Ｐ筒恍卸且驗(yàn)橛洃洈?shù)據(jù)沒(méi)有組織好導(dǎo)致 Agent 讀到了錯(cuò)誤的歷史信息。1.3 oGMemory 在其中的定位從命名和常見(jiàn)記憶系統(tǒng)設(shè)計(jì)來(lái)看oGMemory 可以理解為一條獨(dú)立的記憶數(shù)據(jù)鏈路重點(diǎn)解決 Agent 記憶的組織、存儲(chǔ)、檢索和生命周期管理。和直接在業(yè)務(wù)代碼里零散調(diào)用向量庫(kù)不同oGMemory 這類設(shè)計(jì)會(huì)把記憶系統(tǒng)抽象成獨(dú)立服務(wù)對(duì)外提供寫(xiě)入、查詢、更新、遺忘等接口讓上層 Agent 業(yè)務(wù)只關(guān)心記憶內(nèi)容不關(guān)心底層存儲(chǔ)細(xì)節(jié)。本文作為分集解讀的第一篇聚焦在數(shù)據(jù)分支這一層不展開(kāi)討論底層模型、檢索算法、遺忘機(jī)制的全部細(xì)節(jié)。讀完這一篇你能完成三件事理解記憶系統(tǒng)的整體分層掌握數(shù)據(jù)分支的劃分思路用一套最小代碼跑通“寫(xiě)入分支、按分支查詢、分支歸檔”的完整流程。2. 搭建最小記憶系統(tǒng)需要先確認(rèn)的核心組件2.1 記憶系統(tǒng)的五層結(jié)構(gòu)一個(gè)可工作的記憶系統(tǒng)通常包含五層感知層、編碼層、存儲(chǔ)層、檢索層、遺忘與合并層。數(shù)據(jù)分支主要落在存儲(chǔ)層和檢索層之間但每一層都會(huì)影響分支設(shè)計(jì)。感知層負(fù)責(zé)識(shí)別什么信息值得寫(xiě)入記憶。它可能是對(duì)話中斷言抽取、任務(wù)狀態(tài)識(shí)別、用戶行為事件接收。感知層的輸出是“一條候選記憶”這部分通常要依賴 LLM 或規(guī)則引擎完成。編碼層負(fù)責(zé)把文本轉(zhuǎn)換成可以檢索的形態(tài)。最常見(jiàn)的方式是文本向量化同時(shí)保留原文和結(jié)構(gòu)化字段。編碼層還要生成主題標(biāo)簽、時(shí)間戳、重要程度、來(lái)源標(biāo)識(shí)等元數(shù)據(jù)。存儲(chǔ)層負(fù)責(zé)持久化。向量數(shù)據(jù)進(jìn)入向量庫(kù)結(jié)構(gòu)化字段進(jìn)入關(guān)系型數(shù)據(jù)庫(kù)原始內(nèi)容可能需要對(duì)象存儲(chǔ)。數(shù)據(jù)分支在這一層體現(xiàn)為不同的集合、表或分片。檢索層負(fù)責(zé)把用戶當(dāng)前的問(wèn)題轉(zhuǎn)換成查詢條件從正確的分支中召回記憶。檢索不是只做語(yǔ)義相似度還需要結(jié)合時(shí)間范圍、用戶身份、分支類型、權(quán)限范圍等條件。遺忘與合并層負(fù)責(zé)控制記憶生命周期。它解決記憶過(guò)期、沖突覆蓋、重復(fù)合并、降級(jí)歸檔等問(wèn)題。沒(méi)有這一層記憶數(shù)據(jù)會(huì)無(wú)限膨脹檢索質(zhì)量會(huì)持續(xù)下降。2.2 組件選型和環(huán)境準(zhǔn)備記憶系統(tǒng)的選型不存在一套通用標(biāo)準(zhǔn)答案但通常會(huì)涉及以下幾類組件組件職責(zé)常見(jiàn)選型參考LLM文本理解、信息抽取、摘要生成業(yè)務(wù)現(xiàn)有的大模型服務(wù)Embedding 服務(wù)將文本轉(zhuǎn)換為向量本地嵌入模型接口或平臺(tái)嵌入服務(wù)向量庫(kù)存放向量數(shù)據(jù)支持語(yǔ)義檢索輕量可用 Chroma、生產(chǎn)環(huán)境可用 Milvus 等關(guān)系型數(shù)據(jù)庫(kù)存放記憶記錄、分支元數(shù)據(jù)、狀態(tài)SQLite 適合本地驗(yàn)證生產(chǎn)可用 PostgreSQL 等緩存存儲(chǔ)高頻訪問(wèn)的短期記憶Redis 等定時(shí)任務(wù)執(zhí)行歸檔、合并、遺忘清理APScheduler、Celery Beat 或云廠商定時(shí)任務(wù)這里要特別說(shuō)明本文的示例代碼為了保持最小可運(yùn)行使用 SQLite 存儲(chǔ)結(jié)構(gòu)化數(shù)據(jù)向量部分用一個(gè)本地 Python 列表和一個(gè)模擬的 embedding 函數(shù)代替。這樣做的目的是先把數(shù)據(jù)分支邏輯講清楚。真實(shí)項(xiàng)目接入時(shí)把 embedding 函數(shù)替換成內(nèi)部嵌入服務(wù)把向量列表遷移到向量庫(kù)即可。2.3 環(huán)境準(zhǔn)備清單在開(kāi)始寫(xiě)代碼之前先確認(rèn)本機(jī)環(huán)境滿足以下條件Python 3.10 或更高版本已安裝 FastAPI 和 uvicorn已安裝 SQLite3 驅(qū)動(dòng)Python 自帶的 sqlite3 就夠用已安裝 pandas 或直接使用 Python 標(biāo)準(zhǔn)庫(kù)處理數(shù)據(jù)一個(gè)可用的 embedding 函數(shù)開(kāi)發(fā)階段可以用隨機(jī)向量模擬但驗(yàn)證階段建議接入真實(shí)嵌入服務(wù)如果原始項(xiàng)目沒(méi)有明確版本落地前務(wù)必先確認(rèn)依賴版本和 Python 版本兼容性。這里給出一個(gè) requirements 示例fastapi0.110.0 uvicorn0.29.0 pydantic2.6.0 numpy1.26.4 apscheduler3.10.4注意版本號(hào)只是參考。實(shí)際項(xiàng)目如果使用已有依賴鎖文件以倉(cāng)庫(kù)中的版本為準(zhǔn)不要直接復(fù)制最新版本號(hào)到生產(chǎn)環(huán)境。3. 數(shù)據(jù)分支是什么為什么記憶系統(tǒng)離不開(kāi)它3.1 數(shù)據(jù)分支的定義數(shù)據(jù)分支是指按照某種業(yè)務(wù)維度把記憶數(shù)據(jù)劃分成不同的邏輯通道。每個(gè)通道擁有獨(dú)立的寫(xiě)入規(guī)則、存儲(chǔ)位置、檢索范圍和生命周期策略?？梢园褦?shù)據(jù)分支理解成“記憶的分類目錄”。沒(méi)有分類目錄時(shí)所有記憶是一條無(wú)序的長(zhǎng)河有了分類目錄后寫(xiě)入時(shí)先判斷這條記憶屬于哪個(gè)分類檢索時(shí)只從對(duì)應(yīng)分類中查找效率和準(zhǔn)確率都會(huì)明顯提升。在 oGMemory 這類 Agent 記憶系統(tǒng)中分支不是一個(gè)可有可無(wú)的優(yōu)化項(xiàng)而是決定記憶能否被正確使用的關(guān)鍵設(shè)計(jì)。原因是 Agent 的記憶數(shù)據(jù)天然帶有強(qiáng)烈的“上下文依賴”特征。用戶說(shuō)“我喜歡簡(jiǎn)潔的回答”這是一條偏好記憶用戶說(shuō)“項(xiàng)目 A 的數(shù)據(jù)庫(kù)連接串已經(jīng)改好了”這是一條任務(wù)事件記憶用戶說(shuō)“本周五要上線”這是一條計(jì)劃記憶。這三者的使用場(chǎng)景完全不同混在一起存儲(chǔ)檢索時(shí)很難一次性命中正確信息。3.2 常見(jiàn)分支維度實(shí)際項(xiàng)目中記憶系統(tǒng)通常不會(huì)只使用一個(gè)分支維度而是幾個(gè)維度組合使用。常用維度包括分支維度說(shuō)明示例按時(shí)間區(qū)分短期上下文、中期工作記憶、長(zhǎng)期沉淀short_term、mid_term、long_term按來(lái)源區(qū)分用戶提供、Agent 推導(dǎo)、系統(tǒng)事件、外部知識(shí)user、agent、system、knowledge按類型區(qū)分事實(shí)、偏好、事件、技能、約束fact、preference、event、skill、constraint按業(yè)務(wù)域區(qū)分不同項(xiàng)目、不同知識(shí)庫(kù)、不同團(tuán)隊(duì)project_a、project_b、wiki_base按生命周期區(qū)分活躍、候選歸檔、已過(guò)期、廢棄active、archived、expired、trashed分支維度的選擇不是越多越好。每增加一個(gè)維度寫(xiě)入時(shí)的路由判斷就更復(fù)雜檢索時(shí)的過(guò)濾條件也更多運(yùn)維成本會(huì)指數(shù)上升。多數(shù)中小型記憶系統(tǒng)從“來(lái)源 類型 時(shí)間”三個(gè)維度起步就足夠之后根據(jù)真實(shí)檢索效果再細(xì)化。3.3 數(shù)據(jù)分支與分庫(kù)分表的區(qū)別數(shù)據(jù)分支容易被誤解成“分庫(kù)分表”但它們解決的問(wèn)題不同。分庫(kù)分表解決的是存儲(chǔ)容量和寫(xiě)入性能問(wèn)題。當(dāng)單表數(shù)據(jù)量達(dá)到千萬(wàn)級(jí)索引失效、寫(xiě)入變慢這時(shí)需要把數(shù)據(jù)按照哈?；蚍秶稚⒌蕉鄠€(gè)物理存儲(chǔ)中。分庫(kù)分表是物理層的伸縮方案對(duì)業(yè)務(wù)透明上層 SQL 大多數(shù)情況下不應(yīng)該感知到分片邏輯。數(shù)據(jù)分支解決的是語(yǔ)義隔離和檢索范圍問(wèn)題。它強(qiáng)調(diào)“哪些記憶屬于哪個(gè)業(yè)務(wù)范圍”是邏輯層的分類設(shè)計(jì)。即使數(shù)據(jù)量很小也需要做數(shù)據(jù)分支否則 Agent 會(huì)在兩三百條記憶里被噪聲干擾。兩者可以疊加使用。先按業(yè)務(wù)維度做數(shù)據(jù)分支再在數(shù)據(jù)量增長(zhǎng)后按哈希規(guī)則分片是常見(jiàn)的生產(chǎn)架構(gòu)。實(shí)現(xiàn)時(shí)要注意分支規(guī)則代碼和分片路由代碼不要混在同一個(gè)函數(shù)里否則排查問(wèn)題時(shí)很難定位。4. 用 Python 實(shí)現(xiàn)一個(gè)帶數(shù)據(jù)分支的最小記憶服務(wù)4.1 項(xiàng)目結(jié)構(gòu)下面這個(gè)項(xiàng)目結(jié)構(gòu)適用于本地驗(yàn)證和最小 Demoogmemory_demo/ ├── app.py # FastAPI 入口 ├── memory_core.py # 記憶寫(xiě)入、檢索、路由核心邏輯 ├── storage.py # SQLite 初始化與數(shù)據(jù)訪問(wèn) ├── branch_rules.py # 分支路由規(guī)則 ├── models.py # Pydantic 數(shù)據(jù)模型 ├── requirements.txt # 依賴清單 └── data/ └── memory.db # SQLite 數(shù)據(jù)庫(kù)文件這個(gè)結(jié)構(gòu)把路由規(guī)則、存儲(chǔ)訪問(wèn)、核心邏輯分開(kāi)目的是讓每個(gè)模塊職責(zé)單一。后續(xù)如果要替換向量庫(kù)只需改動(dòng) storage.py 和 memory_core.py 中的向量相關(guān)部分分支規(guī)則不需要?jiǎng)印?.2 數(shù)據(jù)模型設(shè)計(jì)記憶系統(tǒng)的核心表是 memory_record 表。它既保存原始文本也保存結(jié)構(gòu)化元數(shù)據(jù)同時(shí)通過(guò) memory_embedding 表關(guān)聯(lián)向量數(shù)據(jù)。CREATE TABLE IF NOT EXISTS memory_record ( memory_id TEXT PRIMARY KEY, user_id TEXT NOT NULL, branch_type TEXT NOT NULL, memory_type TEXT NOT NULL, source TEXT NOT NULL, content TEXT NOT NULL, importance REAL DEFAULT 0.5, status TEXT DEFAULT active, merged_from TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, expire_at TEXT ); CREATE TABLE IF NOT EXISTS memory_embedding ( memory_id TEXT PRIMARY KEY, vector TEXT NOT NULL, model_name TEXT, updated_at TEXT NOT NULL ); CREATE INDEX IF NOT EXISTS idx_memory_branch ON memory_record(user_id, branch_type, status);字段含義說(shuō)明字段含義memory_id記憶唯一標(biāo)識(shí)建議用 UUIDuser_id記憶歸屬用戶多用戶場(chǎng)景必須隔離branch_type數(shù)據(jù)分支例如 user_preference、task_eventmemory_type記憶類型例如 fact、preference、eventsource來(lái)源例如 user、agent、systemcontent記憶原始內(nèi)容importance重要程度0 到 1影響后續(xù)遺忘優(yōu)先級(jí)status狀態(tài)active、archived、expired、trashedmerged_from如果該記錄由多條記憶合并而來(lái)記錄來(lái)源 IDcreated_at / updated_at時(shí)間字段統(tǒng)一使用 UTC ISO 格式expire_at過(guò)期時(shí)間過(guò)期后進(jìn)入遺忘候選這里要注意時(shí)間字段統(tǒng)一使用 UTC不要使用本地時(shí)間。否則跨時(shí)區(qū)部署時(shí)分支按時(shí)間歸檔會(huì)出現(xiàn)錯(cuò)位問(wèn)題。4.3 寫(xiě)入流程中的分支路由記憶寫(xiě)入時(shí)系統(tǒng)先判斷這條記憶應(yīng)該進(jìn)入哪個(gè)分支再執(zhí)行存儲(chǔ)。分支路由不只是一個(gè)字段賦值它可能影響后續(xù)的索引、召回策略和過(guò)期策略。下面是一個(gè)分支路由規(guī)則示例# branch_rules.py def route_branch(source: str, memory_type: str, content: str) - str: if source user and memory_type preference: return user_preference if memory_type event: return task_event if memory_type fact and len(content) 50: return long_term_knowledge if memory_type fact: return short_term_fact return general_memory這個(gè)示例展示了最基礎(chǔ)的關(guān)鍵詞維度路由。更復(fù)雜的項(xiàng)目可以使用 LLM 抽取結(jié)果來(lái)決定分支。比如先讓模型輸出{ source: user, memory_type: preference, importance: 0.9 }再交給路由函數(shù)判斷。寫(xiě)入核心邏輯import uuid from datetime import datetime, timedelta, timezone def write_memory(user_id, source, memory_type, content, importance0.5): branch route_branch(source, memory_type, content) memory_id str(uuid.uuid4()) now datetime.now(timezone.utc) expire_at now timedelta(days30) if branch in (user_preference, long_term_knowledge): expire_at now timedelta(days365) record { memory_id: memory_id, user_id: user_id, branch_type: branch, memory_type: memory_type, source: source, content: content, importance: importance, status: active, created_at: now.isoformat(), updated_at: now.isoformat(), expire_at: expire_at.isoformat() } save_memory_record(record) vector get_embedding(content) save_memory_embedding(memory_id, vector) return record值得關(guān)注的是route_branch這個(gè)函數(shù)。它是數(shù)據(jù)分支的唯一決策點(diǎn)所有記憶寫(xiě)入都必須經(jīng)過(guò)它。這樣設(shè)計(jì)的好處是當(dāng)業(yè)務(wù)需要調(diào)整分支規(guī)則時(shí)只改一個(gè)文件就能生效不需要在多個(gè)業(yè)務(wù)調(diào)用點(diǎn)里尋找散落的分支判斷。4.4 檢索流程中的分支過(guò)濾檢索時(shí)的核心原則是先限定分支范圍再做語(yǔ)義召回。如果沒(méi)有指定分支系統(tǒng)應(yīng)該使用默認(rèn)分支或“全分支限權(quán)檢索”而不是直接不做過(guò)濾地全局搜索。def search_memory(user_id, query, branch_listNone, top_k5): if branch_list is None: branch_list [user_preference, task_event, short_term_fact] where_conditions [user_id ?, status active] params [user_id] if branch_list: placeholders ,.join(? for _ in branch_list) where_conditions.append(fbranch_type IN ({placeholders})) params.extend(branch_list) sql fSELECT memory_id, content, branch_type, importance FROM memory_record WHERE { AND .join(where_conditions)} ORDER BY importance DESC, updated_at DESC LIMIT ? # 先按 SQL 條件過(guò)濾候選集 candidates query_memory_record(sql, params [top_k * 10]) # 再對(duì)候選集做向量相似度排序 query_vec get_embedding(query) ranked [] for record in candidates: emb load_embedding(record[memory_id]) score cosine_similarity(query_vec, emb) ranked.append({**record, score: score}) ranked.sort(keylambda x: x[score], reverseTrue) return ranked[:top_k]這里的實(shí)現(xiàn)順序是先通過(guò)結(jié)構(gòu)化條件縮小候選集再做向量檢索。不要反過(guò)來(lái)否則每次查詢都會(huì)在全量向量庫(kù)中做相似度計(jì)算數(shù)據(jù)量上來(lái)后延遲會(huì)明顯增加。4.5 分支合并與歸檔策略記憶系統(tǒng)不能只有寫(xiě)入和檢索還需要定時(shí)處理分支中的數(shù)據(jù)狀態(tài)。合并解決的是重復(fù)記憶問(wèn)題歸檔解決的是數(shù)據(jù)膨脹問(wèn)題。合并策略通常按以下規(guī)則處理同一用戶在同一個(gè)分支下短期重復(fù)出現(xiàn)相似內(nèi)容新記憶的重要性高于舊記憶舊記憶已經(jīng)連續(xù)多次未被檢索命中歸檔策略按時(shí)間觸發(fā)def archive_expired_memories(): now datetime.now(timezone.utc).isoformat() sql UPDATE memory_record SET status archived, updated_at ? WHERE status active AND expire_at ? execute_update(sql, [now, now])這段代碼用于把所有過(guò)期且仍處于 active 狀態(tài)的記憶改成 archived。實(shí)際生產(chǎn)環(huán)境中expired 狀態(tài)和 archived 狀態(tài)可以分開(kāi)處理expired 表示不再參與檢索archived 表示仍然保留但降級(jí)為低頻訪問(wèn)。不要在同一個(gè)狀態(tài)里混用否則統(tǒng)計(jì)時(shí)很難區(qū)分。5. 關(guān)鍵參數(shù)和設(shè)計(jì)取舍5.1 分支數(shù)量應(yīng)該怎么控制數(shù)據(jù)分支數(shù)量是一個(gè)典型的取舍問(wèn)題。分支太少記憶混在一起檢索噪聲大分支太多路由規(guī)則復(fù)雜調(diào)用方需要記住一堆分支名運(yùn)維維護(hù)成本也高。分支數(shù)量?jī)?yōu)點(diǎn)缺點(diǎn)適用場(chǎng)景3 到 5 個(gè)路由簡(jiǎn)單、檢索穩(wěn)定粒度較粗某些場(chǎng)景仍有噪聲個(gè)人助手、小型業(yè)務(wù)6 到 15 個(gè)語(yǔ)義隔離清晰需要維護(hù)路由規(guī)則和使用文檔中型團(tuán)隊(duì)知識(shí)庫(kù)、多項(xiàng)目 Agent15 個(gè)以上高度隔離路由復(fù)雜分支管理和監(jiān)控成本高大型組織、強(qiáng)權(quán)限隔離場(chǎng)景推薦做法是先用少量分支跑通完整鏈路觀察檢索命中率。當(dāng)出現(xiàn)“檢索結(jié)果混雜無(wú)關(guān)記憶”時(shí)再根據(jù)失敗樣本拆分新分支。5.2 記憶系統(tǒng)關(guān)鍵參數(shù)速查表參數(shù)常見(jiàn)值影響錯(cuò)誤表現(xiàn)top_k5 到 10返回記憶條數(shù)過(guò)大易引入噪聲Agent 上下文被無(wú)關(guān)信息擠占score_threshold0.6 到 0.8低于閾值的結(jié)果不返回返回不相關(guān)內(nèi)容檢索質(zhì)量下降importance0 到 1排序權(quán)重重要記憶優(yōu)先低價(jià)值記憶長(zhǎng)期占坑expire_after_days30 到 365控制記憶自然過(guò)期時(shí)間過(guò)期太短丟失有用信息太長(zhǎng)數(shù)據(jù)膨脹merge_interval_seconds3600 到 86400控制去重合并頻率過(guò)高增加計(jì)算成本過(guò)低導(dǎo)致重復(fù)記憶殘留branch_list 默認(rèn)值3 個(gè)核心分支未指定分支時(shí)的候選范圍誤查全局導(dǎo)致權(quán)限混雜或噪聲大這里要強(qiáng)調(diào)score_threshold 不是越高越好。設(shè)置太高時(shí)真正有用的記憶可能因?yàn)楸硎霾町惐贿^(guò)濾掉設(shè)置太低時(shí)大量低相關(guān)記憶進(jìn)入上下文模型反而更糊涂。建議在測(cè)試集上統(tǒng)計(jì)相似度分布后再確定閾值。5.3 語(yǔ)義分支與向量集合的關(guān)系數(shù)據(jù)分支落到存儲(chǔ)層有兩種主流實(shí)現(xiàn)方式。第一種是一個(gè)分支對(duì)應(yīng)一個(gè)獨(dú)立向量集合。優(yōu)點(diǎn)是隔離徹底分支之間互不影響權(quán)限控制容易缺點(diǎn)是跨分支檢索時(shí)需要逐個(gè)集合查詢?cè)俸喜⒔Y(jié)果實(shí)現(xiàn)相對(duì)復(fù)雜。第二種是統(tǒng)一向量集合通過(guò) metadata 字段中的 branch_type 標(biāo)簽過(guò)濾。優(yōu)點(diǎn)是實(shí)現(xiàn)簡(jiǎn)單一次查詢可以同時(shí)支持單分支和多分支缺點(diǎn)是數(shù)據(jù)量增大后過(guò)濾條件對(duì)向量檢索的效率影響需要評(píng)估。兩種方式的代碼差異主要體現(xiàn)在存儲(chǔ)和檢索兩個(gè)環(huán)節(jié)。使用第二種方式時(shí)寫(xiě)入向量時(shí)需要附帶 metadata{ id: memory_id_1, vector: [0.1, 0.2, 0.3], metadata: { user_id: user_001, branch_type: user_preference, memory_type: preference } }檢索時(shí)在向量查詢請(qǐng)求中帶上 filter 條件{ query: [0.1, 0.2, 0.3], limit: 5, filter: { user_id: user_001, branch_type: user_preference } }選擇哪種實(shí)現(xiàn)取決于數(shù)據(jù)規(guī)模和是否需要嚴(yán)格的物理隔離。個(gè)人項(xiàng)目和小型團(tuán)隊(duì)建議用第二種復(fù)雜度低最容易落地。6. 運(yùn)行驗(yàn)證從寫(xiě)入到分支查詢6.1 啟動(dòng)最小服務(wù)這里使用 FastAPI 提供 HTTP 接口便于驗(yàn)證完整流程。啟動(dòng)命令如下uvicorn app:app --host 0.0.0.0 --port 8000啟動(dòng)成功后終端會(huì)輸出 uvicorn 的運(yùn)行地址。此時(shí)可以訪問(wèn)http://127.0.0.1:8000/docs查看接口文檔。這一步確認(rèn)服務(wù)本身沒(méi)有報(bào)錯(cuò)。6.2 寫(xiě)入不同分支的數(shù)據(jù)寫(xiě)入接口請(qǐng)求示例POST /memories { user_id: user_001, source: user, memory_type: preference, content: 用戶喜歡簡(jiǎn)潔的技術(shù)方案不喜歡長(zhǎng)篇大論, importance: 0.9 }返回結(jié)果中應(yīng)包含 branch_type 字段值為user_preference。這就是路由函數(shù)生效的驗(yàn)證。再寫(xiě)入一條任務(wù)事件POST /memories { user_id: user_001, source: agent, memory_type: event, content: 用戶在今天 14:00 確認(rèn)了訂單系統(tǒng)的數(shù)據(jù)庫(kù)選型, importance: 0.7 }返回結(jié)果中 branch_type 應(yīng)改為task_event。兩條數(shù)據(jù)屬于不同分支證明路由規(guī)則正常工作。6.3 驗(yàn)證分支過(guò)濾查詢查詢接口請(qǐng)求示例GET /memories?user_iduser_001branch_typeuser_preferencequery喜歡簡(jiǎn)潔方案正常結(jié)果應(yīng)該只返回 user_preference 分支中的記憶不返回 task_event 分支中的內(nèi)容。如果查詢時(shí)不傳 branch_type只傳 user_id則確認(rèn)默認(rèn)分支邏輯是否生效GET /memories?user_iduser_001query訂單系統(tǒng)這里要注意觀察返回結(jié)果是否同時(shí)包含 user_preference 和 task_event 分支的數(shù)據(jù)。如果只返回一個(gè)分支需要回頭檢查search_memory中的默認(rèn) branch_list 配置。6.4 驗(yàn)證歸檔與遺忘手動(dòng)執(zhí)行歸檔函數(shù)驗(yàn)證python -c from memory_core import archive_expired_memories; archive_expired_memories()然后在數(shù)據(jù)庫(kù)里檢查狀態(tài)變化SELECT memory_id, branch_type, status, expire_at FROM memory_record WHERE user_id user_001;正常情況下未過(guò)期的記錄仍是 active已過(guò)期記錄變成 archived。如果所有記錄都變成 archived說(shuō)明寫(xiě)入時(shí) expire_at 計(jì)算用的時(shí)間基準(zhǔn)有問(wèn)題檢查是否使用了錯(cuò)誤的時(shí)區(qū)或者過(guò)期時(shí)間被設(shè)置成當(dāng)前時(shí)間之前。7. 常見(jiàn)問(wèn)題排查7.1 寫(xiě)入后檢索不到可能原因有很多按順序排查寫(xiě)入時(shí) route_branch 返回的分支與查詢時(shí)傳入的 branch_type 不一致。向量數(shù)據(jù)沒(méi)有保存成功memory_embedding 表缺少記錄。查詢時(shí)的 user_id 與寫(xiě)入時(shí)的 user_id 不一致。score_threshold 設(shè)置過(guò)高導(dǎo)致相似度低于閾值的結(jié)果被丟棄。數(shù)據(jù)狀態(tài)不是 active而是 archived、expired 或 trashed。推薦檢查方式先不看向量直接用 SQL 查詢 memory_record 表確認(rèn)記錄存在且 status 為 active。然后再確認(rèn) query 中傳入的過(guò)濾條件是否包含該記錄的分支。7.2 新記憶覆蓋了舊記憶現(xiàn)象是用戶修改偏好后新記錄寫(xiě)入舊記錄仍然存在但 Agent 仍然會(huì)讀到舊記錄。原因是寫(xiě)入新記憶時(shí)沒(méi)有處理舊記憶的沖突舊記錄仍處于 active 狀態(tài)。處理方式在寫(xiě)入相同分支、相同 type 的新記憶時(shí)先將舊記憶的狀態(tài)改為 superseded。增加 version 字段記錄同主題記憶的先后版本。需要支持歷史回溯時(shí)不物理刪除舊記錄只改變狀態(tài)。推薦做法是給 memory_record 增加一個(gè) topic_key 字段用來(lái)標(biāo)識(shí)“同一主題”。寫(xiě)入時(shí)先查詢相同 topic_key 的記錄如果存在新版本就把舊版本置為更新?tīng)顟B(tài)。7.3 表數(shù)據(jù)膨脹后查詢變慢當(dāng) memory_record 表數(shù)據(jù)量持續(xù)增長(zhǎng)即使加了索引查詢也可能變慢。檢查方向是否按 user_id 和 branch_type 建立了聯(lián)合索引。是否定時(shí)執(zhí)行了歸檔任務(wù)active 數(shù)據(jù)是否被控制在合理范圍。向量檢索是否在 SQL 過(guò)濾之后執(zhí)行而不是先全量向量搜索再過(guò)濾。如果 SQLite 單表數(shù)據(jù)量已經(jīng)超過(guò)百萬(wàn)行建議把結(jié)構(gòu)化數(shù)據(jù)遷移到 PostgreSQL把向量數(shù)據(jù)遷移到專業(yè)向量庫(kù)避免在單個(gè)文件數(shù)據(jù)庫(kù)上硬扛大數(shù)據(jù)量。7.4 時(shí)間分支錯(cuò)亂現(xiàn)象是按天歸檔時(shí)部分?jǐn)?shù)據(jù)被歸入錯(cuò)誤日期或過(guò)期時(shí)間判斷錯(cuò)誤。常見(jiàn)原因是時(shí)區(qū)不統(tǒng)一。有的服務(wù)使用本地時(shí)間寫(xiě)入另一個(gè)服務(wù)使用 UTC 讀取導(dǎo)致expire_at和當(dāng)前時(shí)間比較時(shí)出現(xiàn)偏差。排查時(shí)先確認(rèn)所有時(shí)間字段是否統(tǒng)一使用 UTC ISO 格式再確認(rèn)寫(xiě)入時(shí)datetime.now(timezone.utc)是否被誤寫(xiě)成datetime.now()。問(wèn)題現(xiàn)象常見(jiàn)原因檢查方式處理建議寫(xiě)入后檢索不到分支條件不一致或向量缺失先查 SQL 再查向量表統(tǒng)一分支命名增加寫(xiě)入日志新記憶覆蓋舊記憶失敗未處理主題沖突檢查 topic_key 查詢邏輯寫(xiě)入前先查同主題 active 記錄查詢變慢沒(méi)有及時(shí)歸檔或索引缺失查看 SQL 執(zhí)行計(jì)劃增加組合索引定期運(yùn)行歸檔任務(wù)時(shí)間分支錯(cuò)亂時(shí)區(qū)混用檢查數(shù)據(jù)庫(kù)時(shí)間值全部改為 UTC 存儲(chǔ)8. 最佳實(shí)踐與擴(kuò)展方向8.1 學(xué)習(xí)環(huán)境和生產(chǎn)環(huán)境的差異本地 Demo 可以接受 SQLite 和模擬 embedding但生產(chǎn)環(huán)境不能這樣簡(jiǎn)單處理。層面本地驗(yàn)證環(huán)境生產(chǎn)環(huán)境存儲(chǔ)SQLitePostgreSQL 或其他關(guān)系數(shù)據(jù)庫(kù)向量檢索Python 列表遍歷專用向量庫(kù)支持索引和分片嵌入服務(wù)模擬向量?jī)?nèi)部嵌入服務(wù)需監(jiān)控穩(wěn)定性和限流定時(shí)任務(wù)手動(dòng)執(zhí)行腳本獨(dú)立調(diào)度服務(wù)記錄執(zhí)行日志鑒權(quán)無(wú)接口鑒權(quán)、用戶數(shù)據(jù)隔離、操作審計(jì)配置寫(xiě)死在代碼配置中心或環(huán)境變量外置在生產(chǎn)環(huán)境上線記憶系統(tǒng)前至少要補(bǔ)齊日志、監(jiān)控、權(quán)限、回滾和數(shù)據(jù)備份這幾項(xiàng)。記憶數(shù)據(jù)是 Agent 行為的上下文依據(jù)丟失或?qū)戝e(cuò)都會(huì)直接影響業(yè)務(wù)結(jié)果。8.2 生產(chǎn)環(huán)境必須補(bǔ)齊的保障記憶寫(xiě)入接口需要增加調(diào)用方標(biāo)識(shí)、操作審計(jì)和實(shí)施限流。不能讓任意客戶端無(wú)限寫(xiě)入否則惡意調(diào)用可能撐爆存儲(chǔ)。批量任務(wù)要重試和告警。歸檔、合并、遺忘任務(wù)如果失敗不能靜默結(jié)束應(yīng)該記錄失敗原因并觸發(fā)告警否則數(shù)據(jù)會(huì)持續(xù)膨脹。數(shù)據(jù)備份策略要區(qū)分全量備份和增量備份。向量數(shù)據(jù)也要納入備份范圍不能只備份關(guān)系型數(shù)據(jù)庫(kù)。更重要的是要建立記憶回滾能力。當(dāng)一次批量記憶更新導(dǎo)致 Agent 行為異常時(shí)能按分支、按用戶、按時(shí)間段回滾到歷史狀態(tài)。這個(gè)能力在設(shè)計(jì)階段就要預(yù)留不能在事故發(fā)生后靠手工改庫(kù)。8.3 下一步可以怎么擴(kuò)展數(shù)據(jù)分支是記憶系統(tǒng)的基礎(chǔ)能力下一步可以考慮以下方向。第一接入知識(shí)圖譜。將 fact 類型記憶抽取為實(shí)體和關(guān)系用圖結(jié)構(gòu)支撐多跳推理。數(shù)據(jù)分支可以按實(shí)體所屬領(lǐng)域劃分例如產(chǎn)品域、技術(shù)域、用戶域。第二實(shí)現(xiàn)分級(jí)遺忘機(jī)制。根據(jù)重要程度、訪問(wèn)頻率、最后一次使用時(shí)間綜合計(jì)算記憶熱度熱度低的記憶先進(jìn)入候選歸檔列表由人工或規(guī)則確認(rèn)后刪除。第三支持多 Agent 共享記憶。在 user_id 之上增加 agent_id、team_id 維度讓一個(gè)團(tuán)隊(duì)的多個(gè) Agent 共享知識(shí)但用戶私有記憶仍然保持隔離。這一步需要更細(xì)的權(quán)限模型。第四建立記憶反饋閉環(huán)。當(dāng)用戶對(duì) Agent 的回答給出負(fù)面反饋時(shí)回查命中的記憶數(shù)據(jù)分析是否記憶本身不準(zhǔn)確。這樣可以把數(shù)據(jù)分支與模型評(píng)估系統(tǒng)連接起來(lái)。對(duì)新手來(lái)說(shuō)最有價(jià)值的練習(xí)不是直接接入完整框架而是先手寫(xiě)一遍最小的記憶寫(xiě)入、分支路由、查詢和歸檔流程把數(shù)據(jù)模型和狀態(tài)流轉(zhuǎn)理解清楚再去學(xué)習(xí)向量庫(kù)和遺忘機(jī)制。數(shù)據(jù)分支看起來(lái)只是簡(jiǎn)單的字段拆分但它決定了記憶系統(tǒng)在真實(shí)業(yè)務(wù)中能不能穩(wěn)定工作。