10. Library Usage Guide

开源 Agent Memory 库的作用与使用方式

这一章从“能不能拿来用”的角度阅读开源 Agent Memory 库：它们分别解决什么问题、源码入口在哪里、最小接入流程是什么、上线时还要补哪些边界。

第 9 章回答实现路线如何比较，第 10 章回答具体库怎么落地。这里不再按 star 或表格排序，而是按工程接入习惯拆解：先判断库的定位，再看源码入口，再看 add / remember / search / recall / update_context 这些最小操作，最后判断它适不适合你的 agent 类型。

Library Guide

开源 Agent Memory 库的作用与接入方式

每张卡片对应一个可参考的库或框架模块，重点放在源码中可追踪的入口、最小接入流程和适用边界。

01 · Memory Service

mem0

可直接接入

作用：给任意 agent 增加长期事实、偏好和用户画像记忆。它把抽取、存储、搜索和历史变更封装成 add/search/history 这类 API。

源码依据

README 展示了 Memory().search 与 Memory().add 的聊天接入方式；本地源码包含 mem0/memory/main.py、storage.py 和多个 vector store adapter。

mem0/README.mdmem0/memory/main.pymem0/memory/storage.pymem0/vector_stores/*

适用场景

个人助手、客服、教育、健康、生产力工具等需要长期用户事实和偏好记忆的 agent。

接入步骤

1安装 mem0ai，或选择 self-hosted / hosted 平台。
2在每轮回复前用 search 按 user_id 找回相关记忆。
3把返回记忆拼入 system prompt 或工作记忆。
4回复后把用户消息和助手回复交给 add，让系统抽取长期事实。
5上线前补 user_id、agent_id、project_id、删除和纠错策略。

最小代码形态

from mem0 import Memory

memory = Memory()
memories = memory.search(query=user_msg, filters={"user_id": user_id}, top_k=3)
context = "\n".join(f"- {m['memory']}" for m in memories["results"])
# call your LLM with context
memory.add(messages, user_id=user_id)

注意：默认长期写入很方便，但要避免把一次性话语、错误工具结果和临时偏好写成稳定事实。

02 · Stateful Agent Runtime

Letta

适合长期 agent

作用：直接创建带 memory blocks 的 stateful agent，让核心记忆常驻上下文，并用外部档案记忆承接更长历史。

源码依据

README 展示了 letta-client 创建 agent 时传入 memory_blocks；源码的 prompts 和 function_sets 中能看到 core memory 与 archival memory 工具。

letta/README.mdletta/schemas/memory.pyletta/schemas/block.pyletta/functions/function_sets/base.py

适用场景

长期陪伴、项目协作、个人数字分身、需要稳定人设和长期上下文的 agent。

接入步骤

1安装 letta-client，准备 Letta API key 或自托管服务。
2创建 agent 时定义 human、persona 等 memory_blocks。
3通过 client.agents.messages.create 与 agent 对话。
4让 agent 使用 core memory / archival memory 工具维护长期信息。
5为核心记忆设置审查规则，避免错误内容长期常驻。

最小代码形态

from letta_client import Letta

client = Letta(api_key=LETTA_API_KEY)
agent = client.agents.create(
    model="openai/gpt-5.2",
    memory_blocks=[{"label": "human", "value": "User profile..."}],
)
response = client.agents.messages.create(agent_id=agent.id, input="What do you know about me?")

注意：Letta 是完整 agent runtime，不只是轻量 memory SDK；如果你只想给已有应用补一点偏好记忆，可能比 mem0 / Agno 更重。

03 · AI Memory Platform

Cognee

可直接接入

作用：把文档、对话和用户事实变成长期 AI memory，并通过 knowledge graph、向量和自动路由召回给 agent。

源码依据

README 给出 remember、recall、forget、CLI 和 MCP 的接入方式；AGENTS.md 说明 API、CLI、MCP、UI 的项目结构。

cognee/README.mdcognee/AGENTS.mdcognee/cognee/api/*cognee/cognee-mcp/*

适用场景

企业知识、文档记忆、跨会话 agent 记忆、需要图谱和向量混合能力的知识型 agent。

接入步骤

1安装 cognee，并配置 LLM_API_KEY 或对应模型供应商。
2用 remember 写入长期知识，必要时带 session_id 做会话隔离。
3用 recall 查询，Cognee 自动选择合适搜索策略。
4用 forget 删除 dataset 或清理记忆。
5需要 agent 工具化接入时，可使用 CLI、API server 或 MCP server。

最小代码形态

import cognee

await cognee.remember("Cognee turns documents into AI memory.")
await cognee.remember("User prefers detailed explanations.", session_id="chat_1")
results = await cognee.recall("What does the user prefer?", session_id="chat_1")
await cognee.forget(dataset="main_dataset")

注意：Cognee 更像 memory platform；接入前要明确 dataset、tenant、session 和权限边界。

04 · Temporal Graph Memory

Graphiti

适合关系型记忆

作用：把事件、对话和 JSON 数据写成带时间的实体关系图，用图搜索、向量、BM25 和重排找回动态事实。

源码依据

quickstart 示例展示 Graphiti 初始化、build_indices_and_constraints、add_episode 和 search；源码包含 nodes、edges、search 模块。

graphiti/examples/quickstart/quickstart_neo4j.pygraphiti_core/graphiti.pygraphiti_core/nodes.pygraphiti_core/search/search.py

适用场景

客户关系、组织知识、项目事件流、角色关系、需要时间变化解释的长期记忆。

接入步骤

1准备 Neo4j、FalkorDB、Kuzu 或 Neptune 等图后端。
2初始化 Graphiti，并建立索引和约束。
3用 add_episode 写入文本、消息或结构化 JSON。
4用 search 查询相关关系和事实。
5把搜索结果整理成 evidence，再注入 agent prompt。

最小代码形态

from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType

graphiti = Graphiti(neo4j_uri, neo4j_user, neo4j_password)
await graphiti.build_indices_and_constraints()
await graphiti.add_episode(name="event-1", episode_body=text, source=EpisodeType.text)
results = await graphiti.search("What changed about this customer?")

注意：图谱记忆的主要成本是实体消歧、脏边清理和图维护；关系不复杂时不要过早上图。

05 · Local-first Memory OS

EverOS

本地优先

作用：把 agent memory 以 Markdown-first 方式沉淀到本地，同时用 SQLite 和 LanceDB 做派生索引和混合检索。

源码依据

QUICKSTART 展示服务/API、Markdown 目录结构和 cascade 重建索引；README 说明 service、memory、persistence 分层。

everos/QUICKSTART.mdeveros/src/everos/service/memorize.pyeveros/src/everos/service/search.pyeveros/src/everos/memory/cascade/*

适用场景

本地优先助手、隐私敏感记忆、小团队知识沉淀、需要人类可读和可迁移 memory 的系统。

接入步骤

1启动 EverOS service 或使用 CLI/API。
2把会话级事件提交给 memorize，生成 episode、atomic fact、profile、skill 等 memory cell。
3用 search 按用户、session、kind、query 召回相关记忆。
4让 cascade watcher 同步 Markdown 与派生索引。
5用文件系统和版本管理审计长期记忆。

最小代码形态

POST /memorize
{
  "user_id": "alice",
  "session_id": "demo-001",
  "messages": [{"role": "user", "content": "I climb in Yosemite every spring."}]
}

POST /search
{"user_id": "alice", "query": "Where does Alice climb?"}

注意：本地可审计是优势，但也意味着要管理文件、索引、同步和部署复杂度。

06 · LangGraph Memory Toolkit

LangMem

框架内接入

作用：给 LangGraph / LangChain 生态提供长期记忆抽取、搜索、store 管理和 memory tools。

源码依据

src/langmem/__init__.py 暴露 create_memory_manager、create_memory_store_manager、create_search_memory_tool；extraction.py 给出结构化记忆和 BaseStore 示例。

langmem/src/langmem/__init__.pylangmem/src/langmem/knowledge/extraction.pylangmem/examples/standalone_examples/custom_store_example.py

适用场景

已经使用 LangGraph / LangChain 的 agent，需要标准化长期记忆抽取、更新和检索。

接入步骤

1准备 LangGraph BaseStore，例如 InMemoryStore 或持久化 store。
2用 create_memory_store_manager 定义抽取模型、namespace 和 schema。
3对新对话调用 manager，让它新增或更新长期记忆。
4用 create_memory_searcher 或 create_search_memory_tool 在推理前召回相关记忆。
5用 namespace 区分用户、团队、项目和 agent。

最小代码形态

from langmem import create_memory_store_manager, create_memory_searcher
from langgraph.store.memory import InMemoryStore

store = InMemoryStore(index={"dims": 1536, "embed": "openai:text-embedding-3-small"})
manager = create_memory_store_manager("openai:gpt-4o-mini", store=store, namespace=("memories", "user-123"))
await manager.ainvoke({"messages": conversation})
searcher = create_memory_searcher("openai:gpt-4o-mini", namespace=("memories", "{langgraph_user_id}"))

注意：LangMem 是工具包，不是独立平台；BaseStore、namespace、写入策略和治理仍要按应用设计。

07 · Agentic Memory Research

A-MEM

研究型实现

作用：用 AgenticMemorySystem 管理可演化 memory note，自动生成 tags、context、keywords，并用 ChromaDB 做语义搜索。

源码依据

README 和 examples/sovereign_memory.py 展示 AgenticMemorySystem、add_note、read、search_agentic、update、delete；tests 覆盖关系和 consolidation。

a-mem/README.mda-mem/agentic_memory/memory_system.pya-mem/examples/sovereign_memory.pya-mem/tests/test_memory_system.py

适用场景

研究 agentic memory、经验组织、记忆演化和 Zettelkasten 式链接的原型系统。

接入步骤

1从源码安装 A-MEM，配置 embedding model 和 LLM backend。
2初始化 AgenticMemorySystem。
3用 add_note 写入记忆，可附带 tags、category、timestamp。
4用 read 或 search_agentic 读取与搜索。
5需要时调用 update、delete、consolidate_memories 或关系查找方法。

最小代码形态

from agentic_memory.memory_system import AgenticMemorySystem

memory_system = AgenticMemorySystem(
    model_name="all-MiniLM-L6-v2",
    llm_backend="openai",
    llm_model="gpt-4o-mini",
)
memory_id = memory_system.add_note("User values local processing.", tags=["privacy"])
results = memory_system.search_agentic("sovereignty", k=3)

注意：它更像研究实现，不是开箱即用的生产平台；部署、权限、多租户和观测需要自己补。

08 · Composable Memory Blocks

LlamaIndex Memory

组件化接入

作用：在 LlamaIndex agent / chat engine 中组合短期 chat memory、summary buffer、vector memory 和 memory blocks。

源码依据

core/memory 中有 Memory、ChatMemoryBuffer、ChatSummaryMemoryBuffer、VectorMemory、Static/Vector/Fact memory blocks。

llama-index-core/llama_index/core/memory/memory.pyllama-index-core/llama_index/core/memory/chat_memory_buffer.pyllama-index-core/llama_index/core/memory/memory_blocks/*

适用场景

RAG agent、文档助手、已经基于 LlamaIndex 的应用，需要灵活组合短期和长期记忆块。

接入步骤

1选择短期 buffer、summary buffer 或 Memory + memory blocks。
2把 Memory 对象传给 agent 或 chat engine。
3在每轮消息后让 memory 记录聊天历史或 flush 到块。
4需要长期语义召回时加入 VectorMemoryBlock 或 VectorMemory。
5按 token_limit 和 block priority 调整上下文预算。

最小代码形态

from llama_index.core.memory import Memory, ChatMemoryBuffer

chat_memory = ChatMemoryBuffer.from_defaults(token_limit=3000)
# For richer setups, compose Memory with StaticMemoryBlock / VectorMemoryBlock.
# Pass memory into your LlamaIndex agent or chat engine.

注意：组件多但不会自动替你做业务治理；flush、block priority、检索排序和 token budget 需要调。

09 · Framework Memory Interface

AutoGen Memory

接口型接入

作用：在 AutoGen agent 生命周期中接入 ListMemory、ChromaDBVectorMemory、RedisMemory、Mem0Memory 等后端，并通过 update_context 注入模型上下文。

源码依据

autogen_core.memory 定义 Memory、MemoryContent、ListMemory；autogen_ext.memory 提供 ChromaDB、Redis、Mem0 adapter。

autogen_core/memory/_base_memory.pyautogen_core/memory/_list_memory.pyautogen_ext/memory/chromadb/_chromadb.pyautogen_ext/memory/mem0/_mem0.py

适用场景

已经使用 AutoGen 的多 agent 系统，希望统一 memory 接口并替换不同后端。

接入步骤

1选择 Memory 实现：ListMemory 做简单列表，ChromaDB/Redis 做向量记忆，Mem0 adapter 接外部服务。
2用 MemoryContent 写入偏好、事实或上下文。
3在 agent 调用前执行 update_context。
4需要语义搜索时配置对应 vector memory 后端。
5把写入策略放在 agent 或业务层，不要只依赖接口本身。

最小代码形态

from autogen_core.memory import ListMemory, MemoryContent

memory = ListMemory(name="user_memory")
await memory.add(MemoryContent(content="User prefers formal language", mime_type="text/plain"))
await memory.update_context(model_context)

注意：AutoGen 提供的是 memory interface 和 adapters；完整长期记忆策略仍要自己设计。

10 · User Profile Memory

Agno Memory

轻量接入

作用：围绕用户事实和 profile 管理长期记忆，提供 UserMemory、MemoryManager、摘要压缩和增删改查工具化能力。

源码依据

agno/memory/manager.py 包含 add_user_memory、replace_user_memory、delete_user_memory、update_memory_task；strategies/summarize.py 处理记忆压缩。

agno/agno/memory/manager.pyagno/agno/memory/strategies/summarize.pyagno/agno/memory/__init__.py

适用场景

个人助手、轻量用户画像、偏好记忆和不需要复杂图谱的跨会话连续性。

接入步骤

1为 agent 配置 Agno memory DB / storage。
2用 MemoryManager 管理 UserMemory。
3通过 add_user_memory、replace_user_memory、delete_user_memory 做显式维护。
4用 update_memory_task 让 LLM 根据用户消息决定新增、更新或删除。
5用 summarize strategy 压缩同一用户的多条记忆。

最小代码形态

from agno.memory import MemoryManager, UserMemory

manager = MemoryManager(model=model, db=memory_db)
memory_id = manager.add_user_memory(UserMemory(memory="User likes concise answers"), user_id="user-123")
manager.update_memory_task("User now prefers detailed explanations", user_id="user-123")

注意：它偏 profile / user memory；复杂任务状态、关系图谱和经验演化要另行设计。

Project Readings

几个代表项目怎么读

从最小 API 判断接入成本

mem0 和 Cognee 的 remember/add/search/recall 更像独立 memory layer；LangMem、LlamaIndex、AutoGen、Agno 更像框架内 memory module；Letta 更像完整 stateful agent runtime。

Takeaway: API 形态会决定接入成本：独立服务接入快，runtime 能力强但更重，framework module 灵活但治理要自己补。

从存储后端判断适用场景

mem0 更偏向量和混合检索，Graphiti/Cognee 更偏图谱与关系，EverOS 强调 Markdown-first + 本地派生索引，LangMem 依赖 LangGraph store。

Takeaway: 不要只问“有没有 memory”，要问“它把什么东西存成什么形态”。

从上下文注入判断真实效果

有些库返回 memories，需要你手动拼 prompt；有些框架用 update_context 或 memory blocks 自动进入模型上下文；有些 runtime 让核心记忆常驻。

Takeaway: 记忆必须回到 working memory 才会影响 agent，存储只是半条链路。

从治理能力判断是否能上线

研究型或组件型库通常能展示 add/search，但多用户 scope、删除、更正、审计、冲突处理未必开箱即用。

Takeaway: 生产可用性主要看治理，不只看 demo 能不能搜回来。

Architecture Notes

从源码实现角度看这些项目

这一部分补充的是更偏接入落地的判断方法：不只看库名和 star 数，而是看它提供什么 API、依赖什么后端、接入后需要自己补哪些治理能力。

优先选择与你现有 agent 架构同层的库：已有 LangGraph 就优先看 LangMem，已有 LlamaIndex 就优先看其 memory blocks。

如果需要快速加长期偏好记忆，memory service 比完整 runtime 更轻。

如果需要长期人格、核心设定和档案记忆，stateful runtime 更合适。

如果业务核心是关系和时间变化，Graphiti / Cognee 类图谱路线值得优先评估。

如果 memory 必须被人审阅、迁移和版本管理，本地优先路线比黑盒向量库更合适。

接入任何库之前，都先画出写入、存储、召回、注入、删除五条路径。

Misconceptions

读开源 memory 项目时最容易误判的地方

误解一：能 pip install 的 memory 库，就一定能直接生产上线。

误解二：有 search API，就说明上下文注入和 token budget 已经解决。

误解三：图谱 memory 一定优于向量 memory，实际取决于关系和时间是不是核心需求。

误解四：framework memory module 等于完整 memory system。

误解五：研究型 memory 项目能跑 demo，就已经覆盖多用户、权限、删除和审计。

误解六：只要把每轮对话都 add 进去，agent 就会越来越懂用户。

Deep Dive

源码路线解析

库的作用要按边界理解

开源 memory 库大致分成四类：独立 memory service、stateful agent runtime、graph memory platform、framework memory module。它们不是同一层东西，接入方式和责任边界也不同。

mem0、Cognee 更像外部 memory layer，agent 调它们的 API。
Letta 更像 agent runtime，memory 和 agent 生命周期绑定。
Graphiti 更像 temporal graph memory，重点不是聊天历史，而是实体关系和时间事实。
LangMem、LlamaIndex、AutoGen、Agno 更像框架模块，适合嵌入已有 agent 架构。

怎么使用要从写入入口开始

真正接入时先别看架构图，先看第一条记忆怎么进入系统。入口函数通常能暴露库的设计哲学：add 偏记录事实，remember 偏平台化封装，add_episode 偏事件图谱，create_memory_manager 偏抽取和更新流程。

写入入口越自动，越要关心污染治理。
写入入口越显式，越容易控制，但也更依赖业务主动调用。
研究型库常把关系生成和演化放在写入后处理里。
framework module 需要你决定什么时候调用写入。

读取接口不等于 prompt 注入

很多库能 search 或 recall，但返回结果如何进入 prompt 仍然是工程问题。memory 的最终效果取决于 working memory 组装：召回多少、按什么排序、用什么格式注入、和系统指令/工具状态如何共存。

mem0、Cognee、Graphiti 常需要调用方把返回结果整理进 prompt。
AutoGen 的 update_context 和 LlamaIndex 的 memory blocks 更接近框架级注入。
Letta 的 core memory blocks 属于常驻注入，写错的影响也更持久。
召回结果最好带来源、时间和作用域，否则难以调试。

上线前要补的不是代码示例，而是治理

多数 README 展示的是最小成功路径：安装、写入、查询。但生产里的难点是删除、更正、冲突、scope、权限、审计和过期。第 10 章的代码卡片应被理解为接入入口，不是完整上线清单。

至少为 user、agent、project、tenant 设计明确作用域。
提供删除和更正入口，而不是只追加记忆。
为自动写入设置阈值、黑名单或人工审查。
记录 memory 来源，方便解释、回滚和排错。

Failure Modes

常见失败模式

只复制 quickstart，没有设计 user_id / session_id / project_id，导致记忆串线

把 search 返回结果原样塞进 prompt，造成上下文噪声和 token 浪费

把研究型实现当生产服务用，忽略多租户、权限、可观测和迁移

在关系不复杂的场景强上图谱，增加抽取、消歧和维护成本

只支持新增记忆，不支持更正和删除，长期运行后污染不可控

把框架接口误以为完整方案，忘了写入策略和预算分配仍在业务层

Previous Chapter

9. Open-source Implementations

开源 Agent Memory 实现项目对比

聚焦真正实现 agent memory 的开源项目与实现路线

←

Next Chapter

已经是最后一章

你已经读到最后一章了，可以回总览重新跳读，或者继续回看前面的章节。