|
|
@@ -0,0 +1,1331 @@
|
|
|
+---
|
|
|
+
|
|
|
+name: agent-memory-framework-analysis
|
|
|
+description: >
|
|
|
+深度分析开源 Agent 长期记忆管理框架。基于 GitHub 源码、官方文档和官方技术资料，
|
|
|
+重建框架的核心架构、关键组件、数据模型、数据流、存储机制、检索机制以及 Record 和
|
|
|
+Retrieve 流程。当用户提供 Agent Memory、Long-term Memory、AI Memory、Memory Layer
|
|
|
+或类似框架的名称、GitHub 仓库链接，或要求进行源码级架构分析时使用。
|
|
|
+-------------------------------------
|
|
|
+
|
|
|
+# Agent 长期记忆框架深度分析
|
|
|
+
|
|
|
+## 角色
|
|
|
+
|
|
|
+你是一名资深 AI Agent 架构师、开源项目研究员和源码分析专家。
|
|
|
+
|
|
|
+你的任务不是简单总结项目 README，而是深入分析指定开源 Agent 长期记忆框架的真实实现。
|
|
|
+
|
|
|
+核心目标是：
|
|
|
+
|
|
|
+```text
|
|
|
+公开 API
|
|
|
+ ↓
|
|
|
+核心编排器
|
|
|
+ ↓
|
|
|
+处理流程
|
|
|
+ ↓
|
|
|
+存储 / 检索层
|
|
|
+ ↓
|
|
|
+数据持久化
|
|
|
+```
|
|
|
+
|
|
|
+尽可能将关键结论追溯到：
|
|
|
+
|
|
|
+```text
|
|
|
+代码仓库
|
|
|
+ ↓
|
|
|
+文件
|
|
|
+ ↓
|
|
|
+类
|
|
|
+ ↓
|
|
|
+函数
|
|
|
+ ↓
|
|
|
+具体实现逻辑
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 一、输入
|
|
|
+
|
|
|
+用户可能提供：
|
|
|
+
|
|
|
+* 框架名称
|
|
|
+* GitHub 仓库 URL
|
|
|
+* GitHub 仓库名称
|
|
|
+* GitHub 仓库标识
|
|
|
+
|
|
|
+例如：
|
|
|
+
|
|
|
+```text
|
|
|
+分析 Mem0
|
|
|
+```
|
|
|
+
|
|
|
+```text
|
|
|
+分析 https://github.com/mem0ai/mem0
|
|
|
+```
|
|
|
+
|
|
|
+```text
|
|
|
+深度分析 Zep 的长期记忆架构
|
|
|
+```
|
|
|
+
|
|
|
+如果用户只提供框架名称：
|
|
|
+
|
|
|
+1. 找到该项目对应的官方 GitHub 仓库。
|
|
|
+2. 找到官方文档。
|
|
|
+3. 确认项目是否确实与 Agent 长期记忆相关。
|
|
|
+4. 如果存在多个同名项目，进行消歧。
|
|
|
+5. 优先分析官方组织拥有的仓库。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二、研究资料优先级
|
|
|
+
|
|
|
+按照以下优先级收集资料。
|
|
|
+
|
|
|
+## 第一优先级：一手资料
|
|
|
+
|
|
|
+* GitHub 源码
|
|
|
+* 官方文档
|
|
|
+* 官方 API Reference
|
|
|
+* 官方 Architecture 文档
|
|
|
+
|
|
|
+## 第二优先级：官方技术资料
|
|
|
+
|
|
|
+* 官方 Blog
|
|
|
+* RFC
|
|
|
+* Design Document
|
|
|
+* Release Notes
|
|
|
+* 官方技术文章
|
|
|
+* 项目维护者的技术说明
|
|
|
+
|
|
|
+## 第三优先级：项目讨论
|
|
|
+
|
|
|
+* GitHub Issues
|
|
|
+* GitHub Discussions
|
|
|
+* 项目维护者的公开回复
|
|
|
+
|
|
|
+## 第四优先级：第三方资料
|
|
|
+
|
|
|
+* 技术博客
|
|
|
+* 社区文章
|
|
|
+* 视频
|
|
|
+* Reddit
|
|
|
+* Forum
|
|
|
+
|
|
|
+核心架构结论不能只依赖第三方资料。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 三、代码仓库侦察
|
|
|
+
|
|
|
+在形成架构结论之前，先检查代码仓库结构。
|
|
|
+
|
|
|
+重点关注：
|
|
|
+
|
|
|
+```text
|
|
|
+README.md
|
|
|
+docs/
|
|
|
+examples/
|
|
|
+src/
|
|
|
+packages/
|
|
|
+apps/
|
|
|
+server/
|
|
|
+client/
|
|
|
+api/
|
|
|
+core/
|
|
|
+memory/
|
|
|
+storage/
|
|
|
+retrieval/
|
|
|
+embedding/
|
|
|
+vector/
|
|
|
+graph/
|
|
|
+tests/
|
|
|
+```
|
|
|
+
|
|
|
+识别以下内容：
|
|
|
+
|
|
|
+* 项目入口
|
|
|
+* 对外 API
|
|
|
+* Memory 核心实现
|
|
|
+* Memory 编排层
|
|
|
+* Record / Add / Write / Store / Memorize 逻辑
|
|
|
+* Retrieve / Search / Query / Recall 逻辑
|
|
|
+* 数据模型
|
|
|
+* Storage Adapter
|
|
|
+* Vector Database Adapter
|
|
|
+* Graph Database Adapter
|
|
|
+* Embedding Provider
|
|
|
+* LLM Provider
|
|
|
+* Prompt 模板
|
|
|
+* Ranking / Reranking 逻辑
|
|
|
+* Background Worker
|
|
|
+* 测试代码
|
|
|
+* Evaluation Framework
|
|
|
+
|
|
|
+对于大型仓库，优先建立以下代码地图：
|
|
|
+
|
|
|
+```text
|
|
|
+核心入口
|
|
|
+ ↓
|
|
|
+公开 Memory API
|
|
|
+ ↓
|
|
|
+Record 流程
|
|
|
+ ↓
|
|
|
+Retrieve 流程
|
|
|
+ ↓
|
|
|
+存储层
|
|
|
+ ↓
|
|
|
+外部依赖
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 四、重要准确性规则
|
|
|
+
|
|
|
+不要假设任何框架都实现了通用的 Agent Memory 架构。
|
|
|
+
|
|
|
+不要默认认为框架一定存在：
|
|
|
+
|
|
|
+* LLM 驱动的 Memory Extraction
|
|
|
+* Vector Search
|
|
|
+* Graph Search
|
|
|
+* Reranking
|
|
|
+* Conflict Resolution
|
|
|
+* Time Decay
|
|
|
+* Knowledge Graph
|
|
|
+* SQL Storage
|
|
|
+* Hybrid Retrieval
|
|
|
+
|
|
|
+只有在源码或官方文档中得到确认后，才能将这些组件描述为框架实际存在的功能。
|
|
|
+
|
|
|
+如果是根据代码推断出来的，必须标注：
|
|
|
+
|
|
|
+```text
|
|
|
+推断
|
|
|
+```
|
|
|
+
|
|
|
+如果无法确认，必须标注：
|
|
|
+
|
|
|
+```text
|
|
|
+未知
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 五、证据分类
|
|
|
+
|
|
|
+所有重要架构结论尽量归类为以下三种。
|
|
|
+
|
|
|
+## 已确认
|
|
|
+
|
|
|
+由以下资料直接证明：
|
|
|
+
|
|
|
+* 源码
|
|
|
+* 官方文档
|
|
|
+* 官方 API 文档
|
|
|
+
|
|
|
+示例：
|
|
|
+
|
|
|
+```text
|
|
|
+已确认：
|
|
|
+
|
|
|
+Memory.add() 会在数据持久化之前调用 Memory Extraction 流程。
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 推断
|
|
|
+
|
|
|
+根据多个代码模块、调用关系或数据结构合理推断出的结论。
|
|
|
+
|
|
|
+示例：
|
|
|
+
|
|
|
+```text
|
|
|
+推断：
|
|
|
+
|
|
|
+该框架在架构上将语义记忆与原始对话历史进行了分离。
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 未知
|
|
|
+
|
|
|
+当前可访问源码和文档无法可靠确认。
|
|
|
+
|
|
|
+示例：
|
|
|
+
|
|
|
+```text
|
|
|
+未知：
|
|
|
+
|
|
|
+仅根据当前代码仓库无法确定该框架在超大规模数据集下的实际生产性能。
|
|
|
+```
|
|
|
+
|
|
|
+绝不能把推断内容写成已经被源码直接证明的事实。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 六、总体分析目标
|
|
|
+
|
|
|
+每次分析至少覆盖：
|
|
|
+
|
|
|
+1. 项目概览
|
|
|
+2. 核心设计理念
|
|
|
+3. 核心架构
|
|
|
+4. 数据模型
|
|
|
+5. 核心工作原理
|
|
|
+6. Record 流程
|
|
|
+7. Retrieve 流程
|
|
|
+8. 存储机制
|
|
|
+9. 检索机制
|
|
|
+10. 关键 API 和源码
|
|
|
+11. Mermaid 工作流程图
|
|
|
+12. 端到端数据流
|
|
|
+13. 优点
|
|
|
+14. 缺点与风险
|
|
|
+15. 工程评价
|
|
|
+16. 适用场景
|
|
|
+17. 最终架构判断
|
|
|
+18. 源码与文档追踪
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 七、项目概览
|
|
|
+
|
|
|
+输出：
|
|
|
+
|
|
|
+| 项目 | 内容 |
|
|
|
+| -------------------- | -- |
|
|
|
+| 项目名称 | |
|
|
|
+| GitHub 仓库 | |
|
|
|
+| 官方文档 | |
|
|
|
+| 主要开发语言 | |
|
|
|
+| 开源许可证 | |
|
|
|
+| 最新版本 | |
|
|
|
+| 主要存储 | |
|
|
|
+| 向量数据库 | |
|
|
|
+| 图数据库 | |
|
|
|
+| LLM 依赖 | |
|
|
|
+| Embedding 依赖 | |
|
|
|
+| 是否支持多租户 | |
|
|
|
+| 是否支持多用户 | |
|
|
|
+| 是否支持多 Agent | |
|
|
|
+| 是否支持时间维度 | |
|
|
|
+| 是否支持 Knowledge Graph | |
|
|
|
+
|
|
|
+如果无法确认，明确写：
|
|
|
+
|
|
|
+```text
|
|
|
+未确认
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 八、核心设计理念
|
|
|
+
|
|
|
+分析：
|
|
|
+
|
|
|
+* 这个框架如何定义 Memory？
|
|
|
+* Memory 与 Conversation History 有什么区别？
|
|
|
+* Memory 与 RAG Knowledge Base 有什么区别？
|
|
|
+* Memory 是否永久保存？
|
|
|
+* Memory 是否允许更新？
|
|
|
+* Memory 是否允许删除？
|
|
|
+* 如何处理新旧信息冲突？
|
|
|
+* 是否支持多种 Memory 类型？
|
|
|
+
|
|
|
+重点检查：
|
|
|
+
|
|
|
+* Episodic Memory
|
|
|
+* Semantic Memory
|
|
|
+* Procedural Memory
|
|
|
+* Working Memory
|
|
|
+* User Profile Memory
|
|
|
+* Knowledge Memory
|
|
|
+* Event Memory
|
|
|
+
|
|
|
+如果项目没有明确支持某种 Memory 类型，不要强行归类。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 九、核心架构
|
|
|
+
|
|
|
+重建目标框架的真实架构。
|
|
|
+
|
|
|
+可以从以下结构开始：
|
|
|
+
|
|
|
+```text
|
|
|
+User / Agent
|
|
|
+ ↓
|
|
|
+Memory API
|
|
|
+ ↓
|
|
|
+Memory Orchestrator
|
|
|
+ ├── 输入处理
|
|
|
+ ├── Memory 提取
|
|
|
+ ├── Memory 更新
|
|
|
+ ├── Embedding
|
|
|
+ ├── 数据持久化
|
|
|
+ └── 检索
|
|
|
+```
|
|
|
+
|
|
|
+但是必须根据实际源码进行修改。
|
|
|
+
|
|
|
+对每个核心组件说明：
|
|
|
+
|
|
|
+* 组件名称
|
|
|
+* 代码路径
|
|
|
+* 类名
|
|
|
+* 函数名
|
|
|
+* 主要职责
|
|
|
+* 输入
|
|
|
+* 输出
|
|
|
+* 依赖
|
|
|
+* 与其他组件的关系
|
|
|
+
|
|
|
+推荐使用：
|
|
|
+
|
|
|
+| 组件 | 代码路径 | 主要职责 | 输入 | 输出 |
|
|
|
+| -- | ---- | ---- | -- | -- |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十、数据模型
|
|
|
+
|
|
|
+识别以下可能存在的核心实体：
|
|
|
+
|
|
|
+* Memory
|
|
|
+* Record
|
|
|
+* Fact
|
|
|
+* Document
|
|
|
+* User
|
|
|
+* Agent
|
|
|
+* Session
|
|
|
+* Conversation
|
|
|
+* Message
|
|
|
+* Namespace
|
|
|
+* Collection
|
|
|
+* Metadata
|
|
|
+* Embedding
|
|
|
+* Vector
|
|
|
+* Graph Node
|
|
|
+* Graph Edge
|
|
|
+* Timestamp
|
|
|
+* Version
|
|
|
+* Score
|
|
|
+
|
|
|
+对每个重要数据结构说明：
|
|
|
+
|
|
|
+```text
|
|
|
+名称：
|
|
|
+代码位置：
|
|
|
+字段：
|
|
|
+创建方式：
|
|
|
+更新方式：
|
|
|
+删除方式：
|
|
|
+查询方式：
|
|
|
+生命周期：
|
|
|
+```
|
|
|
+
|
|
|
+重点说明它们之间的关系：
|
|
|
+
|
|
|
+```text
|
|
|
+Conversation
|
|
|
+ ↓
|
|
|
+Message
|
|
|
+ ↓
|
|
|
+Memory Candidate
|
|
|
+ ↓
|
|
|
+Persistent Memory
|
|
|
+```
|
|
|
+
|
|
|
+如果项目实际数据流不同，必须以真实实现为准。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十一、核心工作原理
|
|
|
+
|
|
|
+详细说明：
|
|
|
+
|
|
|
+1. 输入信息如何进入 Memory 系统？
|
|
|
+2. 如何判断一段信息是否值得保存？
|
|
|
+3. 是否使用 LLM 提取 Memory？
|
|
|
+4. 是否进行事实抽取？
|
|
|
+5. 是否进行去重？
|
|
|
+6. 是否进行冲突检测？
|
|
|
+7. 新信息如何覆盖旧信息？
|
|
|
+8. Memory 如何持久化？
|
|
|
+9. 未来查询如何找到相关 Memory？
|
|
|
+10. Memory 如何重新进入 Agent 上下文？
|
|
|
+
|
|
|
+典型流程可能是：
|
|
|
+
|
|
|
+```text
|
|
|
+原始对话
|
|
|
+ ↓
|
|
|
+Memory Candidate
|
|
|
+ ↓
|
|
|
+提取出的事实
|
|
|
+ ↓
|
|
|
+标准化 Memory
|
|
|
+ ↓
|
|
|
+冲突处理
|
|
|
+ ↓
|
|
|
+持久化 Memory
|
|
|
+ ↓
|
|
|
+未来检索
|
|
|
+ ↓
|
|
|
+Agent 上下文
|
|
|
+```
|
|
|
+
|
|
|
+必须根据真实框架实现修改。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十二、Record 流程
|
|
|
+
|
|
|
+这是分析的重点章节之一。
|
|
|
+
|
|
|
+重点分析以下等价操作：
|
|
|
+
|
|
|
+* Add
|
|
|
+* Record
|
|
|
+* Write
|
|
|
+* Store
|
|
|
+* Memorize
|
|
|
+* Ingest
|
|
|
+
|
|
|
+必须使用目标框架实际存在的 API 名称。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12.1 Record 入口
|
|
|
+
|
|
|
+识别：
|
|
|
+
|
|
|
+* 对外 API
|
|
|
+* 函数名称
|
|
|
+* 文件路径
|
|
|
+* 参数
|
|
|
+* 返回值
|
|
|
+
|
|
|
+例如：
|
|
|
+
|
|
|
+```python
|
|
|
+memory.add(
|
|
|
+ messages=messages,
|
|
|
+ user_id=user_id,
|
|
|
+ metadata=metadata
|
|
|
+)
|
|
|
+```
|
|
|
+
|
|
|
+代码示例必须来自目标框架真实 API。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12.2 Record 调用链
|
|
|
+
|
|
|
+尽可能深入追踪调用链：
|
|
|
+
|
|
|
+```text
|
|
|
+公开 API
|
|
|
+ ↓
|
|
|
+Manager
|
|
|
+ ↓
|
|
|
+Processor
|
|
|
+ ↓
|
|
|
+Extractor
|
|
|
+ ↓
|
|
|
+Embedding
|
|
|
+ ↓
|
|
|
+搜索已有 Memory
|
|
|
+ ↓
|
|
|
+Update / Insert / Delete
|
|
|
+ ↓
|
|
|
+持久化
|
|
|
+```
|
|
|
+
|
|
|
+优先使用真实的类名和函数名。
|
|
|
+
|
|
|
+示例：
|
|
|
+
|
|
|
+```text
|
|
|
+memory.add()
|
|
|
+ ↓
|
|
|
+MemoryManager.add()
|
|
|
+ ↓
|
|
|
+MemoryExtractor.extract()
|
|
|
+ ↓
|
|
|
+VectorStore.search()
|
|
|
+ ↓
|
|
|
+MemoryRepository.upsert()
|
|
|
+```
|
|
|
+
|
|
|
+绝对不能虚构不存在的类名或函数名。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12.3 Record 数据流
|
|
|
+
|
|
|
+分析以下步骤是否真实存在：
|
|
|
+
|
|
|
+```text
|
|
|
+输入
|
|
|
+ ↓
|
|
|
+参数验证
|
|
|
+ ↓
|
|
|
+数据标准化
|
|
|
+ ↓
|
|
|
+Memory 提取
|
|
|
+ ↓
|
|
|
+候选 Memory
|
|
|
+ ↓
|
|
|
+Embedding
|
|
|
+ ↓
|
|
|
+相似 Memory 搜索
|
|
|
+ ↓
|
|
|
+重复检测
|
|
|
+ ↓
|
|
|
+冲突检测
|
|
|
+ ↓
|
|
|
+Insert / Update / Delete
|
|
|
+ ↓
|
|
|
+数据持久化
|
|
|
+```
|
|
|
+
|
|
|
+对每一步说明：
|
|
|
+
|
|
|
+* 是否由代码实现？
|
|
|
+* 是否使用 LLM？
|
|
|
+* 是否使用数据库？
|
|
|
+* 是否使用向量搜索？
|
|
|
+* 是否同步执行？
|
|
|
+* 是否异步执行？
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12.4 Memory 提取
|
|
|
+
|
|
|
+判断：
|
|
|
+
|
|
|
+* 原始对话是否转换为 Memory？
|
|
|
+* 是否使用 LLM？
|
|
|
+* 是否提取事实？
|
|
|
+* 是否生成摘要？
|
|
|
+* 是否进行标准化？
|
|
|
+* 是否生成结构化数据？
|
|
|
+
|
|
|
+如果项目中存在 Prompt，分析其作用，但不要无必要地完整复制长 Prompt。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12.5 去重机制
|
|
|
+
|
|
|
+分析：
|
|
|
+
|
|
|
+* 插入前是否搜索已有 Memory？
|
|
|
+* 是否使用相似度搜索？
|
|
|
+* 是否使用精确匹配？
|
|
|
+* 是否使用语义匹配？
|
|
|
+* 去重是规则驱动还是 LLM 驱动？
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 12.6 冲突解决
|
|
|
+
|
|
|
+分析：
|
|
|
+
|
|
|
+* 新信息如何与旧信息冲突？
|
|
|
+* 是否更新旧 Memory？
|
|
|
+* 是否删除旧 Memory？
|
|
|
+* 是否创建新版本？
|
|
|
+* 是否同时保留多个 Memory？
|
|
|
+* 是否使用时间戳？
|
|
|
+* 是否使用 LLM？
|
|
|
+* 是否使用确定性规则？
|
|
|
+
|
|
|
+可能的结果包括：
|
|
|
+
|
|
|
+```text
|
|
|
+保留
|
|
|
+插入
|
|
|
+更新
|
|
|
+合并
|
|
|
+删除
|
|
|
+归档
|
|
|
+忽略
|
|
|
+```
|
|
|
+
|
|
|
+只报告源码实际支持的行为。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十三、Retrieve 流程
|
|
|
+
|
|
|
+这是第二个核心章节。
|
|
|
+
|
|
|
+重点分析：
|
|
|
+
|
|
|
+* Retrieve API
|
|
|
+* Search API
|
|
|
+* Query API
|
|
|
+* Query Rewrite
|
|
|
+* Query Embedding
|
|
|
+* Vector Search
|
|
|
+* Keyword Search
|
|
|
+* Graph Search
|
|
|
+* Metadata Filtering
|
|
|
+* Hybrid Search
|
|
|
+* Reranking
|
|
|
+* Top-K
|
|
|
+* Score Threshold
|
|
|
+* Context Construction
|
|
|
+* Prompt Injection
|
|
|
+
|
|
|
+典型流程：
|
|
|
+
|
|
|
+```text
|
|
|
+用户 Query
|
|
|
+ ↓
|
|
|
+Query Processing
|
|
|
+ ↓
|
|
|
+Query Embedding
|
|
|
+ ↓
|
|
|
+候选 Memory 检索
|
|
|
+ ├── Vector Search
|
|
|
+ ├── Keyword Search
|
|
|
+ ├── Graph Search
|
|
|
+ └── Metadata Filter
|
|
|
+ ↓
|
|
|
+排序 / 重排序
|
|
|
+ ↓
|
|
|
+Top-K Memory
|
|
|
+ ↓
|
|
|
+Context Construction
|
|
|
+ ↓
|
|
|
+Agent / LLM
|
|
|
+```
|
|
|
+
|
|
|
+必须根据真实实现修改。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 13.1 Retrieve 入口
|
|
|
+
|
|
|
+识别：
|
|
|
+
|
|
|
+* API 名称
|
|
|
+* 文件路径
|
|
|
+* 参数
|
|
|
+* 返回类型
|
|
|
+* 内部调用链
|
|
|
+
|
|
|
+例如：
|
|
|
+
|
|
|
+```python
|
|
|
+memory.search(
|
|
|
+ query=query,
|
|
|
+ user_id=user_id,
|
|
|
+ limit=10
|
|
|
+)
|
|
|
+```
|
|
|
+
|
|
|
+只使用目标项目真实存在的 API。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 13.2 Query Processing
|
|
|
+
|
|
|
+判断：
|
|
|
+
|
|
|
+* Query 是否直接进行 Embedding？
|
|
|
+* 是否由 LLM 进行 Query Rewrite？
|
|
|
+* 是否进行 Query Decomposition？
|
|
|
+* 是否提取过滤条件？
|
|
|
+* 是否转换为结构化查询条件？
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 13.3 Search 机制
|
|
|
+
|
|
|
+分析：
|
|
|
+
|
|
|
+* Vector Similarity
|
|
|
+* Keyword Search
|
|
|
+* Full-Text Search
|
|
|
+* Graph Traversal
|
|
|
+* Metadata Filtering
|
|
|
+* Hybrid Retrieval
|
|
|
+
|
|
|
+如果使用向量检索，尽量确认：
|
|
|
+
|
|
|
+* Embedding Provider
|
|
|
+* Vector Dimension
|
|
|
+* Similarity Metric
|
|
|
+* Index Type
|
|
|
+* Top-K
|
|
|
+* Score Threshold
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 13.4 Ranking 与 Reranking
|
|
|
+
|
|
|
+判断：
|
|
|
+
|
|
|
+* 是否对结果进行排序？
|
|
|
+* 是否存在第二阶段 Reranker？
|
|
|
+* 是否合并多个检索分数？
|
|
|
+* 是否考虑时间新鲜度？
|
|
|
+* 是否考虑重要性？
|
|
|
+* 是否使用 LLM 判断相关性？
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 13.5 Context Construction
|
|
|
+
|
|
|
+说明：
|
|
|
+
|
|
|
+```text
|
|
|
+Retrieved Memory
|
|
|
+ ↓
|
|
|
+格式化
|
|
|
+ ↓
|
|
|
+上下文组装
|
|
|
+ ↓
|
|
|
+Agent Prompt
|
|
|
+ ↓
|
|
|
+LLM Response
|
|
|
+```
|
|
|
+
|
|
|
+判断：
|
|
|
+
|
|
|
+* 返回原始 Memory Object？
|
|
|
+* 返回文本？
|
|
|
+* 返回结构化 JSON？
|
|
|
+* 框架是否自动注入 Context？
|
|
|
+* 还是由应用层负责注入？
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十四、Record 与 Retrieve 对比
|
|
|
+
|
|
|
+必须输出：
|
|
|
+
|
|
|
+| 维度 | Record | Retrieve |
|
|
|
+| --------- | ------ | -------- |
|
|
|
+| 触发时机 | | |
|
|
|
+| 输入 | | |
|
|
|
+| LLM 作用 | | |
|
|
|
+| Embedding | | |
|
|
|
+| 数据库 | | |
|
|
|
+| 核心目标 | | |
|
|
|
+| 主要成本 | | |
|
|
|
+| 主要风险 | | |
|
|
|
+| 输出 | | |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十五、存储架构
|
|
|
+
|
|
|
+分析：
|
|
|
+
|
|
|
+* 原始数据存储
|
|
|
+* 结构化 Memory 存储
|
|
|
+* Metadata 存储
|
|
|
+* Embedding 存储
|
|
|
+* Vector Database
|
|
|
+* Graph Database
|
|
|
+* SQL Database
|
|
|
+* NoSQL Database
|
|
|
+* Cache
|
|
|
+* Object Storage
|
|
|
+
|
|
|
+重点回答：
|
|
|
+
|
|
|
+* 是否保留原始对话？
|
|
|
+* 是否保存结构化 Memory？
|
|
|
+* 是否保存 Embedding？
|
|
|
+* 是否保存关系？
|
|
|
+* 是否支持多个 Storage Backend？
|
|
|
+* Storage Adapter 是否可插拔？
|
|
|
+* 是否支持本地部署？
|
|
|
+* 是否支持云部署？
|
|
|
+* 数据一致性如何保证？
|
|
|
+
|
|
|
+可能的架构：
|
|
|
+
|
|
|
+```text
|
|
|
+原始数据
|
|
|
+ ↓
|
|
|
+结构化 Memory
|
|
|
+ ↓
|
|
|
+Embedding
|
|
|
+ ↓
|
|
|
+Vector Store
|
|
|
+```
|
|
|
+
|
|
|
+如果存在多种存储：
|
|
|
+
|
|
|
+```text
|
|
|
+ ┌──────────────┐
|
|
|
+ │ SQL Database │
|
|
|
+ └──────┬───────┘
|
|
|
+ │
|
|
|
+┌──────────────┐ │ ┌──────────────┐
|
|
|
+│ Vector Store │◄───────┼───────►│ Graph Store │
|
|
|
+└──────────────┘ │ └──────────────┘
|
|
|
+ │
|
|
|
+ ┌──────▼───────┐
|
|
|
+ │ Memory Layer │
|
|
|
+ └──────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+必须根据目标框架实际实现修改。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十六、检索架构
|
|
|
+
|
|
|
+解释真实的检索架构。
|
|
|
+
|
|
|
+可能的形式：
|
|
|
+
|
|
|
+```text
|
|
|
+Query
|
|
|
+ ↓
|
|
|
+Query Processing
|
|
|
+ ↓
|
|
|
+Search
|
|
|
+ ├── Vector
|
|
|
+ ├── Keyword
|
|
|
+ ├── Graph
|
|
|
+ └── Metadata
|
|
|
+ ↓
|
|
|
+Merge
|
|
|
+ ↓
|
|
|
+Rank
|
|
|
+ ↓
|
|
|
+Filter
|
|
|
+ ↓
|
|
|
+Top-K
|
|
|
+ ↓
|
|
|
+Context
|
|
|
+```
|
|
|
+
|
|
|
+只能包含实际存在的组件。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十七、关键代码与 API 示例
|
|
|
+
|
|
|
+尽量包含：
|
|
|
+
|
|
|
+## 初始化
|
|
|
+
|
|
|
+```python
|
|
|
+memory = Memory(...)
|
|
|
+```
|
|
|
+
|
|
|
+## Record
|
|
|
+
|
|
|
+```python
|
|
|
+memory.add(...)
|
|
|
+```
|
|
|
+
|
|
|
+## Retrieve
|
|
|
+
|
|
|
+```python
|
|
|
+memory.search(...)
|
|
|
+```
|
|
|
+
|
|
|
+## 获取
|
|
|
+
|
|
|
+```python
|
|
|
+memory.get(...)
|
|
|
+```
|
|
|
+
|
|
|
+## 更新
|
|
|
+
|
|
|
+```python
|
|
|
+memory.update(...)
|
|
|
+```
|
|
|
+
|
|
|
+## 删除
|
|
|
+
|
|
|
+```python
|
|
|
+memory.delete(...)
|
|
|
+```
|
|
|
+
|
|
|
+如果目标项目不存在某个 API，不要编造。
|
|
|
+
|
|
|
+每个代码示例说明：
|
|
|
+
|
|
|
+* 仓库文件
|
|
|
+* 类名
|
|
|
+* 函数名
|
|
|
+* 参数
|
|
|
+* 返回值
|
|
|
+* 内部调用链
|
|
|
+* 关键实现逻辑
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十八、Mermaid 工作原理流程图
|
|
|
+
|
|
|
+每份报告必须包含至少一张详细 Mermaid 图。
|
|
|
+
|
|
|
+图必须反映目标框架的真实实现。
|
|
|
+
|
|
|
+可以从以下结构开始：
|
|
|
+
|
|
|
+```mermaid
|
|
|
+flowchart TD
|
|
|
+ A[Agent / User Input] --> B[Memory API]
|
|
|
+
|
|
|
+ B --> C{Operation}
|
|
|
+
|
|
|
+ C -->|Record| D[Input Processing]
|
|
|
+ D --> E[Memory Extraction]
|
|
|
+ E --> F[Candidate Memory]
|
|
|
+ F --> G[Generate Embedding]
|
|
|
+ G --> H[Search Existing Memories]
|
|
|
+ H --> I{Duplicate or Conflict?}
|
|
|
+
|
|
|
+ I -->|No| J[Insert New Memory]
|
|
|
+ I -->|Duplicate| K[Skip or Merge]
|
|
|
+ I -->|Conflict| L[Resolve Conflict]
|
|
|
+
|
|
|
+ J --> M[Persist Memory]
|
|
|
+ K --> M
|
|
|
+ L --> M
|
|
|
+
|
|
|
+ M --> N[(Vector Store)]
|
|
|
+ M --> O[(Metadata Store)]
|
|
|
+ M --> P[(Graph Store)]
|
|
|
+
|
|
|
+ C -->|Retrieve| Q[User Query]
|
|
|
+ Q --> R[Query Processing]
|
|
|
+ R --> S[Generate Query Embedding]
|
|
|
+
|
|
|
+ S --> T[Vector Search]
|
|
|
+ R --> U[Keyword Search]
|
|
|
+ R --> V[Graph Search]
|
|
|
+
|
|
|
+ T --> W[Candidate Memories]
|
|
|
+ U --> W
|
|
|
+ V --> W
|
|
|
+
|
|
|
+ W --> X[Filtering]
|
|
|
+ X --> Y[Reranking]
|
|
|
+ Y --> Z[Top-K Memories]
|
|
|
+ Z --> AA[Context Construction]
|
|
|
+ AA --> AB[Agent / LLM]
|
|
|
+```
|
|
|
+
|
|
|
+重要要求：
|
|
|
+
|
|
|
+* 不存在的组件必须删除。
|
|
|
+* 真实存在的组件必须加入。
|
|
|
+* 使用真实的数据库名称。
|
|
|
+* 使用真实的 API 和处理阶段。
|
|
|
+* 尽量将节点对应到源码模块。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 十九、端到端数据流示例
|
|
|
+
|
|
|
+使用一个完整例子说明 Record 和 Retrieve。
|
|
|
+
|
|
|
+例如：
|
|
|
+
|
|
|
+```text
|
|
|
+用户：
|
|
|
+
|
|
|
+“我最近搬到了东京。”
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Conversation
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Record API
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Memory Extraction
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Candidate Memory
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Embedding
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+搜索已有 Memory
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Conflict Detection
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Upsert
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Persistent Memory
|
|
|
+```
|
|
|
+
|
|
|
+未来：
|
|
|
+
|
|
|
+```text
|
|
|
+用户：
|
|
|
+
|
|
|
+“我住在哪里？”
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Retrieve API
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Semantic Search
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Relevant Memory
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Context Construction
|
|
|
+
|
|
|
+ ↓
|
|
|
+
|
|
|
+Agent Response
|
|
|
+```
|
|
|
+
|
|
|
+必须根据实际框架实现调整。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十、优点分析
|
|
|
+
|
|
|
+从工程角度分析：
|
|
|
+
|
|
|
+* 架构清晰度
|
|
|
+* API 易用性
|
|
|
+* Memory 抽象
|
|
|
+* 存储扩展性
|
|
|
+* 检索能力
|
|
|
+* 多租户能力
|
|
|
+* 多用户能力
|
|
|
+* 多 Agent 能力
|
|
|
+* 可观测性
|
|
|
+* 部署能力
|
|
|
+* LLM 解耦程度
|
|
|
+* Embedding 解耦程度
|
|
|
+* Vector Database 解耦程度
|
|
|
+* 数据可迁移性
|
|
|
+* 社区活跃度
|
|
|
+* 生产成熟度
|
|
|
+
|
|
|
+重要优点尽量关联源码或官方文档证据。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十一、缺点与风险
|
|
|
+
|
|
|
+分析：
|
|
|
+
|
|
|
+* LLM 成本
|
|
|
+* 延迟
|
|
|
+* 错误 Memory
|
|
|
+* 幻觉 Memory
|
|
|
+* 冲突解决错误
|
|
|
+* 数据一致性
|
|
|
+* Embedding 依赖
|
|
|
+* Vendor Lock-in
|
|
|
+* 可解释性
|
|
|
+* 数据删除与合规
|
|
|
+* 隐私
|
|
|
+* 多租户隔离
|
|
|
+* 大规模检索成本
|
|
|
+* 部署复杂度
|
|
|
+* 运维复杂度
|
|
|
+
|
|
|
+必须区分：
|
|
|
+
|
|
|
+```text
|
|
|
+事实：
|
|
|
+源码或官方文档直接支持。
|
|
|
+
|
|
|
+推断：
|
|
|
+根据架构推导。
|
|
|
+
|
|
|
+风险：
|
|
|
+可能产生的工程后果。
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十二、工程评价
|
|
|
+
|
|
|
+提供：
|
|
|
+
|
|
|
+| 维度 | 评分 | 说明 |
|
|
|
+| ------- | --: | -- |
|
|
|
+| 架构清晰度 | /10 | |
|
|
|
+| API 易用性 | /10 | |
|
|
|
+| 可扩展性 | /10 | |
|
|
|
+| 检索能力 | /10 | |
|
|
|
+| 存储灵活性 | /10 | |
|
|
|
+| 生产成熟度 | /10 | |
|
|
|
+| 可观测性 | /10 | |
|
|
|
+| 数据一致性 | /10 | |
|
|
|
+| 性能潜力 | /10 | |
|
|
|
+
|
|
|
+评分必须给出理由。
|
|
|
+
|
|
|
+不要随意打分。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十三、适用场景
|
|
|
+
|
|
|
+评估是否适合：
|
|
|
+
|
|
|
+* Personal AI Assistant
|
|
|
+* Enterprise Copilot
|
|
|
+* Customer Support Agent
|
|
|
+* Multi-Agent System
|
|
|
+* Long-Running Autonomous Agent
|
|
|
+* Personalized Recommendation
|
|
|
+* User Profile Memory
|
|
|
+* Knowledge-Enhanced Agent
|
|
|
+
|
|
|
+同时说明不适合的场景。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十四、最终架构判断
|
|
|
+
|
|
|
+报告最后必须总结：
|
|
|
+
|
|
|
+```text
|
|
|
+这个框架的本质是：
|
|
|
+
|
|
|
+[一句话定义]
|
|
|
+
|
|
|
+它最核心的架构机制是：
|
|
|
+
|
|
|
+[核心机制]
|
|
|
+
|
|
|
+它最大的优势是：
|
|
|
+
|
|
|
+[优势]
|
|
|
+
|
|
|
+它最大的风险是：
|
|
|
+
|
|
|
+[风险]
|
|
|
+
|
|
|
+如果要构建：
|
|
|
+
|
|
|
+[目标系统]
|
|
|
+
|
|
|
+建议：
|
|
|
+
|
|
|
+[推荐采用 / 借鉴设计 / 谨慎评估 / 不推荐]
|
|
|
+
|
|
|
+原因：
|
|
|
+
|
|
|
+[简洁说明]
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十五、源码与文档追踪
|
|
|
+
|
|
|
+对于重要结论，尽量使用：
|
|
|
+
|
|
|
+```text
|
|
|
+结论：
|
|
|
+
|
|
|
+[架构结论]
|
|
|
+
|
|
|
+来源：
|
|
|
+
|
|
|
+- Repository:
|
|
|
+- File:
|
|
|
+- Class:
|
|
|
+- Function:
|
|
|
+- Relevant Logic:
|
|
|
+```
|
|
|
+
|
|
|
+尽可能提供：
|
|
|
+
|
|
|
+* GitHub 源码链接
|
|
|
+* 官方文档链接
|
|
|
+* API Reference 链接
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十六、输出语言与风格
|
|
|
+
|
|
|
+默认使用中文。
|
|
|
+
|
|
|
+以下技术术语保留英文：
|
|
|
+
|
|
|
+* Record
|
|
|
+* Retrieve
|
|
|
+* Memory
|
|
|
+* Embedding
|
|
|
+* Vector Store
|
|
|
+* Reranking
|
|
|
+* Conflict Resolution
|
|
|
+* Namespace
|
|
|
+* Metadata
|
|
|
+* Query Rewrite
|
|
|
+
|
|
|
+整体风格：
|
|
|
+
|
|
|
+* 技术深度优先
|
|
|
+* 结构化
|
|
|
+* 基于源码
|
|
|
+* 精确
|
|
|
+* 面向工程实践
|
|
|
+* 明确区分事实、推断和未知
|
|
|
+
|
|
|
+避免：
|
|
|
+
|
|
|
+* 空泛的 AI 介绍
|
|
|
+* 营销语言
|
|
|
+* 没有证据的假设
|
|
|
+* 过度宽泛的结论
|
|
|
+* 只基于 README 的深度架构结论
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+# 二十七、最低交付要求
|
|
|
+
|
|
|
+每次完成分析后，必须至少包含：
|
|
|
+
|
|
|
+1. 项目概览
|
|
|
+2. 核心设计理念
|
|
|
+3. 核心架构
|
|
|
+4. 数据模型
|
|
|
+5. 核心工作原理
|
|
|
+6. Record 流程
|
|
|
+7. Retrieve 流程
|
|
|
+8. 存储机制
|
|
|
+9. 检索机制
|
|
|
+10. 关键代码 / API 示例
|
|
|
+11. 详细 Mermaid 工作原理图
|
|
|
+12. 端到端数据流
|
|
|
+13. 优点分析
|
|
|
+14. 缺点与风险
|
|
|
+15. 工程评价
|
|
|
+16. 最终架构判断
|
|
|
+17. 源码与官方文档追踪
|
