文章目录
- 第八章 记忆与检索 知识树
- 一、记忆系统（Memory System）
- 核心工具：MemoryTool（hello_agents/tools/builtin/memory_tool.py）
- 核心接口函数
- 初始化逻辑
- 核心协调器：MemoryManager（hello_agents/memory/manager.py）
- 核心函数
- 核心属性
- 四大记忆类型（hello_agents/memory/types/）
- 1. WorkingMemory（working.py）- 工作记忆
- 2. EpisodicMemory（episodic.py）- 情景记忆
- 3. SemanticMemory（semantic.py）- 语义记忆
- 4. PerceptualMemory（perceptual.py）- 感知记忆
- 存储层（hello_agents/memory/storage/）
- 1. SQLiteDocumentStore（document_store.py）
- 2. QdrantVectorStore（qdrant_store.py）
- 3. Neo4jGraphStore（neo4j_store.py）
- 嵌入服务层（hello_agents/memory/embedding.py）
- 二、RAG系统（Retrieval-Augmented Generation）
- 核心工具：RAGTool（hello_agents/tools/builtin/rag_tool.py）
- 核心接口函数
- 初始化逻辑
- RAG管道（hello_agents/memory/rag/pipeline.py）
- 核心流程函数
- 核心属性
- 文档处理层（hello_agents/memory/rag/document.py）
- 核心函数
- 实现方式
- 高级检索策略（hello_agents/memory/rag/retrieval.py）
- 1. 多查询扩展（MQE）
- 2. 假设文档嵌入（HyDE）
- 3. 扩展检索框架
- 核心辅助函数
第八章 记忆与检索 知识树
一、记忆系统（Memory System）
核心工具：MemoryTool（hello_agents/tools/builtin/memory_tool.py）
核心接口函数
execute：统一入口，分发add/search/summary/stats/update/remove/forget/consolidate/clear_all操作_add_memory：添加记忆，处理会话ID/多模态元数据/上下文补充，调用memory_manager.add_memory_search_memory：搜索记忆，参数标准化，调用memory_manager.retrieve_memories，格式化结果_forget：遗忘记忆，支持importance_based/time_based/capacity_based三种策略_consolidate：整合记忆，短期记忆转长期记忆，按importance_threshold筛选
初始化逻辑
- 接收user_id/memory_config/memory_types参数，初始化MemoryManager
- 按需启用working/episodic/semantic/perceptual记忆类型
核心协调器：MemoryManager（hello_agents/memory/manager.py）
核心函数
__init__：初始化MemoryStore/MemoryRetriever，按需实例化各记忆类型add_memory：分发记忆添加请求到对应记忆类型模块retrieve_memories：分发记忆检索请求，聚合多类型结果forget_memories：调用对应记忆类型的遗忘方法，统计遗忘数量consolidate_memories：跨记忆类型迁移数据，按阈值筛选
核心属性
store：MemoryStore实例，统一存储入口retriever：MemoryRetriever实例，统一检索入口memory_types：字典，存储各启用的记忆类型实例
四大记忆类型（hello_agents/memory/types/）
1. WorkingMemory（working.py）- 工作记忆
- 核心函数：
add（添加前过期清理/容量控制）、retrieve（TF-IDF+关键词混合检索） - 评分函数：
_calculate_keyword_score、_calculate_time_decay，综合相似度+时间+重要性 - 实现方式：纯内存存储，TTL自动清理，混合检索策略，容量有限（默认50条）
2. EpisodicMemory（episodic.py）- 情景记忆
- 核心函数：
add（创建Episode对象，更新会话索引，持久化到SQLite+Qdrant）、retrieve（结构化过滤+语义向量检索） - 评分函数：
_calculate_episode_score（向量相似度×0.8+时间近因性×0.2）×重要性权重 - 实现方式：SQLite+Qdrant混合存储，支持时间序列/会话级检索，结构化+向量混合检索
3. SemanticMemory（semantic.py）- 语义记忆
- 核心函数：
add（生成嵌入，提取实体/关系，存储到Neo4j+Qdrant）、retrieve（向量+图+语义推理混合检索） - 融合函数：
_combine_and_rank_results（向量相似度×0.7+图相似度×0.3）×重要性权重 - 实现方式：Neo4j+Qdrant混合架构，实体/关系提取构建知识图谱，多策略混合检索
4. PerceptualMemory（perceptual.py）- 感知记忆
- 核心函数：
add（按模态编码，存储到对应Qdrant集合）、retrieve（同/跨模态向量检索） - 编码函数：
_encode_data（文本/图像/音频分别调用对应编码器） - 评分函数：
_calculate_recency_score（指数衰减模型），融合向量+时间+重要性 - 实现方式：按模态分离的Qdrant向量存储，多模态编码器（CLIP/CLAP），支持跨模态检索
存储层（hello_agents/memory/storage/）
1. SQLiteDocumentStore（document_store.py）
- 核心函数：
save、load、query，结构化数据持久化，支持复杂条件查询
2. QdrantVectorStore（qdrant_store.py）
- 核心函数：
add_vectors、search_similar，高性能向量存储/检索，支持命名空间隔离
3. Neo4jGraphStore（neo4j_store.py）
- 核心函数：
_add_entity_to_graph、_add_relation_to_graph，知识图谱构建/查询
嵌入服务层（hello_agents/memory/embedding.py）
- 核心函数：
create_embedding_model_with_fallback、get_text_embedder - 实现方式：支持DashScopeEmbedding（云端）、LocalTransformerEmbedding（本地）、TFIDFEmbedding（兜底），统一嵌入接口
二、RAG系统（Retrieval-Augmented Generation）
核心工具：RAGTool（hello_agents/tools/builtin/rag_tool.py）
核心接口函数
execute：统一入口，分发add_text/add_document/search/ask/stats操作_add_document：调用RAG管道，处理多格式文档，完成从转换到存储的全流程_search：调用扩展检索框架，支持MQE/HyDE，返回相关知识片段_ask：检索相关片段，构建上下文，调用LLM生成答案
初始化逻辑
- 接收knowledge_base_path/collection_name/rag_namespace参数
- 创建RAG管道，初始化LLM实例，按命名空间隔离知识库
RAG管道（hello_agents/memory/rag/pipeline.py）
核心流程函数
create_rag_pipeline：创建端到端RAG处理管道，整合文档处理/嵌入/存储/检索index_document：调用文档处理→分块→向量化→存储全流程search：调用扩展检索策略，返回Top-K相关片段
核心属性
processor：DocumentProcessor实例，文档处理入口embedder：统一嵌入模型实例，复用记忆系统嵌入服务vector_store：QdrantVectorStore实例，向量存储入口
文档处理层（hello_agents/memory/rag/document.py）
核心函数
_convert_to_markdown：统一转换多格式文档为Markdown，PDF增强处理，其他格式调用MarkItDown_split_paragraphs_with_headings：基于Markdown标题层次的语义分割_chunk_paragraphs：基于Token数量的智能分块，支持重叠策略_approx_token_len：中英文混合Token估算，CJK字符按1Token计算
实现方式
- 多格式统一转换为Markdown，结构化分块（标题层次+Token控制），重叠分块保证信息连续性
高级检索策略（hello_agents/memory/rag/retrieval.py）
1. 多查询扩展（MQE）
- 核心函数：
_prompt_mqe，调用LLM生成语义等价的多样化查询，提升召回率
2. 假设文档嵌入（HyDE）
- 核心函数：
_prompt_hyde，调用LLM生成假设性答案文档，桥接查询与文档语义鸿沟
3. 扩展检索框架
- 核心函数：
search_vectors_expanded，实现「扩展-检索-合并」三步流程- 扩展：生成MQE查询+HyDE假设文档
- 检索：并行执行所有扩展查询的向量检索
- 合并：去重+分数排序，返回Top-K结果
- 可配置参数：
enable_mqe、enable_hyde、candidate_pool_multiplier
核心辅助函数
embed_query：统一查询向量化接口，复用记忆系统嵌入模型_preprocess_markdown_for_embedding：Markdown文本预处理，提升嵌入质量_create_default_vector_store：快速创建Qdrant向量存储实例，简化初始化
