agentmemory 规模化与跨会话评测为何内置记忆在 5000 条观测下必然失效【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory导读本文以 agentmemory 仓库中的 benchmark/SCALE.md 评测报告为骨架结合 benchmark/scale-eval.ts、benchmark/dataset.ts 以及 src/state/search-index.ts、src/state/hybrid-search.ts 等源码系统讲解agentmemory 在 5 档语料规模24050,000 条观测下的索引构建、检索延迟、存储开销与上下文 Token 节省情况以及 12 条跨会话检索查询的命中结果。读完本文你将掌握 agentmemory 检索架构BM25 向量 图的三路融合、内置记忆CLAUDE.md 等在规模扩大后的根本性局限以及如何在本地复现这套评测。1. 评测背景内置记忆与 agentmemory 的本质差异SCALE.md报告开篇就点明了核心矛盾Every built-in agent memory (CLAUDE.md, .cursorrules, Clines memory-bank) loads ALL memory into context every session. agentmemory searches and returns only relevant results.内置记忆CLAUDE.md、.cursorrules、Cline 的 memory-bank的策略是每个会话把全部记忆塞进上下文窗口而 agentmemory 的策略是先检索、后注入只把与当前查询相关的少量结果放进上下文。这个差异在语料规模很小时不显眼一旦观测数量越过数百条全量加载 就会指数级放大上下文占用直至彻底突破窗口上限。本次评测由 benchmark/scale-eval.ts 自动生成报告并写回benchmark/SCALE.md见其main()与generateReport()评测环境为darwin arm64、Node v20.20.0。评测包含两部分Scale tests5 档语料规模240 / 1,000 / 5,000 / 10,000 / 50,000 条观测Cross-session tests12 条针对特定历史会话的查询。2. 规模评测检索延迟恒定内置记忆全面崩溃以下是SCALE.md第 1 节的完整数据表也是该报告的核心证据ObservationsSessionsIndex BuildBM25 SearchHybrid SearchHeapContext Tokens (built-in)Context Tokens (agentmemory)SavingsBuilt-in Unreachable24030177ms0.112ms0.63ms9MB10,5041,92482%17%1,000125155ms0.317ms1.709ms6MB43,8341,96996%80%5,000625810ms1.496ms8.58ms25MB220,3351,97299%96%10,00012501657ms3.195ms17.49ms1MB440,9731,974100%98%50,00062509182ms22.827ms108.722ms316MB2,216,1731,981100%100%2.1 这些数字意味着什么Index Build索引构建时间从 240 条观测的 177ms 到 50,000 条的 9.2 秒构建开销呈亚线性增长——50,000 条观测比 240 条多了约 208 倍的数据量构建时间只增长了约 52 倍。构建流程对应 benchmark/scale-eval.ts逐条向SearchIndex添加观测、将title narrative concepts拼成的文本喂给 384 维确定性 embedding 并写入VectorIndex最后同步写入 KV 存储。BM25 Search50,000 条观测下仅 22.8ms。搜索路径对应 src/state/search-index.ts 的SearchIndex.search()——这是一个标准 BM25 实现k1 1.2、b 0.75见该文件 L19-L20利用倒排索引invertedIndex直接定位命中文档因此延迟随语料增长非常平缓。Hybrid Search50,000 条观测下约 108.7ms是 BM25 的约 5 倍因为混合检索需要并行执行 BM25、向量检索与图谱检索三路并做 RRF 融合详见第 6 节。实测中 10,000 条观测时堆内存出现 1MB 的低值属于评测进程的 GC/分配波动不改变整体趋势。Context Tokens (built-in)Claude Code / Cursor / Cline 若把全部记忆加载进上下文窗口所需的 Token 数。5,000 条观测即约 250K Token已超出绝大多数模型的上下文窗口。Context Tokens (agentmemory)Top-10 检索结果的 Token 消耗。注意它几乎不随语料规模变化——从 1,924 到 1,981波动极小这正是 检索而非全量加载 的价值所在。Built-in Unreachable因超过 200 行 MEMORY.md 上限或上下文窗口限制而无法被内置系统访问的记忆占比。1,000 条观测时80% 的项目历史对内置记忆来说已经不可见到 10,000 条时这一比例达到 98%50,000 条时是 100%。评测细节scale-eval.ts用estimateTokens(text) ceil(text.length / 4)估算 Tokenbenchmark/scale-eval.ts每个规模下用 20 次检索取平均延迟token_savings_pct round((1 - agentmemory_tokens / builtin_tokens) * 100)builtin_unreachable_pct count 200 ? 0 : round((1 - 200 / count) * 100)见 benchmark/scale-eval.ts。这些口径直接解释了表内各列数值的来源。2.2 存储成本全量索引也只占用几百 MBSCALE.md同时给出了索引序列化后的磁盘占用BM25 倒排索引 384 维向量索引ObservationsBM25 IndexVector Index (d384)Total Storage240395 KB494 KB0.9 MB1,0001,599 KB2,060 KB3.6 MB5,0008,006 KB10,298 KB17.9 MB10,00016,005 KB20,596 KB35.7 MB50,00080,126 KB102,979 KB178.8 MB两路索引规模相近向量略大合计随观测数线性增长50,000 条观测的全量双索引仅约 178.8 MB。与之对比同样的记忆如果全量塞进上下文一次会话就要消耗 220 万 Token。这意味着 agentmemory 用磁盘上恒定的索引换取了上下文里恒定的注入量存储开销在可接受范围内。对应的序列化实现可查阅SearchIndex.serialize()与VectorIndex.serialize()均在 src/state/ 目录下。3. 跨会话检索12/12 全部命中跨会话检索是 agentmemory 相对于内置记忆的第二个决胜点内置记忆一旦观测数越过行数/上下文上限就根本找不到早期会话的信息。SCALE.md第 2 节给出了 12 条针对特定历史会话的查询结果QueryTarget SessionGapBM25 FoundBM25 RankHybrid FoundHybrid RankBuilt-in VisibleHow did we set up OAuth providers?ses_005-00924Yes#1Yes#1YesWhat was the N1 query fix?ses_010-01418Yes#1Yes#2YesPostgreSQL full-text search setupses_010-01417Yes#1Yes#1Yesbcrypt password hashing configurationses_005-00920Yes#1Yes#1YesVitest unit testing setupses_020-0249Yes#1Yes#1Yeswebhook retry exponential backoffses_015-01914Yes#1Yes#1YesESLint flat config migrationses_000-00429Yes#1Yes#1YesKubernetes HPA autoscaling configurationses_025-0294Yes#1Yes#1NoPrisma database seed scriptses_010-01416Yes#1Yes#1YesAPI cursor-based paginationses_015-01914Yes#1Yes#1YesCSRF protection double-submit cookieses_005-00924Yes#1Yes#1Yesblue-green deployment rollbackses_025-0294Yes#1Yes#1NoSummary报告原话agentmemory BM25 命中 12/12 条跨会话查询Hybrid 同样命中 12/12而受 200 行上限约束的内置记忆只能触达 10/12。值得注意的细节BM25 全部拿到第一名说明纯词法检索在代码开发类记忆上已经足够强悍——这得益于SearchIndex中的同义词扩展同义词权重 0.7见 src/state/search-index.ts与 BM25 的 IDF 加权Hybrid 在 What was the N1 query fix? 上排名 #2因为向量/图谱路线的得分融合稀释了词法匹配的领先位置两条Built-in Visible No的查询Kubernetes HPA、blue-green 部署都指向ses_025-029即数据集里最新的一组会话——但内置记忆的 200 行窗口内已容纳不下这些观测说明即使是最近的记忆内置方案也可能丢查询的目标会话与当前会话间隔最长 29 个会话ESLint flat config migration 指向 ses_000-004agentmemory 依然从语料库全量检索中精准召回。评测构造可溯源12 条查询及其目标概念如 oauth/nextauth、n1/eager-loading、hpa/autoscaling定义在 benchmark/scale-eval.ts判定逻辑是目标观测是否出现在 top-20 检索结果中内置可见性则以前 200 条观测是否包含目标为准benchmark/scale-eval.ts。4. 上下文窗口问题数学上必然的崩塌SCALE.md第 3 节用一段推演展示了内置记忆为何在规模增长下必然失败Agent context window: ~200K tokens System prompt tools: ~20K tokens User conversation: ~30K tokens Available for memory: ~150K tokens At 50 tokens/observation: 200 observations 10,000 tokens (fits, but 200-line cap hits first) 1,000 observations 50,000 tokens (33% of available budget) 5,000 observations 250,000 tokens (EXCEEDS total context window) agentmemory top-10 results: Any corpus size ~1,924 tokens (0.3% of budget)推演的结论分两层200 行上限先于 Token 预算触顶200 条观测约 10K Token虽在 150K 预算内但 MEMORY.md 的 200 行硬限制会先拦住它5,000 条观测直接超过整个上下文窗口250K Token 200K内置记忆在数学上就装不下agentmemory 恒定注入约 1,924 Token约 0.3% 的预算无论语料多大——Top-10 检索结果的体量在 240 条与 50,000 条观测下几乎没有差别见第 2 节表格。这也是为什么真实开发场景中几周前修过的 N1 查询OAuth 回调的坑这类记忆在 Claude Code/Cursor/Cline 里总是想不起来——不是模型记性差而是这些记忆根本不在注入的上下文里。5. 能力矩阵内置记忆做不到的 11 件事SCALE.md第 4 节用一张能力对照表总结了 agentmemory 相对内置记忆的完整差异CapabilityBuilt-in (CLAUDE.md)agentmemorySemantic searchNo (keyword grep only)BM25 vector graphScale beyond 200 linesNo (hard cap)UnlimitedCross-session recallOnly if in 200-line windowFull corpus searchCross-agent sharingNo (per-agent files)MCP REST APIMulti-agent coordinationNoLeases, signals, actionsTemporal queriesNoPoint-in-time graphMemory lifecycleNo (manual pruning)Ebbinghaus decay evictionKnowledge graphNoEntity extraction traversalQuery expansionNoLLM-generated reformulationsRetention scoringNoTime-frequency decay modelReal-time dashboardNo (read files manually)Viewer on :3113Concurrent accessNo (file lock)Keyed mutex KV store这些能力在源码中均有落点可以逐一印证以下路径均为仓库根目录相对路径Semantic search / Knowledge graph三路检索与实体抽取核心在 src/state/hybrid-search.tsRRF 融合与 src/functions/graph-retrieval.ts、src/functions/query-expansion.tsMemory lifecycle / Retention scoringEbbinghaus 衰减与驱逐策略见 src/functions/retention.ts、src/functions/auto-forget.ts、src/functions/evict.tsMulti-agent coordination租约、信号、动作见 src/functions/leases.ts、src/functions/signals.ts、src/functions/actions.tsTemporal queries时间点图谱见 src/functions/temporal-graph.tsConcurrent access键控互斥与 KV 存储见 src/state/keyed-mutex.ts、src/state/kv.tsCross-agent sharing / Real-time dashboardMCP 服务与 3113 端口 Viewer见 src/mcp/server.ts、src/viewer/server.ts。6. 纵深评测背后的检索实现原理为了让12/12 命中与恒定 1,900 Token这两个结论可复现、可理解这里结合源码说明评测所用检索链路的真实实现。6.1 BM25同义词扩展的词法检索src/state/search-index.ts 实现了标准的 BM25 打分参数k1 1.2、b 0.75L19-L20倒排索引invertedIndex: Mapterm, SetobsId支持 O(命中集) 的查询查询时会为每个原始词条附加同义词权重 0.7并计算 IDF ln((N - df 0.5) / (df 0.5) 1)L106-L110。这就是跨会话评测中 BM25 12/12 全命中、多数排名第一的直接原因像 OAuth providers、N1 query、tsvector 这类专有词条在倒排索引中是强区分度信号。6.2 Hybrid SearchBM25 向量 图谱的三路 RRF 融合src/state/hybrid-search.ts 的HybridSearch类是三路融合的核心权重配置bm25Weight 0.4、vectorWeight 0.6、graphWeight 0.3L30-L32评测中通过构造参数显式传入(0.4, 0.6, 0)关闭图谱路见 benchmark/scale-eval.tsRRF 融合RRF_K 60每条结果按w * 1/(RRF_K rank)加权求和L213-L216多路命中奖励AGREEMENT_BONUS 0.05同时被多路召回的结果获得加成L201、L221退化保护向量检索失败时静默回退 BM25-only图谱检索是 best-effortL99-L101、L116-L118可选 LLM 重排RERANK_ENABLEDtrue时对 top-20 窗口内的结果调用重排器L33、L247-L250。6.3 数据集30 个会话的合成项目历史benchmark/dataset.ts 构造了一个跨 30 个会话ses_000ses_029、每会话 8 条观测的合成 webapp 项目史从 Next.js 初始化、NextAuth OAuth 接入、Prisma/PostgreSQL、REST API 与分页、测试体系到 Kubernetes 与蓝绿部署L17-L113。每个观测包含type / title / subtitle / facts / narrative / concepts / files / importance字段narrative与concepts是检索的主要文本来源。规模评测使用generateScaleDataset(count)按指定观测数生成语料跨会话评测使用generateDataset()embedding 采用确定性哈希实现词元按字符哈希散落到 384 维并归一化见 benchmark/scale-eval.ts保证同一查询在多次运行中得到一致结果从而让 12/12 的结论可复现。7. 何时该用哪种记忆SCALE.md第 5 节给出了明确的选型建议用内置记忆CLAUDE.md当需要记忆的条目少于 200 个单 Agent、单项目只记偏好和快速事实零配置是第一优先级。用 agentmemory 当项目历史超过 200 条观测需要回忆几周前的具体事故如某个 OAuth 回调的坑多个 Agent 在同一个代码库上协作想要语义搜索how does auth work?而不只是关键词匹配需要跟踪记忆的质量、衰减与生命周期想要跨 Claude Code、Cursor、Windsurf 等工具共享一层记忆。报告用一句话收束了这个对比Built-in memory is your sticky notes. agentmemory is the searchable database behind them.内置记忆是你的便利贴agentmemory 是便利贴背后的可检索数据库。8. 如何在本地复现这套评测SCALE.md由scale-eval.ts自动生成复现路径如下# 1. 安装依赖仓库根目录 npm install # 2. 运行规模 跨会话评测报告会重新写入 benchmark/SCALE.md npx tsx benchmark/scale-eval.ts脚本输出两阶段日志1. Scale benchmarks...、2. Cross-session retrieval...随后生成并写回benchmark/SCALE.mdbenchmark/scale-eval.ts。8.1 更贴近真实 daemon 的负载评测如果你想验证的是真实运行中的 agentmemory 守护进程在 100k 记忆、100 并发下的 p99 延迟而不是内存内索引的微基准仓库还提供了 benchmark/load-100k.ts——一个零依赖、可复现的 HTTP 负载压测工具详见 benchmark/README.md# 1. 启动 daemon npx agentmemory/agentmemory # 2. 另一个终端执行负载评测 npm run bench:load其默认矩阵为N ∈ {1000, 10000, 100000}记忆 ×C ∈ {1, 10, 100}并发覆盖POST /agentmemory/remember、POST /agentmemory/smart-search、GET /agentmemory/memories?latesttrue三个端点每格 200 次请求记录 p50 / p90 / p99 / 吞吐benchmark/load-100k.ts。可用环境变量覆盖矩阵BENCH_N1000 BENCH_C1,10 BENCH_OPS100 npm run bench:load内容生成基于mulberry32(BENCH_SEED)可播种 PRNG默认种子0xC0FFEE见 benchmark/load-100k.ts——同一 seed 同一构建 逐字节相同的语料保证延迟方差来自 daemon 本身而非 payload 抖动。结果写入benchmark/results/load-100k-git-sha.json仓库中已留存一份示例报告 benchmark/results/load-100k-96c0ed0.json其中N1000, C10时smart-search的 p50 约 160ms、p99 约 185ms、吞吐 61 ops/s可作为对照基准。9. 结论benchmark/SCALE.md用 5 档规模、12 条跨会话查询给出了两组可复现的证据检索式记忆在规模上碾压全量注入语料从 240 条增长到 50,000 条208 倍agentmemory 的注入 Token 始终稳定在 ~1,900BM25 检索延迟仅从 0.112ms 涨到 22.8ms混合检索为 108.7ms而全量索引磁盘占用不过 178.8 MB内置记忆则在 5,000 条时约 250K Token就已突破整个上下文窗口。跨会话召回是内置记忆的结构性盲区12/12 的跨会话查询被 agentmemory 的 BM25 与混合检索全部命中且大多排名第一而内置记忆受 200 行上限约束只能触达 10/12——即使是最新的会话ses_025-029也可能超出其窗口。这些结论背后是 src/state/search-index.tsBM25 同义词、src/state/hybrid-search.ts三路 RRF 融合与 benchmark/dataset.ts30 会话合成数据集的确定性实现。对开发者而言选型建议清晰低于 200 条观测、单 Agent、求零配置——用 CLAUDE.md一旦项目历史超出这一量级或需要语义检索、跨会话回忆、多 Agent 共享记忆agentmemory 就是那个可检索数据库。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考