ai-memory：为AI Agent打造跨智能体共享的长期记忆层基础设施

1. 项目概述1.1 为什么 Agent 需要一个像样的记忆层每天一个开源项目今天聊 ai-memory。先说结论这不是又一个 Chat 框架也不是 LLM 封装库而是一个专门给 Agent 做记忆层的基础设施项目目前 7.9K Stars在 GitHub 上已经被很多 Agent 相关项目集成。如果你最近在折腾 Agent、想做一个多轮对话更自然的 AI 助手、或者被“Agent 一聊新话题就失忆”折磨到想摔键盘这个项目值得你花十分钟认真看一下。事情的起因其实很现实。我在做 Agent 开发的时候遇到过一堆类似的情况早上问过一句话下午再问它就完全不知道同一个项目里串了好几个机器人各自为政信息完全没法共享想让 Agent 长期记住用户偏好比如“这个用户喜欢简洁的回答”结果每次都要在 Prompt 里写一遍换个 Agent 就得重新教。这些问题本质上都不是模型能力问题而是缺一个能跨 Agent 共享、可持久化、能语义检索的记忆层。ai-memory 就是为了解决这个问题出现的。它在设计上想得很清楚——不做过多的 LLM 调度不碰 Agent 的执行逻辑只做一件事把记忆这件事单独拎出来做成一个可以独立部署、可以被任意 Agent 调用的服务。用官方的话说它是“A generalized memory layer for AI Agents”意思是任何 Agent不管你是 L1 工具型 Agent还是 L2 编排型还是 L3 多 Agent 协作型都可以挂到这套记忆系统上就像给电脑接了一个移动硬盘一样即插即用。1.2 它到底帮你解决了什么事我拆三层来说。第一层是记忆的写入和读取传统方案是让每个 Agent 自己把上下文写进 Prompt 或本地变量ai-memory 把它收拢成统一的 API 和数据结构Agent 只负责随时存取。第二层是记忆的持久化和检索底层用向量存储 混合检索常规的短时记忆能留得住长时记忆也能被批量召回。第三层是跨 Agent 的共享这是它区别于普通记忆插件最核心的一点——只要你把这些 Agent 挂到同一个 memory service 下面它们天然就是共享记忆的简而言之这就是一个多智能体协作的“公共大脑”。为了让你有个直观感受我列三个典型的使用场景多轮对话的 AI 助手你今天问“帮我看看 MySQL 慢查询日志”一周后再问“上次那个慢查询后来怎么样了”它能想起来。多 Agent 协作任务你有一个写代码的 Agent一个查文档的 Agent一个做代码 review 的 Agent它们可以共享同一个项目背景和决策记忆。用户画像与个性化Agent 能记住你偏好的代码风格、语言习惯、时间安排而不是每轮对话都从零开始理解。2. 核心设计思路与技术架构2.1 记忆层架构与 RAG 的分工差异网上很多人在问 ai-memory 和 RAGRetrieval-Augmented Generation有什么区别。我说一个比较容易理解的区别RAG 解决的是“外挂知识”的问题是把外部文档分块、向量化然后根据用户问题去检索相关内容再注入提示词它的核心是“文档”。而 ai-memory 解决的是“会话演化”的问题它是把 Agent 与用户、Agent 与 Agent 之间的交互信息结构化地沉淀下来它的核心是“行为轨迹”和“状态快照”。你可以这么理解RAG 是让人从书架上拿一本书来看ai-memory 是让人记住自己看过的书、以及看书时的感想和思考过程。两者是可以并存的实际项目中我经常同时用RAG和记忆层一个负责事实知识一个负责上下文状态互不冲突。从系统架构上看ai-memory 的典型部署分为三个环节内存索引层负责把新的对话记录、任务反馈、决策信息进行清洗和向量化。它其实不是一个简单的“写进数据库”的过程而是先要做信息提炼排除掉噪音如“嗯”“好的”“再见”这类无用话术然后再用 embedding 模型把重要信息转为向量。检索与召回层通过语义相似度把跟当前问题最相关的历史记忆找出来。和我之前讲的普通向量检索有所不同ai-memory 在召回时做了“时间权重加权”和“重要性排序”也就是说近期发生的记忆和与当前主题直接相关的记忆会得到更高的分数而不是拿一个固定阈值一刀切。Agent 存储接入层统一封装成 Agent 可以调用的 API 或 Python SDK让记忆的读写对上层 Agent 透明化。这一层解决了一个很重要的问题——你在用 LangChain 写 Agent A用 AutoGen 写 Agent B这两者之间本来是没有互相通信通道的但它们可以同时访问同一个记忆服务从而做到“跨框架”信息共享。2.2 跨 Agent 记忆共享的实现逻辑跨 Agent 这个特性是 ai-memory 的核心定位也是和其他记忆项目相比最容易出彩的地方。在实现上它引入了 project、user、agent、run 这类概念来给记忆做分类和隔离。通俗地讲每条记忆都有它的归属对象比如这个记忆来自哪个项目、属于哪个用户、由哪个 Agent 产生、对应哪次运行基于这些字段系统就能做到既能在跨 Agent 之间共享也能做权限换分和局部隔离。举个例子。我起了两个 Agent一个负责资料整理一个负责内容创作。在没有 ai-memory 的情况下资料整理 Agent 找到的信息想给创作 Agent 用只能通过消息队列或者写文件传递非常麻烦。有了 ai-memory 以后资料整理 Agent 把研究结论写入记忆层并标记 project 和 user创作 Agent 在生成内容前先查一下记忆层把前置的研究记忆捞回来就能无缝衔接。整个过程甚至不需要两个 Agent 互相知道对方的存在它们只跟记忆服务打交道即可。这里也意味着如果你在做多 Agent 协作架构想在每个 Agent 之间传递上下文这其实涉及到 Agent 编排的选型问题可能还需要用到 LangGraph 或 AutoGen 这类框架。但 ai-memory 提供了一个更轻量的通用底座——两个框架之间如果互相不兼容硬要让它们直接通信非常痛苦但让它们都把记忆写入同一个服务、从同一个服务读取这个思路实施起来反而简单得多。这也是为什么我把这个项目定义为“记忆层基础设施”它不参与 Agent 的调度逻辑只做信息中转与沉淀。3. 实操过程与部署应用3.1 用 Docker 快速部署一个记忆服务我强烈建议你用 Docker 来部署因为 ai-memory 依赖 Elasticsearch 或 Qdrant 这类外部存储手动配置服务依赖会比较繁琐。官方仓库提供了 docker-compose 编排拉起来就能用非常省心。先看基础环境需求Docker 20.10Python 3.9如果用 SDK 方式调用一个 embedding 模型的 API Key如 OpenAI、Cohere也可以配置本地模型用 Docker Compose 拉起整套服务的步骤如下克隆代码git clone https://github.com/mem0ai/ai-memory.git cd ai-memory查看 Docker Compose 配置核心是三个服务api-serverFastAPI 应用、qdrant向量存储、postgres元数据存储。修改环境变量。打开.env或直接改 docker-compose.yaml把 embedding 服务商配置进去我实测用 OpenAI 的 text-embedding-3-small 最稳定维度 1536性价比也高。启动服务docker-compose up -d确认服务状态curl -X POST http://localhost:8000/memories/ \ -H Content-Type: application/json \ -d {user: zhangsan, text: 用户偏好简洁明了的代码注释不喜欢冗余设计。}看到返回的 memory_id 就说明写入成功。这里要特别说一个容易踩坑的点ai-memory 的环境变量里有一个参数控制 embedding 模型名如果设置错了API 会在启动时正常监听端口但写入记忆时会报 500。我当时排查了很久才发现是模型名没对上建议启动后先做一次写入和召回测试再开始正式集成。3.2 用 Python SDK 进行记忆写入与召回除了 HTTP APIai-memory 还提供了 Python SDK集成到既有 Agent 代码里非常方便。安装命令是pip install memory-ai然后在代码里初始化客户端from memory import Memory from config import Config config Config() memory Memory.from_config(config) # 从记忆中查询 result memory.get_all(user_idzhangsan) # 写入新记忆 memory.add(用户偏好简洁明了的代码注释不喜欢冗余设计。, user_idzhangsan) # 对某段文本做语义搜索 related_memories memory.search(如何写注释, user_idzhangsan)这套 SDK 的设计跟 LangChain 的 VectorStore 很像用过 FAISS 或 Chroma 的人上手会非常快。需要注意的是ai-memory 除了向量检索之外还做了一层自然语言增强。比如你搜索“我该用什么风格写注释”它不仅能召回“用户偏好简洁注释”这条直接记忆还能根据 Agent 之前的对话记录召回“之前讨论过项目命名规范”这类隐性记忆。这种扩展性召回在真实 Agent 场景下非常关键也是它能做到“类人记忆联想”的原因。如果你想直接接入 LangChain它也提供了 LangChain 集成接口可以在 Agent 执行过程中调用记忆服务的工具。我在一个 LangGraph 多节点工作流里让“信息收集”节点把中间产出写入记忆层然后“方案生成”节点从记忆层把这些产出拉回来做输入两者达成了数据流动但代码层面完全解耦这种结构写起来很清爽调试也不用在两个节点之间来回传参。3.3 Agent 记忆配置中短期、长期与永久记忆的实现有不少读者在问 Agent 记忆体系中短期、长期、永久记忆如何实现。ai-memory 的思路值得借鉴。它虽然没有像人一样把时间维度拆得特别死但它实际上是通过“记忆的类型和标签”来实现分层管理的。短期记忆在 Agent 交互过程中产生的瞬时信息默认保存在内存索引层不立即写入持久化存储如果 Agent 进程重启这些记忆默认会被清空。长期记忆被标记为重要或者被重复提及的信息会被写入 Postgres 和 Qdrant在后续对话中可以被检索召回。永久记忆用户画像、偏好设置、项目级约束条件等通过显式 API 写入并打上is_permanenttrue的标记。这类记忆不会被自动清理除非显式删除。这种设计真正的价值在于它允许开发者根据业务场景自由决定哪些信息要“留”哪些信息要“丢”。比如在客服场景里用户当前一次对话的情绪状态就是短期记忆不需要承担太久但用户“对隐私敏感不希望透露财务信息”这类偏好就应该作为永久记忆写入。如果你对 Agent 记忆的层级划分还不熟悉可以直接对照 ai-memory 的这个实现来落地。3.4 记忆检索效果的关键参数与选型使用向量存储加语义检索的项目很多但 ai-memory 在召回质量上的关键区别是“混合检索策略”。它不只用 embedding 相似度还结合了关键词匹配和元数据过滤。在 Qdrant 的底层配置里可以设置hnsw_config的参数来影响检索速度与精度的平衡。我复现下来的经验是对于中小规模记忆集几十万条以内默认 HNSW 参数已经够用不必非得调 M 和 efconstruct。另一个关键参数是 embedding 模型的“维度对齐”。如果你是先存了 1536 维的记忆之后想换成 3072 维的大模型那么新写入的向量和旧向量无法直接比较必须重建索引。这一点务必提前规划。至于为什么我推荐用 Qdrant而不是用 Elasticsearch 或向量插件方案主要在两点。第一是 Qdrant 部署更轻量Docker 镜像小资源占用低第二是 Qdrant 的原生过滤能力很强能很好地配合 ai-memory 的 project/user/agent 元数据做精确提权。Elasticsearch 在文本检索上有传统优势但也意味着你如果要启用向量检索通常还得额外装插件或做字段映射部署成本明显高出一截。我对比过对大部分 Agent 项目目前的记忆量级来说Qdrant 的组合是投入产出比最高的。4. 常见问题与排查技巧实录4.1 记忆写入成功但召回为空的心里没底时刻这是新手接入 ai-memory 时遇到最多的问题。症状是调用 add 写入记忆返回了 memory_id一切正常但等你去 search 的时候却什么都没有。我排查这一类问题的经验是按照顺序检查三件事确认 embedding 模型是否工作正常。很多情况下是因为 embedding 服务的 API 调用失败被 ai-memory 静默吞掉了导致向量索引没有真正建立。检查 Qdrant 的对应 collection 是否存在以及 collection 内的向量数量。如果 Qdrant 里是空的说明写入根本没有落到向量库。确认查询时的 user_id 与写入时的 user_id 是否一致。ai-memory 默认按 user_id 做区分如果写入用 user_a查询用 user_b那自然是查不到的。这里有个容易被忽略的要点查询时如果开启了limit且设置了relevance_threshold当相似度得分低于阈值时即使有相关记忆也不会返回。建议调试阶段把阈值调到 0.1 以下确保不是被过滤掉了等问题排查完再恢复到正常偏好值。4.2 向量库容量增长过快及数据清理策略用久了你会发现记忆条目会越积越多如果不做任何清理不仅查询时会搜索到大量噪音信息还可能拖慢检索速度。ai-memory 并没有像人脑一样会自动遗忘但你可以通过它的 REST API 来做定时清理。我用的策略是设置一个定时任务每天对长期记忆做一次“衰减”处理超过三个月且从未被召回的记忆降低其重要度分数超过半年且多次未被召回的直接删除。这种机制应对真实场景是有效的能给系统制造一种“记得住重要的事、放得下无用的事”的效果。另一种方式是利用 ai-memory 自带的memory_id关联关系。如果你在写入时把同一段对话产生的多条记忆进行了关联绑定那么删除时可以通过db_path或memory_id批量操作避免残留孤立数据。实测下来用这种方式清理后Qdrant 集合的碎片率明显下降召回准确率也有所回升。4.3 多 Agent 并发写入导致的一致性冲突最后说一个我在做多 Agent 协作时遇到的问题多个 Agent 同时往同一个用户、同一个项目写记忆时偶尔会出现新写入的记忆覆盖旧的、或者重复写入的情况。根本原因是 ai-memory 的写入接口在默认情况下不做严格的防重和合并它把“怎么处理重复信息”这层逻辑交给了上层应用。解决思路有两个。第一个是依赖接口层的数据结构来保证唯一性例如写入前先做一次search如果发现已存在高度相似的记忆就不再新增而是更新已有记录的updated_at和关联信息。第二个是做好业务层的语义合并如果两个 Agent 给出的信息存在上下位关系可以用 LLM 调用一次“信息合并”把结果作为一条新记录写入而不是让两条原始记录同时存在。这种在后端加入归并的做法能让记忆层保持整洁也为后续召回节约开销。简单说ai-memory 提供的是稳固的“货架”但把东西放得整齐这件事还是需要上层应用自己多上心。5. 项目选型与横向对比5.1 已有记忆方案横向对比与适用场景关心 Agent 记忆的人一定绕不开 Mem0 和 Zep 这两个名字。做技术选型的时候横向对比是必须的。我把自己实际跑过的三种方案列在下面维度ai-memoryMem0Zep定位跨 Agent 通用记忆层记忆管理服务用户记忆与分析服务跨 Agent 共享原生支持设计核心支持但不突出以用户画像为主数据存储Qdrant Postgres多平台存储适配向量存储 图存储集成方式Python SDK、HTTP APIPython SDKPython SDK、Graphiti适用场景多 Agent 协作、状态共享个性化助手、上下文管理长期用户画像、社交场景部署成本Docker Compose 即可完全本地部署需要自行管理数据库可云端可本地对于一个标准的 Agent 应用ai-memory 和 Mem0 其实都能用。区别大概在定位上Mem0 更偏向于“为当前 Agent 提供更好的记忆体验”而 ai-memory 关键差异是把跨 Agent 共享放在了优先级最高的位置上。如果你只维护一个单机器人助手两个项目体验接近一旦你的架构里出现多个 Agent一个 Agent 的输出要作为另一个 Agent 的输入ai-memory 的价值就会立刻体现出来。Zep 的情况比较特殊它引用了图存储来做知识图谱适合需要做深层关系分析的场景例如用户关系网络或复杂事件链推理但如果只是做对话状态持久化它显得有些重。对我来说选型的核心判断依据始终是我需要的是信息“存得牢”还是信息“传得通”。前者用 Mem0 就够了后者必须上 ai-memory。5.2 7.9K Stars 说明什么社区活跃度怎么看一个开源项目到了 7.9K Stars说明它已经过了“玩具项目”阶段进入了有稳定用户群的成熟期。这个量级的项目通常意味着三件事第一代码质量和项目规划经过了真实用户校验长期维护有保障。大多数半途夭折的 AI 项目都是卡在 1K Stars 以内能到 5K 以上基本说明有人真的在用。第二社区贡献和反馈循环已经跑通。我在 GitHub Issues 区看到不少真实问题包括不同 embedding 模型兼容、Qdrant 版本升级迁移、多线程写入锁竞争等这些都不是论文式的假问题而是真实业务场景下的肉搏记录。第三周边生态开始出现。目前官方文档里已经有 LangChain 集成指南社区里也有人写了 FastAPI 封装和 Streamlit 可视化记忆查看工具。生态起来之后你拿到的不只是一个库而是一个周边工具圈。在我看来选开源项目可以适度关注 Star 数量但不能唯 Star 论。更关键的是看它解决的问题是否真实、维护者对 Issue 的响应速度、以及代码中是否体现出了“站在使用者角度思考”的设计细节。ai-memory 在这方面做得算不错。6. 实战扩展与应用场景延展6.1 用 ai-memory 搭建带长期记忆的个人知识助手前面讲的都是接入层面的东西。聊一个完整场景用 ai-memory 搭建一个带长期记忆的个人知识助手。我的思路是分成三条数据线。第一条线是“用户基本信息线”包括姓名、职业、兴趣、常用语言作为永久记忆写入每次对话都默认加载第二条线是“短期任务线”比如你正在做的项目、当前遇到的卡点作为长期记忆保存过一段时间后自动淘汰第三条线是“交互偏好线”比如用户喜欢用 bullet points 还是长篇分析这部分信息通过对话分析后写入并在后续回答时动态召回。在实现上我封装了一层MemoryService统一封装读写操作上层 Agent 永远不需要直接面对 Qdrant 和 Postgresclass MemoryService: def __init__(self, config): self.memory Memory.from_config(config) def save_user_fact(self, user_id, fact): self.memory.add(fact, user_iduser_id, metadata{type: permanent}) def get_user_context(self, user_id, query): # 混合召回先按用户检索再按相关性排序 results self.memory.search(query, user_iduser_id) return results这样封装的好处在于如果哪一天想从 ai-memory 切换到别的存储方案只需要替换 MemoryService 的内部实现上层的 Agent 逻辑一行都不用动。6.2 多 Agent 协作的数据共享模式至于多 Agent 协作这块我的建议是不要把记忆层想成简单的 KV 存储最好是把它当成消息总线的替代。Agent A、Agent B 之间如果通过消息传递协作会陷入消息格式难统一、消息丢失难追踪的问题如果通过记忆层协作A 把自己的处理结果以“结构化记忆”写入B 在需要时用语义检索拉取整个过程天然具备容错性——即使 B 延迟执行也可以因为记忆还在那里不会因为消息过期而丢失。在这种模式下每个 Agent 只是记忆的读写者记忆服务提供隔离、标签、索引和检索两人互不感知对方的存在。整个系统达到了“软性解耦”这在工程上是比较舒服的状态。7. 经验总结与踩坑备忘最后分享几条实际操作下来的个人体会比较零散但每条都是真金白银。第一在使用 ai-memory 时默认情况下要留意数据同步特别是长时间运行后的存储增长问题。不要把所有内容都当成永久记忆写入否则后期检索时你会发现系统“什么都记得但什么都说不清”。该忘的就要让它忘做记忆系统跟做人一样放下才能轻装前行。第二写 Agent 记忆时要讲究“语义密度”不要存流水账。比如“用户说今天的菜咸了”这类瞬时信息如果不做提炼你最终会得到一条条没有参考价值的记录但如果是用 LLM 做一次信息合并后存的“用户偏爱清淡口味”这条记忆未来会反复发挥作用。第三如果要在生产环境使用建议在 ai-memory 前面加一层自己的逻辑做身份认证、权限管理和数据校验这些事官方没有全套实现需要结合你的实际业务来补齐。第四多关注官方仓库的 Releases 和 CHANGELOGai-memory 的 API 目前还在快速演进中有些字段命名和参数在不同版本间会有微调直接抄网上旧教程时一定要核对版本号。我自己就在从 0.1.x 升级到 0.2.x 时踩过一次参数不兼容的坑。总的说来ai-memory 是当前 Agent 记忆层开源方案里思路较清晰、工程实现较成熟的一个选择。它没有盲目叠加概念而是把一个特定问题解决得足够到位并且留出了很强的扩展空间。如果你正在做 Agent 相关开发不管是个人的 AI 助手还是团队级的多 Agent 协作系统都值得拿它来当记忆层的底座试一试。