深度解析：基于 iii 引擎的編碼代理持久化內(nèi)存服務(wù))
agentmemory 架構(gòu)深度解析基于 iii 引擎的編碼代理持久化內(nèi)存服務(wù)【免費(fèi)下載鏈接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks項(xiàng)目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory 是一個(gè)面向 AI 編碼代理coding agents的本地持久化內(nèi)存服務(wù)器它捕獲代理工作過程中的觀測observations建立混合檢索索引再通過 REST 與 MCP 兩種面surface把記憶回放給代理。它不自己發(fā)明一套運(yùn)行時(shí)而是完整構(gòu)建在 iii 引擎之上一切能力都以函數(shù) 觸發(fā)器的形式存在。讀完本文你將掌握 agentmemory 的整體架構(gòu)骨架、iii 原語的工作方式、三流混合檢索的實(shí)現(xiàn)原理、端口布局規(guī)則以及記憶從捕獲到遺忘的完整生命周期。agentmemory 是什么一個(gè)本地內(nèi)存服務(wù)器從架構(gòu)定位看agentmemory 是一個(gè)常駐本地的內(nèi)存服務(wù)器memory server運(yùn)行鏈路由三部分組成iii 引擎iii-engine——提供進(jìn)程內(nèi)狀態(tài)KV、隊(duì)列、發(fā)布訂閱、定時(shí)任務(wù)、HTTP 服務(wù)器與可觀測性等運(yùn)行時(shí)原語agentmemory worker——由引擎拉起的一個(gè) Node 進(jìn)程node dist/index.mjs它向引擎注冊(cè)全部內(nèi)存函數(shù)對(duì)外接口——REST API默認(rèn):3111錨定端口與 MCP 工具面供 Claude Code、Cursor、Gemini CLI 等編碼代理接入。worker 啟動(dòng)時(shí)會(huì)把~/.agentmemory/.env折疊進(jìn)進(jìn)程環(huán)境僅當(dāng)對(duì)應(yīng)鍵未設(shè)置時(shí)保證真實(shí)環(huán)境變量優(yōu)先然后讀取配置并完成全部函數(shù)注冊(cè)見 src/index.ts 與 src/config.ts。啟動(dòng)日志會(huì)打印引擎地址、provider、embedding 維度、REST 端點(diǎn)與 streams 地址便于確認(rèn)各組件就緒狀態(tài)。iii 原語函數(shù)、觸發(fā)器與 worker 狀態(tài)agentmemory 架構(gòu)上最重要的一條原則是它沒有獨(dú)立的插件系統(tǒng)。所有能力都建立在 iii 引擎的三個(gè)原語之上函數(shù)functionsworker 通過sdk.registerFunction(mem::xxx, handler)注冊(cè)的具名能力例如mem::observe、mem::remember、mem::search、mem::consolidate觸發(fā)器triggersHTTP 觸發(fā)器api::*把 REST 請(qǐng)求路由到函數(shù)內(nèi)部調(diào)用則通過sdk.trigger({ function_id: mem::xxx, payload })觸發(fā)另一個(gè)函數(shù)worker 狀態(tài)worker 啟動(dòng)時(shí)用registerWorker(engineUrl, {...})連接引擎聲明自己的 worker 身份與遙測元數(shù)據(jù)project_name: agentmemory、language: node、framework: iii-sdk此后所有 KV 讀寫都經(jīng)由引擎狀態(tài)層完成。新增一項(xiàng)能力就等于新增一個(gè)函數(shù) 一個(gè)觸發(fā)器而不需要任何注冊(cè)中心之外的設(shè)施。例如注冊(cè)mem::observe后REST 側(cè)由registerApiTriggers暴露/agentmemory/observe二者共用同一個(gè) handler。函數(shù)注冊(cè)清單見 src/index.ts。引擎?zhèn)鹊?worker 拓?fù)鋓ii-config.yamlagentmemory 的引擎配置由倉庫根目錄的 iii-config.yaml 描述它定義了引擎內(nèi)部的一組 worker 拓?fù)鋡orker 名稱職責(zé)iii-httpHTTP 服務(wù)默認(rèn)監(jiān)聽127.0.0.1:3111配置了 CORS 白名單默認(rèn)放行 localhost:3111 / localhost:3113與 180s 默認(rèn)超時(shí)iii-stateKV 狀態(tài)適配器file_based存儲(chǔ)落盤到./data/state_store.dbiii-queue內(nèi)置隊(duì)列適配器iii-pubsub本地發(fā)布訂閱iii-cron基于 KV 的定時(shí)任務(wù)iii-stream實(shí)時(shí)流默認(rèn)監(jiān)聽:3112file_based落盤./data/stream_storeiii-observability可觀測性采集采樣率0.1避免高負(fù)載下日志訂閱積壓形成正反饋指標(biāo)與日志默認(rèn)開啟iii-exec執(zhí)行器監(jiān)聽src/**/*.ts變更執(zhí)行node dist/index.mjs拉起 worker這里有兩個(gè)值得注意的工程細(xì)節(jié)其一iii-observability的sampling_ratio: 0.1是為了防止日志訂閱 lag 告警重新進(jìn)入同一條日志流形成放大循環(huán)代碼注釋記錄了某個(gè)用戶在幾天內(nèi)寫出 137GB 日志的真實(shí)事故其二iii-exec的 watch 配置是開發(fā)態(tài)模型運(yùn)行時(shí) config 會(huì)被 CLI 復(fù)制到數(shù)據(jù)目錄并改寫file_path確保狀態(tài)庫落在用戶指定的數(shù)據(jù)目錄而非倉庫內(nèi)。檢索模型BM25 向量 圖的三流混合召回Recall 是 agentmemory 架構(gòu)的核心。它采用的是混合檢索BM25 關(guān)鍵詞檢索 向量相似度檢索 基于關(guān)聯(lián)概念的圖擴(kuò)展三者融合后再做會(huì)話級(jí)去重與排序。其實(shí)現(xiàn)位于 src/state/hybrid-search.ts核心入口tripleStreamSearch依次執(zhí)行BM25 流對(duì)查詢做詞法檢索取limit * 2條候選BM25 索引在啟動(dòng)時(shí)重建或從持久化快照恢復(fù)見 src/state/search-index.ts向量流若配置了 embedding provider 且向量索引非空先對(duì)查詢生成 embedding再做向量近鄰檢索失敗時(shí)優(yōu)雅降級(jí)為純 BM25圖流從查詢中抽取實(shí)體extractEntitiesFromQuery經(jīng)GraphRetrieval.searchByEntities檢索關(guān)聯(lián)概念再取 Top-5 向量結(jié)果通過expandFromChunks做圖擴(kuò)展形成第二條圖證據(jù)路徑圖檢索是 best-effort失敗不影響前兩流。三流結(jié)果按RRFReciprocal Rank Fusion融合每條結(jié)果記錄其在各流中的排名加權(quán)得分w * 1/(RRF_K rank)RRF_K 60再用各流實(shí)際產(chǎn)生結(jié)果的權(quán)重之和做歸一化避免某條流靜默時(shí)產(chǎn)生懲罰結(jié)果同時(shí)命中多條流的會(huì)獲得AGREEMENT_BONUS0.05加成——這正體現(xiàn)了圖擴(kuò)展存在的價(jià)值即使關(guān)鍵詞或向量命中的不是同一篇文檔只要它們?cè)趫D譜上相鄰也能互相增強(qiáng)。融合之后還有兩道后處理diversifyBySession限制同一會(huì)話最多貢獻(xiàn) 3 條結(jié)果防止單一會(huì)話刷屏enrichResults回查 KV 補(bǔ)齊觀測的完整內(nèi)容。若開啟RERANK_ENABLEDtrue還會(huì)對(duì) Top-20 結(jié)果做一次重排src/state/reranker.ts。零 API Key 設(shè)計(jì)默認(rèn)安裝不需要任何 API key向量 embedding 在本地運(yùn)行on-device見 src/providers/embedding/local.tsBM25 本身無需外部依賴。此時(shí) boot 日志會(huì)明確提示Provider: noop (noop) Embedding provider: local ... Ready. Triple-stream (BM25VectorGraph) search active.LLM provider 只用于兩項(xiàng)可選增強(qiáng)更豐富的摘要LLM compression與上下文自動(dòng)注入context injection二者都默認(rèn)關(guān)閉需顯式開啟見 src/config.ts 的AGENTMEMORY_AUTO_COMPRESS/AGENTMEMORY_INJECT_CONTEXT。因此記憶檢索的核心鏈路在零成本、零密鑰的前提下即可工作。檢索權(quán)重配置混合檢索的三流權(quán)重可在~/.agentmemory/.env中調(diào)節(jié)解析邏輯見 src/config.ts 與 src/index.ts環(huán)境變量默認(rèn)值說明BM25_WEIGHT0.4BM25 流權(quán)重非法值回退 0.4上限 1VECTOR_WEIGHT0.6向量流權(quán)重非法值回退 0.6上限 1AGENTMEMORY_GRAPH_WEIGHT0.3圖流權(quán)重RERANK_ENABLEDfalse是否開啟 LLM 重排EMBEDDING_PROVIDER自動(dòng)檢測顯式指定 embedding provider未設(shè)置時(shí)按 GEMINI → OPENAI → VOYAGE → COHERE → OPENROUTER 的鍵順序自動(dòng)推斷存儲(chǔ)模型與記憶生命周期數(shù)據(jù)模型記憶memories由以下字段構(gòu)成內(nèi)容content、概念concepts、關(guān)聯(lián)文件files、重要度strength/importance與時(shí)間戳createdAt/updatedAt。它們被組織進(jìn)會(huì)話sessions可選地與 git 提交commits關(guān)聯(lián)。KV 的 scope 劃分定義在 src/state/schema.tsmem:sessions—— 會(huì)話元數(shù)據(jù)project、cwd、observationCount、firstPrompt 等mem:obs:sessionId—— 按會(huì)話組織的觀測mem:memories—— 長期記憶含isLatest、version、parentId、supersedes等版本字段mem:summaries、mem:relations、mem:graph:nodes、mem:graph:edges—— 摘要、關(guān)聯(lián)、知識(shí)圖譜其他高級(jí) scopemem:lessons、mem:insights、mem:slots、mem:retention等。生命周期capture → compress → consolidate → forget記憶庫不會(huì)無限增長而是由一套捕獲、壓縮、整合、遺忘的生命周期維持越用越有用的狀態(tài)1. Capture捕獲mem::observesrc/functions/observe.ts接收來自各類 hook 的載荷pre_tool_use/post_tool_use/post_tool_failure/prompt_submit校驗(yàn)sessionId、hookType、timestamp后先做去重DedupMap 對(duì) sessionId toolName toolInput 計(jì)算哈希再做隱私清洗stripPrivateData隨后按會(huì)話級(jí) keyed-mutex 串行寫入 KV 并推送到實(shí)時(shí)流stream::set/stream::send供 viewer 與訂閱方消費(fèi)。每條觀測受MAX_OBS_PER_SESSION默認(rèn) 500上限約束。2. Compress壓縮默認(rèn)走zero-LLM 合成壓縮路徑buildSyntheticCompression無需 API key 即可把原始觀測提煉成可檢索的標(biāo)題、敘述與概念并同步寫入 BM25 與向量索引只有顯式開啟AGENTMEMORY_AUTO_COMPRESStrue時(shí)才改為調(diào)用 LLM 生成摘要代價(jià)是 token 消耗與工具調(diào)用頻率成正比啟動(dòng)時(shí)會(huì)打出醒目告警。3. Consolidate整合mem::consolidatesrc/functions/consolidate.ts把同一項(xiàng)目內(nèi)達(dá)到閾值默認(rèn) 10 條觀測的會(huì)話聚合成長期記憶由 LLM 按系統(tǒng)提示輸出 XML 結(jié)構(gòu)type/title/content/concepts/files/strength隨后寫入mem:memories。此外還有更完整的mem::consolidate-pipeline與每小時(shí)/每日定時(shí)器CONSOLIDATION_INTERVAL_MS默認(rèn) 7200000ms即 2 小時(shí)驅(qū)動(dòng)自動(dòng)整合。4. Forget遺忘mem::forgetsrc/functions/remember.ts支持按 memoryId、按 observationIds 或整會(huì)話刪除刪除會(huì)同步移除 BM25/向量索引條目、圖片引用計(jì)數(shù)與訪問日志并記錄審計(jì)mem::audit。自動(dòng)遺忘由mem::auto-forgetsrc/functions/auto-forget.ts每小時(shí)執(zhí)行AUTO_FORGET_INTERVAL_MS默認(rèn) 3600000ms處理三類對(duì)象TTL 過期記憶remember時(shí)設(shè)置ttlDays的記憶到期后自動(dòng)刪除矛盾記憶同一 concept 桶內(nèi) Jaccard 相似度超過 0.9 的成對(duì)記憶刪除較舊的一條并保留審計(jì)記錄低價(jià)值觀測超過 180 天且 importance ≤ 2 的觀測被回收。dryRun參數(shù)支持只預(yù)覽不執(zhí)行方便評(píng)估影響面。另外mem::remember還內(nèi)置了記憶版本化與取代機(jī)制src/functions/remember.ts保存新記憶時(shí)用 BM25 索引召回候選與新內(nèi)容做 Jaccard 相似度比較相似度 0.7 則新記憶取代舊記憶舊版本保留在 KV 中供 viewer 查看版本鏈但移出檢索索引相似度 0.4~0.7 的命中會(huì)以similarTo提示返回供調(diào)用方?jīng)Q定是否整合。不同 project 的記憶不會(huì)被跨項(xiàng)目取代。端口布局以 REST 為錨點(diǎn)的四端口組agentmemory 的端口分配遵循一個(gè)固定公式REST 是錨點(diǎn)服務(wù)端口公式默認(rèn)值REST APIN3111Streams實(shí)時(shí)流N 13112Viewer網(wǎng)頁查看器N 23113iii engine內(nèi)部總線N 4602349134--instance N會(huì)把整組端口右移N * 100--instance 1得到 3211 / 3212 / 3213 / 49234--instance 0保持規(guī)范的四件套。--instance取值范圍 0~50實(shí)現(xiàn)見 src/cli.ts。此外--port N可單獨(dú)覆蓋 REST 端口streams/viewer/engine 依然自動(dòng)派生避免二次碰撞。端口解析的完整優(yōu)先級(jí)見 src/config.ts 與 src/cli.tsRESTAGENTMEMORY_URL中的端口 III_REST_PORT 默認(rèn) 3111StreamsIII_STREAM_PORTIII_STREAMS_PORT舊名兼容REST 1EngineIII_ENGINE_PORTIII_ENGINE_URL中的端口 REST 46023ViewerAGENTMEMORY_VIEWER_URL 運(yùn)行時(shí)通過/agentmemory/livez探測到的實(shí)際端口 REST 2。/agentmemory/livez是一個(gè)關(guān)鍵的探活端點(diǎn)CLI 的status、doctor與 viewer 地址發(fā)現(xiàn)都依賴它返回的viewerPort字段。iii-config.yaml中iii-http的 CORS 白名單默認(rèn)放行 3111 與 3113 兩個(gè)來源正是為了 REST 與 viewer 之間的跨端口協(xié)作。Viewer實(shí)時(shí)觀測記憶構(gòu)建過程agentmemory 自帶一個(gè)實(shí)時(shí)網(wǎng)頁查看器默認(rèn)地址http://localhost:3113由startViewerServer在 REST2 端口啟動(dòng)見 src/viewer/server.ts。它訂閱mem-live實(shí)時(shí)流viewer group隨著會(huì)話運(yùn)行觀測與壓縮結(jié)果會(huì)實(shí)時(shí)流入頁面因此特別適合演示向他人展示記憶正在被構(gòu)建的過程驗(yàn)證捕獲是否生效跑一輪 hook 后立刻在頁面上看到新增的 raw/compressed 觀測。Viewer 還承擔(dān)了版本鏈查看superseded 記憶的歷史版本與 REST 代理的職責(zé)。安全方面它內(nèi)置了多重防護(hù)Host 頭白名單防 DNS rebinding 攻擊、Origin 白名單VIEWER_ALLOWED_ORIGINS、綁定地址默認(rèn) 127.0.0.1AGENTMEMORY_VIEWER_HOST可改以及可選的AGENTMEMORY_SECRET鑒權(quán)。延伸閱讀圍繞本文涉及的架構(gòu)模塊倉庫內(nèi)還有更深入的配套文檔agentmemory-mcp-tools 技能參考 與 agentmemory-rest-api 技能參考兩種對(duì)外訪問面的完整工具/端點(diǎn)清單agentmemory-hooks 技能參考hook 如何自動(dòng)捕獲觀測、何時(shí)寫入mem::observeagentmemory-config 技能參考端口與全部 feature flag 的權(quán)威說明iii 引擎配置文件 與 CLI 入口引擎 worker 拓?fù)渑c端口派生的實(shí)現(xiàn)依據(jù)。理解這套架構(gòu)后無論是排查為什么搜索返回為空可沿 BM25 索引重建 → 向量維度校驗(yàn) → 三流權(quán)重順序排查還是規(guī)劃新增一種記憶能力新函數(shù) 觸發(fā)器而非新建插件系統(tǒng)都有了清晰的著手點(diǎn)?！久赓M(fèi)下載鏈接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks項(xiàng)目地址: https://gitcode.com/GitHub_Trending/age/agentmemory創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 agentmemory 架構(gòu)深度解析：基于 iii 引擎的編碼代理持久化內(nèi)存服務(wù)
agentmemory 架構(gòu)深度解析基于 iii 引擎的編碼代理持久化內(nèi)存服務(wù)【免費(fèi)下載鏈接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks項(xiàng)目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory 是一個(gè)面向 AI 編碼代理coding agents的本地持久化內(nèi)存服務(wù)器它捕獲代理工作過程中的觀測observations建立混合檢索索引再通過 REST 與 MCP 兩種面surface把記憶回放給代理。它不自己發(fā)明一套運(yùn)行時(shí)而是完整構(gòu)建在 iii 引擎之上一切能力都以函數(shù) 觸發(fā)器的形式存在。讀完本文你將掌握 agentmemory 的整體架構(gòu)骨架、iii 原語的工作方式、三流混合檢索的實(shí)現(xiàn)原理、端口布局規(guī)則以及記憶從捕獲到遺忘的完整生命周期。agentmemory 是什么一個(gè)本地內(nèi)存服務(wù)器從架構(gòu)定位看agentmemory 是一個(gè)常駐本地的內(nèi)存服務(wù)器memory server運(yùn)行鏈路由三部分組成iii 引擎iii-engine——提供進(jìn)程內(nèi)狀態(tài)KV、隊(duì)列、發(fā)布訂閱、定時(shí)任務(wù)、HTTP 服務(wù)器與可觀測性等運(yùn)行時(shí)原語agentmemory worker——由引擎拉起的一個(gè) Node 進(jìn)程node dist/index.mjs它向引擎注冊(cè)全部內(nèi)存函數(shù)對(duì)外接口——REST API默認(rèn):3111錨定端口與 MCP 工具面供 Claude Code、Cursor、Gemini CLI 等編碼代理接入。worker 啟動(dòng)時(shí)會(huì)把~/.agentmemory/.env折疊進(jìn)進(jìn)程環(huán)境僅當(dāng)對(duì)應(yīng)鍵未設(shè)置時(shí)保證真實(shí)環(huán)境變量優(yōu)先然后讀取配置并完成全部函數(shù)注冊(cè)見 src/index.ts 與 src/config.ts。啟動(dòng)日志會(huì)打印引擎地址、provider、embedding 維度、REST 端點(diǎn)與 streams 地址便于確認(rèn)各組件就緒狀態(tài)。iii 原語函數(shù)、觸發(fā)器與 worker 狀態(tài)agentmemory 架構(gòu)上最重要的一條原則是它沒有獨(dú)立的插件系統(tǒng)。所有能力都建立在 iii 引擎的三個(gè)原語之上函數(shù)functionsworker 通過sdk.registerFunction(mem::xxx, handler)注冊(cè)的具名能力例如mem::observe、mem::remember、mem::search、mem::consolidate觸發(fā)器triggersHTTP 觸發(fā)器api::*把 REST 請(qǐng)求路由到函數(shù)內(nèi)部調(diào)用則通過sdk.trigger({ function_id: mem::xxx, payload })觸發(fā)另一個(gè)函數(shù)worker 狀態(tài)worker 啟動(dòng)時(shí)用registerWorker(engineUrl, {...})連接引擎聲明自己的 worker 身份與遙測元數(shù)據(jù)project_name: agentmemory、language: node、framework: iii-sdk此后所有 KV 讀寫都經(jīng)由引擎狀態(tài)層完成。新增一項(xiàng)能力就等于新增一個(gè)函數(shù) 一個(gè)觸發(fā)器而不需要任何注冊(cè)中心之外的設(shè)施。例如注冊(cè)mem::observe后REST 側(cè)由registerApiTriggers暴露/agentmemory/observe二者共用同一個(gè) handler。函數(shù)注冊(cè)清單見 src/index.ts。引擎?zhèn)鹊?worker 拓?fù)鋓ii-config.yamlagentmemory 的引擎配置由倉庫根目錄的 iii-config.yaml 描述它定義了引擎內(nèi)部的一組 worker 拓?fù)鋡orker 名稱職責(zé)iii-httpHTTP 服務(wù)默認(rèn)監(jiān)聽127.0.0.1:3111配置了 CORS 白名單默認(rèn)放行 localhost:3111 / localhost:3113與 180s 默認(rèn)超時(shí)iii-stateKV 狀態(tài)適配器file_based存儲(chǔ)落盤到./data/state_store.dbiii-queue內(nèi)置隊(duì)列適配器iii-pubsub本地發(fā)布訂閱iii-cron基于 KV 的定時(shí)任務(wù)iii-stream實(shí)時(shí)流默認(rèn)監(jiān)聽:3112file_based落盤./data/stream_storeiii-observability可觀測性采集采樣率0.1避免高負(fù)載下日志訂閱積壓形成正反饋指標(biāo)與日志默認(rèn)開啟iii-exec執(zhí)行器監(jiān)聽src/**/*.ts變更執(zhí)行node dist/index.mjs拉起 worker這里有兩個(gè)值得注意的工程細(xì)節(jié)其一iii-observability的sampling_ratio: 0.1是為了防止日志訂閱 lag 告警重新進(jìn)入同一條日志流形成放大循環(huán)代碼注釋記錄了某個(gè)用戶在幾天內(nèi)寫出 137GB 日志的真實(shí)事故其二iii-exec的 watch 配置是開發(fā)態(tài)模型運(yùn)行時(shí) config 會(huì)被 CLI 復(fù)制到數(shù)據(jù)目錄并改寫file_path確保狀態(tài)庫落在用戶指定的數(shù)據(jù)目錄而非倉庫內(nèi)。檢索模型BM25 向量 圖的三流混合召回Recall 是 agentmemory 架構(gòu)的核心。它采用的是混合檢索BM25 關(guān)鍵詞檢索 向量相似度檢索 基于關(guān)聯(lián)概念的圖擴(kuò)展三者融合后再做會(huì)話級(jí)去重與排序。其實(shí)現(xiàn)位于 src/state/hybrid-search.ts核心入口tripleStreamSearch依次執(zhí)行BM25 流對(duì)查詢做詞法檢索取limit * 2條候選BM25 索引在啟動(dòng)時(shí)重建或從持久化快照恢復(fù)見 src/state/search-index.ts向量流若配置了 embedding provider 且向量索引非空先對(duì)查詢生成 embedding再做向量近鄰檢索失敗時(shí)優(yōu)雅降級(jí)為純 BM25圖流從查詢中抽取實(shí)體extractEntitiesFromQuery經(jīng)GraphRetrieval.searchByEntities檢索關(guān)聯(lián)概念再取 Top-5 向量結(jié)果通過expandFromChunks做圖擴(kuò)展形成第二條圖證據(jù)路徑圖檢索是 best-effort失敗不影響前兩流。三流結(jié)果按RRFReciprocal Rank Fusion融合每條結(jié)果記錄其在各流中的排名加權(quán)得分w * 1/(RRF_K rank)RRF_K 60再用各流實(shí)際產(chǎn)生結(jié)果的權(quán)重之和做歸一化避免某條流靜默時(shí)產(chǎn)生懲罰結(jié)果同時(shí)命中多條流的會(huì)獲得AGREEMENT_BONUS0.05加成——這正體現(xiàn)了圖擴(kuò)展存在的價(jià)值即使關(guān)鍵詞或向量命中的不是同一篇文檔只要它們?cè)趫D譜上相鄰也能互相增強(qiáng)。融合之后還有兩道后處理diversifyBySession限制同一會(huì)話最多貢獻(xiàn) 3 條結(jié)果防止單一會(huì)話刷屏enrichResults回查 KV 補(bǔ)齊觀測的完整內(nèi)容。若開啟RERANK_ENABLEDtrue還會(huì)對(duì) Top-20 結(jié)果做一次重排src/state/reranker.ts。零 API Key 設(shè)計(jì)默認(rèn)安裝不需要任何 API key向量 embedding 在本地運(yùn)行on-device見 src/providers/embedding/local.tsBM25 本身無需外部依賴。此時(shí) boot 日志會(huì)明確提示Provider: noop (noop) Embedding provider: local ... Ready. Triple-stream (BM25VectorGraph) search active.LLM provider 只用于兩項(xiàng)可選增強(qiáng)更豐富的摘要LLM compression與上下文自動(dòng)注入context injection二者都默認(rèn)關(guān)閉需顯式開啟見 src/config.ts 的AGENTMEMORY_AUTO_COMPRESS/AGENTMEMORY_INJECT_CONTEXT。因此記憶檢索的核心鏈路在零成本、零密鑰的前提下即可工作。檢索權(quán)重配置混合檢索的三流權(quán)重可在~/.agentmemory/.env中調(diào)節(jié)解析邏輯見 src/config.ts 與 src/index.ts環(huán)境變量默認(rèn)值說明BM25_WEIGHT0.4BM25 流權(quán)重非法值回退 0.4上限 1VECTOR_WEIGHT0.6向量流權(quán)重非法值回退 0.6上限 1AGENTMEMORY_GRAPH_WEIGHT0.3圖流權(quán)重RERANK_ENABLEDfalse是否開啟 LLM 重排EMBEDDING_PROVIDER自動(dòng)檢測顯式指定 embedding provider未設(shè)置時(shí)按 GEMINI → OPENAI → VOYAGE → COHERE → OPENROUTER 的鍵順序自動(dòng)推斷存儲(chǔ)模型與記憶生命周期數(shù)據(jù)模型記憶memories由以下字段構(gòu)成內(nèi)容content、概念concepts、關(guān)聯(lián)文件files、重要度strength/importance與時(shí)間戳createdAt/updatedAt。它們被組織進(jìn)會(huì)話sessions可選地與 git 提交commits關(guān)聯(lián)。KV 的 scope 劃分定義在 src/state/schema.tsmem:sessions—— 會(huì)話元數(shù)據(jù)project、cwd、observationCount、firstPrompt 等mem:obs:sessionId—— 按會(huì)話組織的觀測mem:memories—— 長期記憶含isLatest、version、parentId、supersedes等版本字段mem:summaries、mem:relations、mem:graph:nodes、mem:graph:edges—— 摘要、關(guān)聯(lián)、知識(shí)圖譜其他高級(jí) scopemem:lessons、mem:insights、mem:slots、mem:retention等。生命周期capture → compress → consolidate → forget記憶庫不會(huì)無限增長而是由一套捕獲、壓縮、整合、遺忘的生命周期維持越用越有用的狀態(tài)1. Capture捕獲mem::observesrc/functions/observe.ts接收來自各類 hook 的載荷pre_tool_use/post_tool_use/post_tool_failure/prompt_submit校驗(yàn)sessionId、hookType、timestamp后先做去重DedupMap 對(duì) sessionId toolName toolInput 計(jì)算哈希再做隱私清洗stripPrivateData隨后按會(huì)話級(jí) keyed-mutex 串行寫入 KV 并推送到實(shí)時(shí)流stream::set/stream::send供 viewer 與訂閱方消費(fèi)。每條觀測受MAX_OBS_PER_SESSION默認(rèn) 500上限約束。2. Compress壓縮默認(rèn)走zero-LLM 合成壓縮路徑buildSyntheticCompression無需 API key 即可把原始觀測提煉成可檢索的標(biāo)題、敘述與概念并同步寫入 BM25 與向量索引只有顯式開啟AGENTMEMORY_AUTO_COMPRESStrue時(shí)才改為調(diào)用 LLM 生成摘要代價(jià)是 token 消耗與工具調(diào)用頻率成正比啟動(dòng)時(shí)會(huì)打出醒目告警。3. Consolidate整合mem::consolidatesrc/functions/consolidate.ts把同一項(xiàng)目內(nèi)達(dá)到閾值默認(rèn) 10 條觀測的會(huì)話聚合成長期記憶由 LLM 按系統(tǒng)提示輸出 XML 結(jié)構(gòu)type/title/content/concepts/files/strength隨后寫入mem:memories。此外還有更完整的mem::consolidate-pipeline與每小時(shí)/每日定時(shí)器CONSOLIDATION_INTERVAL_MS默認(rèn) 7200000ms即 2 小時(shí)驅(qū)動(dòng)自動(dòng)整合。4. Forget遺忘mem::forgetsrc/functions/remember.ts支持按 memoryId、按 observationIds 或整會(huì)話刪除刪除會(huì)同步移除 BM25/向量索引條目、圖片引用計(jì)數(shù)與訪問日志并記錄審計(jì)mem::audit。自動(dòng)遺忘由mem::auto-forgetsrc/functions/auto-forget.ts每小時(shí)執(zhí)行AUTO_FORGET_INTERVAL_MS默認(rèn) 3600000ms處理三類對(duì)象TTL 過期記憶remember時(shí)設(shè)置ttlDays的記憶到期后自動(dòng)刪除矛盾記憶同一 concept 桶內(nèi) Jaccard 相似度超過 0.9 的成對(duì)記憶刪除較舊的一條并保留審計(jì)記錄低價(jià)值觀測超過 180 天且 importance ≤ 2 的觀測被回收。dryRun參數(shù)支持只預(yù)覽不執(zhí)行方便評(píng)估影響面。另外mem::remember還內(nèi)置了記憶版本化與取代機(jī)制src/functions/remember.ts保存新記憶時(shí)用 BM25 索引召回候選與新內(nèi)容做 Jaccard 相似度比較相似度 0.7 則新記憶取代舊記憶舊版本保留在 KV 中供 viewer 查看版本鏈但移出檢索索引相似度 0.4~0.7 的命中會(huì)以similarTo提示返回供調(diào)用方?jīng)Q定是否整合。不同 project 的記憶不會(huì)被跨項(xiàng)目取代。端口布局以 REST 為錨點(diǎn)的四端口組agentmemory 的端口分配遵循一個(gè)固定公式REST 是錨點(diǎn)服務(wù)端口公式默認(rèn)值REST APIN3111Streams實(shí)時(shí)流N 13112Viewer網(wǎng)頁查看器N 23113iii engine內(nèi)部總線N 4602349134--instance N會(huì)把整組端口右移N * 100--instance 1得到 3211 / 3212 / 3213 / 49234--instance 0保持規(guī)范的四件套。--instance取值范圍 0~50實(shí)現(xiàn)見 src/cli.ts。此外--port N可單獨(dú)覆蓋 REST 端口streams/viewer/engine 依然自動(dòng)派生避免二次碰撞。端口解析的完整優(yōu)先級(jí)見 src/config.ts 與 src/cli.tsRESTAGENTMEMORY_URL中的端口 III_REST_PORT 默認(rèn) 3111StreamsIII_STREAM_PORTIII_STREAMS_PORT舊名兼容REST 1EngineIII_ENGINE_PORTIII_ENGINE_URL中的端口 REST 46023ViewerAGENTMEMORY_VIEWER_URL 運(yùn)行時(shí)通過/agentmemory/livez探測到的實(shí)際端口 REST 2。/agentmemory/livez是一個(gè)關(guān)鍵的探活端點(diǎn)CLI 的status、doctor與 viewer 地址發(fā)現(xiàn)都依賴它返回的viewerPort字段。iii-config.yaml中iii-http的 CORS 白名單默認(rèn)放行 3111 與 3113 兩個(gè)來源正是為了 REST 與 viewer 之間的跨端口協(xié)作。Viewer實(shí)時(shí)觀測記憶構(gòu)建過程agentmemory 自帶一個(gè)實(shí)時(shí)網(wǎng)頁查看器默認(rèn)地址http://localhost:3113由startViewerServer在 REST2 端口啟動(dòng)見 src/viewer/server.ts。它訂閱mem-live實(shí)時(shí)流viewer group隨著會(huì)話運(yùn)行觀測與壓縮結(jié)果會(huì)實(shí)時(shí)流入頁面因此特別適合演示向他人展示記憶正在被構(gòu)建的過程驗(yàn)證捕獲是否生效跑一輪 hook 后立刻在頁面上看到新增的 raw/compressed 觀測。Viewer 還承擔(dān)了版本鏈查看superseded 記憶的歷史版本與 REST 代理的職責(zé)。安全方面它內(nèi)置了多重防護(hù)Host 頭白名單防 DNS rebinding 攻擊、Origin 白名單VIEWER_ALLOWED_ORIGINS、綁定地址默認(rèn) 127.0.0.1AGENTMEMORY_VIEWER_HOST可改以及可選的AGENTMEMORY_SECRET鑒權(quán)。延伸閱讀圍繞本文涉及的架構(gòu)模塊倉庫內(nèi)還有更深入的配套文檔agentmemory-mcp-tools 技能參考 與 agentmemory-rest-api 技能參考兩種對(duì)外訪問面的完整工具/端點(diǎn)清單agentmemory-hooks 技能參考hook 如何自動(dòng)捕獲觀測、何時(shí)寫入mem::observeagentmemory-config 技能參考端口與全部 feature flag 的權(quán)威說明iii 引擎配置文件 與 CLI 入口引擎 worker 拓?fù)渑c端口派生的實(shí)現(xiàn)依據(jù)。理解這套架構(gòu)后無論是排查為什么搜索返回為空可沿 BM25 索引重建 → 向量維度校驗(yàn) → 三流權(quán)重順序排查還是規(guī)劃新增一種記憶能力新函數(shù) 觸發(fā)器而非新建插件系統(tǒng)都有了清晰的著手點(diǎn)?！久赓M(fèi)下載鏈接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks項(xiàng)目地址: https://gitcode.com/GitHub_Trending/age/agentmemory創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考