从去年年底开始我一直在折腾多 Agent 协作的项目最让我头疼的不是模型选型也不是工具调用而是“记忆”。每个 Agent 各聊各的用户上午跟售前 Agent 说过需求下午换到售后 Agent 就全忘了更别说让多个 Agent 共享同一个用户的长期偏好。那段时间我几乎把 LangChain 的 Memory、LangGraph 的 checkpointer、向量库存对话记录都试了一遍总感觉差一口气。直到我刷到 ai-memory 这个项目7.9K Stars定位是“跨 Agent 记忆层”一下就把我之前零碎拼凑的方案给统一了。它解决的其实是很具体的问题给 Agent 一个可以插拔的长期记忆模块不仅支持单个 Agent 记住用户还能按 user_id 和 agent_id 做双维度隔离与共享让不同 Agent 之间可以访问同一份用户记忆。如果你正在做客服机器人、多角色助手、或者任何“多个 Agent 协作服务同一批用户”的系统这篇关于 ai-memory 的拆解应该能帮你少走不少弯路。我会从架构逻辑、核心 API、落地接入、实测表现几个方面展开直接给到能复现的参考。1. 为什么多 Agent 协作容易栽在“记忆”上1.1 单体记忆和共享记忆的根本差异先聊个都不陌生的问题单体记忆指的是“一个 Agent 自己记住自己的对话历史”最常见的就是 LangChain 里的 ConversationBufferMemory、ConversationSummaryMemory 这种东西。它们把聊天记录往 context window 里塞或者压缩成摘要再塞进去。这在单 Agent、单用户、单会话的场景下是够用的但一旦系统里存在多个 Agent问题就来了。我举个真实场景我的项目里有一个导购 Agent、一个售后 Agent、一个物流查询 Agent。用户跟导购 Agent 聊了半小时选了一款戴尔笔记本还提到自己是学生预算五千以内。然后用户关掉页面第二天打开来咨询物流接话的是物流 Agent。物流 Agent 的 memory 是空的它不知道用户昨天聊过什么更不知道用户是学生、预算有限。这时候用户如果问“我昨天看的那台电脑发货了吗”物流 Agent 只能很尴尬地说“抱歉我这边没有相关记录”。这就是单体记忆的缺陷记忆被绑定在单个 Agent 实例上Agent 与 Agent 之间没有记忆的共享通道。ai-memory 的做法是把记忆从 Agent 里抽出来做成一个独立层任何 Agent 都能通过统一的接口去读写这段记忆记忆的所有权归“用户 记忆层”而不是归某个具体 Agent。1.2 从 Chat Memory 到 Memory Layer 的演进这个演进路线其实很清晰。第一代是 Session Memory以会话为单位会话结束记忆就没了第二代是 Chat History 持久化把对话历史存到数据库但检索靠翻记录效率低第三代是 Vector Memory用向量库存对话片段按语义相似度召回LangChain 的 VectorStoreRetrieverMemory 就是这类第四代是 ai-memory 这种 Memory Layer把记忆的写入、抽取、存储、检索、共享做成一个完整的中台Agent 不需要关心底层是向量库还是关系库只需要调用 save 和 search。这里有个很关键的思路转变前几代方案都在纠结“怎么存”而 Memory Layer 更关心“怎么让记忆流动起来”。用户的一句话可能同时涉及用户的身份信息、商品偏好、时间约束、情绪状态这些不同类型的记忆应该按不同的维度被组织而不是简单堆在一条聊天记录里。ai-memory 的 dual-memory双记忆设计正是冲着这个去的既能按 user_id 存用户长期画像又能按 agent_id 存 Agent 自己的经验积累。1.3 ai-memory 到底解决的是哪几个痛点我把实际使用中感受到的痛点归纳成四类跨 Agent 记忆不可见上面那个例子已经说明了多个 Agent 服务同一用户时记忆被割裂。记忆与业务数据混杂很多项目把记忆直接塞进业务数据库表和表之间耦合严重后续想换向量库或者加个记忆清洗逻辑动一发而牵全身。记忆没有生命周期管理记住的东西越来越多但哪些该长期保留、哪些该过期清理没有统一策略。记忆写入过于机械直接把原始文本扔进存储没有做结构化抽取检索时召回的是一堆噪音。ai-memory 针对这些痛点提供了一个独立部署的 memory server / memory library抽象出 save、search、reset 三个核心能力并且在内部自动化抽取、清洗、排序记忆项。这不只是一个工具库更是一种架构模式把记忆从 Agent 的“附加功能”升级为“基础设施”。2. ai-memory 的核心机制从 save 到 search 的链路2.1 整体架构先看一眼ai-memory 的架构可以用一句话概括它像一个中间件夹在 LLM Agent 和存储后端之间。Agent 产生一段交互内容通过 save 接口丢给记忆层记忆层内部做抽取、格式化、写入当 Agent 需要回想相关信息时通过 search 接口提交 query 和过滤条件记忆层返回排序后的记忆列表。从部署形态上看它既可以直接在 Python 进程里作为库来用也可以跑成独立服务。我实际测试时是在 FastAPI 项目里直接 import非常轻量没有强制引入一堆重依赖。存储后端默认走的 SQLite但通过配置可以挂到向量库。这种“默认轻量、可选重型”的设计对中小型项目非常友好。2.2 save 接口记录 user 和 agent 双维度记忆我最开始看文档时以为 save 就是简单存一条对话记录实际测下来发现它做的事情远不止这些。save 的核心入参包括 user_id、agent_id、prompt用户输入以及可选的 metadata。调用之后ai-memory 会把 prompt 里的关键信息自动抽取成一条结构化的记忆项memory item并打上 user_id 和 agent_id 两个维度的标签。这里我贴一个实际跑通的调用示例用的是我当时测试时的版本具体命名以仓库 README 为准from ai_memory import Memory memory Memory() memory.save( user_iduser_123, agent_idagent_sales, prompt我是一名学生预算五千左右想找一台适合编程和游戏的笔记本, metadata{source: web_chat, session_id: sess_001} )执行完这条 save 之后记忆层内部会生成一个记忆项大致包含记忆内容、user_id、agent_id、时间戳、metadata 这些字段。更重要的是它可能会把“学生”、“预算五千”、“编程和游戏”这些实体或偏好单独抽取出来方便后续精准召回。我没有去深挖它的抽取 prompt 模板但从结果来看抽取后的记忆比原始文本更适合向量化检索和精确过滤。2.3 search 接口按 user、agent、metadata 检索search 是记忆层真正发挥作用的地方。我常用的检索方式有三类按 user_id 全局搜memory.search(user_iduser_123, query笔记本偏好)不管哪个 Agent 问都能拿到这个用户的历史画像。按 agent_id 限定范围memory.search(user_iduser_123, agent_idagent_sales, query...)只搜某个 Agent 与用户的交互记忆。不传 query 纯拉取memory.search(user_iduser_123, agent_idagent_sales)把该 Agent 与该用户的所有记忆按时间倒序列出来。我实际测试中发现search 返回的结果不是简单的原始记录而是经过相关性排序的记忆项列表。每个记忆项还有类似“最后访问时间”之类的信号这为后续做“多久没提到的记忆降权”留了空间。在多 Agent 场景里我最常用的是“先按 user_id 全量搜拿回候选后再在业务层做过滤”的策略因为跨 Agent 共享记忆本身就是这个项目最核心的卖点。2.4 我理解的内部存储机制官方文档没有把存储 schema 铺得很细但根据我扒源码和使用时的观察简单说一下我的理解核心表结构大概围绕 memory items 展开每条记忆项关联 user_id 和 agent_id附带内容、类型、时间戳、metadata 等字段。内容字段会做向量化索引生成 embedding 存入向量索引同时原始文本也存在关系库里方便结构化查询和人工审计。提示如果你打算把这个项目用到生产环境建议先在小流量下跑一跑确认 SQLite 的并发表现是否符合预期。我自己的体会是单机并发不高时完全没问题但如果 QPS 上来了优先考虑把存储后端切换到专业的向量数据库。3. 跨 Agent 记忆共享的边界设计3.1 双维度隔离与共享模型很多人第一次看到 user_id 和 agent_id 同时存在时会困惑到底哪个维度是隔离的哪个维度是共享的我的理解是ai-memory 这个项目在这两个维度上很灵活但如果你要把它用好需要明确自己的“记忆共享矩阵”。我整理了一个四象限模型大家可以直接套用维度组合场景典型用法同 user同 agent单 Agent 持续服务一个用户搜历史偏好同 user不同 agent多 Agent 协作服务同一用户跨 Agent 用户画像共享不同 user同 agentAgent 跨用户积累经验沉淀 Agent 自己的知识库不同 user不同 agent全局记忆系统级常识共享实际项目里最常用的是第二行同一个用户多个 Agent 都能读到他的记忆。比如我在客服系统里售前 Agent 记下来的用户偏好售后 Agent 要能查得到这就是“同 user、不同 agent”的场景。ai-memory 的实现方式是用 user_id 作为共享的主键用 agent_id 作为过滤的次键search 时只要不限制 agent_id就能跨 Agent 共享。3.2 user_id 与 agent_id 怎么配才合理这个坑我踩过值得专门写一段。一开始我把 agent_id 当成可选的只在 save 时随便传了个名字search 的时候又忘了传结果召回结果里有大量别的 Agent 产生的记忆。后来我把每个 Agent 的 agent_id 规范化成“模块/角色”的形式比如agent_sales、agent_aftersale、agent_logistics并且在所有 save 和 search 调用里都显式传入。另外user_id 我建议用业务系统自己的用户主键而不是每次会话随机生成的 ID。如果每次登录生成的 session_id 都不一样那跨会话的记忆就串不起来了。记住user_id 是记忆共享的锚点session_id 应该放进 metadata而不是当 user_id 用。3.3 实战场景三个 Agent 协作的客服机器人拿我最近在做的客服系统举例完整跑一遍 ai-memory 的协作链路from ai_memory import Memory memory Memory() # 用户在售前 Agent 这里咨询笔记本 memory.save( user_iduser_123, agent_idagent_sales, prompt我是一名学生预算五千左右想找一台适合编程和游戏的笔记本, ) # 第二天用户找售后 Agent 查物流售后 Agent 先拉一下用户画像 memories memory.search( user_iduser_123, query用户购买偏好, ) # 售后 Agent 看到用户是学生、预算五千、买的笔记本于是能给出更贴切的回答这个例子看起来简单但里面藏着一个架构决策售后 Agent 和售前 Agent 共享的是“用户记忆”不是“对话历史”。ai-memory 的价值就在于它让售后 Agent 不需要完整翻看昨天的聊天记录只需要拿到结构化、可检索的用户偏好这比原样塞聊天记录高效得多也更节省 token。4. 动手把 ai-memory 接进你的项目4.1 安装与快速启动安装非常简单一行命令搞定pip install ai-memory这里的包名和项目名一致装完之后在 Python 里直接 import 就能用。不需要额外配置环境变量默认配置下就已经是开箱即用的状态。如果你想查看已经存储的记忆内容项目还提供了一个简易的界面入口。我当时是直接在终端跑ai-memory命令或者通过 Python 方式启动具体以最新版 README 为准主要目的就是可视化地审查记忆条目方便调试。提示如果你是在公司内网或者离线环境部署记得提前把依赖包下载好。这个项目的依赖不算重但涉及到 LLM 调用时你需要配好对应的 API Key 环境变量。4.2 用一段完整代码跑通记忆存取为了让大家少踩我踩过的坑我直接给一段可以跑的完整流程包括初始化、保存、检索、删除/重置from ai_memory import Memory # 初始化默认本地存储 memory Memory() # 1. 保存记忆 memory.save( user_iduser_001, agent_idagent_research, prompt我正在研究开源项目重点关注 agent memory 方向的方案, metadata{project: daily_open_source} ) # 2. 检索记忆 results memory.search( user_iduser_001, query我最近关注什么方向 ) print(results) # 3. 清理该用户记忆测试环境用 memory.reset(user_iduser_001, agent_idagent_research)这里需要注意几点第一次运行时会初始化本地数据库无需手动建表。search 的 query 参数是可选的但如果你希望做语义检索建议还是传入一个能表达意图的问题。reset 操作是删库级别的生产环境一定要谨慎最好通过权限控制或者人工审核来使用。4.3 把 ai-memory 接到 LangChain 风格的 Agent 上很多做 Agent 开发的朋友都是 LangChain/LangGraph 的用户那 ai-memory 怎么跟这些框架协同我个人的做法是不用 LangChain 自带的 Memory 类而是直接在 Agent 的工具列表里注册一个“记忆工具”把 ai-memory 的 save 和 search 包装成两个工具函数让 LLM 在需要时自己调用。基本思路如下from langchain.agents import Tool from ai_memory import Memory memory Memory() def save_memory(prompt: str) - str: memory.save(user_iduser_001, agent_idagent_main, promptprompt) return saved def search_memory(query: str) - str: results memory.search(user_iduser_001, agent_idagent_main, queryquery) return str(results) tools [ Tool(namesave_memory, funcsave_memory, description保存用户重要信息到记忆), Tool(namesearch_memory, funcsearch_memory, description检索用户历史记忆), ]这样做的好处是记忆行为由 LLM 自主决定——它会在觉得重要的时候 save会在需要回想的时候 search你不需要在每次对话前手动塞历史记录。缺点也明显就是行为有一定随机性需要你在 prompt 里明确告诉它什么信息值得保存。这个取舍我觉得很值得用一点不确定性换来极大的灵活性。4.4 持久化配置与 LLM 的接入ai-memory 本质上需要一个 LLM 来辅助做记忆项的抽取和排序所以你需要把 LLM 的 API Key 配好。默认情况下它会读取环境变量里的 Key如果你用的是自建模型或者改为走本地小模型需要在初始化时传入对应的 llm 配置参数。关于持久化我强烈建议在一开始就规划好存储目录或数据库连接串。默认的本地模式适合开发和演示但生产环境里如果多台机器同时跑 Agent就得把记忆层指向一个共享存储否则 A 机器写的记忆 B 机器读不到跨 Agent 共享就名存实亡了。5. 实测体验、注意事项与方案对比5.1 我在测试中观察到的明显收益项目 Star 数 7.9K 不是没道理的我实际跑完一圈之后最直观的收益有三个。第一接入成本极低。从我 clone 项目到跑通第一个记忆存取只花了几分钟没有繁琐的配置。这让我很快就把注意力放在业务逻辑上而不是折腾基础设施。第二跨 Agent 共享的语义很清晰。user_id agent_id 双维度组合简单但不简陋。跟直接拼一个 Redis 存聊天记录相比ai-memory 多了抽取和排序的逻辑检索质量高了一个档次。第三记忆项统一结构化。save 进去的是原始文本取出来的是经过组织和排序的记忆项。这一点在给 Agent 做 prompt 拼接时非常关键。我之前用 LangChain 的记忆时经常要把原始对话记录做截断和摘要而 ai-memory 的检索结果可以直接作为 context 拼接进 prompt。5.2 容易踩的几个坑再分享几个我实际踩过、或者预判很多人会踩的坑别把敏感数据无差别写进记忆。ai-memory 会抽取 prompt 里的内容如果你在对话里让用户提供了密码、身份证之类的敏感信息这些内容会进入记忆库。虽然它在存储和传输上都做了不少安全考量但数据安全的第一道关永远是业务侧。建议在调用 save 前做一次脱敏过滤。user_id 不一致导致记忆串不起来。这个前面提过如果你在 A 场景用 user_uuid在 B 场景用 user_phoneAI 再强也匹配不了。最好统一用一个稳定的业务主键。search 的 query 不能太宽泛。比如搜“用户信息”这种召回结果往往不够精准。把 query 写成更具体的问题比如“用户对笔记本的预算要求是多少”效果会好很多。这个跟提示词工程一个道理越是具体的问题记忆召回质量越高。生产环境单机内存模式慎用。如果你想多实例部署 Agent 服务需要把记忆存储切到共享存储否则不同实例之间的记忆是隔离的这会导致同一个用户在不同机器上被对待成“两个用户”。5.3 和 Mem0、LangMem 等方案的简单对照研究过程中我也粗略对比了当前比较主流的几个记忆层方案包括 Mem0、LangMem 以及 ai-memory。由于它们都在快速迭代这里只说我在使用层面感受到的差异不是盖棺定论方案核心思路适用场景上手难度ai-memory双维度 user agent轻量可插拔多 Agent 共享用户记忆中小项目低Mem0面向 Agent 的长期记忆平台属性更强希望托管记忆服务接受外部依赖中LangMem跟 LangGraph 强绑定主要是给 LangChain 生态用深度使用 LangChain 技术栈的项目中我的主观结论如果项目是轻量自建希望快速落地、不被框架锁死ai-memory 是性价比最高的如果你的技术栈已经是 LangChain 全家桶LangMem 的集成可能更顺如果希望用现成的托管服务、少操心运维Mem0 这类平台值得了解。但核心架构思路其实都一样把记忆独立出来而 ai-memory 恰恰把这个思路做到了最轻、最直白。5.4 我的选型建议最后说点个人的选型判断。如果你的系统满足下面任一条件ai-memory 非常值得一试你有多个 Agent 在服务同一批用户且用户画像要互通。你不想被某个 Agent 框架绑定希望记忆层可以独立替换。你不想投入太多精力在记忆系统建设上但又不满足于简单的聊天记录回填。你想在现有 LLM 应用里快速加一个“记忆增强”能力看看效果再决定要不要加大投入。反过来如果你的项目只是单 Agent 单会话或者你已经有成熟稳定的记忆系统那完全没必要为了用而用。工具是为场景服务的不是用来堆砌的。6. 基于 ai-memory 的扩展思路与工程化考虑6.1 把记忆层做成公司内部的基础服务我在实际项目里感受到一个趋势记忆层不应该只服务某个 Agent而应该作为 AI 应用内的基础服务存在。ai-memory 完全可以承担这个角色。你可以把它封装成一个内部 API 服务统一管理 user_id 体系、统一做权限控制、统一审计记忆内容。这种“记忆中台”的架构思路在多部门都有 AI 产品时特别有价值。比如客服部门、营销部门、用户增长部门各自跑着一套 Agent但面对的是同一批用户。如果每个部门单独建一套记忆库用户画像就再次被割裂。而 ai-memory 这种可以独立部署、支持双维度检索的特性天然适合做公司内部的“记忆总线”。6.2 与强化学习中 reward 信号的配合这个点比较进阶但我在调研时留意到 ai-memory 生态里有朋友讨论过将记忆层与强化学习的 reward 机制结合。具体来说Agent 的一次决策如果被标记为“成功”或“失败”这个反馈可以转换成记忆项存入记忆层。后续 Agent 在相似场景中就多了一个参考信号。AI Agent 领域的项目一直在强调 agent 记忆和外部记忆ai-memory 的 dual-memory 设计给了这种扩展一个很自然的载体用户维度的记忆告诉 Agent“这个用户是谁”Agent 维度的记忆告诉 Agent“这种情况下怎么做更好”。两者叠加就形成了越来越贴近真实业务的决策辅助。6.3 和 a-memguard 这类安全工具的联动思考热词里有朋友在关注 a-memguard这是一个面向 LLM Agent 记忆的主动防御框架正好和 ai-memory 形成互补。ai-memory 负责让记忆“存得进、找得到”a-memguard 负责保障记忆写入和读取过程中的数据安全。我在实际架构里也做了类似的分层基础记忆层用开源库快速搭建安全性通过外层的过滤和审计机制来补。记住一个原则任何从对话里抽取用户信息并长期存储的机制都需要伴随严格的用户授权与敏感信息治理。不管项目本身有没有自带安全能力业务侧必须有一个“记忆内容审批流”尤其是涉及 C 端用户数据时这个不能省。6.4 如果你打算为 ai-memory 做二次开发最后给想写代码贡献的同仁一些参考方向。我看源码时首先关注的几个点抽取 prompt 模板的优化空间很大default 模板比较通用如果你的业务领域很垂直自定义抽取模板能显著改善记忆质量排序算法也有迭代空间目前更多取决于向量检索的相关性如果结合记忆新鲜度衰减、记忆重要性权重等信号效果会更贴近真实业务需求。这些方向改造成本都不小但一旦做好了很容易在社区里沉淀下来。毕竟 7.9K Stars 的项目能被记住的一定不只是“能用”而是“好用且不断进化”。就我自己的实践感受来说ai-memory 是我目前看到的把“跨 Agent 记忆层”这个理念落地得最轻巧的方案。它没有堆砌复杂概念也没有强制你接受某种重型架构而是用两个 ID 加两个核心方法就把多 Agent 记忆共享的核心问题讲清楚了。如果你正在被 Agent 记忆问题困扰不妨先拿它把原型跑通再根据自己的业务场景慢慢打磨。
