Merge pull request #26 from jjyaoao/main

add chapter8

README.md

@@ -50,8 +50,8 @@
 | [第六章 框架开发实践](./docs/chapter6/第六章%20框架开发实践.md) | AutoGen、AgentScope、LangGraph 等主流框架应用 | ✅ |
 | [第七章 构建你的Agent框架](./docs/chapter7/第七章%20构建你的Agent框架.md) | 从0开始构建智能体框架 | ✅ |
 | <strong>第三部分：高级知识扩展</strong> |  |  |
-| [第八章 记忆与检索](./docs/chapter9/第八章%20记忆与检索.md) | 记忆系统, RAG, 图\向量数据库 | 🚧 |
-| [第九章 上下文工程](./docs/chapter8/第九章%20上下文工程.md) | 持续交互的"情境理解" | 🚧 |
+| [第八章 记忆与检索](./docs/chapter8/第八章%20记忆与检索.md) | 记忆系统, RAG, 存储 | 🚧 |
+| [第九章 上下文工程](./docs/chapter9/第九章%20上下文工程.md) | 持续交互的"情境理解" | 🚧 |
 | [第十章 智能体通信协议](./docs/chapter10/第十章%20智能体通信协议.md) | MCP, A2A, ANP 等协议解析 | 🚧 |
 | [第十一章 多智能体系统](./docs/chapter11/第十一章%20多智能体系统.md) | 协作、通信、博弈论与 AI Society | 🚧 |
 | [第十二章 智能体性能评估](./docs/chapter12/第十二章%20智能体性能评估.md) | 核心指标、基准测试与评估框架 | 🚧 |

code/chapter8/.env.example

@@ -0,0 +1,77 @@
+# ============================================================================
+# HelloAgents 统一环境变量配置文件
+# ============================================================================
+# 复制此文件为 .env 并填入你的API密钥
+# 系统要求：Python 3.10+ （必需）
+
+# ============================================================================
+# 🚀 统一配置格式（推荐）- 框架自动检测provider
+# ============================================================================
+# 只需配置以下4个通用环境变量，框架会自动识别LLM提供商：
+
+# 模型名称
+LLM_MODEL_ID=your-model-name
+
+# API密钥
+LLM_API_KEY=your-api-key-here
+
+# 服务地址
+LLM_BASE_URL=your-api-base-url
+
+# 超时时间（可选，默认60秒）
+LLM_TIMEOUT=60
+
+# ============================================================================
+# 🛠️ 工具配置（可选）
+# ============================================================================
+
+# Tavily搜索（推荐）- 获取API密钥：https://tavily.com/
+# TAVILY_API_KEY=tvly-your_tavily_key_here
+
+# SerpApi搜索（备选）- 获取API密钥：https://serpapi.com/
+# SERPAPI_API_KEY=your_serpapi_key_here
+
+# ================================
+# Qdrant 向量数据库配置 - 获取API密钥：https://cloud.qdrant.io/
+# ================================
+# 使用Qdrant云服务 (推荐)
+QDRANT_URL=https://your-cluster.qdrant.tech:6333
+QDRANT_API_KEY=your_qdrant_api_key_here
+
+# 或使用本地Qdrant (需要Docker)
+# QDRANT_URL=http://localhost:6333
+# QDRANT_API_KEY=
+
+# Qdrant集合配置
+QDRANT_COLLECTION=hello_agents_vectors
+QDRANT_VECTOR_SIZE=384
+QDRANT_DISTANCE=cosine
+QDRANT_TIMEOUT=30
+
+# ================================
+# Neo4j 图数据库配置 - 获取API密钥：https://neo4j.com/cloud/aura/
+# ================================
+# 使用Neo4j Aura云服务 (推荐)
+NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=your_neo4j_password_here
+
+# 或使用本地Neo4j (需要Docker)
+# NEO4J_URI=bolt://localhost:7687
+# NEO4J_USERNAME=neo4j
+# NEO4J_PASSWORD=hello-agents-password
+
+# Neo4j连接配置
+NEO4J_DATABASE=neo4j
+NEO4J_MAX_CONNECTION_LIFETIME=3600
+NEO4J_MAX_CONNECTION_POOL_SIZE=50
+NEO4J_CONNECTION_TIMEOUT=60
+
+# ==========================
+# 嵌入（Embedding）配置示例 - 可从阿里云控制台获取：https://dashscope.aliyun.com/
+# ==========================
+# - 若为空，dashscope 默认 text-embedding-v3；local 默认 sentence-transformers/all-MiniLM-L6-v2
+EMBED_MODEL_TYPE=dashscope
+EMBED_MODEL_NAME=
+EMBED_API_KEY=
+EMBED_BASE_URL=

code/chapter8/01_MemoryTool_Basic_Operations.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 01: MemoryTool基础操作
+展示MemoryTool的核心execute方法和基本操作
+"""
+
+from datetime import datetime
+from typing import List
+from hello_agents.tools import MemoryTool
+
+def memory_tool_execute_demo():
+    """MemoryTool execute方法演示"""
+    print("🧠 MemoryTool基础操作演示")
+    print("=" * 50)
+    
+    # 初始化MemoryTool
+    memory_tool = MemoryTool(
+        user_id="demo_user",
+        memory_types=["working", "episodic", "semantic", "perceptual"]
+    )
+    
+    print("✅ MemoryTool初始化完成")
+    print(f"📋 支持的操作: add, search, summary, stats, update, remove, forget, consolidate, clear_all")
+    
+    return memory_tool
+
+def add_memory_demo(memory_tool):
+    """添加记忆演示 - 模拟人类记忆编码过程"""
+    print("\n📝 添加记忆演示")
+    print("-" * 30)
+    
+    # 添加工作记忆
+    result = memory_tool.execute(
+        "add",
+        content="正在学习HelloAgents框架的记忆系统",
+        memory_type="working",
+        importance=0.7,
+        task_type="learning"
+    )
+    print(f"工作记忆: {result}")
+    
+    # 添加情景记忆
+    result = memory_tool.execute(
+        "add",
+        content="2024年开始深入研究AI Agent技术",
+        memory_type="episodic",
+        importance=0.8,
+        event_type="milestone",
+        location="研发中心"
+    )
+    print(f"情景记忆: {result}")
+    
+    # 添加语义记忆
+    result = memory_tool.execute(
+        "add",
+        content="记忆系统包括工作记忆、情景记忆、语义记忆和感知记忆四种类型",
+        memory_type="semantic",
+        importance=0.9,
+        concept="memory_types",
+        domain="cognitive_science"
+    )
+    print(f"语义记忆: {result}")
+    
+    # 添加感知记忆
+    result = memory_tool.execute(
+        "add",
+        content="查看了记忆系统的架构图和实现代码",
+        memory_type="perceptual",
+        importance=0.6,
+        modality="document",
+        source="technical_documentation"
+    )
+    print(f"感知记忆: {result}")
+
+def search_memory_demo(memory_tool):
+    """搜索记忆演示 - 实现语义理解的检索"""
+    print("\n🔍 搜索记忆演示")
+    print("-" * 30)
+    
+    # 基础搜索
+    print("基础搜索 - '记忆系统':")
+    result = memory_tool.execute("search", query="记忆系统", limit=3)
+    print(result)
+    
+    # 按类型搜索
+    print("\n按类型搜索 - 语义记忆中的'记忆':")
+    result = memory_tool.execute(
+        "search", 
+        query="记忆", 
+        memory_type="semantic", 
+        limit=2
+    )
+    print(result)
+    
+    # 设置重要性阈值
+    print("\n高重要性记忆搜索:")
+    result = memory_tool.execute(
+        "search", 
+        query="AI Agent", 
+        min_importance=0.7, 
+        limit=3
+    )
+    print(result)
+
+def memory_summary_demo(memory_tool):
+    """记忆摘要演示 - 提供系统全貌"""
+    print("\n📋 记忆摘要演示")
+    print("-" * 30)
+    
+    # 获取记忆摘要
+    result = memory_tool.execute("summary", limit=5)
+    print("记忆摘要:")
+    print(result)
+    
+    # 获取统计信息
+    print("\n📊 统计信息:")
+    result = memory_tool.execute("stats")
+    print(result)
+
+def memory_management_demo(memory_tool):
+    """记忆管理演示 - 遗忘和整合"""
+    print("\n⚙️ 记忆管理演示")
+    print("-" * 30)
+    
+    # 添加一个低重要性记忆用于遗忘测试
+    memory_tool.execute(
+        "add",
+        content="这是一个临时的测试记忆，重要性很低",
+        memory_type="working",
+        importance=0.1
+    )
+    
+    # 基于重要性的遗忘
+    print("基于重要性的遗忘 (阈值=0.2):")
+    result = memory_tool.execute(
+        "forget",
+        strategy="importance_based",
+        threshold=0.2
+    )
+    print(result)
+    
+    # 记忆整合 - 将重要的工作记忆转为情景记忆
+    print("\n记忆整合 (working → episodic):")
+    result = memory_tool.execute(
+        "consolidate",
+        from_type="working",
+        to_type="episodic",
+        importance_threshold=0.6
+    )
+    print(result)
+
+def main():
+    """主函数"""
+    print("🚀 MemoryTool基础操作完整演示")
+    print("展示记忆系统的核心功能和操作方法")
+    print("=" * 60)
+    
+    try:
+        # 1. 初始化MemoryTool
+        memory_tool = memory_tool_execute_demo()
+        
+        # 2. 添加记忆演示
+        add_memory_demo(memory_tool)
+        
+        # 3. 搜索记忆演示
+        search_memory_demo(memory_tool)
+        
+        # 4. 记忆摘要演示
+        memory_summary_demo(memory_tool)
+        
+        # 5. 记忆管理演示
+        memory_management_demo(memory_tool)
+        
+        print("\n" + "=" * 60)
+        print("🎉 MemoryTool基础操作演示完成！")
+        print("=" * 60)
+        
+        print("\n✨ 演示的核心功能:")
+        print("1. 🧠 四种记忆类型的添加和管理")
+        print("2. 🔍 智能语义搜索和过滤")
+        print("3. 📋 记忆摘要和统计分析")
+        print("4. ⚙️ 记忆整合和选择性遗忘")
+        
+        print("\n🎯 设计特点:")
+        print("• 统一的execute接口，操作简洁一致")
+        print("• 丰富的元数据支持，便于分类和检索")
+        print("• 智能的重要性评估和时间衰减机制")
+        print("• 模拟人类认知的记忆管理策略")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/02_MemoryTool_Architecture.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 02: MemoryTool架构设计
+展示MemoryTool和MemoryManager的分层架构
+"""
+
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+from hello_agents.tools import MemoryTool
+from hello_agents.memory import MemoryConfig
+
+class MemoryToolArchitectureDemo:
+    """MemoryTool架构演示类"""
+    
+    def __init__(self):
+        self.memory_config = MemoryConfig()
+        self.memory_types = ["working", "episodic", "semantic", "perceptual"]
+    
+    def demonstrate_memory_tool_init(self):
+        """演示MemoryTool初始化过程"""
+        print("🏗️ MemoryTool架构设计演示")
+        print("=" * 50)
+        
+        print("📋 MemoryTool初始化过程:")
+        print("1. 创建MemoryConfig配置对象")
+        print("2. 指定启用的记忆类型")
+        print("3. 初始化MemoryManager管理器")
+        print("4. 根据配置启用不同记忆模块")
+        
+        # 演示MemoryTool的初始化
+        memory_tool = MemoryTool(
+            user_id="architecture_demo_user",
+            memory_config=self.memory_config,
+            memory_types=self.memory_types
+        )
+        
+        print(f"\n✅ MemoryTool初始化完成")
+        print(f"👤 用户ID: {self.user_id}")
+        print(f"🧠 启用的记忆类型: {memory_tool.memory_types}")
+        print(f"⚙️ 配置对象: {type(memory_tool.memory_config).__name__}")
+        
+        return memory_tool
+    
+    def demonstrate_memory_manager_architecture(self, memory_tool):
+        """演示MemoryManager的组合模式架构"""
+        print("\n🔧 MemoryManager架构设计")
+        print("-" * 40)
+        
+        print("MemoryManager采用组合模式设计:")
+        print("- 统一的记忆操作接口")
+        print("- 独立的记忆类型组件")
+        print("- 灵活的配置和扩展能力")
+        
+        # 获取MemoryManager实例
+        memory_manager = memory_tool.memory_manager
+        
+        print(f"\n📊 MemoryManager状态:")
+        print(f"用户ID: {memory_manager.user_id}")
+        print(f"配置类型: {type(memory_manager.config).__name__}")
+        print(f"记忆类型数量: {len(memory_manager.memory_types)}")
+        
+        # 显示各记忆类型的状态
+        print(f"\n🧠 记忆类型组件:")
+        for memory_type, memory_instance in memory_manager.memory_types.items():
+            print(f"  • {memory_type}: {type(memory_instance).__name__}")
+    
+    def demonstrate_memory_types_specialization(self, memory_tool):
+        """演示四种记忆类型的专业化特点"""
+        print("\n🎯 四种记忆类型的专业化设计")
+        print("-" * 40)
+        
+        memory_types_info = {
+            "working": {
+                "name": "工作记忆",
+                "features": ["容量有限", "访问速度快", "自动清理", "临时存储"],
+                "storage": "纯内存存储",
+                "ttl": "60分钟TTL机制"
+            },
+            "episodic": {
+                "name": "情景记忆", 
+                "features": ["事件序列", "时间序列", "上下文丰富", "会话关联"],
+                "storage": "SQLite + Qdrant混合存储",
+                "ttl": "持久化存储"
+            },
+            "semantic": {
+                "name": "语义记忆",
+                "features": ["概念知识", "实体关系", "知识图谱", "语义推理"],
+                "storage": "Neo4j + Qdrant混合存储", 
+                "ttl": "长期存储"
+            },
+            "perceptual": {
+                "name": "感知记忆",
+                "features": ["多模态", "跨模态检索", "感知数据", "内容生成"],
+                "storage": "分模态向量存储",
+                "ttl": "按重要性管理"
+            }
+        }
+        
+        for memory_type, info in memory_types_info.items():
+            print(f"\n📚 {info['name']} ({memory_type}):")
+            print(f"   特点: {', '.join(info['features'])}")
+            print(f"   存储: {info['storage']}")
+            print(f"   生命周期: {info['ttl']}")
+            
+            # 添加示例记忆来演示特点
+            if memory_type == "working":
+                memory_tool.execute("add",
+                    content=f"演示{info['name']}的临时存储特性",
+                    memory_type=memory_type,
+                    importance=0.6,
+                    demo_feature="temporary_storage"
+                )
+            elif memory_type == "episodic":
+                memory_tool.execute("add",
+                    content=f"演示{info['name']}的事件记录特性",
+                    memory_type=memory_type,
+                    importance=0.7,
+                    event_type="demonstration",
+                    session_context="architecture_demo"
+                )
+            elif memory_type == "semantic":
+                memory_tool.execute("add",
+                    content=f"{info['name']}用于存储概念性知识和实体关系",
+                    memory_type=memory_type,
+                    importance=0.8,
+                    concept="memory_architecture",
+                    domain="cognitive_computing"
+                )
+            elif memory_type == "perceptual":
+                memory_tool.execute("add",
+                    content=f"演示{info['name']}的多模态数据处理",
+                    memory_type=memory_type,
+                    importance=0.6,
+                    modality="text",
+                    data_type="demonstration"
+                )
+    
+    def demonstrate_unified_interface(self, memory_tool):
+        """演示统一接口的设计优势"""
+        print("\n🔗 统一接口设计优势")
+        print("-" * 40)
+        
+        print("统一的execute方法提供:")
+        print("• 一致的调用方式")
+        print("• 灵活的参数传递")
+        print("• 统一的错误处理")
+        print("• 简化的用户体验")
+        
+        # 演示统一接口的使用
+        operations = [
+            ("search", {"query": "演示", "limit": 2}),
+            ("summary", {"limit": 3}),
+            ("stats", {}),
+        ]
+        
+        print(f"\n🔧 统一接口操作演示:")
+        for operation, params in operations:
+            print(f"\n操作: {operation}")
+            print(f"参数: {params}")
+            result = memory_tool.execute(operation, **params)
+            print(f"结果: {result[:100]}..." if len(str(result)) > 100 else f"结果: {result}")
+    
+    def demonstrate_extensibility(self):
+        """演示系统的扩展性设计"""
+        print("\n🚀 系统扩展性设计")
+        print("-" * 40)
+        
+        print("扩展性特点:")
+        print("• 插件化的记忆类型")
+        print("• 可配置的存储后端") 
+        print("• 灵活的记忆策略")
+        print("• 模块化的组件设计")
+        
+        # 演示自定义配置
+        custom_config = MemoryConfig()
+        custom_config.working_memory_capacity = 100
+        custom_config.working_memory_ttl = 120
+        
+        print(f"\n⚙️ 自定义配置示例:")
+        print(f"工作记忆容量: {custom_config.working_memory_capacity}")
+        print(f"工作记忆TTL: {custom_config.working_memory_ttl}分钟")
+        
+        # 演示选择性启用记忆类型
+        selective_memory_tool = MemoryTool(
+            user_id="selective_user",
+            memory_config=custom_config,
+            memory_types=["working", "semantic"]  # 只启用部分类型
+        )
+        
+        print(f"\n🎯 选择性启用示例:")
+        print(f"启用的记忆类型: {selective_memory_tool.memory_types}")
+        print("✅ 系统支持根据需求灵活配置")
+
+def main():
+    """主函数"""
+    print("🏗️ MemoryTool架构设计完整演示")
+    print("展示记忆系统的分层架构和设计模式")
+    print("=" * 60)
+    
+    try:
+        demo = MemoryToolArchitectureDemo()
+        
+        # 1. MemoryTool初始化演示
+        memory_tool = demo.demonstrate_memory_tool_init()
+        
+        # 2. MemoryManager架构演示
+        demo.demonstrate_memory_manager_architecture(memory_tool)
+        
+        # 3. 记忆类型专业化演示
+        demo.demonstrate_memory_types_specialization(memory_tool)
+        
+        # 4. 统一接口演示
+        demo.demonstrate_unified_interface(memory_tool)
+        
+        # 5. 扩展性演示
+        demo.demonstrate_extensibility()
+        
+        print("\n" + "=" * 60)
+        print("🎉 MemoryTool架构演示完成！")
+        print("=" * 60)
+        
+        print("\n✨ 架构设计亮点:")
+        print("1. 🏗️ 分层架构 - 关注点分离，职责清晰")
+        print("2. 🔧 组合模式 - 灵活组合，独立管理")
+        print("3. 🎯 专业化设计 - 各记忆类型特点鲜明")
+        print("4. 🔗 统一接口 - 简化使用，一致体验")
+        print("5. 🚀 高扩展性 - 插件化设计，灵活配置")
+        
+        print("\n🎯 设计原则:")
+        print("• 单一职责原则 - 每个组件专注特定功能")
+        print("• 开闭原则 - 对扩展开放，对修改封闭")
+        print("• 依赖倒置原则 - 依赖抽象，不依赖具体")
+        print("• 组合优于继承 - 灵活组合，避免复杂继承")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/03_WorkingMemory_Implementation.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 03: WorkingMemory实现详解
+展示工作记忆的混合检索策略和TTL机制
+"""
+
+import time
+from datetime import datetime, timedelta
+from typing import List, Dict, Any
+from hello_agents.tools import MemoryTool
+from hello_agents.memory import MemoryItem
+
+class WorkingMemoryDemo:
+    """工作记忆演示类"""
+    
+    def __init__(self):
+        self.memory_tool = MemoryTool(
+            user_id="working_memory_demo",
+            memory_types=["working"]  # 只启用工作记忆
+        )
+    
+    def demonstrate_capacity_management(self):
+        """演示容量管理和TTL机制"""
+        print("🧠 工作记忆容量管理演示")
+        print("=" * 50)
+        
+        print("工作记忆特点:")
+        print("• 容量有限（默认50条）")
+        print("• TTL机制（默认60分钟）")
+        print("• 自动清理过期记忆")
+        print("• 优先级管理（重要性排序）")
+        
+        # 添加多条记忆来演示容量管理
+        print(f"\n📝 添加测试记忆...")
+        for i in range(10):
+            importance = 0.3 + (i * 0.07)  # 递增重要性
+            self.memory_tool.execute("add",
+                content=f"工作记忆测试项目 {i+1} - 重要性 {importance:.2f}",
+                memory_type="working",
+                importance=importance,
+                test_id=i+1,
+                category="capacity_test"
+            )
+        
+        # 查看当前状态
+        stats = self.memory_tool.execute("stats")
+        print(f"当前状态: {stats}")
+        
+        # 演示重要性排序
+        print(f"\n🔍 按重要性搜索:")
+        result = self.memory_tool.execute("search", 
+            query="测试项目", 
+            memory_type="working",
+            limit=5
+        )
+        print(result)
+    
+    def demonstrate_mixed_retrieval_strategy(self):
+        """演示混合检索策略"""
+        print("\n🔍 混合检索策略演示")
+        print("-" * 40)
+        
+        print("混合检索策略包括:")
+        print("• TF-IDF向量化语义检索")
+        print("• 关键词匹配检索")
+        print("• 时间衰减因子")
+        print("• 重要性权重调整")
+        
+        # 添加不同类型的记忆用于检索测试
+        test_memories = [
+            {
+                "content": "Python是一种高级编程语言，语法简洁清晰",
+                "importance": 0.8,
+                "topic": "programming",
+                "language": "python"
+            },
+            {
+                "content": "机器学习是人工智能的重要分支，包括监督学习和无监督学习",
+                "importance": 0.9,
+                "topic": "ai",
+                "domain": "machine_learning"
+            },
+            {
+                "content": "数据结构包括数组、链表、栈、队列等基本结构",
+                "importance": 0.7,
+                "topic": "computer_science",
+                "category": "data_structures"
+            },
+            {
+                "content": "算法复杂度分析使用大O记号来描述时间和空间复杂度",
+                "importance": 0.8,
+                "topic": "algorithms",
+                "analysis": "complexity"
+            }
+        ]
+        
+        print(f"\n📝 添加测试记忆...")
+        for i, memory in enumerate(test_memories):
+            content = memory.pop("content")
+            importance = memory.pop("importance")
+            self.memory_tool.execute("add",
+                content=content,
+                memory_type="working",
+                importance=importance,
+                **memory
+            )
+        
+        # 测试不同类型的检索
+        search_tests = [
+            ("Python编程", "测试语义匹配"),
+            ("学习", "测试关键词匹配"),
+            ("复杂度", "测试部分匹配"),
+            ("人工智能机器学习", "测试多词匹配")
+        ]
+        
+        print(f"\n🔍 混合检索测试:")
+        for query, description in search_tests:
+            print(f"\n查询: '{query}' ({description})")
+            result = self.memory_tool.execute("search",
+                query=query,
+                memory_type="working",
+                limit=2
+            )
+            print(f"结果: {result}")
+    
+    def demonstrate_time_decay_mechanism(self):
+        """演示时间衰减机制"""
+        print("\n⏰ 时间衰减机制演示")
+        print("-" * 40)
+        
+        print("时间衰减机制:")
+        print("• 新记忆权重更高")
+        print("• 旧记忆权重衰减")
+        print("• 模拟人类记忆特点")
+        print("• 平衡新旧信息重要性")
+        
+        # 添加不同时间的记忆（模拟）
+        time_test_memories = [
+            ("最新的重要信息 - 刚刚学习的概念", 0.7, "newest"),
+            ("较新的信息 - 昨天学习的内容", 0.7, "recent"), 
+            ("较旧的信息 - 上周学习的内容", 0.7, "older"),
+            ("最旧的信息 - 很久以前的内容", 0.7, "oldest")
+        ]
+        
+        print(f"\n📝 添加不同时期的记忆...")
+        for content, importance, age_category in time_test_memories:
+            self.memory_tool.execute("add",
+                content=content,
+                memory_type="working",
+                importance=importance,
+                age_category=age_category,
+                timestamp_category=age_category
+            )
+        
+        # 搜索测试时间衰减效果
+        print(f"\n🔍 时间衰减效果测试:")
+        result = self.memory_tool.execute("search",
+            query="学习的内容",
+            memory_type="working",
+            limit=4
+        )
+        print("搜索结果（注意时间因素对排序的影响）:")
+        print(result)
+    
+    def demonstrate_automatic_cleanup(self):
+        """演示自动清理机制"""
+        print("\n🧹 自动清理机制演示")
+        print("-" * 40)
+        
+        print("自动清理机制:")
+        print("• 过期记忆自动清理")
+        print("• 容量超限时清理低优先级记忆")
+        print("• 保持系统性能和响应速度")
+        print("• 模拟工作记忆的有限容量")
+        
+        # 获取清理前的状态
+        stats_before = self.memory_tool.execute("stats")
+        print(f"\n清理前状态: {stats_before}")
+        
+        # 添加一些低重要性的记忆
+        print(f"\n📝 添加低重要性记忆...")
+        for i in range(5):
+            self.memory_tool.execute("add",
+                content=f"低重要性临时记忆 {i+1}",
+                memory_type="working",
+                importance=0.1 + i * 0.05,
+                temporary=True,
+                cleanup_test=True
+            )
+        
+        # 触发基于重要性的清理
+        print(f"\n🧹 执行基于重要性的清理...")
+        cleanup_result = self.memory_tool.execute("forget",
+            strategy="importance_based",
+            threshold=0.3
+        )
+        print(f"清理结果: {cleanup_result}")
+        
+        # 获取清理后的状态
+        stats_after = self.memory_tool.execute("stats")
+        print(f"\n清理后状态: {stats_after}")
+    
+    def demonstrate_performance_characteristics(self):
+        """演示性能特征"""
+        print("\n⚡ 性能特征演示")
+        print("-" * 40)
+        
+        print("工作记忆性能特点:")
+        print("• 纯内存存储，访问速度极快")
+        print("• 无需磁盘I/O，响应时间短")
+        print("• 适合频繁访问的临时数据")
+        print("• 系统重启后数据丢失（符合设计）")
+        
+        # 性能测试
+        print(f"\n⏱️ 性能测试:")
+        
+        # 批量添加测试
+        start_time = time.time()
+        for i in range(20):
+            self.memory_tool.execute("add",
+                content=f"性能测试记忆 {i+1}",
+                memory_type="working",
+                importance=0.5,
+                performance_test=True
+            )
+        add_time = time.time() - start_time
+        print(f"批量添加20条记忆耗时: {add_time:.3f}秒")
+        
+        # 批量搜索测试
+        start_time = time.time()
+        for i in range(10):
+            self.memory_tool.execute("search",
+                query=f"性能测试",
+                memory_type="working",
+                limit=3
+            )
+        search_time = time.time() - start_time
+        print(f"批量搜索10次耗时: {search_time:.3f}秒")
+        
+        # 获取最终统计
+        final_stats = self.memory_tool.execute("stats")
+        print(f"\n📊 最终统计: {final_stats}")
+
+def main():
+    """主函数"""
+    print("🧠 WorkingMemory实现详解")
+    print("展示工作记忆的核心特性和实现机制")
+    print("=" * 60)
+    
+    try:
+        demo = WorkingMemoryDemo()
+        
+        # 1. 容量管理演示
+        demo.demonstrate_capacity_management()
+        
+        # 2. 混合检索策略演示
+        demo.demonstrate_mixed_retrieval_strategy()
+        
+        # 3. 时间衰减机制演示
+        demo.demonstrate_time_decay_mechanism()
+        
+        # 4. 自动清理机制演示
+        demo.demonstrate_automatic_cleanup()
+        
+        # 5. 性能特征演示
+        demo.demonstrate_performance_characteristics()
+        
+        print("\n" + "=" * 60)
+        print("🎉 WorkingMemory实现演示完成！")
+        print("=" * 60)
+        
+        print("\n✨ 工作记忆核心特性:")
+        print("1. 🧠 有限容量 - 模拟人类工作记忆限制")
+        print("2. ⚡ 高速访问 - 纯内存存储，响应迅速")
+        print("3. 🔍 混合检索 - 语义+关键词+时间+重要性")
+        print("4. ⏰ 时间衰减 - 新信息优先，旧信息衰减")
+        print("5. 🧹 自动清理 - TTL机制+优先级管理")
+        
+        print("\n🎯 设计理念:")
+        print("• 临时性 - 存储当前会话的临时信息")
+        print("• 高效性 - 快速访问和处理能力")
+        print("• 智能性 - 自动管理和优化策略")
+        print("• 仿生性 - 模拟人类工作记忆特点")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/04_RAGTool_MarkItDown_Pipeline.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 04: RAGTool的MarkItDown处理管道
+展示Any格式→Markdown→分块→向量化的完整流程
+"""
+
+import os
+import time
+import tempfile
+from hello_agents.tools import RAGTool
+
+class MarkItDownPipelineDemo:
+    """MarkItDown处理管道演示类"""
+    
+    def __init__(self):
+        self.rag_tool = RAGTool(
+            knowledge_base_path="./demo_rag_kb",
+            rag_namespace="markitdown_demo"
+        )
+        self.temp_dir = tempfile.mkdtemp()
+    
+    def create_sample_documents(self):
+        """创建多格式示例文档"""
+        print("📄 创建多格式示例文档")
+        print("=" * 50)
+        
+        # 创建Markdown文档
+        markdown_content = """# Python编程指南
+
+## 基础语法
+Python是一种解释型、高级编程语言。
+
+### 变量和数据类型
+- 整数：`42`
+- 字符串：`"Hello World"`
+- 列表：`[1, 2, 3]`
+
+### 函数定义
+```python
+def greet(name):
+    return f"Hello, {name}!"
+```
+
+## 面向对象编程
+Python支持面向对象编程范式。
+
+### 类定义
+```python
+class Person:
+    def __init__(self, name):
+        self.name = name
+    
+    def say_hello(self):
+        return f"Hello, I'm {self.name}"
+```
+"""
+        
+        # 创建HTML文档
+        html_content = """<!DOCTYPE html>
+<html>
+<head>
+    <title>Web开发基础</title>
+</head>
+<body>
+    <h1>HTML基础</h1>
+    <p>HTML是超文本标记语言，用于创建网页结构。</p>
+    
+    <h2>常用标签</h2>
+    <ul>
+        <li>h1-h6: 标题标签</li>
+        <li>p: 段落标签</li>
+        <li>div: 容器标签</li>
+        <li>span: 行内标签</li>
+    </ul>
+    
+    <h2>CSS样式</h2>
+    <p>CSS用于控制网页的样式和布局。</p>
+    <code>
+        body { font-family: Arial, sans-serif; }
+        .container { max-width: 1200px; margin: 0 auto; }
+    </code>
+</body>
+</html>"""
+        
+        # 创建JSON文档
+        json_content = """{
+    "project": "HelloAgents",
+    "version": "1.0.0",
+    "description": "AI Agent开发框架",
+    "features": [
+        "记忆系统",
+        "RAG检索",
+        "工具集成",
+        "多模态支持"
+    ],
+    "components": {
+        "memory": {
+            "types": ["working", "episodic", "semantic", "perceptual"],
+            "storage": ["SQLite", "Qdrant", "Neo4j"]
+        },
+        "rag": {
+            "formats": ["PDF", "Word", "Excel", "HTML", "Markdown"],
+            "pipeline": ["MarkItDown", "Chunking", "Embedding", "Storage"]
+        }
+    }
+}"""
+        
+        # 创建CSV文档
+        csv_content = """名称,类型,重要性,描述
+工作记忆,临时存储,0.7,存储当前会话的临时信息
+情景记忆,事件记录,0.8,记录具体的事件和经历
+语义记忆,知识存储,0.9,存储概念性知识和规则
+感知记忆,多模态,0.6,处理图像音频等感知数据
+向量检索,技术组件,0.8,基于语义相似度的检索
+知识图谱,技术组件,0.9,实体关系的结构化表示"""
+        
+        # 保存文档到临时目录
+        documents = {
+            "python_guide.md": markdown_content,
+            "web_basics.html": html_content,
+            "project_info.json": json_content,
+            "memory_types.csv": csv_content
+        }
+        
+        file_paths = {}
+        for filename, content in documents.items():
+            file_path = os.path.join(self.temp_dir, filename)
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+            file_paths[filename] = file_path
+            print(f"✅ 创建文档: {filename}")
+        
+        return file_paths
+    
+    def demonstrate_markitdown_conversion(self, file_paths):
+        """演示MarkItDown转换过程"""
+        print("\n🔄 MarkItDown转换过程演示")
+        print("-" * 50)
+        
+        print("MarkItDown处理流程:")
+        print("1. 📄 检测文档格式")
+        print("2. 🔄 转换为Markdown")
+        print("3. 📝 保持结构信息")
+        print("4. ✨ 统一格式输出")
+        
+        conversion_results = {}
+        
+        for filename, file_path in file_paths.items():
+            print(f"\n处理文档: {filename}")
+            print(f"原始格式: {os.path.splitext(filename)[1]}")
+            
+            start_time = time.time()
+            
+            # 使用RAGTool添加文档，内部会调用MarkItDown
+            result = self.rag_tool.execute("add_document", 
+                                         file_path=file_path)
+            
+            process_time = time.time() - start_time
+            
+            print(f"处理结果: {result}")
+            print(f"处理时间: {process_time:.3f}秒")
+            print(f"✅ {filename} → Markdown → 分块 → 向量化")
+            
+            conversion_results[filename] = {
+                "result": result,
+                "time": process_time
+            }
+        
+        return conversion_results
+    
+    def demonstrate_markdown_chunking(self):
+        """演示基于Markdown的智能分块"""
+        print("\n📊 基于Markdown的智能分块演示")
+        print("-" * 50)
+        
+        print("Markdown分块策略:")
+        print("• 🏷️ 标题层次感知 - 利用#、##、###结构")
+        print("• 📝 段落语义保持 - 保持内容完整性")
+        print("• 🔢 Token精确控制 - 适配嵌入模型")
+        print("• 🔗 智能重叠策略 - 避免信息丢失")
+        
+        # 添加一个复杂的Markdown文档来演示分块
+        complex_markdown = """# 人工智能技术栈
+
+## 机器学习基础
+
+### 监督学习
+监督学习使用标注数据训练模型，包括分类和回归任务。
+
+#### 分类算法
+- 逻辑回归：用于二分类和多分类问题
+- 决策树：基于特征分割的树形结构
+- 随机森林：多个决策树的集成方法
+- 支持向量机：寻找最优分离超平面
+
+#### 回归算法
+- 线性回归：建立特征与目标的线性关系
+- 多项式回归：处理非线性关系
+- 岭回归：添加L2正则化的线性回归
+
+### 无监督学习
+无监督学习从无标注数据中发现模式和结构。
+
+#### 聚类算法
+- K-means：基于距离的聚类方法
+- 层次聚类：构建聚类树状结构
+- DBSCAN：基于密度的聚类算法
+
+#### 降维算法
+- PCA：主成分分析，线性降维
+- t-SNE：非线性降维，适合可视化
+- UMAP：保持局部和全局结构的降维
+
+## 深度学习
+
+### 神经网络基础
+神经网络是深度学习的基础，模拟人脑神经元结构。
+
+#### 基本组件
+- 神经元：基本计算单元
+- 激活函数：引入非线性
+- 损失函数：衡量预测误差
+- 优化器：更新网络参数
+
+### 常见架构
+- CNN：卷积神经网络，适合图像处理
+- RNN：循环神经网络，处理序列数据
+- LSTM：长短期记忆网络，解决梯度消失
+- Transformer：注意力机制，处理长序列
+
+## 自然语言处理
+
+### 文本预处理
+- 分词：将文本分割为词汇单元
+- 词性标注：识别词汇的语法角色
+- 命名实体识别：提取人名、地名等实体
+- 情感分析：判断文本的情感倾向
+
+### 语言模型
+- N-gram：基于统计的语言模型
+- Word2Vec：词向量表示学习
+- BERT：双向编码器表示
+- GPT：生成式预训练模型
+"""
+        
+        print(f"\n📝 添加复杂Markdown文档进行分块测试...")
+        result = self.rag_tool.execute("add_text",
+                                     text=complex_markdown,
+                                     document_id="ai_tech_stack",
+                                     chunk_size=800,
+                                     chunk_overlap=100)
+        
+        print(f"分块结果: {result}")
+        
+        # 测试基于结构的检索
+        print(f"\n🔍 测试基于Markdown结构的检索:")
+        
+        search_queries = [
+            ("监督学习算法", "测试二级标题内容检索"),
+            ("神经网络基础", "测试跨层级内容检索"),
+            ("BERT GPT", "测试具体技术检索"),
+            ("聚类降维", "测试相关概念检索")
+        ]
+        
+        for query, description in search_queries:
+            print(f"\n查询: '{query}' ({description})")
+            search_result = self.rag_tool.execute("search",
+                                                query=query,
+                                                limit=2)
+            print(f"检索结果: {search_result[:200]}...")
+    
+    def demonstrate_embedding_optimization(self):
+        """演示面向嵌入的Markdown预处理"""
+        print("\n🎯 面向嵌入的Markdown预处理演示")
+        print("-" * 50)
+        
+        print("Markdown预处理优化:")
+        print("• 🏷️ 移除格式标记，保留语义内容")
+        print("• 🔗 处理链接格式，保留链接文本")
+        print("• 💻 清理代码块，保留代码内容")
+        print("• 🧹 清理多余空白，优化向量表示")
+        
+        # 演示预处理前后的对比
+        raw_markdown = """## 代码示例
+
+这是一个**重要的**Python函数：
+
+```python
+def process_data(data):
+    \"\"\"处理数据的函数\"\"\"
+    return [item.strip() for item in data if item]
+```
+
+更多信息请参考[官方文档](https://docs.python.org)。
+
+*注意*：这个函数会`自动过滤`空值。
+"""
+        
+        print(f"\n📝 原始Markdown内容:")
+        print(raw_markdown)
+        
+        # 添加到RAG系统，内部会进行预处理
+        result = self.rag_tool.execute("add_text",
+                                     text=raw_markdown,
+                                     document_id="preprocessing_demo")
+        
+        print(f"\n✅ 预处理并添加完成: {result}")
+        
+        # 测试预处理后的检索效果
+        print(f"\n🔍 测试预处理后的检索效果:")
+        search_result = self.rag_tool.execute("search",
+                                            query="Python函数处理数据",
+                                            limit=1)
+        print(f"检索结果: {search_result}")
+    
+    def demonstrate_pipeline_performance(self):
+        """演示处理管道性能"""
+        print("\n⚡ 处理管道性能演示")
+        print("-" * 50)
+        
+        print("性能测试指标:")
+        print("• 📄 文档转换速度")
+        print("• 📊 分块处理效率")
+        print("• 🎯 向量化时间")
+        print("• 💾 存储操作耗时")
+        
+        # 批量处理性能测试
+        batch_texts = [
+            f"批量处理测试文档 {i+1}：这是一个用于测试MarkItDown处理管道性能的示例文档。"
+            f"文档包含了多种格式的内容，包括标题、段落、列表等结构化信息。"
+            f"通过批量处理可以评估系统的整体性能表现。" 
+            for i in range(10)
+        ]
+        
+        print(f"\n⏱️ 批量处理性能测试 (10个文档):")
+        start_time = time.time()
+        
+        batch_result = self.rag_tool.batch_add_texts(
+            batch_texts,
+            document_ids=[f"perf_test_{i+1}" for i in range(10)]
+        )
+        
+        batch_time = time.time() - start_time
+        
+        print(f"批量处理结果: {batch_result}")
+        print(f"总耗时: {batch_time:.3f}秒")
+        print(f"平均每文档: {batch_time/10:.3f}秒")
+        
+        # 获取最终统计
+        stats = self.rag_tool.execute("stats")
+        print(f"\n📊 最终统计: {stats}")
+
+def main():
+    """主函数"""
+    print("🔄 RAGTool的MarkItDown处理管道演示")
+    print("展示Any格式→Markdown→分块→向量化的完整流程")
+    print("=" * 70)
+    
+    try:
+        demo = MarkItDownPipelineDemo()
+        
+        # 1. 创建多格式示例文档
+        file_paths = demo.create_sample_documents()
+        
+        # 2. 演示MarkItDown转换过程
+        conversion_results = demo.demonstrate_markitdown_conversion(file_paths)
+        
+        # 3. 演示基于Markdown的智能分块
+        demo.demonstrate_markdown_chunking()
+        
+        # 4. 演示面向嵌入的预处理优化
+        demo.demonstrate_embedding_optimization()
+        
+        # 5. 演示处理管道性能
+        demo.demonstrate_pipeline_performance()
+        
+        print("\n" + "=" * 70)
+        print("🎉 MarkItDown处理管道演示完成！")
+        print("=" * 70)
+        
+        print("\n✨ 处理管道核心特性:")
+        print("1. 🔄 格式统一 - Any格式→Markdown标准化")
+        print("2. 🏗️ 结构保持 - 保留文档逻辑结构")
+        print("3. 📊 智能分块 - 基于Markdown结构的语义分割")
+        print("4. 🎯 嵌入优化 - 针对向量化的预处理")
+        print("5. ⚡ 高效处理 - 批量处理和性能优化")
+        
+        print("\n🎯 技术优势:")
+        print("• 统一处理 - 一套流程处理所有格式")
+        print("• 结构感知 - 充分利用Markdown结构信息")
+        print("• 语义保持 - 在格式转换中保持语义完整性")
+        print("• 检索优化 - 为向量检索优化的文本表示")
+        
+        # 清理临时文件
+        import shutil
+        shutil.rmtree(demo.temp_dir)
+        print(f"\n🧹 清理临时文件: {demo.temp_dir}")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/05_RAGTool_Advanced_Search.py

@@ -0,0 +1,444 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 05: RAGTool高级检索策略
+展示MQE、HyDE等先进检索技术的实现和应用
+"""
+
+import time
+from hello_agents.tools import RAGTool
+
+class AdvancedSearchDemo:
+    """高级检索演示类"""
+    
+    def __init__(self):
+        self.rag_tool = RAGTool(
+            knowledge_base_path="./advanced_search_kb",
+            rag_namespace="advanced_search_demo"
+        )
+        self._setup_knowledge_base()
+    
+    def _setup_knowledge_base(self):
+        """设置知识库内容"""
+        print("📚 设置知识库内容")
+        print("=" * 50)
+        
+        # 添加技术文档
+        tech_documents = [
+            {
+                "id": "transformer_architecture",
+                "content": """# Transformer架构详解
+
+## 注意力机制
+Transformer的核心是自注意力机制（Self-Attention），它允许模型在处理序列时关注到序列中的不同位置。
+
+### 多头注意力
+多头注意力机制将输入投影到多个不同的子空间，每个头关注不同的表示子空间。
+
+### 位置编码
+由于Transformer没有循环结构，需要位置编码来提供序列中位置信息。
+
+## 编码器-解码器结构
+- 编码器：将输入序列编码为表示
+- 解码器：基于编码器输出生成目标序列
+
+## 应用领域
+- 机器翻译
+- 文本摘要
+- 问答系统
+- 代码生成
+"""
+            },
+            {
+                "id": "deep_learning_optimization",
+                "content": """# 深度学习优化技术
+
+## 梯度下降算法
+梯度下降是深度学习中最基础的优化算法。
+
+### 随机梯度下降（SGD）
+- 每次使用单个样本更新参数
+- 计算效率高，但收敛不稳定
+
+### 批量梯度下降
+- 使用全部训练数据计算梯度
+- 收敛稳定，但计算成本高
+
+### 小批量梯度下降
+- 平衡了SGD和批量梯度下降的优缺点
+- 是实际应用中最常用的方法
+
+## 自适应学习率算法
+- Adam：结合动量和自适应学习率
+- AdaGrad：根据历史梯度调整学习率
+- RMSprop：解决AdaGrad学习率衰减过快的问题
+
+## 正则化技术
+- Dropout：随机丢弃神经元防止过拟合
+- Batch Normalization：标准化层输入
+- Weight Decay：权重衰减正则化
+"""
+            },
+            {
+                "id": "nlp_applications",
+                "content": """# 自然语言处理应用
+
+## 文本分类
+文本分类是NLP中的基础任务，包括情感分析、主题分类、垃圾邮件检测等。
+
+### 传统方法
+- 词袋模型（Bag of Words）
+- TF-IDF特征
+- 朴素贝叶斯分类器
+
+### 深度学习方法
+- CNN用于文本分类
+- RNN和LSTM处理序列信息
+- BERT等预训练模型
+
+## 命名实体识别（NER）
+识别文本中的人名、地名、组织名等实体。
+
+### 序列标注方法
+- BIO标注体系
+- CRF条件随机场
+- BiLSTM-CRF模型
+
+## 机器翻译
+将一种语言的文本翻译成另一种语言。
+
+### 统计机器翻译
+- 基于短语的翻译模型
+- 语言模型和翻译模型
+
+### 神经机器翻译
+- Seq2Seq模型
+- 注意力机制
+- Transformer架构
+"""
+            },
+            {
+                "id": "computer_vision",
+                "content": """# 计算机视觉技术
+
+## 图像分类
+图像分类是计算机视觉的基础任务，目标是将图像分配到预定义的类别中。
+
+### 卷积神经网络（CNN）
+- 卷积层：提取局部特征
+- 池化层：降低维度和计算量
+- 全连接层：进行最终分类
+
+### 经典架构
+- LeNet：最早的CNN架构
+- AlexNet：深度学习在图像识别的突破
+- VGG：使用小卷积核的深层网络
+- ResNet：残差连接解决梯度消失
+
+## 目标检测
+在图像中定位和识别多个对象。
+
+### 两阶段方法
+- R-CNN：区域提议+CNN分类
+- Fast R-CNN：端到端训练
+- Faster R-CNN：RPN网络生成提议
+
+### 单阶段方法
+- YOLO：将检测作为回归问题
+- SSD：多尺度特征检测
+
+## 图像分割
+将图像分割为不同的区域或对象。
+
+### 语义分割
+- FCN：全卷积网络
+- U-Net：编码器-解码器结构
+- DeepLab：空洞卷积
+
+### 实例分割
+- Mask R-CNN：在Faster R-CNN基础上添加分割分支
+"""
+            }
+        ]
+        
+        # 批量添加文档
+        for doc in tech_documents:
+            result = self.rag_tool.execute("add_text",
+                                         text=doc["content"],
+                                         document_id=doc["id"])
+            print(f"✅ 添加文档: {doc['id']}")
+        
+        print(f"📊 知识库设置完成，共添加 {len(tech_documents)} 个文档")
+    
+    def demonstrate_basic_search(self):
+        """演示基础搜索功能"""
+        print("\n🔍 基础搜索功能演示")
+        print("-" * 50)
+        
+        print("基础搜索特点:")
+        print("• 向量相似度匹配")
+        print("• 基于嵌入的语义理解")
+        print("• 相关性排序")
+        print("• 快速响应")
+        
+        basic_queries = [
+            ("注意力机制", "测试精确概念匹配"),
+            ("深度学习优化", "测试主题匹配"),
+            ("图像分类CNN", "测试多词匹配"),
+            ("机器翻译模型", "测试跨文档匹配")
+        ]
+        
+        print(f"\n🔍 基础搜索测试:")
+        for query, description in basic_queries:
+            print(f"\n查询: '{query}' ({description})")
+            
+            start_time = time.time()
+            result = self.rag_tool.execute("search",
+                                         query=query,
+                                         limit=2,
+                                         enable_advanced_search=False)
+            search_time = time.time() - start_time
+            
+            print(f"耗时: {search_time:.3f}秒")
+            print(f"结果: {result[:200]}...")
+    
+    def demonstrate_mqe_search(self):
+        """演示多查询扩展（MQE）搜索"""
+        print("\n🔄 多查询扩展（MQE）搜索演示")
+        print("-" * 50)
+        
+        print("MQE搜索原理:")
+        print("• 🤖 使用LLM生成语义等价查询")
+        print("• 🔍 并行执行多个查询")
+        print("• 📊 合并和去重结果")
+        print("• 🎯 提高召回率和覆盖面")
+        
+        mqe_queries = [
+            ("深度学习", "测试概念扩展"),
+            ("优化算法", "测试技术扩展"),
+            ("神经网络", "测试架构扩展")
+        ]
+        
+        print(f"\n🔄 MQE搜索测试:")
+        for query, description in mqe_queries:
+            print(f"\n查询: '{query}' ({description})")
+            
+            # 基础搜索对比
+            start_time = time.time()
+            basic_result = self.rag_tool.execute("search",
+                                               query=query,
+                                               limit=3,
+                                               enable_advanced_search=False)
+            basic_time = time.time() - start_time
+            
+            # MQE搜索
+            start_time = time.time()
+            mqe_result = self.rag_tool.execute("search",
+                                             query=query,
+                                             limit=3,
+                                             enable_advanced_search=True)
+            mqe_time = time.time() - start_time
+            
+            print(f"基础搜索耗时: {basic_time:.3f}秒")
+            print(f"MQE搜索耗时: {mqe_time:.3f}秒")
+            print(f"基础结果: {basic_result[:150]}...")
+            print(f"MQE结果: {mqe_result[:150]}...")
+            print(f"性能对比: MQE搜索耗时是基础搜索的 {mqe_time/basic_time:.1f} 倍")
+    
+    def demonstrate_hyde_search(self):
+        """演示假设文档嵌入（HyDE）搜索"""
+        print("\n📝 假设文档嵌入（HyDE）搜索演示")
+        print("-" * 50)
+        
+        print("HyDE搜索原理:")
+        print("• 🤖 LLM生成假设性答案文档")
+        print("• 📄 将假设文档作为查询向量")
+        print("• 🎯 改善查询-文档匹配效果")
+        print("• 🔍 特别适合复杂问题检索")
+        
+        hyde_queries = [
+            ("如何提高深度学习模型的性能？", "测试方法性问题"),
+            ("Transformer相比RNN有什么优势？", "测试对比性问题"),
+            ("什么是计算机视觉中的目标检测？", "测试定义性问题")
+        ]
+        
+        print(f"\n📝 HyDE搜索测试:")
+        for query, description in hyde_queries:
+            print(f"\n查询: '{query}' ({description})")
+            
+            # 使用智能问答（内部使用HyDE）
+            start_time = time.time()
+            hyde_result = self.rag_tool.execute("ask",
+                                              question=query,
+                                              limit=3,
+                                              enable_advanced_search=True)
+            hyde_time = time.time() - start_time
+            
+            print(f"HyDE问答耗时: {hyde_time:.3f}秒")
+            print(f"HyDE结果: {hyde_result[:300]}...")
+    
+    def demonstrate_combined_advanced_search(self):
+        """演示组合高级搜索"""
+        print("\n🚀 组合高级搜索演示")
+        print("-" * 50)
+        
+        print("组合搜索策略:")
+        print("• 🔄 MQE + HyDE 双重扩展")
+        print("• 📊 多策略结果融合")
+        print("• 🎯 最大化检索效果")
+        print("• ⚡ 智能缓存优化")
+        
+        complex_queries = [
+            ("深度学习中的注意力机制是如何工作的？", "复杂技术问题"),
+            ("比较不同的梯度下降优化算法", "对比分析问题"),
+            ("计算机视觉和自然语言处理的共同技术", "跨领域问题")
+        ]
+        
+        print(f"\n🚀 组合高级搜索测试:")
+        for query, description in complex_queries:
+            print(f"\n查询: '{query}' ({description})")
+            
+            # 组合高级搜索
+            start_time = time.time()
+            
+            # 先进行高级搜索获取相关片段
+            search_result = self.rag_tool.execute("search",
+                                                query=query,
+                                                limit=4,
+                                                enable_advanced_search=True)
+            
+            # 再进行智能问答生成完整答案
+            qa_result = self.rag_tool.execute("ask",
+                                            question=query,
+                                            limit=4,
+                                            enable_advanced_search=True,
+                                            include_citations=True)
+            
+            combined_time = time.time() - start_time
+            
+            print(f"组合搜索耗时: {combined_time:.3f}秒")
+            print(f"搜索片段: {search_result[:200]}...")
+            print(f"智能问答: {qa_result[:400]}...")
+    
+    def demonstrate_search_performance_analysis(self):
+        """演示搜索性能分析"""
+        print("\n📊 搜索性能分析")
+        print("-" * 50)
+        
+        print("性能分析指标:")
+        print("• ⏱️ 响应时间对比")
+        print("• 🎯 检索质量评估")
+        print("• 💾 资源使用情况")
+        print("• 📈 扩展性分析")
+        
+        # 性能测试查询
+        performance_queries = [
+            "机器学习",
+            "深度学习优化算法",
+            "Transformer注意力机制原理",
+            "计算机视觉目标检测方法比较"
+        ]
+        
+        print(f"\n📊 性能对比测试:")
+        
+        # 测试不同搜索策略的性能
+        strategies = [
+            ("基础搜索", {"enable_advanced_search": False}),
+            ("高级搜索", {"enable_advanced_search": True})
+        ]
+        
+        performance_results = {}
+        
+        for strategy_name, params in strategies:
+            print(f"\n{strategy_name}性能测试:")
+            strategy_times = []
+            
+            for query in performance_queries:
+                start_time = time.time()
+                
+                result = self.rag_tool.execute("search",
+                                             query=query,
+                                             limit=3,
+                                             **params)
+                
+                query_time = time.time() - start_time
+                strategy_times.append(query_time)
+                
+                print(f"  查询: '{query[:20]}...' 耗时: {query_time:.3f}秒")
+            
+            avg_time = sum(strategy_times) / len(strategy_times)
+            performance_results[strategy_name] = {
+                "times": strategy_times,
+                "average": avg_time
+            }
+            
+            print(f"  平均耗时: {avg_time:.3f}秒")
+        
+        # 性能对比分析
+        print(f"\n📈 性能对比分析:")
+        basic_avg = performance_results["基础搜索"]["average"]
+        advanced_avg = performance_results["高级搜索"]["average"]
+        
+        print(f"基础搜索平均耗时: {basic_avg:.3f}秒")
+        print(f"高级搜索平均耗时: {advanced_avg:.3f}秒")
+        print(f"性能比值: {advanced_avg/basic_avg:.1f}x")
+        print(f"分析: 高级搜索通过多策略提升检索质量，耗时增加 {((advanced_avg/basic_avg-1)*100):.0f}%")
+        
+        # 获取系统统计
+        stats = self.rag_tool.execute("stats")
+        print(f"\n📊 系统统计: {stats}")
+
+def main():
+    """主函数"""
+    print("🚀 RAGTool高级检索策略演示")
+    print("展示MQE、HyDE等先进检索技术的实现和应用")
+    print("=" * 70)
+    
+    try:
+        demo = AdvancedSearchDemo()
+        
+        # 1. 基础搜索演示
+        demo.demonstrate_basic_search()
+        
+        # 2. MQE搜索演示
+        demo.demonstrate_mqe_search()
+        
+        # 3. HyDE搜索演示
+        demo.demonstrate_hyde_search()
+        
+        # 4. 组合高级搜索演示
+        demo.demonstrate_combined_advanced_search()
+        
+        # 5. 搜索性能分析
+        demo.demonstrate_search_performance_analysis()
+        
+        print("\n" + "=" * 70)
+        print("🎉 高级检索策略演示完成！")
+        print("=" * 70)
+        
+        print("\n✨ 高级检索核心技术:")
+        print("1. 🔄 MQE多查询扩展 - 提高召回率和覆盖面")
+        print("2. 📝 HyDE假设文档嵌入 - 改善查询匹配效果")
+        print("3. 🚀 组合搜索策略 - 多技术融合优化")
+        print("4. 📊 智能结果排序 - 多因素评分机制")
+        print("5. ⚡ 性能优化 - 缓存和批量处理")
+        
+        print("\n🎯 技术优势:")
+        print("• 语义理解 - 超越关键词匹配的语义检索")
+        print("• 查询扩展 - 自动生成相关查询提升召回")
+        print("• 上下文感知 - 理解查询意图和上下文")
+        print("• 质量优化 - 多策略融合提升检索质量")
+        
+        print("\n💡 应用场景:")
+        print("• 技术文档问答 - 复杂技术问题的精准回答")
+        print("• 知识发现 - 从大量文档中发现相关知识")
+        print("• 智能搜索 - 理解用户意图的智能搜索")
+        print("• 内容推荐 - 基于语义相似度的内容推荐")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/06_Memory_Consolidation_Demo.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 06: 记忆整合机制演示
+展示从短期记忆到长期记忆的智能转化过程
+"""
+
+import time
+from datetime import datetime, timedelta
+from hello_agents.tools import MemoryTool
+
+class MemoryConsolidationDemo:
+    """记忆整合演示类"""
+    
+    def __init__(self):
+        self.memory_tool = MemoryTool(
+            user_id="consolidation_demo_user",
+            memory_types=["working", "episodic", "semantic", "perceptual"]
+        )
+    
+    def setup_initial_memories(self):
+        """设置初始记忆数据"""
+        print("📝 设置初始记忆数据")
+        print("=" * 50)
+        
+        # 添加不同重要性的工作记忆
+        working_memories = [
+            {
+                "content": "学习了Transformer架构的基本原理",
+                "importance": 0.9,
+                "topic": "deep_learning",
+                "session": "study_session_1"
+            },
+            {
+                "content": "完成了Python代码调试任务",
+                "importance": 0.8,
+                "topic": "programming",
+                "task_type": "debugging"
+            },
+            {
+                "content": "参加了团队会议讨论项目进展",
+                "importance": 0.7,
+                "topic": "teamwork",
+                "meeting_type": "progress_review"
+            },
+            {
+                "content": "查看了今天的天气预报",
+                "importance": 0.3,
+                "topic": "daily_life",
+                "category": "routine"
+            },
+            {
+                "content": "阅读了关于注意力机制的论文",
+                "importance": 0.85,
+                "topic": "research",
+                "paper_type": "technical"
+            },
+            {
+                "content": "喝了一杯咖啡",
+                "importance": 0.2,
+                "topic": "daily_life",
+                "category": "routine"
+            },
+            {
+                "content": "解决了一个复杂的算法问题",
+                "importance": 0.9,
+                "topic": "problem_solving",
+                "difficulty": "high"
+            },
+            {
+                "content": "整理了桌面文件",
+                "importance": 0.4,
+                "topic": "organization",
+                "category": "maintenance"
+            }
+        ]
+        
+        print("添加工作记忆:")
+        for i, memory in enumerate(working_memories):
+            content = memory.pop("content")
+            importance = memory.pop("importance")
+            
+            result = self.memory_tool.execute("add",
+                                            content=content,
+                                            memory_type="working",
+                                            importance=importance,
+                                            **memory)
+            
+            print(f"  {i+1}. {content[:40]}... (重要性: {importance})")
+        
+        print(f"\n✅ 已添加 {len(working_memories)} 条工作记忆")
+        
+        # 显示当前状态
+        stats = self.memory_tool.execute("stats")
+        print(f"\n📊 当前记忆统计:\n{stats}")
+    
+    def demonstrate_consolidation_criteria(self):
+        """演示整合标准和筛选过程"""
+        print("\n🎯 记忆整合标准演示")
+        print("-" * 50)
+        
+        print("整合标准:")
+        print("• 重要性阈值筛选")
+        print("• 按重要性排序")
+        print("• 类型转换处理")
+        print("• 元数据更新")
+        
+        # 获取当前工作记忆摘要
+        print("\n📋 整合前的工作记忆状态:")
+        summary = self.memory_tool.execute("summary", limit=10)
+        print(summary)
+        
+        # 测试不同阈值的整合效果
+        thresholds = [0.5, 0.7, 0.8]
+        
+        for threshold in thresholds:
+            print(f"\n🔍 测试重要性阈值 {threshold}:")
+            
+            # 模拟整合过程（不实际执行，只是分析）
+            working_memories = []
+            # 这里应该从实际的工作记忆中获取，简化演示
+            
+            print(f"  阈值 {threshold} 下符合整合条件的记忆:")
+            print(f"  • 重要性 >= {threshold} 的记忆将被整合")
+            print(f"  • 整合后类型: working → episodic")
+            print(f"  • 重要性提升: importance × 1.1")
+    
+    def demonstrate_consolidation_process(self):
+        """演示实际的整合过程"""
+        print("\n🔄 记忆整合过程演示")
+        print("-" * 50)
+        
+        print("整合过程步骤:")
+        print("1. 筛选符合条件的记忆")
+        print("2. 按重要性排序")
+        print("3. 创建新的记忆项")
+        print("4. 更新类型和元数据")
+        print("5. 添加整合标记")
+        
+        # 执行不同阈值的整合
+        consolidation_tests = [
+            (0.6, "低阈值整合 - 整合更多记忆"),
+            (0.8, "高阈值整合 - 只整合最重要的记忆")
+        ]
+        
+        for threshold, description in consolidation_tests:
+            print(f"\n🔄 {description} (阈值: {threshold}):")
+            
+            # 获取整合前状态
+            stats_before = self.memory_tool.execute("stats")
+            print(f"整合前状态: {stats_before}")
+            
+            # 执行整合
+            start_time = time.time()
+            consolidation_result = self.memory_tool.execute("consolidate",
+                                                          from_type="working",
+                                                          to_type="episodic",
+                                                          importance_threshold=threshold)
+            consolidation_time = time.time() - start_time
+            
+            print(f"整合结果: {consolidation_result}")
+            print(f"整合耗时: {consolidation_time:.3f}秒")
+            
+            # 获取整合后状态
+            stats_after = self.memory_tool.execute("stats")
+            print(f"整合后状态: {stats_after}")
+            
+            # 查看整合后的情景记忆
+            print(f"\n📚 整合后的情景记忆:")
+            episodic_search = self.memory_tool.execute("search",
+                                                     query="",
+                                                     memory_type="episodic",
+                                                     limit=5)
+            print(episodic_search)
+    
+    def demonstrate_consolidation_metadata(self):
+        """演示整合过程中的元数据处理"""
+        print("\n📋 整合元数据处理演示")
+        print("-" * 50)
+        
+        print("元数据处理:")
+        print("• 保留原始元数据")
+        print("• 添加整合标记")
+        print("• 记录整合时间")
+        print("• 保存原始ID引用")
+        
+        # 添加一个特殊的工作记忆用于演示
+        special_memory_result = self.memory_tool.execute("add",
+            content="这是一个用于演示整合元数据处理的特殊记忆",
+            memory_type="working",
+            importance=0.85,
+            special_tag="metadata_demo",
+            original_context="demonstration",
+            creation_purpose="show_consolidation_metadata"
+        )
+        
+        print(f"添加特殊记忆: {special_memory_result}")
+        
+        # 执行整合
+        print(f"\n🔄 执行整合...")
+        consolidation_result = self.memory_tool.execute("consolidate",
+                                                       from_type="working",
+                                                       to_type="episodic",
+                                                       importance_threshold=0.8)
+        
+        print(f"整合结果: {consolidation_result}")
+        
+        # 搜索整合后的记忆查看元数据
+        print(f"\n🔍 查看整合后的记忆元数据:")
+        search_result = self.memory_tool.execute("search",
+                                                query="特殊记忆",
+                                                memory_type="episodic",
+                                                limit=1)
+        print(search_result)
+    
+    def demonstrate_multi_type_consolidation(self):
+        """演示多类型记忆整合"""
+        print("\n🔀 多类型记忆整合演示")
+        print("-" * 50)
+        
+        print("多类型整合场景:")
+        print("• working → episodic (经历记录)")
+        print("• working → semantic (知识提取)")
+        print("• episodic → semantic (经验总结)")
+        
+        # 添加一些适合不同整合路径的记忆
+        consolidation_candidates = [
+            {
+                "content": "学习了深度学习中的反向传播算法原理",
+                "memory_type": "working",
+                "importance": 0.9,
+                "learning_type": "concept",
+                "suitable_for": "semantic"
+            },
+            {
+                "content": "今天下午参加了AI技术分享会",
+                "memory_type": "working", 
+                "importance": 0.8,
+                "event_type": "meeting",
+                "suitable_for": "episodic"
+            },
+            {
+                "content": "通过多次实践掌握了Transformer的实现技巧",
+                "memory_type": "episodic",
+                "importance": 0.85,
+                "experience_type": "skill",
+                "suitable_for": "semantic"
+            }
+        ]
+        
+        print(f"\n📝 添加整合候选记忆:")
+        for memory in consolidation_candidates:
+            content = memory.pop("content")
+            memory_type = memory.pop("memory_type")
+            importance = memory.pop("importance")
+            suitable_for = memory.pop("suitable_for")
+            
+            result = self.memory_tool.execute("add",
+                                            content=content,
+                                            memory_type=memory_type,
+                                            importance=importance,
+                                            **memory)
+            
+            print(f"  • {content[:50]}... → 适合整合为{suitable_for}")
+        
+        # 执行不同类型的整合
+        consolidation_paths = [
+            ("working", "episodic", 0.75, "经历记录整合"),
+            ("working", "semantic", 0.85, "知识提取整合"),
+            ("episodic", "semantic", 0.8, "经验总结整合")
+        ]
+        
+        for from_type, to_type, threshold, description in consolidation_paths:
+            print(f"\n🔄 {description} ({from_type} → {to_type}):")
+            
+            result = self.memory_tool.execute("consolidate",
+                                            from_type=from_type,
+                                            to_type=to_type,
+                                            importance_threshold=threshold)
+            
+            print(f"整合结果: {result}")
+    
+    def demonstrate_consolidation_benefits(self):
+        """演示记忆整合的益处"""
+        print("\n✨ 记忆整合益处演示")
+        print("-" * 50)
+        
+        print("整合益处:")
+        print("• 长期保存重要信息")
+        print("• 释放工作记忆空间")
+        print("• 形成知识体系")
+        print("• 提升检索效率")
+        
+        # 获取最终的记忆系统状态
+        print(f"\n📊 最终记忆系统状态:")
+        final_stats = self.memory_tool.execute("stats")
+        print(final_stats)
+        
+        # 获取各类型记忆的摘要
+        print(f"\n📋 各类型记忆摘要:")
+        
+        memory_types = ["working", "episodic", "semantic"]
+        for memory_type in memory_types:
+            print(f"\n{memory_type.upper()}记忆:")
+            type_summary = self.memory_tool.execute("search",
+                                                   query="",
+                                                   memory_type=memory_type,
+                                                   limit=3)
+            print(type_summary)
+        
+        # 演示整合后的检索效果
+        print(f"\n🔍 整合后的检索效果测试:")
+        search_queries = [
+            ("深度学习", "测试跨类型检索"),
+            ("学习经历", "测试整合记忆检索"),
+            ("重要概念", "测试语义记忆检索")
+        ]
+        
+        for query, description in search_queries:
+            print(f"\n查询: '{query}' ({description})")
+            result = self.memory_tool.execute("search",
+                                            query=query,
+                                            limit=3)
+            print(result)
+
+def main():
+    """主函数"""
+    print("🔄 记忆整合机制演示")
+    print("展示从短期记忆到长期记忆的智能转化过程")
+    print("=" * 60)
+    
+    try:
+        demo = MemoryConsolidationDemo()
+        
+        # 1. 设置初始记忆数据
+        demo.setup_initial_memories()
+        
+        # 2. 演示整合标准
+        demo.demonstrate_consolidation_criteria()
+        
+        # 3. 演示整合过程
+        demo.demonstrate_consolidation_process()
+        
+        # 4. 演示元数据处理
+        demo.demonstrate_consolidation_metadata()
+        
+        # 5. 演示多类型整合
+        demo.demonstrate_multi_type_consolidation()
+        
+        # 6. 演示整合益处
+        demo.demonstrate_consolidation_benefits()
+        
+        print("\n" + "=" * 60)
+        print("🎉 记忆整合机制演示完成！")
+        print("=" * 60)
+        
+        print("\n✨ 记忆整合核心特性:")
+        print("1. 🎯 智能筛选 - 基于重要性阈值的自动筛选")
+        print("2. 🔄 类型转换 - 灵活的记忆类型转换机制")
+        print("3. 📋 元数据保持 - 完整保留原始上下文信息")
+        print("4. ⚡ 自动化处理 - 无需人工干预的自动整合")
+        print("5. 🔀 多路径支持 - 支持多种整合路径")
+        
+        print("\n🎯 设计理念:")
+        print("• 仿生性 - 模拟人类大脑的记忆固化过程")
+        print("• 智能性 - 自动识别和处理重要信息")
+        print("• 灵活性 - 支持多种整合策略和路径")
+        print("• 完整性 - 保持记忆的完整性和可追溯性")
+        
+        print("\n💡 应用价值:")
+        print("• 知识管理 - 将临时学习转化为长期知识")
+        print("• 经验积累 - 保存重要的实践经验")
+        print("• 系统优化 - 释放短期记忆空间")
+        print("• 智能决策 - 基于历史经验的决策支持")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/07_RAGTool_Intelligent_QA.py

@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 07: RAGTool智能问答系统
+展示完整的检索→上下文构建→答案生成流程
+"""
+
+import time
+from hello_agents.tools import RAGTool
+
+class IntelligentQADemo:
+    """智能问答演示类"""
+    
+    def __init__(self):
+        self.rag_tool = RAGTool(
+            knowledge_base_path="./qa_demo_kb",
+            rag_namespace="intelligent_qa_demo"
+        )
+        self._setup_knowledge_base()
+    
+    def _setup_knowledge_base(self):
+        """设置知识库"""
+        print("📚 设置智能问答知识库")
+        print("=" * 50)
+        
+        # 添加技术知识文档
+        knowledge_documents = [
+            {
+                "id": "ai_fundamentals",
+                "content": """# 人工智能基础
+
+## 定义和历史
+人工智能（Artificial Intelligence, AI）是计算机科学的一个分支，旨在创造能够执行通常需要人类智能的任务的机器。AI的概念最早由Alan Turing在1950年提出。
+
+## 主要分支
+### 机器学习（Machine Learning）
+机器学习是AI的核心分支，使计算机能够从数据中学习而无需明确编程。
+
+#### 监督学习
+- 分类：预测离散标签
+- 回归：预测连续数值
+- 常用算法：线性回归、决策树、随机森林、SVM
+
+#### 无监督学习
+- 聚类：发现数据中的群组
+- 降维：减少数据维度
+- 常用算法：K-means、PCA、t-SNE
+
+#### 强化学习
+通过与环境交互学习最优策略，应用于游戏AI、机器人控制等。
+
+### 深度学习（Deep Learning）
+基于人工神经网络的机器学习方法，在图像识别、自然语言处理等领域取得突破。
+
+#### 神经网络架构
+- 前馈神经网络：最基础的网络结构
+- 卷积神经网络（CNN）：专门处理图像数据
+- 循环神经网络（RNN）：处理序列数据
+- Transformer：基于注意力机制的架构
+
+### 自然语言处理（NLP）
+使计算机能够理解、解释和生成人类语言。
+
+#### 核心任务
+- 文本分类：判断文本类别
+- 命名实体识别：提取人名、地名等
+- 情感分析：判断文本情感倾向
+- 机器翻译：语言间的自动翻译
+- 问答系统：理解问题并生成答案
+"""
+            },
+            {
+                "id": "programming_best_practices",
+                "content": """# 编程最佳实践
+
+## 代码质量
+高质量的代码应该具备可读性、可维护性和可扩展性。
+
+### 命名规范
+- 使用有意义的变量名和函数名
+- 遵循一致的命名约定
+- 避免使用缩写和模糊的名称
+
+### 函数设计
+- 单一职责原则：每个函数只做一件事
+- 函数长度适中：通常不超过20-30行
+- 参数数量合理：避免过多参数
+
+### 代码组织
+- 模块化设计：将相关功能组织在一起
+- 层次化结构：清晰的目录和文件组织
+- 接口设计：定义清晰的模块接口
+
+## 测试策略
+### 单元测试
+- 测试单个函数或方法
+- 使用断言验证预期结果
+- 覆盖边界条件和异常情况
+
+### 集成测试
+- 测试模块间的交互
+- 验证系统的整体功能
+- 模拟真实使用场景
+
+### 性能测试
+- 测量执行时间和内存使用
+- 识别性能瓶颈
+- 优化关键路径
+
+## 版本控制
+### Git最佳实践
+- 频繁提交，小步快跑
+- 编写清晰的提交信息
+- 使用分支管理功能开发
+- 代码审查确保质量
+
+### 协作开发
+- 制定编码规范
+- 使用Issue跟踪问题
+- 文档化API和架构
+- 持续集成和部署
+"""
+            },
+            {
+                "id": "system_design",
+                "content": """# 系统设计原则
+
+## 设计模式
+设计模式是软件设计中常见问题的典型解决方案。
+
+### 创建型模式
+- 单例模式：确保类只有一个实例
+- 工厂模式：创建对象的接口
+- 建造者模式：构建复杂对象
+
+### 结构型模式
+- 适配器模式：接口适配和转换
+- 装饰器模式：动态添加功能
+- 组合模式：树形结构的统一处理
+
+### 行为型模式
+- 观察者模式：对象间的一对多依赖
+- 策略模式：算法的封装和切换
+- 命令模式：请求的封装和参数化
+
+## 架构原则
+### SOLID原则
+- 单一职责原则（SRP）
+- 开闭原则（OCP）
+- 里氏替换原则（LSP）
+- 接口隔离原则（ISP）
+- 依赖倒置原则（DIP）
+
+### 高内聚低耦合
+- 模块内部元素紧密相关
+- 模块间依赖关系最小化
+- 提高代码的可维护性
+
+## 性能优化
+### 算法优化
+- 选择合适的数据结构
+- 优化算法复杂度
+- 避免不必要的计算
+
+### 系统优化
+- 缓存策略：减少重复计算
+- 并发处理：提高系统吞吐量
+- 资源管理：合理使用内存和CPU
+"""
+            }
+        ]
+        
+        # 批量添加知识文档
+        for doc in knowledge_documents:
+            result = self.rag_tool.execute("add_text",
+                                         text=doc["content"],
+                                         document_id=doc["id"])
+            print(f"✅ 添加知识文档: {doc['id']}")
+        
+        print(f"📊 知识库设置完成")
+    
+    def demonstrate_question_understanding(self):
+        """演示问题理解和分类"""
+        print("\n🧠 问题理解和分类演示")
+        print("-" * 50)
+        
+        print("问题类型分析:")
+        print("• 📖 概念定义类 - '什么是...？'")
+        print("• 🔍 方法询问类 - '如何...？'")
+        print("• ⚖️ 对比分析类 - '...和...的区别？'")
+        print("• 💡 应用场景类 - '...用于什么？'")
+        print("• 🔧 实现细节类 - '...是怎么实现的？'")
+        
+        question_categories = [
+            {
+                "category": "概念定义",
+                "questions": [
+                    "什么是人工智能？",
+                    "什么是深度学习？",
+                    "什么是Transformer架构？"
+                ]
+            },
+            {
+                "category": "方法询问",
+                "questions": [
+                    "如何提高代码质量？",
+                    "如何进行系统设计？",
+                    "如何优化算法性能？"
+                ]
+            },
+            {
+                "category": "对比分析",
+                "questions": [
+                    "监督学习和无监督学习的区别是什么？",
+                    "CNN和RNN有什么不同？",
+                    "单元测试和集成测试的区别？"
+                ]
+            },
+            {
+                "category": "应用场景",
+                "questions": [
+                    "强化学习主要用于什么场景？",
+                    "设计模式在什么情况下使用？",
+                    "缓存策略适用于哪些场景？"
+                ]
+            }
+        ]
+        
+        # 测试不同类型问题的处理效果
+        for category_info in question_categories:
+            category = category_info["category"]
+            questions = category_info["questions"]
+            
+            print(f"\n📋 {category}问题测试:")
+            
+            for question in questions[:2]:  # 每类测试2个问题
+                print(f"\n❓ 问题: {question}")
+                
+                start_time = time.time()
+                answer = self.rag_tool.execute("ask",
+                                             question=question,
+                                             limit=3,
+                                             include_citations=True)
+                qa_time = time.time() - start_time
+                
+                print(f"⏱️ 响应时间: {qa_time:.3f}秒")
+                print(f"🤖 回答: {answer[:300]}...")
+                print("-" * 40)
+    
+    def demonstrate_context_construction(self):
+        """演示上下文构建过程"""
+        print("\n🏗️ 上下文构建过程演示")
+        print("-" * 50)
+        
+        print("上下文构建步骤:")
+        print("1. 🔍 检索相关文档片段")
+        print("2. 📊 按相关性排序")
+        print("3. 🧹 清理和格式化内容")
+        print("4. ✂️ 智能截断保持完整性")
+        print("5. 🔗 添加引用信息")
+        
+        # 使用复杂问题演示上下文构建
+        complex_question = "如何设计一个高质量的机器学习系统？"
+        
+        print(f"\n❓ 复杂问题: {complex_question}")
+        print("这个问题需要整合多个文档的信息...")
+        
+        # 先进行搜索，查看检索到的片段
+        print(f"\n🔍 第一步：检索相关片段")
+        search_result = self.rag_tool.execute("search",
+                                            query=complex_question,
+                                            limit=4,
+                                            enable_advanced_search=True)
+        print(f"检索片段: {search_result}")
+        
+        # 然后进行智能问答，查看完整的上下文构建
+        print(f"\n🤖 第二步：构建上下文并生成答案")
+        start_time = time.time()
+        qa_result = self.rag_tool.execute("ask",
+                                        question=complex_question,
+                                        limit=4,
+                                        enable_advanced_search=True,
+                                        include_citations=True,
+                                        max_chars=1500)
+        qa_time = time.time() - start_time
+        
+        print(f"问答耗时: {qa_time:.3f}秒")
+        print(f"完整回答: {qa_result}")
+    
+    def demonstrate_answer_quality_analysis(self):
+        """演示答案质量分析"""
+        print("\n📊 答案质量分析演示")
+        print("-" * 50)
+        
+        print("质量评估指标:")
+        print("• 🎯 相关性得分 - 检索内容与问题的匹配度")
+        print("• 📚 引用完整性 - 答案来源的可追溯性")
+        print("• 💡 答案完整性 - 回答的全面性和准确性")
+        print("• ⚡ 响应速度 - 系统的响应时间")
+        
+        # 质量测试问题集
+        quality_test_questions = [
+            {
+                "question": "什么是机器学习？",
+                "expected_aspects": ["定义", "分类", "应用"],
+                "difficulty": "简单"
+            },
+            {
+                "question": "如何选择合适的机器学习算法？",
+                "expected_aspects": ["数据特点", "问题类型", "性能要求"],
+                "difficulty": "中等"
+            },
+            {
+                "question": "在设计大规模系统时如何平衡性能和可维护性？",
+                "expected_aspects": ["架构设计", "性能优化", "代码质量"],
+                "difficulty": "复杂"
+            }
+        ]
+        
+        print(f"\n📊 答案质量测试:")
+        
+        quality_results = []
+        
+        for test_case in quality_test_questions:
+            question = test_case["question"]
+            difficulty = test_case["difficulty"]
+            expected_aspects = test_case["expected_aspects"]
+            
+            print(f"\n❓ 问题: {question}")
+            print(f"🎯 难度: {difficulty}")
+            print(f"📋 期望涵盖: {', '.join(expected_aspects)}")
+            
+            # 执行问答
+            start_time = time.time()
+            answer = self.rag_tool.execute("ask",
+                                         question=question,
+                                         limit=4,
+                                         enable_advanced_search=True,
+                                         include_citations=True)
+            qa_time = time.time() - start_time
+            
+            # 分析答案质量
+            answer_length = len(answer)
+            has_citations = "参考来源" in answer
+            response_time = qa_time
+            
+            quality_score = self._calculate_quality_score(
+                answer, expected_aspects, response_time
+            )
+            
+            quality_results.append({
+                "question": question,
+                "difficulty": difficulty,
+                "answer_length": answer_length,
+                "has_citations": has_citations,
+                "response_time": response_time,
+                "quality_score": quality_score
+            })
+            
+            print(f"⏱️ 响应时间: {response_time:.3f}秒")
+            print(f"📏 答案长度: {answer_length}字符")
+            print(f"📚 包含引用: {'是' if has_citations else '否'}")
+            print(f"⭐ 质量评分: {quality_score:.2f}/10")
+            print(f"🤖 答案预览: {answer[:200]}...")
+            print("-" * 50)
+        
+        # 质量分析总结
+        self._analyze_quality_results(quality_results)
+    
+    def _calculate_quality_score(self, answer: str, expected_aspects: list, response_time: float) -> float:
+        """计算答案质量评分"""
+        score = 0.0
+        
+        # 内容完整性评分 (40%)
+        content_score = 0
+        for aspect in expected_aspects:
+            if aspect.lower() in answer.lower():
+                content_score += 1
+        content_score = (content_score / len(expected_aspects)) * 4.0
+        
+        # 答案长度评分 (30%)
+        length_score = min(len(answer) / 500, 1.0) * 3.0
+        
+        # 引用完整性评分 (20%)
+        citation_score = 2.0 if "参考来源" in answer else 0.0
+        
+        # 响应速度评分 (10%)
+        speed_score = max(0, 1.0 - (response_time - 1.0) / 5.0) * 1.0
+        
+        total_score = content_score + length_score + citation_score + speed_score
+        return min(total_score, 10.0)
+    
+    def _analyze_quality_results(self, results: list):
+        """分析质量测试结果"""
+        print(f"\n📈 质量分析总结:")
+        
+        avg_score = sum(r["quality_score"] for r in results) / len(results)
+        avg_time = sum(r["response_time"] for r in results) / len(results)
+        citation_rate = sum(1 for r in results if r["has_citations"]) / len(results)
+        
+        print(f"平均质量评分: {avg_score:.2f}/10")
+        print(f"平均响应时间: {avg_time:.3f}秒")
+        print(f"引用完整率: {citation_rate:.1%}")
+        
+        # 按难度分析
+        difficulty_analysis = {}
+        for result in results:
+            difficulty = result["difficulty"]
+            if difficulty not in difficulty_analysis:
+                difficulty_analysis[difficulty] = []
+            difficulty_analysis[difficulty].append(result["quality_score"])
+        
+        print(f"\n📊 按难度分析:")
+        for difficulty, scores in difficulty_analysis.items():
+            avg_difficulty_score = sum(scores) / len(scores)
+            print(f"  {difficulty}: {avg_difficulty_score:.2f}/10")
+    
+    def demonstrate_prompt_engineering(self):
+        """演示提示词工程"""
+        print("\n🎨 提示词工程演示")
+        print("-" * 50)
+        
+        print("提示词设计要素:")
+        print("• 🎯 系统角色定义")
+        print("• 📋 任务明确描述")
+        print("• 🔍 上下文信息注入")
+        print("• 📝 输出格式要求")
+        print("• 🚫 限制和约束条件")
+        
+        # 演示不同的提示词策略
+        prompt_strategies = [
+            {
+                "name": "基础提示",
+                "system_prompt": "你是一个AI助手，请回答用户的问题。",
+                "description": "简单直接的角色定义"
+            },
+            {
+                "name": "专业提示",
+                "system_prompt": """你是一个专业的技术顾问，具备以下能力：
+1. 深入理解技术概念和原理
+2. 提供准确可靠的技术建议
+3. 用清晰简洁的语言解释复杂概念
+4. 基于提供的上下文信息回答问题""",
+                "description": "详细的能力描述和要求"
+            },
+            {
+                "name": "结构化提示",
+                "system_prompt": """你是一个专业的知识助手，请按以下要求回答：
+【理解】仔细分析问题的核心意图
+【检索】基于提供的上下文信息
+【整合】从多个片段提取关键信息
+【回答】用结构化格式清晰表达
+【引用】标注信息来源和依据""",
+                "description": "结构化的处理流程"
+            }
+        ]
+        
+        test_question = "什么是深度学习，它有哪些主要应用？"
+        
+        print(f"\n🧪 提示词策略对比测试:")
+        print(f"测试问题: {test_question}")
+        
+        for strategy in prompt_strategies:
+            print(f"\n📝 {strategy['name']} ({strategy['description']}):")
+            
+            # 这里简化演示，实际的提示词工程在RAGTool内部实现
+            start_time = time.time()
+            answer = self.rag_tool.execute("ask",
+                                         question=test_question,
+                                         limit=3)
+            response_time = time.time() - start_time
+            
+            print(f"⏱️ 响应时间: {response_time:.3f}秒")
+            print(f"🤖 回答长度: {len(answer)}字符")
+            print(f"📄 回答预览: {answer[:250]}...")
+    
+    def demonstrate_citation_system(self):
+        """演示引用系统"""
+        print("\n📚 引用系统演示")
+        print("-" * 50)
+        
+        print("引用系统特点:")
+        print("• 🔗 自动标注信息来源")
+        print("• 📊 显示相似度得分")
+        print("• 📄 提供文档定位")
+        print("• ✅ 确保答案可追溯性")
+        
+        citation_test_questions = [
+            "机器学习有哪些主要类型？",
+            "如何进行代码质量管理？",
+            "系统设计中的SOLID原则是什么？"
+        ]
+        
+        print(f"\n📚 引用系统测试:")
+        
+        for question in citation_test_questions:
+            print(f"\n❓ 问题: {question}")
+            
+            # 启用引用的问答
+            answer_with_citations = self.rag_tool.execute("ask",
+                                                        question=question,
+                                                        limit=3,
+                                                        include_citations=True)
+            
+            # 禁用引用的问答对比
+            answer_without_citations = self.rag_tool.execute("ask",
+                                                           question=question,
+                                                           limit=3,
+                                                           include_citations=False)
+            
+            print(f"🔗 带引用回答: {answer_with_citations[:400]}...")
+            print(f"📝 无引用回答: {answer_without_citations[:200]}...")
+            
+            # 分析引用信息
+            citation_count = answer_with_citations.count("参考来源")
+            print(f"📊 引用分析: 包含 {citation_count} 个引用来源")
+
+def main():
+    """主函数"""
+    print("🤖 RAGTool智能问答系统演示")
+    print("展示完整的检索→上下文构建→答案生成流程")
+    print("=" * 70)
+    
+    try:
+        demo = IntelligentQADemo()
+        
+        # 1. 问题理解和分类演示
+        demo.demonstrate_question_understanding()
+        
+        # 2. 上下文构建过程演示
+        demo.demonstrate_context_construction()
+        
+        # 3. 答案质量分析演示
+        demo.demonstrate_answer_quality_analysis()
+        
+        # 4. 提示词工程演示
+        demo.demonstrate_prompt_engineering()
+        
+        # 5. 引用系统演示
+        demo.demonstrate_citation_system()
+        
+        print("\n" + "=" * 70)
+        print("🎉 智能问答系统演示完成！")
+        print("=" * 70)
+        
+        print("\n✨ 智能问答核心能力:")
+        print("1. 🧠 问题理解 - 准确识别问题类型和意图")
+        print("2. 🔍 智能检索 - 多策略检索相关内容")
+        print("3. 🏗️ 上下文构建 - 智能整合检索结果")
+        print("4. 🤖 答案生成 - 基于上下文的准确回答")
+        print("5. 📚 引用标注 - 完整的来源追溯")
+        
+        print("\n🎯 技术优势:")
+        print("• 语义理解 - 深度理解问题语义和意图")
+        print("• 上下文感知 - 充分利用检索上下文")
+        print("• 质量保证 - 多层次的质量控制机制")
+        print("• 可追溯性 - 完整的答案来源追溯")
+        
+        print("\n💡 应用场景:")
+        print("• 技术支持 - 自动回答技术问题")
+        print("• 知识问答 - 企业内部知识查询")
+        print("• 学习辅导 - 个性化学习问答")
+        print("• 文档助手 - 快速理解复杂文档")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/08_Agent_Tool_Integration.py

@@ -0,0 +1,466 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 08: Agent工具集成
+展示如何在HelloAgents框架中集成MemoryTool和RAGTool
+"""
+
+import time
+from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry
+from hello_agents.tools import MemoryTool, RAGTool
+
+class AgentIntegrationDemo:
+    """Agent工具集成演示类"""
+    
+    def __init__(self):
+        self.setup_agent()
+    
+    def setup_agent(self):
+        """设置Agent和工具"""
+        print("🤖 Agent工具集成设置")
+        print("=" * 50)
+        
+        # 初始化工具
+        print("1. 初始化工具...")
+        self.memory_tool = MemoryTool(
+            user_id="agent_integration_user",
+            memory_types=["working", "episodic", "semantic", "perceptual"]
+        )
+        
+        self.rag_tool = RAGTool(
+            knowledge_base_path="./agent_integration_kb",
+            rag_namespace="agent_demo"
+        )
+        
+        print("✅ MemoryTool和RAGTool初始化完成")
+        
+        # 创建Agent
+        print("\n2. 创建Agent...")
+        self.llm = HelloAgentsLLM()
+        self.agent = SimpleAgent(
+            name="智能学习助手",
+            llm=self.llm,
+            description="集成记忆和RAG功能的智能助手"
+        )
+        
+        print("✅ Agent创建完成")
+        
+        # 注册工具
+        print("\n3. 注册工具...")
+        self.tool_registry = ToolRegistry()
+        self.tool_registry.register_tool(self.memory_tool)
+        self.tool_registry.register_tool(self.rag_tool)
+        self.agent.tool_registry = self.tool_registry
+        
+        print("✅ 工具注册完成")
+        
+        # 显示Agent状态
+        print(f"\n📊 Agent状态:")
+        print(f"  名称: {self.agent.name}")
+        print(f"  描述: {self.agent.description}")
+        print(f"  可用工具: {list(self.tool_registry.tools.keys())}")
+    
+    def demonstrate_tool_registry_pattern(self):
+        """演示工具注册模式"""
+        print("\n🔧 工具注册模式演示")
+        print("-" * 50)
+        
+        print("工具注册模式特点:")
+        print("• 🔌 统一的工具接口")
+        print("• 📋 集中的工具管理")
+        print("• 🔄 动态工具加载")
+        print("• 🎯 工具能力发现")
+        
+        # 演示工具注册过程
+        print(f"\n🔧 工具注册详情:")
+        
+        for tool_name, tool_instance in self.tool_registry.tools.items():
+            print(f"\n工具: {tool_name}")
+            print(f"  类型: {type(tool_instance).__name__}")
+            print(f"  描述: {tool_instance.description}")
+            
+            # 显示工具的主要功能
+            if tool_name == "memory":
+                print(f"  主要功能: 记忆管理、搜索、整合、遗忘")
+                print(f"  记忆类型: {tool_instance.memory_types}")
+            elif tool_name == "rag":
+                print(f"  主要功能: 文档处理、智能问答、知识检索")
+                print(f"  命名空间: {tool_instance.rag_namespace}")
+        
+        # 演示工具发现机制
+        print(f"\n🔍 工具能力发现:")
+        available_tools = self.tool_registry.list_tools()
+        print(f"可用工具列表: {available_tools}")
+        
+        # 演示工具获取
+        memory_tool = self.tool_registry.get_tool("memory")
+        rag_tool = self.tool_registry.get_tool("rag")
+        
+        print(f"\n✅ 工具获取成功:")
+        print(f"  Memory工具: {type(memory_tool).__name__}")
+        print(f"  RAG工具: {type(rag_tool).__name__}")
+    
+    def demonstrate_unified_interface(self):
+        """演示统一接口模式"""
+        print("\n🔗 统一接口模式演示")
+        print("-" * 50)
+        
+        print("统一接口优势:")
+        print("• 🎯 一致的调用方式")
+        print("• 📝 标准化的参数传递")
+        print("• 🛡️ 统一的错误处理")
+        print("• 🔄 简化的工具切换")
+        
+        # 演示统一的execute接口
+        print(f"\n🔗 统一execute接口演示:")
+        
+        # Memory工具操作
+        print(f"\n1. Memory工具操作:")
+        memory_operations = [
+            ("add", {
+                "content": "学习了Agent工具集成模式",
+                "memory_type": "episodic",
+                "importance": 0.8,
+                "topic": "agent_integration"
+            }),
+            ("search", {
+                "query": "Agent集成",
+                "limit": 2
+            }),
+            ("stats", {})
+        ]
+        
+        for operation, params in memory_operations:
+            print(f"  操作: memory.execute('{operation}', {params})")
+            result = self.memory_tool.execute(operation, **params)
+            print(f"  结果: {str(result)[:100]}...")
+        
+        # RAG工具操作
+        print(f"\n2. RAG工具操作:")
+        
+        # 先添加一些内容
+        self.rag_tool.execute("add_text",
+                            text="Agent工具集成是HelloAgents框架的核心特性，允许Agent使用多种工具来完成复杂任务。",
+                            document_id="agent_integration_guide")
+        
+        rag_operations = [
+            ("search", {
+                "query": "Agent工具集成",
+                "limit": 2
+            }),
+            ("ask", {
+                "question": "什么是Agent工具集成？",
+                "limit": 2
+            }),
+            ("stats", {})
+        ]
+        
+        for operation, params in rag_operations:
+            print(f"  操作: rag.execute('{operation}', {params})")
+            result = self.rag_tool.execute(operation, **params)
+            print(f"  结果: {str(result)[:100]}...")
+    
+    def demonstrate_collaborative_workflow(self):
+        """演示协同工作流程"""
+        print("\n🤝 协同工作流程演示")
+        print("-" * 50)
+        
+        print("协同工作场景:")
+        print("• 📚 学习新知识 → RAG存储 + Memory记录")
+        print("• 🔍 回顾学习历程 → Memory检索 + RAG补充")
+        print("• 💡 知识应用 → RAG查询 + Memory更新")
+        print("• 📊 学习分析 → 两工具统计整合")
+        
+        # 场景1：学习新知识
+        print(f"\n📚 场景1：学习新知识")
+        
+        # 向RAG添加学习资料
+        learning_content = """# 设计模式：观察者模式
+
+## 定义
+观察者模式定义了对象间的一对多依赖关系，当一个对象的状态发生改变时，所有依赖它的对象都会得到通知并自动更新。
+
+## 结构
+- Subject（主题）：维护观察者列表，提供注册和删除观察者的方法
+- Observer（观察者）：定义更新接口
+- ConcreteSubject（具体主题）：实现主题接口
+- ConcreteObserver（具体观察者）：实现观察者接口
+
+## 应用场景
+- GUI事件处理
+- 模型-视图架构
+- 发布-订阅系统
+"""
+        
+        rag_result = self.rag_tool.execute("add_text",
+                                         text=learning_content,
+                                         document_id="observer_pattern")
+        print(f"RAG添加结果: {rag_result}")
+        
+        # 记录学习活动到记忆系统
+        memory_result = self.memory_tool.execute("add",
+                                                content="学习了观察者设计模式的定义、结构和应用场景",
+                                                memory_type="episodic",
+                                                importance=0.8,
+                                                topic="design_patterns",
+                                                pattern_type="observer")
+        print(f"Memory记录结果: {memory_result}")
+        
+        # 场景2：回顾学习历程
+        print(f"\n🔍 场景2：回顾学习历程")
+        
+        # 从记忆系统检索学习历史
+        memory_search = self.memory_tool.execute("search",
+                                                query="设计模式学习",
+                                                limit=3)
+        print(f"学习历史回顾: {memory_search}")
+        
+        # 从RAG获取相关知识补充
+        rag_search = self.rag_tool.execute("search",
+                                         query="观察者模式",
+                                         limit=2)
+        print(f"知识内容补充: {rag_search}")
+        
+        # 场景3：知识应用
+        print(f"\n💡 场景3：知识应用")
+        
+        # 通过RAG查询应用方法
+        application_query = self.rag_tool.execute("ask",
+                                                question="观察者模式适用于什么场景？",
+                                                limit=2)
+        print(f"应用场景查询: {application_query}")
+        
+        # 记录应用实践到记忆
+        application_memory = self.memory_tool.execute("add",
+                                                     content="查询了观察者模式的应用场景，准备在GUI项目中使用",
+                                                     memory_type="working",
+                                                     importance=0.7,
+                                                     application_context="gui_project")
+        print(f"应用记录: {application_memory}")
+        
+        # 场景4：学习分析
+        print(f"\n📊 场景4：学习分析")
+        
+        # 获取记忆系统统计
+        memory_stats = self.memory_tool.execute("stats")
+        print(f"记忆统计: {memory_stats}")
+        
+        # 获取RAG系统统计
+        rag_stats = self.rag_tool.execute("stats")
+        print(f"知识库统计: {rag_stats}")
+        
+        # 生成学习摘要
+        learning_summary = self.memory_tool.execute("summary", limit=5)
+        print(f"学习摘要: {learning_summary}")
+    
+    def demonstrate_agent_orchestration(self):
+        """演示Agent编排能力"""
+        print("\n🎭 Agent编排能力演示")
+        print("-" * 50)
+        
+        print("Agent编排特点:")
+        print("• 🧠 智能工具选择")
+        print("• 🔄 工具链式调用")
+        print("• 📊 结果整合分析")
+        print("• 🎯 目标导向执行")
+        
+        # 模拟复杂任务的工具编排
+        print(f"\n🎭 复杂任务编排示例:")
+        print(f"任务: 创建一个关于机器学习的学习计划")
+        
+        # 步骤1：从RAG获取机器学习知识结构
+        print(f"\n步骤1: 获取知识结构")
+        
+        # 添加机器学习知识
+        ml_content = """# 机器学习学习路径
+
+## 基础阶段
+1. 数学基础：线性代数、概率统计、微积分
+2. 编程基础：Python、NumPy、Pandas
+3. 机器学习概念：监督学习、无监督学习、强化学习
+
+## 进阶阶段
+1. 算法实现：从零实现经典算法
+2. 深度学习：神经网络、CNN、RNN、Transformer
+3. 实践项目：端到端机器学习项目
+
+## 高级阶段
+1. 模型优化：超参数调优、模型压缩
+2. 部署运维：模型部署、监控、更新
+3. 前沿技术：最新论文、开源项目
+"""
+        
+        self.rag_tool.execute("add_text",
+                            text=ml_content,
+                            document_id="ml_learning_path")
+        
+        knowledge_structure = self.rag_tool.execute("ask",
+                                                  question="机器学习的学习路径是什么？",
+                                                  limit=3)
+        print(f"知识结构: {knowledge_structure[:200]}...")
+        
+        # 步骤2：记录学习计划到记忆系统
+        print(f"\n步骤2: 记录学习计划")
+        
+        plan_memory = self.memory_tool.execute("add",
+                                             content="制定了机器学习学习计划，包括基础、进阶、高级三个阶段",
+                                             memory_type="episodic",
+                                             importance=0.9,
+                                             plan_type="learning",
+                                             subject="machine_learning")
+        print(f"计划记录: {plan_memory}")
+        
+        # 步骤3：检索相关学习经验
+        print(f"\n步骤3: 检索学习经验")
+        
+        experience_search = self.memory_tool.execute("search",
+                                                    query="学习计划 学习经验",
+                                                    limit=3)
+        print(f"相关经验: {experience_search}")
+        
+        # 步骤4：整合生成最终建议
+        print(f"\n步骤4: 生成最终建议")
+        
+        final_advice = self.rag_tool.execute("ask",
+                                            question="如何制定有效的机器学习学习计划？",
+                                            limit=4)
+        print(f"最终建议: {final_advice[:300]}...")
+        
+        # 记录编排过程
+        orchestration_memory = self.memory_tool.execute("add",
+                                                       content="完成了复杂的学习计划制定任务，使用了RAG和Memory的协同编排",
+                                                       memory_type="working",
+                                                       importance=0.8,
+                                                       task_type="orchestration")
+        print(f"\n编排记录: {orchestration_memory}")
+    
+    def demonstrate_performance_analysis(self):
+        """演示性能分析"""
+        print("\n📊 性能分析演示")
+        print("-" * 50)
+        
+        print("性能分析指标:")
+        print("• ⏱️ 工具响应时间")
+        print("• 🔄 工具切换开销")
+        print("• 💾 内存使用情况")
+        print("• 🎯 任务完成效率")
+        
+        # 性能测试
+        print(f"\n📊 性能测试:")
+        
+        # 单工具性能测试
+        print(f"\n1. 单工具性能:")
+        
+        # Memory工具性能
+        start_time = time.time()
+        for i in range(5):
+            self.memory_tool.execute("add",
+                                   content=f"性能测试记忆 {i+1}",
+                                   memory_type="working",
+                                   importance=0.5)
+        memory_time = time.time() - start_time
+        print(f"Memory工具 - 5次添加操作: {memory_time:.3f}秒")
+        
+        # RAG工具性能
+        start_time = time.time()
+        for i in range(3):
+            self.rag_tool.execute("search",
+                                query=f"测试查询 {i+1}",
+                                limit=2)
+        rag_time = time.time() - start_time
+        print(f"RAG工具 - 3次搜索操作: {rag_time:.3f}秒")
+        
+        # 协同工作性能测试
+        print(f"\n2. 协同工作性能:")
+        
+        start_time = time.time()
+        
+        # 模拟协同工作流程
+        self.rag_tool.execute("add_text",
+                            text="这是一个性能测试文档",
+                            document_id="perf_test")
+        
+        self.memory_tool.execute("add",
+                                content="执行了性能测试",
+                                memory_type="working",
+                                importance=0.6)
+        
+        rag_result = self.rag_tool.execute("search",
+                                         query="性能测试",
+                                         limit=1)
+        
+        memory_result = self.memory_tool.execute("search",
+                                                query="性能测试",
+                                                limit=1)
+        
+        collaborative_time = time.time() - start_time
+        print(f"协同工作流程: {collaborative_time:.3f}秒")
+        
+        # 性能分析总结
+        print(f"\n📈 性能分析总结:")
+        print(f"Memory工具平均响应: {memory_time/5:.3f}秒/操作")
+        print(f"RAG工具平均响应: {rag_time/3:.3f}秒/操作")
+        print(f"协同工作效率: {collaborative_time:.3f}秒/流程")
+        
+        # 获取最终统计
+        final_memory_stats = self.memory_tool.execute("stats")
+        final_rag_stats = self.rag_tool.execute("stats")
+        
+        print(f"\n📊 最终系统状态:")
+        print(f"Memory系统: {final_memory_stats}")
+        print(f"RAG系统: {final_rag_stats}")
+
+def main():
+    """主函数"""
+    print("🤖 Agent工具集成演示")
+    print("展示如何在HelloAgents框架中集成MemoryTool和RAGTool")
+    print("=" * 70)
+    
+    try:
+        demo = AgentIntegrationDemo()
+        
+        # 1. 工具注册模式演示
+        demo.demonstrate_tool_registry_pattern()
+        
+        # 2. 统一接口模式演示
+        demo.demonstrate_unified_interface()
+        
+        # 3. 协同工作流程演示
+        demo.demonstrate_collaborative_workflow()
+        
+        # 4. Agent编排能力演示
+        demo.demonstrate_agent_orchestration()
+        
+        # 5. 性能分析演示
+        demo.demonstrate_performance_analysis()
+        
+        print("\n" + "=" * 70)
+        print("🎉 Agent工具集成演示完成！")
+        print("=" * 70)
+        
+        print("\n✨ Agent集成核心特性:")
+        print("1. 🔧 工具注册模式 - 统一的工具管理和发现")
+        print("2. 🔗 统一接口设计 - 一致的工具调用方式")
+        print("3. 🤝 协同工作流程 - 工具间的智能协作")
+        print("4. 🎭 智能编排能力 - 复杂任务的自动分解")
+        print("5. 📊 性能监控分析 - 全面的性能评估")
+        
+        print("\n🎯 设计优势:")
+        print("• 模块化 - 工具独立开发，灵活组合")
+        print("• 可扩展 - 支持动态添加新工具")
+        print("• 高内聚 - 每个工具专注特定功能")
+        print("• 低耦合 - 工具间依赖关系最小")
+        
+        print("\n💡 应用价值:")
+        print("• 智能助手 - 构建多功能智能助手")
+        print("• 知识管理 - 企业级知识管理系统")
+        print("• 学习平台 - 个性化学习支持系统")
+        print("• 决策支持 - 基于知识和经验的决策")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/09_Memory_Types_Deep_Dive.py

@@ -0,0 +1,742 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 09: 四种记忆类型深度解析
+详细展示WorkingMemory、EpisodicMemory、SemanticMemory、PerceptualMemory的实现特点
+"""
+
+import os
+import time
+import hashlib
+from datetime import datetime, timedelta
+from typing import List, Dict, Any, Optional
+from hello_agents.tools import MemoryTool
+
+class MemoryTypesDeepDive:
+    """四种记忆类型深度解析演示类"""
+    
+    def __init__(self):
+        self.setup_memory_systems()
+    
+    def setup_memory_systems(self):
+        """设置不同的记忆系统"""
+        print("🧠 四种记忆类型深度解析")
+        print("=" * 60)
+        
+        # 创建专门的记忆工具实例
+        self.working_memory_tool = MemoryTool(
+            user_id="working_memory_user",
+            memory_types=["working"]
+        )
+        
+        self.episodic_memory_tool = MemoryTool(
+            user_id="episodic_memory_user", 
+            memory_types=["episodic"]
+        )
+        
+        self.semantic_memory_tool = MemoryTool(
+            user_id="semantic_memory_user",
+            memory_types=["semantic"]
+        )
+        
+        self.perceptual_memory_tool = MemoryTool(
+            user_id="perceptual_memory_user",
+            memory_types=["perceptual"]
+        )
+        
+        print("✅ 四种记忆系统初始化完成")
+    
+    def demonstrate_working_memory(self):
+        """演示工作记忆的特点"""
+        print("\n💭 工作记忆 (Working Memory) 深度解析")
+        print("-" * 60)
+        
+        print("🔍 工作记忆特点:")
+        print("• ⚡ 访问速度极快（纯内存存储）")
+        print("• 📏 容量有限（默认50条记忆）")
+        print("• ⏰ 自动过期（TTL机制）")
+        print("• 🔄 适合临时信息存储")
+        
+        # 演示容量限制
+        print(f"\n1. 容量限制演示:")
+        print("添加大量临时记忆，观察容量管理...")
+        
+        for i in range(8):
+            content = f"临时工作记忆 {i+1}: 当前正在处理任务步骤 {i+1}"
+            result = self.working_memory_tool.execute("add",
+                                                    content=content,
+                                                    memory_type="working",
+                                                    importance=0.3 + (i * 0.1),
+                                                    task_step=i+1)
+            print(f"  添加记忆 {i+1}: {result}")
+        
+        # 检查当前状态
+        stats = self.working_memory_tool.execute("stats")
+        print(f"\n当前工作记忆状态: {stats}")
+        
+        # 演示TTL机制
+        print(f"\n2. TTL（生存时间）机制演示:")
+        
+        # 添加一些带时间戳的记忆
+        current_time = datetime.now()
+        
+        # 模拟不同时间的记忆
+        time_memories = [
+            ("刚刚的想法", 0, 0.8),
+            ("5分钟前的任务", 5, 0.6),
+            ("10分钟前的提醒", 10, 0.4),
+            ("很久以前的笔记", 30, 0.2)
+        ]
+        
+        for content, minutes_ago, importance in time_memories:
+            # 这里我们模拟时间差异
+            result = self.working_memory_tool.execute("add",
+                                                    content=content,
+                                                    memory_type="working",
+                                                    importance=importance,
+                                                    simulated_age_minutes=minutes_ago)
+            print(f"  添加记忆: {content} (模拟 {minutes_ago} 分钟前)")
+        
+        # 演示快速检索
+        print(f"\n3. 快速检索演示:")
+        
+        search_queries = ["任务", "想法", "提醒"]
+        
+        for query in search_queries:
+            start_time = time.time()
+            results = self.working_memory_tool.execute("search",
+                                                     query=query,
+                                                     memory_type="working",
+                                                     limit=3)
+            search_time = time.time() - start_time
+            print(f"  查询 '{query}': {search_time:.4f}秒")
+            print(f"    结果: {results[:100]}...")
+        
+        # 演示自动清理
+        print(f"\n4. 自动清理机制:")
+        
+        # 获取清理前的统计
+        before_stats = self.working_memory_tool.execute("stats")
+        print(f"清理前: {before_stats}")
+        
+        # 触发清理（通过遗忘低重要性记忆）
+        forget_result = self.working_memory_tool.execute("forget",
+                                                       strategy="importance_based",
+                                                       threshold=0.4)
+        print(f"清理结果: {forget_result}")
+        
+        # 获取清理后的统计
+        after_stats = self.working_memory_tool.execute("stats")
+        print(f"清理后: {after_stats}")
+    
+    def demonstrate_episodic_memory(self):
+        """演示情景记忆的特点"""
+        print("\n📖 情景记忆 (Episodic Memory) 深度解析")
+        print("-" * 60)
+        
+        print("🔍 情景记忆特点:")
+        print("• 📅 完整的时间序列记录")
+        print("• 🎭 丰富的上下文信息")
+        print("• 🔗 支持记忆链条构建")
+        print("• 💾 持久化存储")
+        
+        # 演示完整事件记录
+        print(f"\n1. 完整事件记录演示:")
+        
+        # 模拟一个完整的学习会话
+        learning_session = [
+            {
+                "content": "开始学习Python机器学习",
+                "context": "学习开始",
+                "location": "家里书房",
+                "mood": "专注",
+                "importance": 0.7
+            },
+            {
+                "content": "学习了线性回归的数学原理",
+                "context": "理论学习",
+                "chapter": "第3章",
+                "difficulty": "中等",
+                "importance": 0.8
+            },
+            {
+                "content": "实现了第一个线性回归模型",
+                "context": "实践编程",
+                "code_lines": 45,
+                "bugs_fixed": 2,
+                "importance": 0.9
+            },
+            {
+                "content": "完成了课后练习题",
+                "context": "练习巩固",
+                "exercises_completed": 5,
+                "accuracy": 0.8,
+                "importance": 0.6
+            },
+            {
+                "content": "总结今天的学习收获",
+                "context": "学习总结",
+                "key_concepts": ["线性回归", "梯度下降", "损失函数"],
+                "importance": 0.8
+            }
+        ]
+        
+        session_id = f"learning_session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        
+        for i, event in enumerate(learning_session):
+            result = self.episodic_memory_tool.execute("add",
+                                                     content=event["content"],
+                                                     memory_type="episodic",
+                                                     importance=event["importance"],
+                                                     session_id=session_id,
+                                                     sequence_number=i+1,
+                                                     **{k: v for k, v in event.items() if k not in ["content", "importance"]})
+            print(f"  事件 {i+1}: {result}")
+        
+        # 演示时间序列检索
+        print(f"\n2. 时间序列检索演示:")
+        
+        # 按时间顺序检索
+        timeline_search = self.episodic_memory_tool.execute("search",
+                                                          query="学习",
+                                                          memory_type="episodic",
+                                                          limit=10)
+        print(f"学习时间线: {timeline_search}")
+        
+        # 按会话检索
+        session_search = self.episodic_memory_tool.execute("search",
+                                                         query="线性回归",
+                                                         memory_type="episodic",
+                                                         limit=5)
+        print(f"会话内容: {session_search}")
+        
+        # 演示上下文丰富性
+        print(f"\n3. 上下文信息演示:")
+        
+        # 添加带有丰富上下文的记忆
+        rich_context_memory = {
+            "content": "参加了AI技术分享会",
+            "event_type": "conference",
+            "location": "北京国际会议中心",
+            "speakers": ["张教授", "李博士", "王工程师"],
+            "topics": ["深度学习", "自然语言处理", "计算机视觉"],
+            "attendees_count": 200,
+            "duration_hours": 6,
+            "weather": "晴朗",
+            "transportation": "地铁",
+            "networking_contacts": 3,
+            "key_insights": ["Transformer架构的演进", "多模态学习的前景"],
+            "follow_up_actions": ["阅读推荐论文", "尝试新框架"],
+            "satisfaction_rating": 9
+        }
+        
+        context_result = self.episodic_memory_tool.execute("add",
+                                                         content=rich_context_memory["content"],
+                                                         memory_type="episodic",
+                                                         importance=0.9,
+                                                         **{k: v for k, v in rich_context_memory.items() if k != "content"})
+        print(f"丰富上下文记忆: {context_result}")
+        
+        # 演示记忆链条
+        print(f"\n4. 记忆链条构建:")
+        
+        # 创建相关联的记忆序列
+        memory_chain = [
+            ("看到一篇关于GPT的论文", "trigger", None),
+            ("决定深入研究Transformer架构", "decision", "trigger"),
+            ("下载并阅读Attention is All You Need论文", "action", "decision"),
+            ("实现了简化版的自注意力机制", "implementation", "action"),
+            ("在项目中应用了学到的知识", "application", "implementation")
+        ]
+        
+        chain_memories = {}
+        for content, chain_type, parent_type in memory_chain:
+            parent_id = chain_memories.get(parent_type) if parent_type else None
+            
+            result = self.episodic_memory_tool.execute("add",
+                                                     content=content,
+                                                     memory_type="episodic",
+                                                     importance=0.7,
+                                                     chain_type=chain_type,
+                                                     parent_memory=parent_id,
+                                                     chain_id="gpt_learning_chain")
+            
+            # 提取记忆ID（简化处理）
+            memory_id = f"{chain_type}_memory"
+            chain_memories[chain_type] = memory_id
+            print(f"  链条记忆: {content} (类型: {chain_type})")
+        
+        # 检索整个链条
+        chain_search = self.episodic_memory_tool.execute("search",
+                                                        query="GPT Transformer",
+                                                        memory_type="episodic",
+                                                        limit=8)
+        print(f"记忆链条检索: {chain_search}")
+    
+    def demonstrate_semantic_memory(self):
+        """演示语义记忆的特点"""
+        print("\n🧠 语义记忆 (Semantic Memory) 深度解析")
+        print("-" * 60)
+        
+        print("🔍 语义记忆特点:")
+        print("• 🔗 知识图谱结构化存储")
+        print("• 🎯 概念和关系的抽象表示")
+        print("• 🔍 语义相似度检索")
+        print("• 🧮 支持推理和关联")
+        
+        # 演示概念存储
+        print(f"\n1. 概念知识存储演示:")
+        
+        # 添加不同类型的概念知识
+        concepts = [
+            {
+                "content": "机器学习是人工智能的一个分支，通过算法让计算机从数据中学习模式",
+                "concept_type": "definition",
+                "domain": "artificial_intelligence",
+                "keywords": ["机器学习", "人工智能", "算法", "数据", "模式"],
+                "importance": 0.9
+            },
+            {
+                "content": "监督学习使用标记数据训练模型，包括分类和回归两大类任务",
+                "concept_type": "category",
+                "domain": "machine_learning",
+                "parent_concept": "机器学习",
+                "subcategories": ["分类", "回归"],
+                "importance": 0.8
+            },
+            {
+                "content": "梯度下降是一种优化算法，通过迭代更新参数来最小化损失函数",
+                "concept_type": "algorithm",
+                "domain": "optimization",
+                "mathematical_basis": "微积分",
+                "applications": ["神经网络训练", "线性回归"],
+                "importance": 0.8
+            },
+            {
+                "content": "过拟合是指模型在训练数据上表现很好，但在新数据上泛化能力差",
+                "concept_type": "problem",
+                "domain": "machine_learning",
+                "causes": ["模型复杂度过高", "训练数据不足"],
+                "solutions": ["正则化", "交叉验证", "早停"],
+                "importance": 0.7
+            }
+        ]
+        
+        for concept in concepts:
+            result = self.semantic_memory_tool.execute("add",
+                                                     content=concept["content"],
+                                                     memory_type="semantic",
+                                                     importance=concept["importance"],
+                                                     **{k: v for k, v in concept.items() if k not in ["content", "importance"]})
+            print(f"  概念存储: {concept['concept_type']} - {result}")
+        
+        # 演示关系推理
+        print(f"\n2. 关系推理演示:")
+        
+        # 添加关系知识
+        relationships = [
+            {
+                "content": "深度学习是机器学习的子集，使用多层神经网络",
+                "relation_type": "is_subset_of",
+                "subject": "深度学习",
+                "object": "机器学习",
+                "strength": 0.9
+            },
+            {
+                "content": "卷积神经网络特别适合处理图像数据",
+                "relation_type": "suitable_for",
+                "subject": "卷积神经网络",
+                "object": "图像处理",
+                "strength": 0.8
+            },
+            {
+                "content": "反向传播算法用于训练神经网络",
+                "relation_type": "used_for",
+                "subject": "反向传播",
+                "object": "神经网络训练",
+                "strength": 0.9
+            }
+        ]
+        
+        for relation in relationships:
+            result = self.semantic_memory_tool.execute("add",
+                                                     content=relation["content"],
+                                                     memory_type="semantic",
+                                                     importance=0.8,
+                                                     **{k: v for k, v in relation.items() if k != "content"})
+            print(f"  关系存储: {relation['relation_type']} - {result}")
+        
+        # 演示语义检索
+        print(f"\n3. 语义相似度检索:")
+        
+        semantic_queries = [
+            "什么是人工智能？",
+            "如何防止模型过拟合？",
+            "神经网络的训练方法",
+            "图像识别技术"
+        ]
+        
+        for query in semantic_queries:
+            start_time = time.time()
+            results = self.semantic_memory_tool.execute("search",
+                                                      query=query,
+                                                      memory_type="semantic",
+                                                      limit=3)
+            search_time = time.time() - start_time
+            print(f"  查询: '{query}' ({search_time:.4f}秒)")
+            print(f"    结果: {results[:150]}...")
+        
+        # 演示知识图谱构建
+        print(f"\n4. 知识图谱构建:")
+        
+        # 添加实体和关系
+        entities_and_relations = [
+            {
+                "content": "TensorFlow是Google开发的深度学习框架",
+                "entity_type": "framework",
+                "developer": "Google",
+                "domain": "deep_learning",
+                "language": "Python",
+                "year": 2015
+            },
+            {
+                "content": "PyTorch是Facebook开发的深度学习框架，以动态图著称",
+                "entity_type": "framework", 
+                "developer": "Facebook",
+                "domain": "deep_learning",
+                "feature": "dynamic_graph",
+                "language": "Python"
+            },
+            {
+                "content": "BERT是基于Transformer的预训练语言模型",
+                "entity_type": "model",
+                "architecture": "Transformer",
+                "task": "natural_language_processing",
+                "training_method": "pre_training"
+            }
+        ]
+        
+        for item in entities_and_relations:
+            result = self.semantic_memory_tool.execute("add",
+                                                     content=item["content"],
+                                                     memory_type="semantic",
+                                                     importance=0.8,
+                                                     **{k: v for k, v in item.items() if k != "content"})
+            print(f"  实体关系: {item['entity_type']} - {result}")
+        
+        # 获取语义记忆统计
+        semantic_stats = self.semantic_memory_tool.execute("stats")
+        print(f"\n语义记忆统计: {semantic_stats}")
+    
+    def demonstrate_perceptual_memory(self):
+        """演示感知记忆的特点"""
+        print("\n👁️ 感知记忆 (Perceptual Memory) 深度解析")
+        print("-" * 60)
+        
+        print("🔍 感知记忆特点:")
+        print("• 🎨 多模态数据支持")
+        print("• 🔄 跨模态相似性搜索")
+        print("• 📊 感知数据的语义理解")
+        print("• 🎯 内容生成和检索")
+        
+        # 演示文本感知记忆
+        print(f"\n1. 文本感知记忆:")
+        
+        text_perceptions = [
+            {
+                "content": "这是一段优美的诗歌：春江潮水连海平，海上明月共潮生",
+                "modality": "text",
+                "genre": "poetry",
+                "emotion": "peaceful",
+                "language": "chinese",
+                "aesthetic_value": 0.9
+            },
+            {
+                "content": "技术文档：API接口返回JSON格式数据，包含状态码和响应体",
+                "modality": "text",
+                "genre": "technical",
+                "complexity": "medium",
+                "language": "chinese",
+                "practical_value": 0.8
+            }
+        ]
+        
+        for perception in text_perceptions:
+            result = self.perceptual_memory_tool.execute("add",
+                                                       content=perception["content"],
+                                                       memory_type="perceptual",
+                                                       importance=0.7,
+                                                       **{k: v for k, v in perception.items() if k != "content"})
+            print(f"  文本感知: {perception['genre']} - {result}")
+        
+        # 演示图像感知记忆（模拟）
+        print(f"\n2. 图像感知记忆（模拟）:")
+        
+        # 模拟图像数据
+        image_perceptions = [
+            {
+                "content": "一张美丽的日落风景照片",
+                "modality": "image",
+                "file_path": "/simulated/sunset.jpg",
+                "scene_type": "landscape",
+                "colors": ["orange", "red", "purple"],
+                "objects": ["sun", "clouds", "horizon"],
+                "mood": "serene",
+                "quality": "high"
+            },
+            {
+                "content": "技术架构图展示了微服务系统设计",
+                "modality": "image", 
+                "file_path": "/simulated/architecture.png",
+                "diagram_type": "technical",
+                "components": ["API Gateway", "Services", "Database"],
+                "complexity": "high",
+                "purpose": "documentation"
+            }
+        ]
+        
+        for perception in image_perceptions:
+            result = self.perceptual_memory_tool.execute("add",
+                                                       content=perception["content"],
+                                                       memory_type="perceptual",
+                                                       importance=0.8,
+                                                       **{k: v for k, v in perception.items() if k != "content"})
+            print(f"  图像感知: {perception['scene_type']} - {result}")
+        
+        # 演示音频感知记忆（模拟）
+        print(f"\n3. 音频感知记忆（模拟）:")
+        
+        audio_perceptions = [
+            {
+                "content": "一段优美的古典音乐演奏",
+                "modality": "audio",
+                "file_path": "/simulated/classical.mp3",
+                "genre": "classical",
+                "instruments": ["piano", "violin", "cello"],
+                "tempo": "andante",
+                "emotion": "elegant",
+                "duration_seconds": 240
+            },
+            {
+                "content": "技术会议的录音，讨论AI发展趋势",
+                "modality": "audio",
+                "file_path": "/simulated/conference.wav",
+                "content_type": "speech",
+                "topic": "artificial_intelligence",
+                "speakers": 3,
+                "language": "chinese",
+                "duration_seconds": 1800
+            }
+        ]
+        
+        for perception in audio_perceptions:
+            result = self.perceptual_memory_tool.execute("add",
+                                                       content=perception["content"],
+                                                       memory_type="perceptual",
+                                                       importance=0.7,
+                                                       **{k: v for k, v in perception.items() if k != "content"})
+            print(f"  音频感知: {perception['genre']} - {result}")
+        
+        # 演示跨模态检索
+        print(f"\n4. 跨模态检索演示:")
+        
+        cross_modal_queries = [
+            ("美丽的风景", "寻找视觉美感相关内容"),
+            ("技术文档", "查找技术相关的多模态内容"),
+            ("音乐和艺术", "检索艺术相关的感知记忆"),
+            ("会议和讨论", "查找交流相关的内容")
+        ]
+        
+        for query, description in cross_modal_queries:
+            results = self.perceptual_memory_tool.execute("search",
+                                                        query=query,
+                                                        memory_type="perceptual",
+                                                        limit=3)
+            print(f"  跨模态查询: '{query}' ({description})")
+            print(f"    结果: {results[:120]}...")
+        
+        # 演示感知特征分析
+        print(f"\n5. 感知特征分析:")
+        
+        # 获取感知记忆统计
+        perceptual_stats = self.perceptual_memory_tool.execute("stats")
+        print(f"感知记忆统计: {perceptual_stats}")
+        
+        # 分析不同模态的分布
+        modality_analysis = self.perceptual_memory_tool.execute("search",
+                                                              query="模态分析",
+                                                              memory_type="perceptual",
+                                                              limit=10)
+        print(f"模态分布分析: {modality_analysis}")
+    
+    def demonstrate_memory_interactions(self):
+        """演示四种记忆类型的交互"""
+        print("\n🔄 四种记忆类型交互演示")
+        print("-" * 60)
+        
+        print("🔍 记忆交互模式:")
+        print("• 🔄 工作记忆 → 情景记忆（重要事件固化）")
+        print("• 📚 情景记忆 → 语义记忆（经验抽象化）")
+        print("• 👁️ 感知记忆 → 其他记忆（多模态信息整合）")
+        print("• 🧠 语义记忆 → 工作记忆（知识激活）")
+        
+        # 模拟一个完整的学习过程
+        print(f"\n完整学习过程模拟:")
+        
+        # 1. 感知阶段：接收多模态信息
+        print(f"\n1. 感知阶段 - 接收信息:")
+        
+        perceptual_input = self.perceptual_memory_tool.execute("add",
+                                                             content="观看了一个关于深度学习的视频教程",
+                                                             memory_type="perceptual",
+                                                             importance=0.8,
+                                                             modality="video",
+                                                             topic="deep_learning",
+                                                             duration_minutes=45,
+                                                             quality="high")
+        print(f"感知记忆: {perceptual_input}")
+        
+        # 2. 工作记忆阶段：临时处理和思考
+        print(f"\n2. 工作记忆阶段 - 临时处理:")
+        
+        working_thoughts = [
+            "理解了卷积神经网络的基本原理",
+            "需要记住反向传播的计算步骤",
+            "想到了之前学过的线性代数知识",
+            "计划实现一个简单的CNN模型"
+        ]
+        
+        for thought in working_thoughts:
+            result = self.working_memory_tool.execute("add",
+                                                    content=thought,
+                                                    memory_type="working",
+                                                    importance=0.6,
+                                                    processing_stage="active_thinking")
+            print(f"  工作记忆: {thought[:30]}... - {result}")
+        
+        # 3. 情景记忆阶段：记录完整学习事件
+        print(f"\n3. 情景记忆阶段 - 事件记录:")
+        
+        episodic_event = self.episodic_memory_tool.execute("add",
+                                                         content="完成了深度学习视频教程的学习，理解了CNN的核心概念",
+                                                         memory_type="episodic",
+                                                         importance=0.9,
+                                                         event_type="learning_session",
+                                                         duration_minutes=45,
+                                                         location="家里",
+                                                         learning_outcome="理解CNN原理",
+                                                         next_action="实践编程")
+        print(f"情景记忆: {episodic_event}")
+        
+        # 4. 语义记忆阶段：抽象知识存储
+        print(f"\n4. 语义记忆阶段 - 知识抽象:")
+        
+        semantic_knowledge = [
+            {
+                "content": "卷积神经网络通过卷积层提取图像特征，适合计算机视觉任务",
+                "concept": "CNN",
+                "domain": "deep_learning",
+                "application": "computer_vision"
+            },
+            {
+                "content": "反向传播算法通过链式法则计算梯度，用于更新网络参数",
+                "concept": "backpropagation",
+                "domain": "optimization",
+                "mathematical_basis": "chain_rule"
+            }
+        ]
+        
+        for knowledge in semantic_knowledge:
+            result = self.semantic_memory_tool.execute("add",
+                                                     content=knowledge["content"],
+                                                     memory_type="semantic",
+                                                     importance=0.8,
+                                                     **{k: v for k, v in knowledge.items() if k != "content"})
+            print(f"  语义记忆: {knowledge['concept']} - {result}")
+        
+        # 5. 记忆整合演示
+        print(f"\n5. 记忆整合演示:")
+        
+        # 从工作记忆整合到情景记忆
+        consolidation_result = self.working_memory_tool.execute("consolidate",
+                                                              from_type="working",
+                                                              to_type="episodic",
+                                                              importance_threshold=0.6)
+        print(f"工作记忆整合: {consolidation_result}")
+        
+        # 跨记忆类型检索
+        print(f"\n6. 跨记忆类型检索:")
+        
+        query = "深度学习CNN"
+        
+        # 在所有记忆类型中搜索
+        memory_tools = [
+            ("工作记忆", self.working_memory_tool),
+            ("情景记忆", self.episodic_memory_tool),
+            ("语义记忆", self.semantic_memory_tool),
+            ("感知记忆", self.perceptual_memory_tool)
+        ]
+        
+        for memory_name, tool in memory_tools:
+            results = tool.execute("search", query=query, limit=2)
+            print(f"  {memory_name}检索: {results[:80]}...")
+        
+        # 获取所有记忆系统的统计
+        print(f"\n7. 系统整体状态:")
+        
+        for memory_name, tool in memory_tools:
+            stats = tool.execute("stats")
+            print(f"  {memory_name}: {stats}")
+
+def main():
+    """主函数"""
+    print("🧠 四种记忆类型深度解析演示")
+    print("详细展示WorkingMemory、EpisodicMemory、SemanticMemory、PerceptualMemory")
+    print("=" * 80)
+    
+    try:
+        demo = MemoryTypesDeepDive()
+        
+        # 1. 工作记忆演示
+        demo.demonstrate_working_memory()
+        
+        # 2. 情景记忆演示
+        demo.demonstrate_episodic_memory()
+        
+        # 3. 语义记忆演示
+        demo.demonstrate_semantic_memory()
+        
+        # 4. 感知记忆演示
+        demo.demonstrate_perceptual_memory()
+        
+        # 5. 记忆交互演示
+        demo.demonstrate_memory_interactions()
+        
+        print("\n" + "=" * 80)
+        print("🎉 四种记忆类型深度解析完成！")
+        print("=" * 80)
+        
+        print("\n✨ 记忆类型特性总结:")
+        print("1. 💭 工作记忆 - 快速临时存储，容量有限，自动过期")
+        print("2. 📖 情景记忆 - 完整事件记录，时间序列，丰富上下文")
+        print("3. 🧠 语义记忆 - 抽象知识存储，概念关系，语义推理")
+        print("4. 👁️ 感知记忆 - 多模态支持，跨模态检索，感知理解")
+        
+        print("\n🔄 记忆交互模式:")
+        print("• 感知 → 工作 → 情景 → 语义（信息处理流程）")
+        print("• 语义 → 工作（知识激活和应用）")
+        print("• 跨类型检索和整合（智能记忆管理）")
+        
+        print("\n💡 设计价值:")
+        print("• 模拟人类认知过程")
+        print("• 支持多层次信息处理")
+        print("• 实现智能记忆管理")
+        print("• 提供丰富的检索能力")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/10_RAG_Pipeline_Complete.py

@@ -0,0 +1,855 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代码示例 10: RAG完整处理管道
+展示从文档处理到智能问答的完整RAG流程
+"""
+
+import os
+import time
+import json
+from datetime import datetime
+from typing import List, Dict, Any, Optional
+from hello_agents.tools import RAGTool
+
+class RAGPipelineComplete:
+    """RAG完整处理管道演示类"""
+    
+    def __init__(self):
+        self.setup_rag_system()
+    
+    def setup_rag_system(self):
+        """设置RAG系统"""
+        print("📚 RAG完整处理管道演示")
+        print("=" * 60)
+        
+        # 初始化RAG工具
+        self.rag_tool = RAGTool(
+            knowledge_base_path="./rag_pipeline_kb",
+            rag_namespace="complete_pipeline"
+        )
+        
+        print("✅ RAG系统初始化完成")
+        
+        # 显示系统配置
+        print(f"\n📊 系统配置:")
+        print(f"  知识库路径: ./rag_pipeline_kb")
+        print(f"  命名空间: complete_pipeline")
+        print(f"  支持格式: PDF, DOCX, TXT, MD, HTML, JSON")
+    
+    def demonstrate_document_ingestion(self):
+        """演示文档摄取过程"""
+        print("\n📥 文档摄取过程演示")
+        print("-" * 60)
+        
+        print("🔍 文档摄取特点:")
+        print("• 📄 多格式文档支持")
+        print("• 🔄 MarkItDown格式转换")
+        print("• ✂️ 智能文档分块")
+        print("• 🎯 元数据提取")
+        
+        # 演示不同类型文档的处理
+        print(f"\n1. 多格式文档处理:")
+        
+        # 模拟不同格式的文档
+        documents = [
+            {
+                "content": """# 机器学习基础教程
+
+## 第一章：机器学习概述
+
+机器学习是人工智能的一个重要分支，它使计算机能够在没有明确编程的情况下学习和改进。
+
+### 1.1 机器学习的定义
+
+机器学习是一种数据分析方法，它自动化分析模型的构建。它是人工智能的一个分支，基于系统可以从数据中学习、识别模式并在最少人工干预的情况下做出决策的想法。
+
+### 1.2 机器学习的类型
+
+1. **监督学习**：使用标记的训练数据来学习映射函数
+2. **无监督学习**：从未标记的数据中发现隐藏的模式
+3. **强化学习**：通过与环境交互来学习最优行为
+
+### 1.3 常见算法
+
+- 线性回归
+- 逻辑回归
+- 决策树
+- 随机森林
+- 支持向量机
+- 神经网络
+
+## 第二章：数据预处理
+
+数据预处理是机器学习流程中的关键步骤...
+""",
+                "document_id": "ml_tutorial_chapter1",
+                "format": "markdown",
+                "metadata": {
+                    "title": "机器学习基础教程",
+                    "chapter": 1,
+                    "author": "AI教学团队",
+                    "difficulty": "beginner",
+                    "estimated_reading_time": 15
+                }
+            },
+            {
+                "content": """深度学习技术报告
+
+执行摘要：
+本报告分析了深度学习在计算机视觉领域的最新进展。通过对比不同架构的性能，我们发现Transformer架构在多个任务上都表现出色。
+
+主要发现：
+1. Vision Transformer (ViT) 在图像分类任务上超越了传统CNN
+2. CLIP模型实现了图像和文本的统一表示
+3. 自监督学习方法显著减少了对标注数据的依赖
+
+技术细节：
+- 数据集：ImageNet-1K, COCO, OpenImages
+- 评估指标：Top-1准确率, mAP, FID分数
+- 计算资源：8x V100 GPU, 训练时间72小时
+
+结论：
+深度学习技术在计算机视觉领域持续快速发展，Transformer架构的引入为该领域带来了新的突破。建议在实际项目中优先考虑基于Transformer的模型。
+
+附录：
+详细的实验数据和代码实现请参考GitHub仓库。
+""",
+                "document_id": "deep_learning_report",
+                "format": "text",
+                "metadata": {
+                    "title": "深度学习技术报告",
+                    "type": "technical_report",
+                    "date": "2024-01-15",
+                    "department": "AI研究部",
+                    "confidentiality": "internal"
+                }
+            },
+            {
+                "content": """{
+    "api_documentation": {
+        "title": "机器学习API文档",
+        "version": "v2.1",
+        "base_url": "https://api.ml-platform.com/v2",
+        "endpoints": [
+            {
+                "path": "/models",
+                "method": "GET",
+                "description": "获取可用模型列表",
+                "parameters": {
+                    "category": "模型类别 (classification, regression, clustering)",
+                    "limit": "返回结果数量限制"
+                },
+                "response": {
+                    "models": [
+                        {
+                            "id": "model_123",
+                            "name": "RandomForest分类器",
+                            "category": "classification",
+                            "accuracy": 0.95,
+                            "training_data_size": 10000
+                        }
+                    ]
+                }
+            },
+            {
+                "path": "/predict",
+                "method": "POST",
+                "description": "使用指定模型进行预测",
+                "parameters": {
+                    "model_id": "模型ID",
+                    "data": "输入数据"
+                },
+                "response": {
+                    "prediction": "预测结果",
+                    "confidence": "置信度",
+                    "processing_time": "处理时间(ms)"
+                }
+            }
+        ],
+        "authentication": {
+            "type": "API Key",
+            "header": "X-API-Key",
+            "description": "在请求头中包含API密钥"
+        },
+        "rate_limits": {
+            "requests_per_minute": 100,
+            "requests_per_day": 10000
+        }
+    }
+}""",
+                "document_id": "ml_api_docs",
+                "format": "json",
+                "metadata": {
+                    "title": "机器学习API文档",
+                    "version": "v2.1",
+                    "type": "api_documentation",
+                    "last_updated": "2024-01-20"
+                }
+            }
+        ]
+        
+        # 处理每个文档
+        for doc in documents:
+            print(f"\n处理文档: {doc['document_id']} ({doc['format']})")
+            
+            result = self.rag_tool.execute("add_text",
+                                         text=doc["content"],
+                                         document_id=doc["document_id"],
+                                         **doc["metadata"])
+            print(f"  摄取结果: {result}")
+            
+            # 显示文档统计
+            doc_stats = {
+                "字符数": len(doc["content"]),
+                "行数": doc["content"].count('\n') + 1,
+                "格式": doc["format"],
+                "元数据字段": len(doc["metadata"])
+            }
+            print(f"  文档统计: {doc_stats}")
+        
+        # 演示批量文档处理
+        print(f"\n2. 批量文档处理:")
+        
+        batch_documents = []
+        for i in range(3):
+            batch_doc = {
+                "content": f"""# 批量文档 {i+1}
+
+这是第 {i+1} 个批量处理的文档。它包含了关于人工智能发展的重要信息。
+
+## 主要内容
+- AI技术趋势分析
+- 行业应用案例
+- 未来发展预测
+
+## 详细描述
+人工智能技术在过去几年中取得了显著进展，特别是在深度学习、自然语言处理和计算机视觉领域。
+
+### 技术突破
+1. 大语言模型的涌现
+2. 多模态AI的发展
+3. 自动化机器学习的普及
+
+### 应用领域
+- 医疗诊断
+- 金融风控
+- 智能制造
+- 自动驾驶
+
+这些技术的发展为各行各业带来了新的机遇和挑战。
+""",
+                "document_id": f"batch_doc_{i+1}",
+                "metadata": {
+                    "batch_id": "batch_001",
+                    "sequence": i+1,
+                    "topic": "artificial_intelligence",
+                    "processing_date": datetime.now().isoformat()
+                }
+            }
+            batch_documents.append(batch_doc)
+        
+        # 批量处理
+        start_time = time.time()
+        for doc in batch_documents:
+            result = self.rag_tool.execute("add_text",
+                                         text=doc["content"],
+                                         document_id=doc["document_id"],
+                                         **doc["metadata"])
+            print(f"  批量处理 {doc['document_id']}: {result}")
+        
+        batch_time = time.time() - start_time
+        print(f"  批量处理耗时: {batch_time:.3f}秒")
+        
+        # 获取摄取统计
+        stats = self.rag_tool.execute("stats")
+        print(f"\n📊 文档摄取统计: {stats}")
+    
+    def demonstrate_chunking_strategies(self):
+        """演示文档分块策略"""
+        print("\n✂️ 文档分块策略演示")
+        print("-" * 60)
+        
+        print("🔍 分块策略特点:")
+        print("• 📏 基于语义的智能分块")
+        print("• 🔗 保持上下文连贯性")
+        print("• ⚖️ 平衡块大小和信息完整性")
+        print("• 🎯 优化检索效果")
+        
+        # 演示不同分块策略
+        print(f"\n1. 分块策略对比:")
+        
+        # 长文档示例
+        long_document = """# 人工智能发展史
+
+## 引言
+人工智能（Artificial Intelligence, AI）的发展历程可以追溯到20世纪50年代。从最初的符号主义方法到现代的深度学习，AI经历了多次重要的发展阶段。
+
+## 第一阶段：符号主义时代（1950s-1980s）
+### 起源与发展
+1950年，阿兰·图灵发表了著名的论文《计算机器与智能》，提出了"图灵测试"的概念。这标志着人工智能研究的正式开始。
+
+### 主要成就
+- 1956年达特茅斯会议，正式提出"人工智能"概念
+- 专家系统的发展，如MYCIN医疗诊断系统
+- 逻辑推理和知识表示方法的建立
+
+### 局限性
+符号主义方法虽然在某些领域取得了成功，但面临着知识获取瓶颈和常识推理困难等问题。
+
+## 第二阶段：连接主义复兴（1980s-2000s）
+### 神经网络的回归
+1986年，Rumelhart等人重新发现了反向传播算法，使得多层神经网络的训练成为可能。
+
+### 重要突破
+- 多层感知机的成功应用
+- 卷积神经网络在图像识别中的应用
+- 循环神经网络处理序列数据
+
+### 技术限制
+由于计算能力和数据量的限制，神经网络在这一时期的应用仍然有限。
+
+## 第三阶段：深度学习革命（2000s-至今）
+### 深度学习的兴起
+2006年，Geoffrey Hinton等人提出了深度信念网络，开启了深度学习的新时代。
+
+### 关键技术突破
+- GPU并行计算的应用
+- 大数据的可获得性
+- 改进的训练算法和正则化技术
+
+### 重大成就
+- 2012年AlexNet在ImageNet竞赛中的突破性表现
+- 2016年AlphaGo击败世界围棋冠军
+- 2017年Transformer架构的提出
+- 2020年GPT-3等大语言模型的出现
+
+## 第四阶段：通用人工智能探索（2020s-未来）
+### 当前趋势
+- 多模态AI的发展
+- 自监督学习方法的普及
+- 神经符号结合的新方法
+
+### 未来展望
+人工智能正朝着更加通用、可解释和安全的方向发展。通用人工智能（AGI）的实现仍然是一个长期目标。
+
+## 结论
+人工智能的发展是一个螺旋上升的过程，每个阶段都有其独特的贡献和局限性。理解这一发展历程有助于我们更好地把握AI技术的未来方向。
+
+## 参考文献
+1. Turing, A. M. (1950). Computing machinery and intelligence.
+2. Russell, S., & Norvig, P. (2020). Artificial Intelligence: A Modern Approach.
+3. Goodfellow, I., Bengio, Y., & Courville, A. (2016). Deep Learning.
+"""
+        
+        # 添加长文档并观察分块效果
+        chunking_result = self.rag_tool.execute("add_text",
+                                               text=long_document,
+                                               document_id="ai_history_long",
+                                               title="人工智能发展史",
+                                               type="historical_overview",
+                                               chunking_strategy="semantic")
+        print(f"长文档分块结果: {chunking_result}")
+        
+        # 演示不同分块大小的影响
+        print(f"\n2. 分块大小影响分析:")
+        
+        # 搜索测试，观察分块对检索的影响
+        test_queries = [
+            "图灵测试是什么？",
+            "深度学习的关键技术突破",
+            "AlphaGo的意义",
+            "通用人工智能的未来"
+        ]
+        
+        for query in test_queries:
+            start_time = time.time()
+            results = self.rag_tool.execute("search",
+                                          query=query,
+                                          limit=3)
+            search_time = time.time() - start_time
+            print(f"  查询: '{query}' ({search_time:.4f}秒)")
+            print(f"    结果: {results[:120]}...")
+        
+        # 演示结构化文档的分块
+        print(f"\n3. 结构化文档分块:")
+        
+        structured_doc = """# 机器学习算法手册
+
+## 监督学习算法
+
+### 线性回归
+**定义**: 线性回归是一种用于预测连续数值的算法。
+**公式**: y = wx + b
+**优点**: 简单易懂，计算效率高
+**缺点**: 只能处理线性关系
+**应用场景**: 房价预测、销售预测
+
+### 逻辑回归
+**定义**: 逻辑回归用于二分类问题。
+**公式**: p = 1/(1+e^(-wx+b))
+**优点**: 输出概率值，可解释性强
+**缺点**: 对特征工程要求高
+**应用场景**: 邮件分类、医疗诊断
+
+### 决策树
+**定义**: 基于特征进行分层决策的树形结构。
+**算法**: ID3, C4.5, CART
+**优点**: 可解释性强，处理非线性关系
+**缺点**: 容易过拟合
+**应用场景**: 信用评估、医疗诊断
+
+## 无监督学习算法
+
+### K-means聚类
+**定义**: 将数据分为K个簇的聚类算法。
+**步骤**: 初始化中心点 → 分配样本 → 更新中心点 → 重复
+**优点**: 简单高效
+**缺点**: 需要预设簇数
+**应用场景**: 客户分群、图像分割
+
+### 主成分分析(PCA)
+**定义**: 降维算法，保留主要信息。
+**原理**: 找到数据的主要变化方向
+**优点**: 降低维度，去除噪声
+**缺点**: 损失部分信息
+**应用场景**: 数据可视化、特征提取
+"""
+        
+        structured_result = self.rag_tool.execute("add_text",
+                                                 text=structured_doc,
+                                                 document_id="ml_algorithms_handbook",
+                                                 title="机器学习算法手册",
+                                                 type="reference_manual",
+                                                 structure="hierarchical")
+        print(f"结构化文档分块: {structured_result}")
+        
+        # 测试结构化检索
+        structured_queries = [
+            "线性回归的优缺点",
+            "K-means聚类算法",
+            "PCA降维原理"
+        ]
+        
+        for query in structured_queries:
+            results = self.rag_tool.execute("search",
+                                          query=query,
+                                          limit=2)
+            print(f"  结构化查询 '{query}': {results[:100]}...")
+    
+    def demonstrate_advanced_retrieval(self):
+        """演示高级检索策略"""
+        print("\n🔍 高级检索策略演示")
+        print("-" * 60)
+        
+        print("🔍 高级检索特点:")
+        print("• 🎯 多查询扩展（MQE）")
+        print("• 💭 假设文档嵌入（HyDE）")
+        print("• 🔄 混合检索策略")
+        print("• 📊 相关性重排序")
+        
+        # 演示多查询扩展
+        print(f"\n1. 多查询扩展（MQE）演示:")
+        
+        base_query = "如何提高机器学习模型的性能？"
+        print(f"原始查询: {base_query}")
+        
+        # 模拟查询扩展
+        expanded_queries = [
+            "机器学习模型性能优化方法",
+            "提升ML模型准确率的技巧",
+            "模型调优和超参数优化",
+            "机器学习模型评估指标"
+        ]
+        
+        print(f"扩展查询:")
+        for i, query in enumerate(expanded_queries, 1):
+            print(f"  {i}. {query}")
+        
+        # 执行多查询检索
+        all_results = []
+        for query in [base_query] + expanded_queries:
+            results = self.rag_tool.execute("search",
+                                          query=query,
+                                          limit=3)
+            all_results.append((query, results))
+            print(f"  查询结果 '{query[:20]}...': {results[:80]}...")
+        
+        # 演示假设文档嵌入（HyDE）
+        print(f"\n2. 假设文档嵌入（HyDE）演示:")
+        
+        user_question = "什么是深度学习？"
+        print(f"用户问题: {user_question}")
+        
+        # 生成假设答案
+        hypothetical_answer = """深度学习是机器学习的一个子领域，它使用多层神经网络来学习数据的复杂模式。深度学习模型通过多个隐藏层来提取数据的层次化特征表示。常见的深度学习架构包括卷积神经网络（CNN）、循环神经网络（RNN）和Transformer。深度学习在图像识别、自然语言处理、语音识别等领域取得了突破性进展。"""
+        
+        print(f"假设答案: {hypothetical_answer[:100]}...")
+        
+        # 使用假设答案进行检索
+        hyde_results = self.rag_tool.execute("search",
+                                           query=hypothetical_answer,
+                                           limit=5)
+        print(f"HyDE检索结果: {hyde_results[:120]}...")
+        
+        # 对比直接查询结果
+        direct_results = self.rag_tool.execute("search",
+                                             query=user_question,
+                                             limit=5)
+        print(f"直接查询结果: {direct_results[:120]}...")
+        
+        # 演示混合检索策略
+        print(f"\n3. 混合检索策略演示:")
+        
+        complex_query = "比较监督学习和无监督学习的区别，并给出具体应用例子"
+        print(f"复杂查询: {complex_query}")
+        
+        # 分解查询
+        sub_queries = [
+            "监督学习的定义和特点",
+            "无监督学习的定义和特点", 
+            "监督学习的应用例子",
+            "无监督学习的应用例子",
+            "监督学习和无监督学习的区别"
+        ]
+        
+        print(f"查询分解:")
+        mixed_results = {}
+        for sub_query in sub_queries:
+            results = self.rag_tool.execute("search",
+                                          query=sub_query,
+                                          limit=2)
+            mixed_results[sub_query] = results
+            print(f"  子查询: {sub_query}")
+            print(f"    结果: {results[:80]}...")
+        
+        # 演示相关性重排序
+        print(f"\n4. 相关性重排序演示:")
+        
+        ranking_query = "神经网络训练过程"
+        print(f"排序查询: {ranking_query}")
+        
+        # 获取初始结果
+        initial_results = self.rag_tool.execute("search",
+                                              query=ranking_query,
+                                              limit=8)
+        print(f"初始检索结果: {initial_results[:150]}...")
+        
+        # 模拟重排序过程（基于多个因素）
+        print(f"重排序因素:")
+        print(f"  • 语义相似度权重: 0.6")
+        print(f"  • 文档新鲜度权重: 0.2") 
+        print(f"  • 文档权威性权重: 0.2")
+        
+        # 最终排序结果
+        final_results = self.rag_tool.execute("search",
+                                            query=ranking_query,
+                                            limit=5)
+        print(f"重排序后结果: {final_results[:150]}...")
+    
+    def demonstrate_intelligent_qa(self):
+        """演示智能问答生成"""
+        print("\n🤖 智能问答生成演示")
+        print("-" * 60)
+        
+        print("🔍 智能问答特点:")
+        print("• 🎯 问题理解和分类")
+        print("• 📚 上下文构建")
+        print("• 💡 答案生成和优化")
+        print("• 🔗 引用和溯源")
+        
+        # 演示不同类型问题的处理
+        print(f"\n1. 不同类型问题处理:")
+        
+        qa_examples = [
+            {
+                "question": "什么是机器学习？",
+                "type": "定义类问题",
+                "expected_approach": "提供清晰定义和基本概念"
+            },
+            {
+                "question": "如何选择合适的机器学习算法？",
+                "type": "方法类问题", 
+                "expected_approach": "提供步骤和决策框架"
+            },
+            {
+                "question": "深度学习和传统机器学习有什么区别？",
+                "type": "比较类问题",
+                "expected_approach": "对比分析优缺点"
+            },
+            {
+                "question": "为什么神经网络需要激活函数？",
+                "type": "原理类问题",
+                "expected_approach": "解释技术原理和必要性"
+            },
+            {
+                "question": "在图像分类项目中应该使用哪种算法？",
+                "type": "应用类问题",
+                "expected_approach": "结合场景给出具体建议"
+            }
+        ]
+        
+        for example in qa_examples:
+            print(f"\n问题类型: {example['type']}")
+            print(f"问题: {example['question']}")
+            print(f"处理策略: {example['expected_approach']}")
+            
+            # 执行问答
+            start_time = time.time()
+            answer = self.rag_tool.execute("ask",
+                                         question=example["question"],
+                                         limit=4)
+            qa_time = time.time() - start_time
+            
+            print(f"回答 ({qa_time:.3f}秒): {answer[:200]}...")
+        
+        # 演示上下文构建过程
+        print(f"\n2. 上下文构建过程演示:")
+        
+        context_question = "如何防止神经网络过拟合？"
+        print(f"问题: {context_question}")
+        
+        # 模拟上下文构建步骤
+        print(f"上下文构建步骤:")
+        print(f"  1. 问题分析 - 识别关键概念：过拟合、神经网络、防止方法")
+        print(f"  2. 相关文档检索 - 搜索相关技术文档")
+        print(f"  3. 上下文筛选 - 选择最相关的信息片段")
+        print(f"  4. 上下文排序 - 按相关性和重要性排序")
+        
+        # 执行上下文构建
+        context_search = self.rag_tool.execute("search",
+                                             query="神经网络过拟合防止方法",
+                                             limit=6)
+        print(f"  检索到的上下文: {context_search[:180]}...")
+        
+        # 生成最终答案
+        final_answer = self.rag_tool.execute("ask",
+                                           question=context_question,
+                                           limit=5)
+        print(f"  最终答案: {final_answer[:250]}...")
+        
+        # 演示多轮对话支持
+        print(f"\n3. 多轮对话支持:")
+        
+        conversation = [
+            "什么是卷积神经网络？",
+            "它主要用于什么任务？",
+            "相比传统方法有什么优势？",
+            "在实际项目中如何使用？"
+        ]
+        
+        print(f"模拟对话场景:")
+        for i, question in enumerate(conversation, 1):
+            print(f"\n  轮次 {i}: {question}")
+            
+            # 在多轮对话中，后续问题可能需要前面的上下文
+            if i > 1:
+                context_query = f"卷积神经网络 {question}"
+            else:
+                context_query = question
+            
+            answer = self.rag_tool.execute("ask",
+                                         question=context_query,
+                                         limit=3)
+            print(f"  回答: {answer[:150]}...")
+        
+        # 演示答案质量评估
+        print(f"\n4. 答案质量评估:")
+        
+        quality_question = "解释反向传播算法的工作原理"
+        print(f"评估问题: {quality_question}")
+        
+        answer = self.rag_tool.execute("ask",
+                                     question=quality_question,
+                                     limit=5)
+        
+        print(f"生成答案: {answer[:300]}...")
+        
+        # 模拟质量评估指标
+        quality_metrics = {
+            "相关性": "高 - 答案直接回应了问题",
+            "准确性": "高 - 技术描述准确",
+            "完整性": "中 - 涵盖了主要概念",
+            "可读性": "高 - 结构清晰易懂",
+            "引用质量": "中 - 基于可靠来源"
+        }
+        
+        print(f"质量评估:")
+        for metric, score in quality_metrics.items():
+            print(f"  {metric}: {score}")
+    
+    def demonstrate_performance_optimization(self):
+        """演示性能优化"""
+        print("\n⚡ 性能优化演示")
+        print("-" * 60)
+        
+        print("🔍 性能优化特点:")
+        print("• 🚀 检索速度优化")
+        print("• 💾 内存使用优化")
+        print("• 🎯 结果质量提升")
+        print("• 📊 系统监控")
+        
+        # 演示检索性能测试
+        print(f"\n1. 检索性能测试:")
+        
+        performance_queries = [
+            "机器学习基础概念",
+            "深度学习应用场景", 
+            "神经网络训练技巧",
+            "数据预处理方法",
+            "模型评估指标"
+        ]
+        
+        total_time = 0
+        total_queries = len(performance_queries)
+        
+        print(f"执行 {total_queries} 个查询的性能测试:")
+        
+        for i, query in enumerate(performance_queries, 1):
+            start_time = time.time()
+            results = self.rag_tool.execute("search",
+                                          query=query,
+                                          limit=5)
+            query_time = time.time() - start_time
+            total_time += query_time
+            
+            print(f"  查询 {i}: '{query}' - {query_time:.4f}秒")
+        
+        avg_time = total_time / total_queries
+        print(f"\n性能统计:")
+        print(f"  总耗时: {total_time:.4f}秒")
+        print(f"  平均查询时间: {avg_time:.4f}秒")
+        print(f"  查询吞吐量: {1/avg_time:.2f} 查询/秒")
+        
+        # 演示批量处理优化
+        print(f"\n2. 批量处理优化:")
+        
+        batch_queries = [
+            "什么是监督学习？",
+            "什么是无监督学习？",
+            "什么是强化学习？",
+            "什么是深度学习？",
+            "什么是神经网络？"
+        ]
+        
+        # 单个处理
+        start_time = time.time()
+        individual_results = []
+        for query in batch_queries:
+            result = self.rag_tool.execute("search", query=query, limit=2)
+            individual_results.append(result)
+        individual_time = time.time() - start_time
+        
+        print(f"  单个处理耗时: {individual_time:.4f}秒")
+        
+        # 模拟批量处理（实际实现中可能有优化）
+        start_time = time.time()
+        batch_results = []
+        for query in batch_queries:
+            result = self.rag_tool.execute("search", query=query, limit=2)
+            batch_results.append(result)
+        batch_time = time.time() - start_time
+        
+        print(f"  批量处理耗时: {batch_time:.4f}秒")
+        print(f"  性能提升: {((individual_time - batch_time) / individual_time * 100):.1f}%")
+        
+        # 演示缓存机制
+        print(f"\n3. 缓存机制演示:")
+        
+        cache_query = "机器学习算法分类"
+        
+        # 第一次查询（无缓存）
+        start_time = time.time()
+        first_result = self.rag_tool.execute("search",
+                                           query=cache_query,
+                                           limit=3)
+        first_time = time.time() - start_time
+        print(f"  首次查询: {first_time:.4f}秒")
+        
+        # 第二次查询（可能有缓存）
+        start_time = time.time()
+        second_result = self.rag_tool.execute("search",
+                                            query=cache_query,
+                                            limit=3)
+        second_time = time.time() - start_time
+        print(f"  重复查询: {second_time:.4f}秒")
+        
+        if second_time < first_time:
+            speedup = (first_time - second_time) / first_time * 100
+            print(f"  缓存加速: {speedup:.1f}%")
+        
+        # 演示系统监控
+        print(f"\n4. 系统监控:")
+        
+        # 获取系统统计
+        system_stats = self.rag_tool.execute("stats")
+        print(f"  系统统计: {system_stats}")
+        
+        # 模拟资源使用监控
+        resource_usage = {
+            "文档数量": "15个",
+            "索引大小": "约2.5MB",
+            "内存使用": "约128MB",
+            "平均响应时间": f"{avg_time:.4f}秒",
+            "成功率": "100%"
+        }
+        
+        print(f"  资源使用情况:")
+        for metric, value in resource_usage.items():
+            print(f"    {metric}: {value}")
+
+def main():
+    """主函数"""
+    print("📚 RAG完整处理管道演示")
+    print("展示从文档处理到智能问答的完整RAG流程")
+    print("=" * 80)
+    
+    try:
+        demo = RAGPipelineComplete()
+        
+        # 1. 文档摄取演示
+        demo.demonstrate_document_ingestion()
+        
+        # 2. 分块策略演示
+        demo.demonstrate_chunking_strategies()
+        
+        # 3. 高级检索演示
+        demo.demonstrate_advanced_retrieval()
+        
+        # 4. 智能问答演示
+        demo.demonstrate_intelligent_qa()
+        
+        # 5. 性能优化演示
+        demo.demonstrate_performance_optimization()
+        
+        print("\n" + "=" * 80)
+        print("🎉 RAG完整处理管道演示完成！")
+        print("=" * 80)
+        
+        print("\n✨ RAG管道核心特性:")
+        print("1. 📥 多格式文档摄取 - 支持PDF、DOCX、TXT、MD等")
+        print("2. ✂️ 智能文档分块 - 基于语义的分块策略")
+        print("3. 🔍 高级检索策略 - MQE、HyDE、混合检索")
+        print("4. 🤖 智能问答生成 - 上下文构建和答案优化")
+        print("5. ⚡ 性能优化 - 缓存、批量处理、监控")
+        
+        print("\n🎯 技术优势:")
+        print("• 端到端处理流程")
+        print("• 多策略检索优化")
+        print("• 智能上下文构建")
+        print("• 高质量答案生成")
+        print("• 全面性能监控")
+        
+        print("\n💡 应用场景:")
+        print("• 企业知识库问答")
+        print("• 技术文档助手")
+        print("• 学习辅导系统")
+        print("• 智能客服系统")
+        
+    except Exception as e:
+        print(f"\n❌ 演示过程中发生错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

code/chapter8/11_Q&A_Assistant.py

@@ -0,0 +1,447 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+智能文档问答助手 - 基于HelloAgents的智能文档问答系统
+
+这是一个完整的PDF学习助手应用，支持：
+- 加载PDF文档并构建知识库
+- 智能问答（基于RAG）
+- 学习历程记录（基于Memory）
+- 学习回顾和报告生成
+"""
+
+import os
+import time
+import json
+from datetime import datetime
+from typing import Dict, List, Optional, Any, Tuple
+from hello_agents.tools import MemoryTool, RAGTool
+import gradio as gr
+
+
+class PDFLearningAssistant:
+    """智能文档问答助手"""
+
+    def __init__(self, user_id: str = "default_user"):
+        """初始化学习助手
+
+        Args:
+            user_id: 用户ID，用于隔离不同用户的数据
+        """
+        self.user_id = user_id
+        self.session_id = f"session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+        # 初始化工具
+        self.memory_tool = MemoryTool(user_id=user_id)
+        self.rag_tool = RAGTool(rag_namespace=f"pdf_{user_id}")
+
+        # 学习统计
+        self.stats = {
+            "session_start": datetime.now(),
+            "documents_loaded": 0,
+            "questions_asked": 0,
+            "concepts_learned": 0
+        }
+
+        # 当前加载的文档
+        self.current_document = None
+
+    def load_document(self, pdf_path: str) -> Dict[str, Any]:
+        """加载PDF文档到知识库
+
+        Args:
+            pdf_path: PDF文件路径
+
+        Returns:
+            Dict: 包含success和message的结果
+        """
+        if not os.path.exists(pdf_path):
+            return {"success": False, "message": f"文件不存在: {pdf_path}"}
+
+        start_time = time.time()
+
+        try:
+            # 使用RAG工具处理PDF
+            result = self.rag_tool.execute(
+                "add_document",
+                file_path=pdf_path,
+                chunk_size=1000,
+                chunk_overlap=200
+            )
+
+            process_time = time.time() - start_time
+
+            # RAG工具返回的是字符串消息
+            self.current_document = os.path.basename(pdf_path)
+            self.stats["documents_loaded"] += 1
+
+            # 记录到学习记忆
+            self.memory_tool.execute(
+                "add",
+                content=f"加载了文档《{self.current_document}》",
+                memory_type="episodic",
+                importance=0.9,
+                event_type="document_loaded",
+                session_id=self.session_id
+            )
+
+            return {
+                "success": True,
+                "message": f"加载成功！(耗时: {process_time:.1f}秒)",
+                "document": self.current_document
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"加载失败: {str(e)}"
+            }
+
+    def ask(self, question: str, use_advanced_search: bool = True) -> str:
+        """向文档提问
+
+        Args:
+            question: 用户问题
+            use_advanced_search: 是否使用高级检索（MQE + HyDE）
+
+        Returns:
+            str: 答案
+        """
+        if not self.current_document:
+            return "⚠️ 请先加载文档！使用 load_document() 方法加载PDF文档。"
+
+        # 记录问题到工作记忆
+        self.memory_tool.execute(
+            "add",
+            content=f"提问: {question}",
+            memory_type="working",
+            importance=0.6,
+            session_id=self.session_id
+        )
+
+        # 使用RAG检索答案
+        answer = self.rag_tool.execute(
+            "ask",
+            question=question,
+            limit=5,
+            enable_advanced_search=use_advanced_search,
+            enable_mqe=use_advanced_search,
+            enable_hyde=use_advanced_search
+        )
+
+        # 记录到情景记忆
+        self.memory_tool.execute(
+            "add",
+            content=f"关于'{question}'的学习",
+            memory_type="episodic",
+            importance=0.7,
+            event_type="qa_interaction",
+            session_id=self.session_id
+        )
+
+        self.stats["questions_asked"] += 1
+
+        return answer
+
+    def add_note(self, content: str, concept: Optional[str] = None):
+        """添加学习笔记
+
+        Args:
+            content: 笔记内容
+            concept: 相关概念（可选）
+        """
+        self.memory_tool.execute(
+            "add",
+            content=content,
+            memory_type="semantic",
+            importance=0.8,
+            concept=concept or "general",
+            session_id=self.session_id
+        )
+
+        self.stats["concepts_learned"] += 1
+
+    def recall(self, query: str, limit: int = 5) -> str:
+        """回顾学习历程
+
+        Args:
+            query: 查询关键词
+            limit: 返回结果数量
+
+        Returns:
+            str: 相关记忆
+        """
+        result = self.memory_tool.execute(
+            "search",
+            query=query,
+            limit=limit
+        )
+        return result
+
+    def get_stats(self) -> Dict[str, Any]:
+        """获取学习统计
+
+        Returns:
+            Dict: 统计信息
+        """
+        duration = (datetime.now() - self.stats["session_start"]).total_seconds()
+
+        return {
+            "会话时长": f"{duration:.0f}秒",
+            "加载文档": self.stats["documents_loaded"],
+            "提问次数": self.stats["questions_asked"],
+            "学习笔记": self.stats["concepts_learned"],
+            "当前文档": self.current_document or "未加载"
+        }
+
+    def generate_report(self, save_to_file: bool = True) -> Dict[str, Any]:
+        """生成学习报告
+
+        Args:
+            save_to_file: 是否保存到文件
+
+        Returns:
+            Dict: 学习报告
+        """
+        # 获取记忆摘要
+        memory_summary = self.memory_tool.execute("summary", limit=10)
+
+        # 获取RAG统计
+        rag_stats = self.rag_tool.execute("stats")
+
+        # 生成报告
+        duration = (datetime.now() - self.stats["session_start"]).total_seconds()
+        report = {
+            "session_info": {
+                "session_id": self.session_id,
+                "user_id": self.user_id,
+                "start_time": self.stats["session_start"].isoformat(),
+                "duration_seconds": duration
+            },
+            "learning_metrics": {
+                "documents_loaded": self.stats["documents_loaded"],
+                "questions_asked": self.stats["questions_asked"],
+                "concepts_learned": self.stats["concepts_learned"]
+            },
+            "memory_summary": memory_summary,
+            "rag_status": rag_stats
+        }
+
+        # 保存到文件
+        if save_to_file:
+            report_file = f"learning_report_{self.session_id}.json"
+            try:
+                with open(report_file, 'w', encoding='utf-8') as f:
+                    json.dump(report, f, ensure_ascii=False, indent=2, default=str)
+                report["report_file"] = report_file
+            except Exception as e:
+                report["save_error"] = str(e)
+
+        return report
+
+
+
+
+
+def create_gradio_ui():
+    """创建Gradio Web UI"""
+    # 全局助手实例
+    assistant_state = {"assistant": None}
+
+    def init_assistant(user_id: str) -> str:
+        """初始化助手"""
+        if not user_id:
+            user_id = "web_user"
+        assistant_state["assistant"] = PDFLearningAssistant(user_id=user_id)
+        return f"✅ 助手已初始化 (用户: {user_id})"
+
+    def load_pdf(pdf_file) -> str:
+        """加载PDF文件"""
+        if assistant_state["assistant"] is None:
+            return "❌ 请先初始化助手"
+
+        if pdf_file is None:
+            return "❌ 请上传PDF文件"
+
+        # Gradio上传的文件是临时文件对象
+        pdf_path = pdf_file.name
+        result = assistant_state["assistant"].load_document(pdf_path)
+
+        if result["success"]:
+            return f"✅ {result['message']}\n📄 文档: {result['document']}"
+        else:
+            return f"❌ {result['message']}"
+
+    def chat(message: str, history: List) -> Tuple[str, List]:
+        """聊天功能"""
+        if assistant_state["assistant"] is None:
+            return "", history + [[message, "❌ 请先初始化助手并加载文档"]]
+
+        if not message.strip():
+            return "", history
+
+        # 判断是技术问题还是回顾问题
+        if any(keyword in message for keyword in ["之前", "学过", "回顾", "历史", "记得"]):
+            # 回顾学习历程
+            response = assistant_state["assistant"].recall(message)
+            response = f"🧠 **学习回顾**\n\n{response}"
+        else:
+            # 技术问答
+            response = assistant_state["assistant"].ask(message)
+            response = f"💡 **回答**\n\n{response}"
+
+        history.append([message, response])
+        return "", history
+
+    def add_note_ui(note_content: str, concept: str) -> str:
+        """添加笔记"""
+        if assistant_state["assistant"] is None:
+            return "❌ 请先初始化助手"
+
+        if not note_content.strip():
+            return "❌ 笔记内容不能为空"
+
+        assistant_state["assistant"].add_note(note_content, concept or None)
+        return f"✅ 笔记已保存: {note_content[:50]}..."
+
+    def get_stats_ui() -> str:
+        """获取统计信息"""
+        if assistant_state["assistant"] is None:
+            return "❌ 请先初始化助手"
+
+        stats = assistant_state["assistant"].get_stats()
+        result = "📊 **学习统计**\n\n"
+        for key, value in stats.items():
+            result += f"- **{key}**: {value}\n"
+        return result
+
+    def generate_report_ui() -> str:
+        """生成报告"""
+        if assistant_state["assistant"] is None:
+            return "❌ 请先初始化助手"
+
+        report = assistant_state["assistant"].generate_report(save_to_file=True)
+
+        result = f"✅ 学习报告已生成\n\n"
+        result += f"**会话信息**\n"
+        result += f"- 会话时长: {report['session_info']['duration_seconds']:.0f}秒\n"
+        result += f"- 加载文档: {report['learning_metrics']['documents_loaded']}\n"
+        result += f"- 提问次数: {report['learning_metrics']['questions_asked']}\n"
+        result += f"- 学习笔记: {report['learning_metrics']['concepts_learned']}\n"
+
+        if "report_file" in report:
+            result += f"\n💾 报告已保存至: {report['report_file']}"
+
+        return result
+
+    # 创建Gradio界面
+    with gr.Blocks(title="智能文档问答助手", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("""
+        # 📚 智能文档问答助手
+
+        基于HelloAgents的智能文档问答系统，支持：
+        - 📄 加载PDF文档并构建知识库
+        - 💬 智能问答（基于RAG）
+        - 📝 学习笔记记录
+        - 🧠 学习历程回顾
+        - 📊 学习报告生成
+        """)
+
+        with gr.Tab("🏠 开始使用"):
+            with gr.Row():
+                user_id_input = gr.Textbox(
+                    label="用户ID",
+                    placeholder="输入你的用户ID（可选，默认为web_user）",
+                    value="web_user"
+                )
+                init_btn = gr.Button("初始化助手", variant="primary")
+
+            init_output = gr.Textbox(label="初始化状态", interactive=False)
+            init_btn.click(init_assistant, inputs=[user_id_input], outputs=[init_output])
+
+            gr.Markdown("### 📄 加载PDF文档")
+            pdf_upload = gr.File(
+                label="上传PDF文件",
+                file_types=[".pdf"],
+                type="filepath"
+            )
+            load_btn = gr.Button("加载文档", variant="primary")
+            load_output = gr.Textbox(label="加载状态", interactive=False)
+            load_btn.click(load_pdf, inputs=[pdf_upload], outputs=[load_output])
+
+        with gr.Tab("💬 智能问答"):
+            gr.Markdown("### 向文档提问或回顾学习历程")
+            chatbot = gr.Chatbot(
+                label="对话历史",
+                height=400,
+                bubble_full_width=False
+            )
+            with gr.Row():
+                msg_input = gr.Textbox(
+                    label="输入问题",
+                    placeholder="例如：什么是Transformer？ 或 我之前学过什么？",
+                    scale=4
+                )
+                send_btn = gr.Button("发送", variant="primary", scale=1)
+
+            gr.Examples(
+                examples=[
+                    "什么是大语言模型？",
+                    "Transformer架构有哪些核心组件？",
+                    "如何训练大语言模型？",
+                    "我之前学过什么内容？",
+                    "回顾一下关于注意力机制的学习"
+                ],
+                inputs=msg_input
+            )
+
+            msg_input.submit(chat, inputs=[msg_input, chatbot], outputs=[msg_input, chatbot])
+            send_btn.click(chat, inputs=[msg_input, chatbot], outputs=[msg_input, chatbot])
+
+        with gr.Tab("📝 学习笔记"):
+            gr.Markdown("### 记录学习心得和重要概念")
+            note_content = gr.Textbox(
+                label="笔记内容",
+                placeholder="输入你的学习笔记...",
+                lines=3
+            )
+            concept_input = gr.Textbox(
+                label="相关概念（可选）",
+                placeholder="例如：transformer, attention"
+            )
+            note_btn = gr.Button("保存笔记", variant="primary")
+            note_output = gr.Textbox(label="保存状态", interactive=False)
+            note_btn.click(add_note_ui, inputs=[note_content, concept_input], outputs=[note_output])
+
+        with gr.Tab("📊 学习统计"):
+            gr.Markdown("### 查看学习进度和统计信息")
+            stats_btn = gr.Button("刷新统计", variant="primary")
+            stats_output = gr.Markdown()
+            stats_btn.click(get_stats_ui, outputs=[stats_output])
+
+            gr.Markdown("### 生成学习报告")
+            report_btn = gr.Button("生成报告", variant="primary")
+            report_output = gr.Textbox(label="报告状态", interactive=False)
+            report_btn.click(generate_report_ui, outputs=[report_output])
+
+    return demo
+
+
+def main():
+    """主函数 - 启动Gradio Web UI"""
+    print("\n" + "="*60)
+    print("� 智能文档问答助手")
+    print("="*60)
+    print("正在启动Web界面...\n")
+
+    demo = create_gradio_ui()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )
+
+
+if __name__ == "__main__":
+    main()
+

docs/README.md

@@ -52,8 +52,8 @@
 | [第六章 框架开发实践](./chapter6/第六章%20框架开发实践.md) | AutoGen、AgentScope、LangGraph 等主流框架应用 | ✅ |
 | [第七章 构建你的Agent框架](./chapter7/第七章%20构建你的Agent框架.md) | 从0开始构建智能体框架 | ✅ |
 | <strong>第三部分：高级知识扩展</strong> |  |  |
-| [第八章 记忆与检索](./chapter9/第八章%20记忆与检索.md) | 记忆系统, RAG, 图\向量数据库 | 🚧 |
-| [第九章 上下文工程](./chapter8/第九章%20上下文工程.md) | 持续交互的"情境理解" | 🚧 |
+| [第八章 记忆与检索](./chapter8/第八章%20记忆与检索.md) | 记忆系统, RAG, 存储 | 🚧 |
+| [第九章 上下文工程](./chapter9/第九章%20上下文工程.md) | 持续交互的"情境理解" | 🚧 |
 | [第十章 智能体通信协议](./chapter10/第十章%20智能体通信协议.md) | MCP, A2A, ANP 等协议解析 | 🚧 |
 | [第十一章 多智能体系统](./chapter11/第十一章%20多智能体系统.md) | 协作、通信、博弈论与 AI Society | 🚧 |
 | [第十二章 智能体性能评估](./chapter12/第十二章%20智能体性能评估.md) | 核心指标、基准测试与评估框架 | 🚧 |

docs/chapter8/第八章 记忆与检索.md

@@ -1,3 +1,2039 @@
-# 第八章 记忆与检索
+# 第八章 记忆与检索增强生成
 
-本章内容待补充...
+在前面的章节中，我们构建了HelloAgents框架的基础架构，实现了多种智能体范式和工具系统。不过，我们的框架还缺少一个关键能力：**记忆**。如果智能体无法记住之前的交互内容，也无法从历史经验中学习，那么在连续对话或复杂任务中，其表现将受到极大限制。
+
+本章将在第七章构建的框架基础上，为HelloAgents增加两个核心能力：**记忆系统（Memory System）**和**检索增强生成（Retrieval-Augmented Generation, RAG）**。我们将采用"框架扩展 + 知识科普"的方式，在构建过程中深入理解Memory和RAG的理论基础，最终实现一个具有完整记忆和知识检索能力的智能体系统。
+
+
+## 8.1 从认知科学到智能体记忆
+
+### 8.1.1 人类记忆系统的启发
+
+在构建智能体的记忆系统之前，让我们先从认知科学的角度理解人类是如何处理和存储信息的。人类记忆是一个多层级的认知系统，它不仅能存储信息，还能根据重要性、时间和上下文对信息进行分类和整理。认知心理学为理解记忆的结构和过程提供了经典的理论框架<sup>[1]</sup>，如图8.1所示。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-1.png" alt="人类记忆系统结构图" width="85%"/>
+  <p>图 8.1 人类记忆系统的层次结构</p>
+</div>
+
+根据认知心理学的研究，人类记忆可以分为以下几个层次：
+
+1. **感觉记忆（Sensory Memory）**：持续时间极短（0.5-3秒），容量巨大，负责暂时保存感官接收到的所有信息
+2. **工作记忆（Working Memory）**：持续时间短（15-30秒），容量有限（7±2个项目），负责当前任务的信息处理
+3. **长期记忆（Long-term Memory）**：持续时间长（可达终生），容量几乎无限，进一步分为：
+   - **程序性记忆**：技能和习惯（如骑自行车）
+   - **陈述性记忆**：可以用语言表达的知识，又分为：
+     - **语义记忆**：一般知识和概念（如"巴黎是法国首都"）
+     - **情景记忆**：个人经历和事件（如"昨天的会议内容"）
+
+### 8.1.2 为何智能体需要记忆与RAG
+
+借鉴人类记忆系统的设计，我们可以理解为什么智能体也需要类似的记忆能力。人类智能的一个重要特征就是能够记住过去的经历，从中学习，并将这些经验应用到新的情况中。同样，一个真正智能的智能体也需要具备记忆能力。对于基于LLM的智能体而言，通常面临两个根本性局限：**对话状态的遗忘**和**内置知识的局限**。
+
+（1）局限一：无状态导致的对话遗忘
+
+当前的大语言模型虽然强大，但设计上是**无状态的**。这意味着，每一次用户请求（或API调用）都是一次独立的、无关联的计算。模型本身不会自动“记住”上一次对话的内容。这带来了几个问题：
+
+1. **上下文丢失**：在长对话中，早期的重要信息可能会因为上下文窗口限制而丢失
+2. **个性化缺失**：Agent无法记住用户的偏好、习惯或特定需求
+3. **学习能力受限**：无法从过往的成功或失败经验中学习改进
+4. **一致性问题**：在多轮对话中可能出现前后矛盾的回答
+
+让我们通过一个具体例子来理解这个问题：
+
+```python
+# 第七章的Agent使用方式
+from hello_agents import SimpleAgent, HelloAgentsLLM
+
+agent = SimpleAgent(name="学习助手", llm=HelloAgentsLLM())
+
+# 第一次对话
+response1 = agent.run("我叫张三，正在学习Python，目前掌握了基础语法")
+print(response1)  # "很好！Python基础语法是编程的重要基础..."
+ 
+# 第二次对话（新的会话）
+response2 = agent.run("你还记得我的学习进度吗？")
+print(response2)  # "抱歉，我不知道您的学习进度..."
+```
+
+要解决这个问题，我们的框架需要引入记忆系统。
+
+（2）局限二：模型内置知识的局限性
+
+除了遗忘对话历史，LLM 的另一个核心局限在于其知识是**静态的、有限的**。这些知识完全来自于它的训练数据，并因此带来一系列问题：
+
+1. **知识时效性**：大模型的训练数据有时间截止点，无法获取最新信息
+2. **专业领域知识**：通用模型在特定领域的深度知识可能不足
+3. **事实准确性**：通过检索验证，减少模型的幻觉问题
+4. **可解释性**：提供信息来源，增强回答的可信度
+
+为了克服这一局限，RAG技术应运而生。它的核心思想是在模型生成回答之前，先从一个外部知识库（如文档、数据库、API）中检索出最相关的信息，并将这些信息作为上下文一同提供给模型。
+
+### 8.1.3 记忆与RAG系统架构设计
+
+基于第七章建立的框架基础和认知科学的启发，我们设计了一个分层的记忆与RAG系统架构，如图8.2所示。这个架构不仅借鉴了人类记忆系统的层次结构，还充分考虑了工程实现的可扩展性。在实现上，我们将记忆和RAG设计为两个独立的工具：`memory_tool`负责存储和维护对话过程中的交互信息，`rag_tool`则负责从用户提供的知识库中检索相关信息作为上下文，并可将重要的检索结果自动存储到记忆系统中。
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-2.png" alt="HelloAgents记忆与RAG系统架构图" width="95%"/>
+  <p>图 8.2 HelloAgents记忆与RAG系统整体架构</p>
+</div>
+
+记忆系统采用了四层架构设计：
+
+```
+HelloAgents记忆系统
+├── 基础设施层 (Infrastructure Layer)
+│   ├── MemoryManager - 记忆管理器（统一调度和协调）
+│   ├── MemoryItem - 记忆数据结构（标准化记忆项）
+│   ├── MemoryConfig - 配置管理（系统参数设置）
+│   └── BaseMemory - 记忆基类（通用接口定义）
+├── 记忆类型层 (Memory Types Layer)
+│   ├── WorkingMemory - 工作记忆（临时信息，TTL管理）
+│   ├── EpisodicMemory - 情景记忆（具体事件，时间序列）
+│   ├── SemanticMemory - 语义记忆（抽象知识，图谱关系）
+│   └── PerceptualMemory - 感知记忆（多模态数据）
+├── 存储后端层 (Storage Backend Layer)
+│   ├── QdrantVectorStore - 向量存储（高性能语义检索）
+│   ├── Neo4jGraphStore - 图存储（知识图谱管理）
+│   └── SQLiteDocumentStore - 文档存储（结构化持久化）
+└── 嵌入服务层 (Embedding Service Layer)
+    ├── DashScopeEmbedding - 通义千问嵌入（云端API）
+    ├── LocalTransformerEmbedding - 本地嵌入（离线部署）
+    └── TFIDFEmbedding - TFIDF嵌入（轻量级兜底）
+```
+
+RAG系统专注于外部知识的获取和利用：
+
+```
+HelloAgents RAG系统
+├── 文档处理层 (Document Processing Layer)
+│   ├── DocumentProcessor - 文档处理器（多格式解析）
+│   ├── Document - 文档对象（元数据管理）
+│   └── Pipeline - RAG管道（端到端处理）
+├── 嵌入表示层 (Embedding Layer)
+│   └── 统一嵌入接口 - 复用记忆系统的嵌入服务
+├── 向量存储层 (Vector Storage Layer)
+│   └── QdrantVectorStore - 向量数据库（命名空间隔离）
+└── 智能问答层 (Intelligent Q&A Layer)
+    ├── 多策略检索 - 向量检索 + MQE + HyDE
+    ├── 上下文构建 - 智能片段合并与截断
+    └── LLM增强生成 - 基于上下文的准确问答
+```
+
+### 8.1.4 本章学习目标与快速体验
+
+让我们先看看第八章的核心学习内容：
+
+```
+hello-agents/
+├── hello_agents/
+│   ├── memory/                   # 记忆系统模块
+│   │   ├── base.py               # 基础数据结构（MemoryItem, MemoryConfig, BaseMemory）
+│   │   ├── manager.py            # 记忆管理器（统一协调调度）
+│   │   ├── embedding.py          # 统一嵌入服务（DashScope/Local/TFIDF）
+│   │   ├── types/                # 记忆类型实现
+│   │   │   ├── working.py        # 工作记忆（TTL管理，纯内存）
+│   │   │   ├── episodic.py       # 情景记忆（事件序列，SQLite+Qdrant）
+│   │   │   ├── semantic.py       # 语义记忆（知识图谱，Qdrant+Neo4j）
+│   │   │   └── perceptual.py     # 感知记忆（多模态，SQLite+Qdrant）
+│   │   ├── storage/              # 存储后端实现
+│   │   │   ├── qdrant_store.py   # Qdrant向量存储（高性能向量检索）
+│   │   │   ├── neo4j_store.py    # Neo4j图存储（知识图谱管理）
+│   │   │   └── document_store.py # SQLite文档存储（结构化持久化）
+│   │   └── rag/                  # RAG系统
+│   │       ├── pipeline.py       # RAG管道（端到端处理）
+│   │       └── document.py       # 文档处理器（多格式解析）
+│   └── tools/builtin/            # 扩展内置工具
+│       ├── memory_tool.py        # 记忆工具（Agent记忆能力）
+│       └── rag_tool.py           # RAG工具（智能问答能力）
+└──
+```
+
+**快速开始：安装HelloAgents框架**
+
+为了让读者能够快速体验本章的完整功能，我们提供了可直接安装的Python包。你可以通过以下命令安装本章对应的版本：
+
+```bash
+pip install hello-agents[all]==0.2.0
+```
+
+除了这一个指令外，还需要在`.env`配置图数据库，向量数据库，LLM以及Embedding方案的API。在教程中向量数据库采用Qdrant，图数据库采用Neo4J，Embedding首选百炼平台，若没有API可切换为本地部署模型方案。
+
+```bash
+# ================================
+# Qdrant 向量数据库配置 - 获取API密钥：https://cloud.qdrant.io/
+# ================================
+# 使用Qdrant云服务 (推荐)
+QDRANT_URL=https://your-cluster.qdrant.tech:6333
+QDRANT_API_KEY=your_qdrant_api_key_here
+
+# 或使用本地Qdrant (需要Docker)
+# QDRANT_URL=http://localhost:6333
+# QDRANT_API_KEY=
+
+# Qdrant集合配置
+QDRANT_COLLECTION=hello_agents_vectors
+QDRANT_VECTOR_SIZE=384
+QDRANT_DISTANCE=cosine
+QDRANT_TIMEOUT=30
+
+# ================================
+# Neo4j 图数据库配置 - 获取API密钥：https://neo4j.com/cloud/aura/
+# ================================
+# 使用Neo4j Aura云服务 (推荐)
+NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=your_neo4j_password_here
+
+# 或使用本地Neo4j (需要Docker)
+# NEO4J_URI=bolt://localhost:7687
+# NEO4J_USERNAME=neo4j
+# NEO4J_PASSWORD=hello-agents-password
+
+# Neo4j连接配置
+NEO4J_DATABASE=neo4j
+NEO4J_MAX_CONNECTION_LIFETIME=3600
+NEO4J_MAX_CONNECTION_POOL_SIZE=50
+NEO4J_CONNECTION_TIMEOUT=60
+
+# ==========================
+# 嵌入（Embedding）配置示例 - 可从阿里云控制台获取：https://dashscope.aliyun.com/
+# ==========================
+# - 若为空，dashscope 默认 text-embedding-v3；local 默认 sentence-transformers/all-MiniLM-L6-v2
+EMBED_MODEL_TYPE=dashscope
+EMBED_MODEL_NAME=
+EMBED_API_KEY=
+EMBED_BASE_URL=
+```
+
+本章的学习可以采用两种方式：
+
+1. **体验式学习**：直接使用`pip`安装框架，运行示例代码，快速体验各种功能
+2. **深度学习**：跟随本章内容，从零开始实现每个组件，深入理解框架的设计思想和实现细节
+
+我们建议采用"先体验，后实现"的学习路径。在本章中，我们提供了完整的测试文件，你可以重写核心函数并运行测试，以检验你的实现是否正确。
+
+遵循第七章确立的设计原则，我们将记忆和RAG能力封装为标准工具，而不是创建新的Agent类。在开始之前，让我们用30秒体验使用Hello-agents构建具有记忆和RAG能力的智能体！
+
+```python
+# 配置好同级文件夹下.env中的大模型API
+from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry
+from hello_agents.tools import MemoryTool, RAGTool
+
+# 创建LLM实例
+llm = HelloAgentsLLM()
+
+# 创建Agent
+agent = SimpleAgent(
+    name="智能助手",
+    llm=llm,
+    system_prompt="你是一个有记忆和知识检索能力的AI助手"
+)
+
+# 创建工具注册表
+tool_registry = ToolRegistry()
+
+# 添加记忆工具
+memory_tool = MemoryTool(user_id="user123")
+tool_registry.register_tool(memory_tool)
+
+# 添加RAG工具
+rag_tool = RAGTool(knowledge_base_path="./knowledge_base")
+tool_registry.register_tool(rag_tool)
+
+# 为Agent配置工具
+agent.tool_registry = tool_registry
+
+# 开始对话
+response = agent.run("你好！请记住我叫张三，我是一名Python开发者")
+print(response)
+```
+
+如果一切配置完毕，可以看到以下内容。
+
+```bash
+[OK] SQLite 数据库表和索引创建完成
+[OK] SQLite 文档存储初始化完成: ./memory_data\memory.db
+INFO:hello_agents.memory.storage.qdrant_store:✅ 成功连接到Qdrant云服务: https://0c517275-2ad0-4442-8309-11c36dc7e811.us-east-1-1.aws.cloud.qdrant.io:6333
+INFO:hello_agents.memory.storage.qdrant_store:✅ 使用现有Qdrant集合: hello_agents_vectors
+INFO:hello_agents.memory.types.semantic:✅ 嵌入模型就绪，维度: 1024
+INFO:hello_agents.memory.types.semantic:✅ Qdrant向量数据库初始化完成
+INFO:hello_agents.memory.storage.neo4j_store:✅ 成功连接到Neo4j云服务: neo4j+s://851b3a28.databases.neo4j.io      NFO:hello_agents.memory.types.semantic:✅ Neo4j图数据库初始化完成
+INFO:hello_agents.memory.storage.neo4j_store:✅ Neo4j索引创建完成
+INFO:hello_agents.memory.types.semantic:✅ Neo4j图数据库初始化完成
+INFO:hello_agents.memory.types.semantic:🏥 数据库健康状态: Qdrant=✅, Neo4j=✅
+INFO:hello_agents.memory.types.semantic:✅ 加载中文spaCy模型: zh_core_web_sm
+INFO:hello_agents.memory.types.semantic:✅ 加载英文spaCy模型: en_core_web_sm
+INFO:hello_agents.memory.types.semantic:📚 可用语言模型: 中文, 英文
+INFO:hello_agents.memory.types.semantic:增强语义记忆初始化完成（使用Qdrant+Neo4j专业数据库）
+INFO:hello_agents.memory.manager:MemoryManager初始化完成，启用记忆类型: ['working', 'episodic', 'semantic']      
+✅ 工具 'memory' 已注册。
+INFO:hello_agents.memory.storage.qdrant_store:✅ 成功连接到Qdrant云服务: https://0c517275-2ad0-4442-8309-11c36dc7eNFO:hello_agents.memory.storage.qdrant_store:✅ 使用现有Qdrant集合: rag_knowledge_base
+811.us-east-1-1.aws.cloud.qdrant.io:6333
+INFO:hello_agents.memory.storage.qdrant_store:✅ 使用现有Qdrant集合: rag_knowledge_base
+✅ RAG工具初始化成功: namespace=default, collection=rag_knowledge_base
+✅ 工具 'rag' 已注册。
+你好，张三！很高兴认识你。作为一名Python开发者，你一定对编程很有热情。如果你有任何技术问题或者需要讨论Python相关 
+的话题，随时可以找我。我会尽力帮助你。有什么我现在就能帮到你的吗？
+```
+
+## 8.2 记忆系统：让智能体拥有记忆
+
+### 8.2.1 记忆系统的工作流程
+
+在进入代码实现阶段前，我们需要先定义记忆系统的工作流程。该流程参考了认知科学中的记忆模型，并将每个认知阶段映射为具体的技术组件和操作。理解这一映射关系，有助于我们后续的代码实现。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-3.png" alt="记忆形成过程" width="90%"/>
+  <p>图 8.3 记忆形成的认知过程</p>
+</div>
+
+如图8.3所示，根据认知科学的研究，人类记忆的形成经历以下几个阶段：
+
+
+1. **编码（Encoding）**：将感知到的信息转换为可存储的形式
+2. **存储（Storage）**：将编码后的信息保存在记忆系统中
+3. **检索（Retrieval）**：根据需要从记忆中提取相关信息
+4. **整合（Consolidation）**：将短期记忆转化为长期记忆
+5. **遗忘（Forgetting）**：删除不重要或过时的信息
+
+基于该启发，我们为 HelloAgents 设计了一套完整的记忆系统。其核心思想是模仿人类大脑处理不同类型信息的方式，将记忆划分为多个专门的模块，并建立一套智能化的管理机制。图8.4详细展示了这套系统的工作流程，包括记忆的添加、检索、整合和遗忘等关键环节。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-4.png" alt="记忆系统工作流程" width="95%"/>
+  <p>图 8.4 HelloAgents记忆系统的完整工作流程</p>
+</div>
+
+我们的记忆系统由四种不同类型的记忆模块构成，每种模块都针对特定的应用场景和生命周期进行了优化：
+
+首先是**工作记忆 (Working Memory)**，它扮演着智能体“短期记忆”的角色，主要用于存储当前对话的上下文信息。为确保高速访问和响应，其容量被有意限制（例如，默认50条），并且生命周期与单个会话绑定，会话结束后便会自动清理。
+
+其次是**情景记忆 (Episodic Memory)**，它负责长期存储具体的交互事件和智能体的学习经历。与工作记忆不同，情景记忆包含了丰富的上下文信息，并支持按时间序列或主题进行回顾式检索，是智能体“复盘”和学习过往经验的基础。
+
+与具体事件相对应的是**语义记忆 (Semantic Memory)**，它存储的是更为抽象的知识、概念和规则。例如，通过对话了解到的用户偏好、需要长期遵守的指令或领域知识点，都适合存放在这里。这部分记忆具有高度的持久性和重要性，是智能体形成“知识体系”和进行关联推理的核心。
+
+最后，为了与日益丰富的多媒体交互，我们引入了**感知记忆 (Perceptual Memory)**。该模块专门处理图像、音频等多模态信息，并支持跨模态检索。其生命周期会根据信息的重要性和可用存储空间进行动态管理。
+
+### 8.2.2 快速体验：30秒上手记忆功能
+
+在深入实现细节之前，让我们先快速体验一下记忆系统的基本功能：
+
+```python
+from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry
+from hello_agents.tools import MemoryTool
+
+# 创建具有记忆能力的Agent
+llm = HelloAgentsLLM()
+agent = SimpleAgent(name="记忆助手", llm=llm)
+
+# 创建记忆工具
+memory_tool = MemoryTool(user_id="user123")
+tool_registry = ToolRegistry()
+tool_registry.register_tool(memory_tool)
+agent.tool_registry = tool_registry
+ 
+# 体验记忆功能
+print("=== 添加多个记忆 ===")
+
+# 添加第一个记忆
+result1 = memory_tool.execute("add", content="用户张三是一名Python开发者，专注于机器学习和数据分析", memory_type="semantic", importance=0.8)
+print(f"记忆1: {result1}")
+
+# 添加第二个记忆
+result2 = memory_tool.execute("add", content="李四是前端工程师，擅长React和Vue.js开发", memory_type="semantic", importance=0.7)
+print(f"记忆2: {result2}")
+
+# 添加第三个记忆
+result3 = memory_tool.execute("add", content="王五是产品经理，负责用户体验设计和需求分析", memory_type="semantic", importance=0.6)
+print(f"记忆3: {result3}")
+
+print("\n=== 搜索特定记忆 ===")
+# 搜索前端相关的记忆
+print("🔍 搜索 '前端工程师':")
+result = memory_tool.execute("search", query="前端工程师", limit=3)
+print(result)
+
+print("\n=== 记忆摘要 ===")
+result = memory_tool.execute("summary")
+print(result)
+```
+
+### 8.2.3 MemoryTool详解
+
+现在让我们采用自顶向下的方式，从MemoryTool支持的具体操作开始，逐步深入到底层实现。MemoryTool作为记忆系统的统一接口，其设计遵循了"统一入口，分发处理"的架构模式：
+
+````python
+def execute(self, action: str, **kwargs) -> str:
+    """执行记忆操作
+
+    支持的操作：
+    - add: 添加记忆（支持4种类型: working/episodic/semantic/perceptual）
+    - search: 搜索记忆
+    - summary: 获取记忆摘要
+    - stats: 获取统计信息
+    - update: 更新记忆
+    - remove: 删除记忆
+    - forget: 遗忘记忆（多种策略）
+    - consolidate: 整合记忆（短期→长期）
+    - clear_all: 清空所有记忆
+    """
+
+    if action == "add":
+        return self._add_memory(**kwargs)
+    elif action == "search":
+        return self._search_memory(**kwargs)
+    elif action == "summary":
+        return self._get_summary(**kwargs)
+    # ... 其他操作
+````
+
+这种统一的`execute`接口设计简化了Agent的调用方式，通过`action`参数指定具体操作，使用`**kwargs`允许每个操作有不同的参数需求。在这里我们会将比较重要的几个操作罗列出来：
+
+（1）操作1：add
+
+`add`操作是记忆系统的基础，它模拟了人类大脑将感知信息编码为记忆的过程。在实现中，我们不仅要存储记忆内容，还要为每个记忆添加丰富的上下文信息，这些信息将在后续的检索和管理中发挥重要作用。
+
+````python
+def _add_memory(
+    self,
+    content: str = "",
+    memory_type: str = "working",
+    importance: float = 0.5,
+    file_path: str = None,
+    modality: str = None,
+    **metadata
+) -> str:
+    """添加记忆"""
+    try:
+        # 确保会话ID存在
+        if self.current_session_id is None:
+            self.current_session_id = f"session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+        # 感知记忆文件支持
+        if memory_type == "perceptual" and file_path:
+            inferred = modality or self._infer_modality(file_path)
+            metadata.setdefault("modality", inferred)
+            metadata.setdefault("raw_data", file_path)
+
+        # 添加会话信息到元数据
+        metadata.update({
+            "session_id": self.current_session_id,
+            "timestamp": datetime.now().isoformat()
+        })
+
+        memory_id = self.memory_manager.add_memory(
+            content=content,
+            memory_type=memory_type,
+            importance=importance,
+            metadata=metadata,
+            auto_classify=False
+        )
+
+        return f"✅ 记忆已添加 (ID: {memory_id[:8]}...)"
+
+    except Exception as e:
+        return f"❌ 添加记忆失败: {str(e)}"
+````
+
+这里主要实现了三个关键任务：会话ID的自动管理（确保每个记忆都有明确的会话归属）、多模态数据的智能处理（自动推断文件类型并保存相关元数据）、以及上下文信息的自动补充（为每个记忆添加时间戳和会话信息）。其中，`importance`参数（默认0.5）用于标记记忆的重要程度，取值范围0.0-1.0，这个机制模拟了人类大脑对不同信息重要性的评估。这种设计让Agent能够自动区分不同时间段的对话，并为后续的检索和管理提供丰富的上下文信息。
+
+其中，对每个记忆类型，我们提供了不同的使用示例：
+
+```python
+# 1. 工作记忆 - 临时信息，容量有限
+memory_tool.execute("add",
+    content="用户刚才问了关于Python函数的问题",
+    memory_type="working",
+    importance=0.6
+)
+
+# 2. 情景记忆 - 具体事件和经历
+memory_tool.execute("add",
+    content="2024年3月15日，用户张三完成了第一个Python项目",
+    memory_type="episodic",
+    importance=0.8,
+    event_type="milestone",
+    location="在线学习平台"
+)
+
+# 3. 语义记忆 - 抽象知识和概念
+memory_tool.execute("add",
+    content="Python是一种解释型、面向对象的编程语言",
+    memory_type="semantic",
+    importance=0.9,
+    knowledge_type="factual"
+)
+
+# 4. 感知记忆 - 多模态信息
+memory_tool.execute("add",
+    content="用户上传了一张Python代码截图，包含函数定义",
+    memory_type="perceptual",
+    importance=0.7,
+    modality="image",
+    file_path="./uploads/code_screenshot.png"
+)
+```
+
+（2）操作2：search
+
+`search`操作是记忆系统的核心功能，它需要在大量记忆中快速找到与查询最相关的内容。它涉及语义理解、相关性计算和结果排序等多个环节。
+
+````python
+def _search_memory(
+    self,
+    query: str,
+    limit: int = 5,
+    memory_types: List[str] = None,
+    memory_type: str = None,
+    min_importance: float = 0.1
+) -> str:
+    """搜索记忆"""
+    try:
+        # 参数标准化处理
+        if memory_type and not memory_types:
+            memory_types = [memory_type]
+
+        results = self.memory_manager.retrieve_memories(
+            query=query,
+            limit=limit,
+            memory_types=memory_types,
+            min_importance=min_importance
+        )
+
+        if not results:
+            return f"🔍 未找到与 '{query}' 相关的记忆"
+
+        # 格式化结果
+        formatted_results = []
+        formatted_results.append(f"🔍 找到 {len(results)} 条相关记忆:")
+
+        for i, memory in enumerate(results, 1):
+            memory_type_label = {
+                "working": "工作记忆",
+                "episodic": "情景记忆", 
+                "semantic": "语义记忆",
+                "perceptual": "感知记忆"
+            }.get(memory.memory_type, memory.memory_type)
+
+            content_preview = memory.content[:80] + "..." if len(memory.content) > 80 else memory.content
+            formatted_results.append(
+                f"{i}. [{memory_type_label}] {content_preview} (重要性: {memory.importance:.2f})"
+            )
+
+        return "\n".join(formatted_results)
+
+    except Exception as e:
+        return f"❌ 搜索记忆失败: {str(e)}"
+````
+
+搜索操作在设计上支持单数和复数两种参数形式（`memory_type`和`memory_types`），让用户以最自然的方式表达需求。其中，`min_importance`参数（默认0.1）用于过滤低质量记忆。对于搜索功能的使用，可以参考这个示例。
+
+```python
+# 基础搜索
+result = memory_tool.execute("search", query="Python编程", limit=5)
+
+# 指定记忆类型搜索
+result = memory_tool.execute("search",
+    query="学习进度",
+    memory_type="episodic",
+    limit=3
+)
+
+# 多类型搜索
+result = memory_tool.execute("search",
+    query="函数定义",
+    memory_types=["semantic", "episodic"],
+    min_importance=0.5
+)
+```
+
+（3）操作3：forget
+
+遗忘机制是最具认知科学色彩的功能，它模拟人类大脑的选择性遗忘过程，支持三种策略：基于重要性（删除不重要的记忆）、基于时间（删除过时的记忆）和基于容量（当存储接近上限时删除最不重要的记忆）。
+
+````python
+def _forget(self, strategy: str = "importance_based", threshold: float = 0.1, max_age_days: int = 30) -> str:
+    """遗忘记忆（支持多种策略）"""
+    try:
+        count = self.memory_manager.forget_memories(
+            strategy=strategy,
+            threshold=threshold,
+            max_age_days=max_age_days
+        )
+        return f"🧹 已遗忘 {count} 条记忆（策略: {strategy}）"
+    except Exception as e:
+        return f"❌ 遗忘记忆失败: {str(e)}"
+````
+
+**三种遗忘策略的使用：**
+
+```python
+# 1. 基于重要性的遗忘 - 删除重要性低于阈值的记忆
+memory_tool.execute("forget",
+    strategy="importance_based",
+    threshold=0.2
+)
+
+# 2. 基于时间的遗忘 - 删除超过指定天数的记忆
+memory_tool.execute("forget",
+    strategy="time_based",
+    max_age_days=30
+)
+
+# 3. 基于容量的遗忘 - 当记忆数量超限时删除最不重要的
+memory_tool.execute("forget",
+    strategy="capacity_based",
+    threshold=0.3
+)
+```
+
+（4）操作4：consolidate
+
+````python
+def _consolidate(self, from_type: str = "working", to_type: str = "episodic", importance_threshold: float = 0.7) -> str:
+    """整合记忆（将重要的短期记忆提升为长期记忆）"""
+    try:
+        count = self.memory_manager.consolidate_memories(
+            from_type=from_type,
+            to_type=to_type,
+            importance_threshold=importance_threshold,
+        )
+        return f"🔄 已整合 {count} 条记忆为长期记忆（{from_type} → {to_type}，阈值={importance_threshold}）"
+    except Exception as e:
+        return f"❌ 整合记忆失败: {str(e)}"
+````
+
+consolidate操作借鉴了神经科学中的记忆固化概念，模拟人类大脑将短期记忆转化为长期记忆的过程。默认设置是将重要性超过0.7的工作记忆转换为情景记忆，这个阈值确保只有真正重要的信息才会被长期保存。整个过程是自动化的，用户无需手动选择具体的记忆，系统会智能地识别符合条件的记忆并执行类型转换。
+
+**记忆整合的使用示例：**
+
+```python
+# 将重要的工作记忆转为情景记忆
+memory_tool.execute("consolidate",
+    from_type="working",
+    to_type="episodic",
+    importance_threshold=0.7
+)
+
+# 将重要的情景记忆转为语义记忆
+memory_tool.execute("consolidate",
+    from_type="episodic",
+    to_type="semantic",
+    importance_threshold=0.8
+)
+```
+
+通过以上几个核心操作协作，MemoryTool构建了一个完整的记忆生命周期管理体系。从记忆的创建、检索、摘要到遗忘、整合和管理，形成了一个闭环的智能记忆管理系统，让Agent真正具备了类人的记忆能力。
+
+### 8.2.4 MemoryManager详解
+
+理解了MemoryTool的接口设计后，让我们深入到底层实现，看看MemoryTool是如何与MemoryManager协作的。这种分层设计体现了软件工程中的关注点分离原则，MemoryTool专注于用户接口和参数处理，而MemoryManager则负责核心的记忆管理逻辑。
+
+MemoryTool在初始化时会创建一个MemoryManager实例，并根据配置启用不同类型的记忆模块。这种设计让用户可以根据具体需求选择启用哪些记忆类型，既保证了功能的完整性，又避免了不必要的资源消耗。
+
+````python
+class MemoryTool(Tool):
+    """记忆工具 - 为Agent提供记忆功能"""
+    
+    def __init__(
+        self,
+        user_id: str = "default_user",
+        memory_config: MemoryConfig = None,
+        memory_types: List[str] = None
+    ):
+        super().__init__(
+            name="memory",
+            description="记忆工具 - 可以存储和检索对话历史、知识和经验"
+        )
+        
+        # 初始化记忆管理器
+        self.memory_config = memory_config or MemoryConfig()
+        self.memory_types = memory_types or ["working", "episodic", "semantic"]
+        
+        self.memory_manager = MemoryManager(
+            config=self.memory_config,
+            user_id=user_id,
+            enable_working="working" in self.memory_types,
+            enable_episodic="episodic" in self.memory_types,
+            enable_semantic="semantic" in self.memory_types,
+            enable_perceptual="perceptual" in self.memory_types
+        )
+````
+MemoryManager作为记忆系统的核心协调者，负责管理不同类型的记忆模块，并提供统一的操作接口。
+
+````python
+class MemoryManager:
+    """记忆管理器 - 统一的记忆操作接口"""
+
+    def __init__(
+        self,
+        config: Optional[MemoryConfig] = None,
+        user_id: str = "default_user",
+        enable_working: bool = True,
+        enable_episodic: bool = True,
+        enable_semantic: bool = True,
+        enable_perceptual: bool = False
+    ):
+        self.config = config or MemoryConfig()
+        self.user_id = user_id
+
+        # 初始化存储和检索组件
+        self.store = MemoryStore(self.config)
+        self.retriever = MemoryRetriever(self.store, self.config)
+
+        # 初始化各类型记忆
+        self.memory_types = {}
+
+        if enable_working:
+            self.memory_types['working'] = WorkingMemory(self.config, self.store)
+
+        if enable_episodic:
+            self.memory_types['episodic'] = EpisodicMemory(self.config, self.store)
+
+        if enable_semantic:
+            self.memory_types['semantic'] = SemanticMemory(self.config, self.store)
+
+        if enable_perceptual:
+            self.memory_types['perceptual'] = PerceptualMemory(self.config, self.store)
+````
+### 8.2.5 四种记忆类型
+
+现在让我们深入了解四种记忆类型的具体实现，每种记忆类型都有其独特的特点和应用场景：
+
+（1）工作记忆（WorkingMemory）
+
+工作记忆是记忆系统中最活跃的部分，它负责存储当前对话会话中的临时信息。工作记忆的设计重点在于快速访问和自动清理，这种设计确保了系统的响应速度和资源效率。
+
+工作记忆采用了纯内存存储方案，配合TTL（Time To Live）机制进行自动清理。这种设计的优势在于访问速度极快，但也意味着工作记忆的内容在系统重启后会丢失。这种特性正好符合工作记忆的定位，存储临时的、易变的信息。
+
+
+````python
+class WorkingMemory:
+    """工作记忆实现
+    特点：
+    - 容量有限（默认50条）+ TTL自动清理
+    - 纯内存存储，访问速度极快
+    - 混合检索：TF-IDF向量化 + 关键词匹配
+    """
+    
+    def __init__(self, config: MemoryConfig):
+        self.max_capacity = config.working_memory_capacity or 50
+        self.max_age_minutes = config.working_memory_ttl or 60
+        self.memories = []
+    
+    def add(self, memory_item: MemoryItem) -> str:
+        """添加工作记忆"""
+        self._expire_old_memories()  # 过期清理
+        
+        if len(self.memories) >= self.max_capacity:
+            self._remove_lowest_priority_memory()  # 容量管理
+        
+        self.memories.append(memory_item)
+        return memory_item.id
+    
+    def retrieve(self, query: str, limit: int = 5, **kwargs) -> List[MemoryItem]:
+        """混合检索：TF-IDF向量化 + 关键词匹配"""
+        self._expire_old_memories()
+        
+        # 尝试TF-IDF向量检索
+        vector_scores = self._try_tfidf_search(query)
+        
+        # 计算综合分数
+        scored_memories = []
+        for memory in self.memories:
+            vector_score = vector_scores.get(memory.id, 0.0)
+            keyword_score = self._calculate_keyword_score(query, memory.content)
+            
+            # 混合评分
+            base_relevance = vector_score * 0.7 + keyword_score * 0.3 if vector_score > 0 else keyword_score
+            time_decay = self._calculate_time_decay(memory.timestamp)
+            importance_weight = 0.8 + (memory.importance * 0.4)
+            
+            final_score = base_relevance * time_decay * importance_weight
+            if final_score > 0:
+                scored_memories.append((final_score, memory))
+        
+        scored_memories.sort(key=lambda x: x[0], reverse=True)
+        return [memory for _, memory in scored_memories[:limit]]
+````
+工作记忆的检索采用了混合检索策略，首先尝试使用TF-IDF向量化进行语义检索，如果失败则回退到关键词匹配。这种设计确保了在各种环境下都能提供可靠的检索服务。评分算法结合了语义相似度、时间衰减和重要性权重，最终得分公式为：`(相似度 × 时间衰减) × (0.8 + 重要性 × 0.4)`。
+
+（2）情景记忆（EpisodicMemory）
+
+情景记忆负责存储具体的事件和经历，它的设计重点在于保持事件的完整性和时间序列关系。情景记忆采用了SQLite+Qdrant的混合存储方案，SQLite负责结构化数据的存储和复杂查询，Qdrant负责高效的向量检索。
+
+````python
+class EpisodicMemory:
+    """情景记忆实现
+    特点：
+    - SQLite+Qdrant混合存储架构
+    - 支持时间序列和会话级检索
+    - 结构化过滤 + 语义向量检索
+    """
+    
+    def __init__(self, config: MemoryConfig):
+        self.doc_store = SQLiteDocumentStore(config.database_path)
+        self.vector_store = QdrantVectorStore(config.qdrant_url, config.qdrant_api_key)
+        self.embedder = create_embedding_model_with_fallback()
+        self.sessions = {}  # 会话索引
+    
+    def add(self, memory_item: MemoryItem) -> str:
+        """添加情景记忆"""
+        # 创建情景对象
+        episode = Episode(
+            episode_id=memory_item.id,
+            session_id=memory_item.metadata.get("session_id", "default"),
+            timestamp=memory_item.timestamp,
+            content=memory_item.content,
+            context=memory_item.metadata
+        )
+        
+        # 更新会话索引
+        session_id = episode.session_id
+        if session_id not in self.sessions:
+            self.sessions[session_id] = []
+        self.sessions[session_id].append(episode.episode_id)
+        
+        # 持久化存储（SQLite + Qdrant）
+        self._persist_episode(episode)
+        return memory_item.id
+    
+    def retrieve(self, query: str, limit: int = 5, **kwargs) -> List[MemoryItem]:
+        """混合检索：结构化过滤 + 语义向量检索"""
+        # 1. 结构化预过滤（时间范围、重要性等）
+        candidate_ids = self._structured_filter(**kwargs)
+        
+        # 2. 向量语义检索
+        hits = self._vector_search(query, limit * 5, kwargs.get("user_id"))
+        
+        # 3. 综合评分与排序
+        results = []
+        for hit in hits:
+            if self._should_include(hit, candidate_ids, kwargs):
+                score = self._calculate_episode_score(hit)
+                memory_item = self._create_memory_item(hit)
+                results.append((score, memory_item))
+        
+        results.sort(key=lambda x: x[0], reverse=True)
+        return [item for _, item in results[:limit]]
+    
+    def _calculate_episode_score(self, hit) -> float:
+        """情景记忆评分算法"""
+        vec_score = float(hit.get("score", 0.0))
+        recency_score = self._calculate_recency(hit["metadata"]["timestamp"])
+        importance = hit["metadata"].get("importance", 0.5)
+        
+        # 评分公式：(向量相似度 × 0.8 + 时间近因性 × 0.2) × 重要性权重
+        base_relevance = vec_score * 0.8 + recency_score * 0.2
+        importance_weight = 0.8 + (importance * 0.4)
+        
+        return base_relevance * importance_weight
+````
+情景记忆的检索实现展现了复杂的多因素评分机制。它不仅考虑了语义相似度，还加入了时间近因性的考量，最终通过重要性权重进行调节。评分公式为：`(向量相似度 × 0.8 + 时间近因性 × 0.2) × (0.8 + 重要性 × 0.4)`，确保检索结果既语义相关又时间相关。
+
+（3）语义记忆（SemanticMemory）
+
+语义记忆是记忆系统中最复杂的部分，它负责存储抽象的概念、规则和知识。语义记忆的设计重点在于知识的结构化表示和智能推理能力。语义记忆采用了Neo4j图数据库和Qdrant向量数据库的混合架构，这种设计让系统既能进行快速的语义检索，又能利用知识图谱进行复杂的关系推理。
+
+````python
+class SemanticMemory(BaseMemory):
+    """语义记忆实现
+    
+    特点：
+    - 使用HuggingFace中文预训练模型进行文本嵌入
+    - 向量检索进行快速相似度匹配
+    - 知识图谱存储实体和关系
+    - 混合检索策略：向量+图+语义推理
+    """
+    
+    def __init__(self, config: MemoryConfig, storage_backend=None):
+        super().__init__(config, storage_backend)
+        
+        # 嵌入模型（统一提供）
+        self.embedding_model = get_text_embedder()
+        
+        # 专业数据库存储
+        self.vector_store = QdrantConnectionManager.get_instance(**qdrant_config)
+        self.graph_store = Neo4jGraphStore(**neo4j_config)
+        
+        # 实体和关系缓存
+        self.entities: Dict[str, Entity] = {}
+        self.relations: List[Relation] = []
+        
+        # NLP处理器（支持中英文）
+        self.nlp = self._init_nlp()
+````
+语义记忆的添加过程体现了知识图谱构建的完整流程。系统不仅存储记忆内容，还会自动提取实体和关系，构建结构化的知识表示：
+
+```python
+def add(self, memory_item: MemoryItem) -> str:
+    """添加语义记忆"""
+    # 1. 生成文本嵌入
+    embedding = self.embedding_model.encode(memory_item.content)
+    
+    # 2. 提取实体和关系
+    entities = self._extract_entities(memory_item.content)
+    relations = self._extract_relations(memory_item.content, entities)
+    
+    # 3. 存储到Neo4j图数据库
+    for entity in entities:
+        self._add_entity_to_graph(entity, memory_item)
+    
+    for relation in relations:
+        self._add_relation_to_graph(relation, memory_item)
+    
+    # 4. 存储到Qdrant向量数据库
+    metadata = {
+        "memory_id": memory_item.id,
+        "entities": [e.entity_id for e in entities],
+        "entity_count": len(entities),
+        "relation_count": len(relations)
+    }
+    
+    self.vector_store.add_vectors(
+        vectors=[embedding.tolist()],
+        metadata=[metadata],
+        ids=[memory_item.id]
+    )
+```
+
+语义记忆的检索实现了混合搜索策略，结合了向量检索的语义理解能力和图检索的关系推理能力：
+
+```python
+def retrieve(self, query: str, limit: int = 5, **kwargs) -> List[MemoryItem]:
+    """检索语义记忆"""
+    # 1. 向量检索
+    vector_results = self._vector_search(query, limit * 2, user_id)
+    
+    # 2. 图检索
+    graph_results = self._graph_search(query, limit * 2, user_id)
+    
+    # 3. 混合排序
+    combined_results = self._combine_and_rank_results(
+        vector_results, graph_results, query, limit
+    )
+    
+    return combined_results[:limit]
+```
+
+混合排序算法采用了多因素评分机制：
+
+```python
+def _combine_and_rank_results(self, vector_results, graph_results, query, limit):
+    """混合排序结果"""
+    combined = {}
+    
+    # 合并向量和图检索结果
+    for result in vector_results:
+        combined[result["memory_id"]] = {
+            **result,
+            "vector_score": result.get("score", 0.0),
+            "graph_score": 0.0
+        }
+    
+    for result in graph_results:
+        memory_id = result["memory_id"]
+        if memory_id in combined:
+            combined[memory_id]["graph_score"] = result.get("similarity", 0.0)
+        else:
+            combined[memory_id] = {
+                **result,
+                "vector_score": 0.0,
+                "graph_score": result.get("similarity", 0.0)
+            }
+    
+    # 计算混合分数
+    for memory_id, result in combined.items():
+        vector_score = result["vector_score"]
+        graph_score = result["graph_score"]
+        importance = result.get("importance", 0.5)
+        
+        # 基础相似度得分
+        base_relevance = vector_score * 0.7 + graph_score * 0.3
+        
+        # 重要性权重 [0.8, 1.2]
+        importance_weight = 0.8 + (importance * 0.4)
+        
+        # 最终得分：相似度 * 重要性权重
+        combined_score = base_relevance * importance_weight
+        result["combined_score"] = combined_score
+    
+    # 排序并返回
+    sorted_results = sorted(
+        combined.values(),
+        key=lambda x: x["combined_score"],
+        reverse=True
+    )
+    
+    return sorted_results[:limit]
+```
+
+语义记忆的评分公式为：`(向量相似度 × 0.7 + 图相似度 × 0.3) × (0.8 + 重要性 × 0.4)`。这种设计的核心思想是：
+
+- **向量检索权重（0.7）**：语义相似度是主要因素，确保检索结果与查询语义相关
+- **图检索权重（0.3）**：关系推理作为补充，发现概念间的隐含关联
+- **重要性权重范围[0.8, 1.2]**：避免重要性过度影响相似度排序，保持检索的准确性
+
+（4）感知记忆（PerceptualMemory）
+
+感知记忆支持文本、图像、音频等多种模态的数据存储和检索。它采用了模态分离的存储策略，为不同模态的数据创建独立的向量集合，这种设计避免了维度不匹配的问题，同时保证了检索的准确性：
+
+````python
+class PerceptualMemory(BaseMemory):
+    """感知记忆实现
+    
+    特点：
+    - 支持多模态数据（文本、图像、音频等）
+    - 跨模态相似性搜索
+    - 感知数据的语义理解
+    - 支持内容生成和检索
+    """
+    
+    def __init__(self, config: MemoryConfig, storage_backend=None):
+        super().__init__(config, storage_backend)
+        
+        # 多模态编码器
+        self.text_embedder = get_text_embedder()
+        self._clip_model = self._init_clip_model()  # 图像编码
+        self._clap_model = self._init_clap_model()  # 音频编码
+        
+        # 按模态分离的向量存储
+        self.vector_stores = {
+            "text": QdrantConnectionManager.get_instance(
+                collection_name="perceptual_text",
+                vector_size=self.vector_dim
+            ),
+            "image": QdrantConnectionManager.get_instance(
+                collection_name="perceptual_image", 
+                vector_size=self._image_dim
+            ),
+            "audio": QdrantConnectionManager.get_instance(
+                collection_name="perceptual_audio",
+                vector_size=self._audio_dim
+            )
+        }
+````
+感知记忆的检索支持同模态和跨模态两种模式。同模态检索利用专业的编码器进行精确匹配，而跨模态检索则需要更复杂的语义对齐机制：
+
+```python
+def retrieve(self, query: str, limit: int = 5, **kwargs) -> List[MemoryItem]:
+    """检索感知记忆（可筛模态；同模态向量检索+时间/重要性融合）"""
+    user_id = kwargs.get("user_id")
+    target_modality = kwargs.get("target_modality")
+    query_modality = kwargs.get("query_modality", target_modality or "text")
+    
+    # 同模态向量检索
+    try:
+        query_vector = self._encode_data(query, query_modality)
+        store = self._get_vector_store_for_modality(target_modality or query_modality)
+        
+        where = {"memory_type": "perceptual"}
+        if user_id:
+            where["user_id"] = user_id
+        if target_modality:
+            where["modality"] = target_modality
+        
+        hits = store.search_similar(
+            query_vector=query_vector,
+            limit=max(limit * 5, 20),
+            where=where
+        )
+    except Exception:
+        hits = []
+    
+    # 融合排序（向量相似度 + 时间近因性 + 重要性权重）
+    results = []
+    for hit in hits:
+        vector_score = float(hit.get("score", 0.0))
+        recency_score = self._calculate_recency_score(hit["metadata"]["timestamp"])
+        importance = hit["metadata"].get("importance", 0.5)
+        
+        # 评分算法
+        base_relevance = vector_score * 0.8 + recency_score * 0.2
+        importance_weight = 0.8 + (importance * 0.4)
+        combined_score = base_relevance * importance_weight
+        
+        results.append((combined_score, self._create_memory_item(hit)))
+    
+    results.sort(key=lambda x: x[0], reverse=True)
+    return [item for _, item in results[:limit]]
+```
+
+感知记忆的评分公式为：`(向量相似度 × 0.8 + 时间近因性 × 0.2) × (0.8 + 重要性 × 0.4)`。感知记忆的评分机制还支持跨模态检索，通过统一的向量空间实现文本、图像、音频等不同模态数据的语义对齐。当进行跨模态检索时，系统会自动调整评分权重，确保检索结果的多样性和准确性。此外，感知记忆中的时间近因性计算采用了指数衰减模型：
+
+```python
+def _calculate_recency_score(self, timestamp: str) -> float:
+    """计算时间近因性得分"""
+    try:
+        memory_time = datetime.fromisoformat(timestamp)
+        current_time = datetime.now()
+        age_hours = (current_time - memory_time).total_seconds() / 3600
+        
+        # 指数衰减：24小时内保持高分，之后逐渐衰减
+        decay_factor = 0.1  # 衰减系数
+        recency_score = math.exp(-decay_factor * age_hours / 24)
+        
+        return max(0.1, recency_score)  # 最低保持0.1的基础分数
+    except Exception:
+        return 0.5  # 默认中等分数
+```
+
+这种时间衰减模型模拟了人类记忆中的遗忘曲线，确保了感知记忆系统能够优先检索到时间上更相关的记忆内容。
+
+## 8.3 RAG系统：知识检索增强
+
+### 8.3.1 RAG的基础知识
+
+在深入HelloAgents的RAG系统实现之前，让我们先了解RAG技术的基础概念、发展历程和核心原理。由于本文内容不是以RAG为基础进行创作，为此这里只帮读者快速梳理相关概念，以便更好地理解系统设计的技术选择和创新点。
+
+（1）什么是RAG？
+
+检索增强生成（Retrieval-Augmented Generation，RAG）是一种结合了信息检索和文本生成的技术。它的核心思想是：在生成回答之前，先从外部知识库中检索相关信息，然后将检索到的信息作为上下文提供给大语言模型，从而生成更准确、更可靠的回答。
+
+因此，检索增强生成可以拆分为三个词汇。**检索**是指从知识库中查询相关内容；**增强**是将检索结果融入提示词，辅助模型生成；**生成**则输出兼具准确性与透明度的答案。
+
+（2）基本工作流程
+
+一个完整的RAG应用流程主要分为两大核心环节。在**数据准备阶段**，系统通过**数据提取**、**文本分割**和**向量化**，将外部知识构建成一个可检索的数据库。随后在**应用阶段**，系统会响应用户的**提问**，从数据库中**检索**相关信息，将其**注入Prompt**，并最终驱动大语言模型**生成答案**。
+
+（3）发展历程
+
+第一阶段：朴素RAG（Naive RAG, 2020-2021）。这是RAG技术的萌芽阶段，其流程直接而简单，通常被称为“检索-读取”（Retrieve-Read）模式。**检索方式**：主要依赖传统的关键词匹配算法，如`TF-IDF`或`BM25`。这些方法计算词频和文档频率来评估相关性，对字面匹配效果好，但难以理解语义上的相似性。**生成模式**：将检索到的文档内容不加处理地直接拼接到提示词的上下文中，然后送给生成模型。
+
+第二阶段：高级RAG（Advanced RAG, 2022-2023）。随着向量数据库和文本嵌入技术的成熟，RAG进入了快速发展阶段。研究者和开发者们在“检索”和“生成”的各个环节引入了大量优化技术。**检索方式**：转向基于**稠密嵌入（Dense Embedding）**的语义检索。通过将文本转换为高维向量，模型能够理解和匹配语义上的相似性，而不仅仅是关键词。**生成模式**：引入了很多优化技术，例如查询重写，文档分块，重排序等。
+
+第三阶段：模块化RAG（Modular RAG, 2023-至今）。在高级RAG的基础上，现代RAG系统进一步向着模块化、自动化和智能化的方向发展。系统的各个部分被设计成可插拔、可组合的独立模块，以适应更多样化和复杂的应用场景。**检索方式**：如混合检索，多查询扩展，假设性文档嵌入等。**生成模式**：思维链推理，自我反思与修正等。
+
+
+
+### 8.3.2 RAG系统工作原理
+
+在深入实现细节之前，可以通过流程图来梳理Helloagents的RAG系统完整工作流程：
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-5.png" alt="RAG系统核心原理" width="85%"/>
+  <p>图 8.5 RAG系统的核心工作原理</p>
+</div>
+
+如图8.5所示，展示了RAG系统的两个主要工作模式：
+1. **数据处理流程**：处理和存储知识文档，在这里我们采取工具`Markitdown`，设计思路是将传入的一切外部知识源统一转化为Markdown格式进行处理。
+2. **查询与生成流程**：根据查询检索相关信息并生成回答。
+
+### 8.3.3 快速体验：30秒上手RAG功能
+
+让我们先快速体验一下RAG系统的基本功能：
+
+```python
+from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry
+from hello_agents.tools import RAGTool
+
+# 创建具有RAG能力的Agent
+llm = HelloAgentsLLM()
+agent = SimpleAgent(name="知识助手", llm=llm)
+
+# 创建RAG工具
+rag_tool = RAGTool(
+    knowledge_base_path="./knowledge_base",
+    collection_name="test_collection",
+    rag_namespace="test"
+)
+
+tool_registry = ToolRegistry()
+tool_registry.register_tool(rag_tool)
+agent.tool_registry = tool_registry
+
+# 体验RAG功能
+# 添加第一个知识
+result1 = rag_tool.execute("add_text", 
+    text="Python是一种高级编程语言，由Guido van Rossum于1991年首次发布。Python的设计哲学强调代码的可读性和简洁的语法。",
+    document_id="python_intro")
+print(f"知识1: {result1}")
+
+# 添加第二个知识  
+result2 = rag_tool.execute("add_text",
+    text="机器学习是人工智能的一个分支，通过算法让计算机从数据中学习模式。主要包括监督学习、无监督学习和强化学习三种类型。",
+    document_id="ml_basics")
+print(f"知识2: {result2}")
+
+# 添加第三个知识
+result3 = rag_tool.execute("add_text",
+    text="RAG（检索增强生成）是一种结合信息检索和文本生成的AI技术。它通过检索相关知识来增强大语言模型的生成能力。",
+    document_id="rag_concept")
+print(f"知识3: {result3}")
+
+
+print("\n=== 搜索知识 ===")
+result = rag_tool.execute("search",
+    query="Python编程语言的历史",
+    limit=3,
+    min_score=0.1
+)
+print(result)
+
+print("\n=== 知识库统计 ===")
+result = rag_tool.execute("stats")
+print(result)
+```
+
+接下来，我们将深入探讨HelloAgents RAG系统的具体实现。
+
+### 8.3.4 RAG系统架构设计
+
+在这一节中，我们采取与记忆系统不同的方式讲解。因为`Memory_tool`是系统性的实现，而RAG在我们的设计中被定义为一种工具，可以梳理为一条pipeline。我们的RAG系统的核心架构可以概括为"五层七步"的设计模式：
+
+```
+用户层：RAGTool统一接口
+  ↓
+应用层：智能问答、搜索、管理
+  ↓  
+处理层：文档解析、分块、向量化
+  ↓
+存储层：向量数据库、文档存储
+  ↓
+基础层：嵌入模型、LLM、数据库
+```
+
+这种分层设计的优势在于每一层都可以独立优化和替换，同时保持整体系统的稳定性。例如，可以轻松地将嵌入模型从sentence-transformers切换到百炼API，而不影响上层的业务逻辑。同样的，这些处理的流程代码是完全可复用的，也可以选取自己需要的部分放进自己的项目中。RAGTool作为RAG系统的统一入口，提供了简洁的API接口。
+
+````python
+class RAGTool(Tool):
+    """RAG工具
+    
+    提供完整的 RAG 能力：
+    - 添加多格式文档（PDF、Office、图片、音频等）
+    - 智能检索与召回
+    - LLM 增强问答
+    - 知识库管理
+    """
+    
+    def __init__(
+        self,
+        knowledge_base_path: str = "./knowledge_base",
+        qdrant_url: str = None,
+        qdrant_api_key: str = None,
+        collection_name: str = "rag_knowledge_base",
+        rag_namespace: str = "default"
+    ):
+        # 初始化RAG管道
+        self._pipelines: Dict[str, Dict[str, Any]] = {}
+        self.llm = HelloAgentsLLM()
+        
+        # 创建默认管道
+        default_pipeline = create_rag_pipeline(
+            qdrant_url=self.qdrant_url,
+            qdrant_api_key=self.qdrant_api_key,
+            collection_name=self.collection_name,
+            rag_namespace=self.rag_namespace
+        )
+        self._pipelines[self.rag_namespace] = default_pipeline
+````
+整个处理流程如下所示：
+```
+任意格式文档 → MarkItDown转换 → Markdown文本 → 智能分块 → 向量化 → 存储检索
+```
+
+（1）多模态文档载入
+
+RAG系统的核心优势之一是其强大的多模态文档处理能力。系统使用MarkItDown作为统一的文档转换引擎，支持几乎所有常见的文档格式。MarkItDown是微软开源的通用文档转换工具，它是HelloAgents RAG系统的核心组件，负责将任意格式的文档统一转换为结构化的Markdown文本。无论输入是PDF、Word、Excel、图片还是音频，最终都会转换为标准的Markdown格式，然后进入统一的分块、向量化和存储流程。
+
+```python
+def _convert_to_markdown(path: str) -> str:
+    """
+    Universal document reader using MarkItDown with enhanced PDF processing.
+    核心功能：将任意格式文档转换为Markdown文本
+    
+    支持格式：
+    - 文档：PDF、Word、Excel、PowerPoint
+    - 图像：JPG、PNG、GIF（通过OCR）
+    - 音频：MP3、WAV、M4A（通过转录）
+    - 文本：TXT、CSV、JSON、XML、HTML
+    - 代码：Python、JavaScript、Java等
+    """
+    if not os.path.exists(path):
+        return ""
+    
+    # 对PDF文件使用增强处理
+    ext = (os.path.splitext(path)[1] or '').lower()
+    if ext == '.pdf':
+        return _enhanced_pdf_processing(path)
+    
+    # 其他格式使用MarkItDown统一转换
+    md_instance = _get_markitdown_instance()
+    if md_instance is None:
+        return _fallback_text_reader(path)
+    
+    try:
+        result = md_instance.convert(path)
+        markdown_text = getattr(result, "text_content", None)
+        if isinstance(markdown_text, str) and markdown_text.strip():
+            print(f"[RAG] MarkItDown转换成功: {path} -> {len(markdown_text)} chars Markdown")
+            return markdown_text
+        return ""
+    except Exception as e:
+        print(f"[WARNING] MarkItDown转换失败 {path}: {e}")
+        return _fallback_text_reader(path)
+```
+
+（2）智能分块策略
+
+经过MarkItDown转换后，所有文档都统一为标准的Markdown格式。这为后续的智能分块提供了结构化的基础。HelloAgents实现了专门针对Markdown格式的智能分块策略，充分利用Markdown的结构化特性进行精确分割。
+
+Markdown结构感知的分块流程：
+
+```
+标准Markdown文本 → 标题层次解析 → 段落语义分割 → Token计算分块 → 重叠策略优化 → 向量化准备
+       ↓                ↓              ↓            ↓           ↓            ↓
+   统一格式          #/##/###        语义边界      大小控制     信息连续性    嵌入向量
+   结构清晰          层次识别        完整性保证    检索优化     上下文保持    相似度匹配
+```
+
+由于所有文档都已转换为Markdown格式，系统可以利用Markdown的标题结构（#、##、###等）进行精确的语义分割：
+
+```python
+def _split_paragraphs_with_headings(text: str) -> List[Dict]:
+    """根据标题层次分割段落，保持语义完整性"""
+    lines = text.splitlines()
+    heading_stack: List[str] = []
+    paragraphs: List[Dict] = []
+    buf: List[str] = []
+    char_pos = 0
+    
+    def flush_buf(end_pos: int):
+        if not buf:
+            return
+        content = "\n".join(buf).strip()
+        if not content:
+            return
+        paragraphs.append({
+            "content": content,
+            "heading_path": " > ".join(heading_stack) if heading_stack else None,
+            "start": max(0, end_pos - len(content)),
+            "end": end_pos,
+        })
+    
+    for ln in lines:
+        raw = ln
+        if raw.strip().startswith("#"):
+            # 处理标题行
+            flush_buf(char_pos)
+            level = len(raw) - len(raw.lstrip('#'))
+            title = raw.lstrip('#').strip()
+            
+            if level <= 0:
+                level = 1
+            if level <= len(heading_stack):
+                heading_stack = heading_stack[:level-1]
+            heading_stack.append(title)
+            
+            char_pos += len(raw) + 1
+            continue
+        
+        # 段落内容累积
+        if raw.strip() == "":
+            flush_buf(char_pos)
+            buf = []
+        else:
+            buf.append(raw)
+        char_pos += len(raw) + 1
+    
+    flush_buf(char_pos)
+    
+    if not paragraphs:
+        paragraphs = [{"content": text, "heading_path": None, "start": 0, "end": len(text)}]
+    
+    return paragraphs
+```
+
+在Markdown段落分割的基础上，系统进一步根据Token数量进行智能分块。由于输入已经是结构化的Markdown文本，系统可以更精确地控制分块边界，确保每个分块既适合向量化处理，又保持Markdown结构的完整性：
+
+```
+def _chunk_paragraphs(paragraphs: List[Dict], chunk_tokens: int, overlap_tokens: int) -> List[Dict]:
+    """基于Token数量的智能分块"""
+    chunks: List[Dict] = []
+    cur: List[Dict] = []
+    cur_tokens = 0
+    i = 0
+    
+    while i < len(paragraphs):
+        p = paragraphs[i]
+        p_tokens = _approx_token_len(p["content"]) or 1
+        
+        if cur_tokens + p_tokens <= chunk_tokens or not cur:
+            cur.append(p)
+            cur_tokens += p_tokens
+            i += 1
+        else:
+            # 生成当前分块
+            content = "\n\n".join(x["content"] for x in cur)
+            start = cur[0]["start"]
+            end = cur[-1]["end"]
+            heading_path = next((x["heading_path"] for x in reversed(cur) if x.get("heading_path")), None)
+            
+            chunks.append({
+                "content": content,
+                "start": start,
+                "end": end,
+                "heading_path": heading_path,
+            })
+            
+            # 构建重叠部分
+            if overlap_tokens > 0 and cur:
+                kept: List[Dict] = []
+                kept_tokens = 0
+                for x in reversed(cur):
+                    t = _approx_token_len(x["content"]) or 1
+                    if kept_tokens + t > overlap_tokens:
+                        break
+                    kept.append(x)
+                    kept_tokens += t
+                cur = list(reversed(kept))
+                cur_tokens = kept_tokens
+            else:
+                cur = []
+                cur_tokens = 0
+    
+    # 处理最后一个分块
+    if cur:
+        content = "\n\n".join(x["content"] for x in cur)
+        start = cur[0]["start"]
+        end = cur[-1]["end"]
+        heading_path = next((x["heading_path"] for x in reversed(cur) if x.get("heading_path")), None)
+        
+        chunks.append({
+            "content": content,
+            "start": start,
+            "end": end,
+            "heading_path": heading_path,
+        })
+    
+    return chunks
+```
+
+同时为了兼容不同语言，系统实现了针对中英文混合文本的Token估算算法，这对于准确控制分块大小至关重要：
+
+```python
+def _approx_token_len(text: str) -> int:
+    """近似估计Token长度，支持中英文混合"""
+    # CJK字符按1 token计算
+    cjk = sum(1 for ch in text if _is_cjk(ch))
+    # 其他字符按空白分词计算
+    non_cjk_tokens = len([t for t in text.split() if t])
+    return cjk + non_cjk_tokens
+
+def _is_cjk(ch: str) -> bool:
+    """判断是否为CJK字符"""
+    code = ord(ch)
+    return (
+        0x4E00 <= code <= 0x9FFF or  # CJK统一汉字
+        0x3400 <= code <= 0x4DBF or  # CJK扩展A
+        0x20000 <= code <= 0x2A6DF or # CJK扩展B
+        0x2A700 <= code <= 0x2B73F or # CJK扩展C
+        0x2B740 <= code <= 0x2B81F or # CJK扩展D
+        0x2B820 <= code <= 0x2CEAF or # CJK扩展E
+        0xF900 <= code <= 0xFAFF      # CJK兼容汉字
+    )
+```
+
+（3）统一嵌入与向量存储
+
+嵌入模型是RAG系统的核心，它负责将文本转换为高维向量，使得计算机能够理解和比较文本的语义相似性。RAG系统的检索能力很大程度上取决于嵌入模型的质量和向量存储的效率。HelloAgents实现了统一的嵌入接口。在这里为了演示，使用百炼API，如果尚未配置可以切换为本地的`all-MiniLM-L6-v2`模型，如果两种方案都不支持，也配置了TF-IDF算法来兜底。实际使用可以替换为自己想要的模型或者API，也可以尝试去扩展框架内容~
+
+```python
+def index_chunks(
+    store = None, 
+    chunks: List[Dict] = None, 
+    cache_db: Optional[str] = None, 
+    batch_size: int = 64,
+    rag_namespace: str = "default"
+) -> None:
+    """
+    Index markdown chunks with unified embedding and Qdrant storage.
+    Uses百炼 API with fallback to sentence-transformers.
+    """
+    if not chunks:
+        print("[RAG] No chunks to index")
+        return
+    
+    # 使用统一嵌入模型
+    embedder = get_text_embedder()
+    dimension = get_dimension(384)
+    
+    # 创建默认Qdrant存储
+    if store is None:
+        store = _create_default_vector_store(dimension)
+        print(f"[RAG] Created default Qdrant store with dimension {dimension}")
+    
+    # 预处理Markdown文本以获得更好的嵌入质量
+    processed_texts = []
+    for c in chunks:
+        raw_content = c["content"]
+        processed_content = _preprocess_markdown_for_embedding(raw_content)
+        processed_texts.append(processed_content)
+    
+    print(f"[RAG] Embedding start: total_texts={len(processed_texts)} batch_size={batch_size}")
+    
+    # 批量编码
+    vecs: List[List[float]] = []
+    for i in range(0, len(processed_texts), batch_size):
+        part = processed_texts[i:i+batch_size]
+        try:
+            # 使用统一嵌入器（内部处理缓存）
+            part_vecs = embedder.encode(part)
+            
+            # 标准化为List[List[float]]格式
+            if not isinstance(part_vecs, list):
+                if hasattr(part_vecs, "tolist"):
+                    part_vecs = [part_vecs.tolist()]
+                else:
+                    part_vecs = [list(part_vecs)]
+            
+            # 处理向量格式和维度
+            for v in part_vecs:
+                try:
+                    if hasattr(v, "tolist"):
+                        v = v.tolist()
+                    v_norm = [float(x) for x in v]
+                    
+                    # 维度检查和调整
+                    if len(v_norm) != dimension:
+                        print(f"[WARNING] 向量维度异常: 期望{dimension}, 实际{len(v_norm)}")
+                        if len(v_norm) < dimension:
+                            v_norm.extend([0.0] * (dimension - len(v_norm)))
+                        else:
+                            v_norm = v_norm[:dimension]
+                    
+                    vecs.append(v_norm)
+                except Exception as e:
+                    print(f"[WARNING] 向量转换失败: {e}, 使用零向量")
+                    vecs.append([0.0] * dimension)
+                    
+        except Exception as e:
+            print(f"[WARNING] Batch {i} encoding failed: {e}")
+            # 实现重试机制
+            # ... 重试逻辑 ...
+        
+        print(f"[RAG] Embedding progress: {min(i+batch_size, len(processed_texts))}/{len(processed_texts)}")
+```
+
+### 8.3.5 高级检索策略
+
+RAG系统的检索能力是其核心竞争力。在实际应用中，用户的查询表述与文档中的实际内容可能存在用词差异，导致相关文档无法被检索到。为了解决这个问题，HelloAgents实现了三种互补的高级检索策略：多查询扩展（MQE）、假设文档嵌入（HyDE）和统一的扩展检索框架。
+
+（1）多查询扩展（MQE）
+
+多查询扩展（Multi-Query Expansion）是一种通过生成语义等价的多样化查询来提高检索召回率的技术。这种方法的核心洞察是：同一个问题可以有多种不同的表述方式，而不同的表述可能匹配到不同的相关文档。例如，"如何学习Python"可以扩展为"Python入门教程"、"Python学习方法"、"Python编程指南"等多个查询。通过并行执行这些扩展查询并合并结果，系统能够覆盖更广泛的相关文档，避免因用词差异而遗漏重要信息。
+
+MQE的优势在于它能够自动理解用户查询的多种可能含义，特别是对于模糊查询或专业术语查询效果显著。系统使用LLM生成扩展查询，确保扩展的多样性和语义相关性：
+
+```python
+def _prompt_mqe(query: str, n: int) -> List[str]:
+    """使用LLM生成多样化的查询扩展"""
+    try:
+        from ...core.llm import HelloAgentsLLM
+        llm = HelloAgentsLLM()
+        prompt = [
+            {"role": "system", "content": "你是检索查询扩展助手。生成语义等价或互补的多样化查询。使用中文，简短，避免标点。"},
+            {"role": "user", "content": f"原始查询：{query}\n请给出{n}个不同表述的查询，每行一个。"}
+        ]
+        text = llm.invoke(prompt)
+        lines = [ln.strip("- \t") for ln in (text or "").splitlines()]
+        outs = [ln for ln in lines if ln]
+        return outs[:n] or [query]
+    except Exception:
+        return [query]
+```
+
+（2）假设文档嵌入（HyDE）
+
+假设文档嵌入（Hypothetical Document Embeddings，HyDE）是一种创新的检索技术，它的核心思想是"用答案找答案"。传统的检索方法是用问题去匹配文档，但问题和答案在语义空间中的分布往往存在差异——问题通常是疑问句，而文档内容是陈述句。HyDE通过让LLM先生成一个假设性的答案段落，然后用这个答案段落去检索真实文档，从而缩小了查询和文档之间的语义鸿沟。
+
+这种方法的优势在于，假设答案与真实答案在语义空间中更加接近，因此能够更准确地匹配到相关文档。即使假设答案的内容不完全正确，它所包含的关键术语、概念和表述风格也能有效引导检索系统找到正确的文档。特别是对于专业领域的查询，HyDE能够生成包含领域术语的假设文档，显著提升检索精度：
+
+```python
+def _prompt_hyde(query: str) -> Optional[str]:
+    """生成假设性文档用于改善检索"""
+    try:
+        from ...core.llm import HelloAgentsLLM
+        llm = HelloAgentsLLM()
+        prompt = [
+            {"role": "system", "content": "根据用户问题，先写一段可能的答案性段落，用于向量检索的查询文档（不要分析过程）。"},
+            {"role": "user", "content": f"问题：{query}\n请直接写一段中等长度、客观、包含关键术语的段落。"}
+        ]
+        return llm.invoke(prompt)
+    except Exception:
+        return None
+```
+
+（3）扩展检索框架
+
+HelloAgents将MQE和HyDE两种策略整合到统一的扩展检索框架中。系统通过`enable_mqe`和`enable_hyde`参数让用户可以根据具体场景选择启用哪些策略：对于需要高召回率的场景可以同时启用两种策略，对于性能敏感的场景可以只使用基础检索。
+
+扩展检索的核心机制是"扩展-检索-合并"三步流程。首先，系统根据原始查询生成多个扩展查询（包括MQE生成的多样化查询和HyDE生成的假设文档）；然后，对每个扩展查询并行执行向量检索，获取候选文档池；最后，通过去重和分数排序合并所有结果，返回最相关的top-k文档。这种设计的巧妙之处在于，它通过`candidate_pool_multiplier`参数（默认为4）扩大候选池，确保有足够的候选文档进行筛选，同时通过智能去重避免返回重复内容。
+
+```python
+def search_vectors_expanded(
+    store = None,
+    query: str = "",
+    top_k: int = 8,
+    rag_namespace: Optional[str] = None,
+    only_rag_data: bool = True,
+    score_threshold: Optional[float] = None,
+    enable_mqe: bool = False,
+    mqe_expansions: int = 2,
+    enable_hyde: bool = False,
+    candidate_pool_multiplier: int = 4,
+) -> List[Dict]:
+    """
+    Search with query expansion using unified embedding and Qdrant.
+    """
+    if not query:
+        return []
+    
+    # 创建默认存储
+    if store is None:
+        store = _create_default_vector_store()
+    
+    # 查询扩展
+    expansions: List[str] = [query]
+    
+    if enable_mqe and mqe_expansions > 0:
+        expansions.extend(_prompt_mqe(query, mqe_expansions))
+    if enable_hyde:
+        hyde_text = _prompt_hyde(query)
+        if hyde_text:
+            expansions.append(hyde_text)
+
+    # 去重和修剪
+    uniq: List[str] = []
+    for e in expansions:
+        if e and e not in uniq:
+            uniq.append(e)
+    expansions = uniq[: max(1, len(uniq))]
+
+    # 分配候选池
+    pool = max(top_k * candidate_pool_multiplier, 20)
+    per = max(1, pool // max(1, len(expansions)))
+
+    # 构建RAG数据过滤器
+    where = {"memory_type": "rag_chunk"}
+    if only_rag_data:
+        where["is_rag_data"] = True
+        where["data_source"] = "rag_pipeline"
+    if rag_namespace:
+        where["rag_namespace"] = rag_namespace
+
+    # 收集所有扩展查询的结果
+    agg: Dict[str, Dict] = {}
+    for q in expansions:
+        qv = embed_query(q)
+        hits = store.search_similar(
+            query_vector=qv, 
+            limit=per, 
+            score_threshold=score_threshold, 
+            where=where
+        )
+        for h in hits:
+            mid = h.get("metadata", {}).get("memory_id", h.get("id"))
+            s = float(h.get("score", 0.0))
+            if mid not in agg or s > float(agg[mid].get("score", 0.0)):
+                agg[mid] = h
+    
+    # 按分数排序返回
+    merged = list(agg.values())
+    merged.sort(key=lambda x: float(x.get("score", 0.0)), reverse=True)
+    return merged[:top_k]
+```
+
+实际应用中，这三种策略的组合使用效果最佳。MQE擅长处理用词多样性问题，HyDE擅长处理语义鸿沟问题，而统一框架则确保了结果的质量和多样性。对于一般查询，建议启用MQE；对于专业领域查询，建议同时启用MQE和HyDE；对于性能敏感场景，可以只使用基础检索或仅启用MQE。
+
+当然还有很多有趣的方法，这里只是为大家适当的扩展介绍，在实际的使用场景里也需要去尝试寻找适合问题的解决方案。
+
+
+
+## 8.4 构建智能文档问答助手
+
+在前面的章节中，我们详细介绍了HelloAgents的记忆系统和RAG系统的设计与实现。现在，让我们通过一个完整的实战案例，展示如何将这两个系统有机结合，构建一个智能文档问答助手。
+
+### 8.4.1 案例背景与目标
+
+在实际工作中，我们经常需要处理大量的技术文档、研究论文、产品手册等PDF文件。传统的文档阅读方式效率低下，难以快速定位关键信息，更无法建立知识间的关联。
+
+本案例将基于Datawhale另外一门动手学大模型教程Happy-LLM的公测PDF文档`Happy-LLM-0727.pdf`为例，构建一个**基于Gradio的Web应用**，展示如何使用RAGTool和MemoryTool构建完整的交互式学习助手。PDF可在这个[链接](https://github.com/datawhalechina/happy-llm/releases/download/v1.0.1/Happy-LLM-0727.pdf)获取。
+
+我们希望实现以下功能：
+
+1. **智能文档处理**：使用MarkItDown实现PDF到Markdown的统一转换，基于Markdown结构的智能分块策略，高效的向量化和索引构建
+
+2. **高级检索问答**：多查询扩展（MQE）提升召回率，假设文档嵌入（HyDE）改善检索精度，上下文感知的智能问答
+
+3. **多层次记忆管理**：工作记忆管理当前学习任务和上下文，情景记忆记录学习事件和查询历史，语义记忆存储概念知识和理解，感知记忆处理文档特征和多模态信息
+
+4. **个性化学习支持**：基于学习历史的个性化推荐，记忆整合和选择性遗忘，学习报告生成和进度追踪
+
+为了更清晰地展示整个系统的工作流程，图8.6展示了五个步骤之间的关系和数据流动。五个步骤形成了一个完整的闭环：步骤1将PDF文档处理后的信息记录到记忆系统，步骤2的检索结果也会记录到记忆系统，步骤3展示记忆系统的完整功能（添加、检索、整合、遗忘），步骤4整合RAG和Memory提供智能路由，步骤5收集所有统计信息生成学习报告。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-6.png" alt="" width="85%"/>
+  <p>图 8.6 智能问答助手的五步执行流程</p>
+</div>
+
+接下来，我们将展示如何实现这个Web应用。整个应用分为三个核心部分：
+
+1. **核心助手类（PDFLearningAssistant）**：封装RAGTool和MemoryTool的调用逻辑
+2. **Gradio Web界面**：提供友好的用户交互界面，这个部分可以参考示例代码学习
+3. **其他核心功能**：笔记记录、学习回顾、统计查看和报告生成
+
+### 8.4.2 核心助手类的实现
+
+首先，我们实现核心的助手类`PDFLearningAssistant`，它封装了RAGTool和MemoryTool的调用逻辑。
+
+（1）类的初始化
+
+```python
+class PDFLearningAssistant:
+    """智能文档问答助手"""
+
+    def __init__(self, user_id: str = "default_user"):
+        """初始化学习助手
+
+        Args:
+            user_id: 用户ID，用于隔离不同用户的数据
+        """
+        self.user_id = user_id
+        self.session_id = f"session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+        # 初始化工具
+        self.memory_tool = MemoryTool(user_id=user_id)
+        self.rag_tool = RAGTool(rag_namespace=f"pdf_{user_id}")
+
+        # 学习统计
+        self.stats = {
+            "session_start": datetime.now(),
+            "documents_loaded": 0,
+            "questions_asked": 0,
+            "concepts_learned": 0
+        }
+
+        # 当前加载的文档
+        self.current_document = None
+```
+
+在这个初始化过程中，我们做了几个关键的设计决策：
+
+**MemoryTool的初始化**：通过`user_id`参数实现用户级别的记忆隔离。不同用户的学习记忆是完全独立的，每个用户都有自己的工作记忆、情景记忆、语义记忆和感知记忆空间。
+
+**RAGTool的初始化**：通过`rag_namespace`参数实现知识库的命名空间隔离。使用`f"pdf_{user_id}"`作为命名空间，每个用户都有自己独立的PDF知识库。
+
+**会话管理**：`session_id`用于追踪单次学习会话的完整过程，便于后续的学习历程回顾和分析。
+
+**统计信息**：`stats`字典记录关键的学习指标，用于生成学习报告。
+
+（2）加载PDF文档
+
+```python
+def load_document(self, pdf_path: str) -> Dict[str, Any]:
+    """加载PDF文档到知识库
+
+    Args:
+        pdf_path: PDF文件路径
+
+    Returns:
+        Dict: 包含success和message的结果
+    """
+    if not os.path.exists(pdf_path):
+        return {"success": False, "message": f"文件不存在: {pdf_path}"}
+
+    start_time = time.time()
+
+    # 【RAGTool】处理PDF: MarkItDown转换 → 智能分块 → 向量化
+    result = self.rag_tool.execute(
+        "add_document",
+        file_path=pdf_path,
+        chunk_size=1000,
+        chunk_overlap=200
+    )
+
+    process_time = time.time() - start_time
+
+    if result.get("success", False):
+        self.current_document = os.path.basename(pdf_path)
+        self.stats["documents_loaded"] += 1
+
+        # 【MemoryTool】记录到学习记忆
+        self.memory_tool.execute(
+            "add",
+            content=f"加载了文档《{self.current_document}》",
+            memory_type="episodic",
+            importance=0.9,
+            event_type="document_loaded",
+            session_id=self.session_id
+        )
+
+        return {
+            "success": True,
+            "message": f"加载成功！(耗时: {process_time:.1f}秒)",
+            "document": self.current_document
+        }
+    else:
+        return {
+            "success": False,
+            "message": f"加载失败: {result.get('error', '未知错误')}"
+        }
+```
+
+我们通过一行代码就能完成PDF的处理：
+
+```python
+result = self.rag_tool.execute(
+    "add_document",
+    file_path=pdf_path,
+    chunk_size=1000,
+    chunk_overlap=200
+)
+```
+
+这个调用会触发RAGTool的完整处理流程（MarkItDown转换、增强处理、智能分块、向量化存储），这些内部细节在8.3节已经详细介绍过。我们只需要关注：
+
+- **操作类型**：`"add_document"` - 添加文档到知识库
+- **文件路径**：`file_path` - PDF文件的路径
+- **分块参数**：`chunk_size=1000, chunk_overlap=200` - 控制文本分块
+- **返回结果**：包含处理状态和统计信息的字典
+
+文档加载成功后，我们使用MemoryTool记录到情景记忆：
+
+```python
+self.memory_tool.execute(
+    "add",
+    content=f"加载了文档《{self.current_document}》",
+    memory_type="episodic",
+    importance=0.9,
+    event_type="document_loaded",
+    session_id=self.session_id
+)
+```
+
+**为什么用情景记忆？** 因为这是一个具体的、有时间戳的事件，适合用情景记忆记录。`session_id`参数将这个事件关联到当前学习会话，便于后续回顾学习历程。
+
+这个记忆记录为后续的个性化服务奠定了基础：
+
+- 用户询问"我之前加载过哪些文档？" → 从情景记忆中检索
+- 系统可以追踪用户的学习历程和文档使用情况
+
+### 8.4.3 智能问答功能
+
+文档加载完成后，用户就可以向文档提问了。我们实现一个`ask`方法来处理用户的问题：
+
+```python
+def ask(self, question: str, use_advanced_search: bool = True) -> str:
+    """向文档提问
+
+    Args:
+        question: 用户问题
+        use_advanced_search: 是否使用高级检索（MQE + HyDE）
+
+    Returns:
+        str: 答案
+    """
+    if not self.current_document:
+        return "⚠️ 请先加载文档！"
+
+    # 【MemoryTool】记录问题到工作记忆
+    self.memory_tool.execute(
+        "add",
+        content=f"提问: {question}",
+        memory_type="working",
+        importance=0.6,
+        session_id=self.session_id
+    )
+
+    # 【RAGTool】使用高级检索获取答案
+    answer = self.rag_tool.execute(
+        "ask",
+        question=question,
+        limit=5,
+        enable_advanced_search=use_advanced_search,
+        enable_mqe=use_advanced_search,
+        enable_hyde=use_advanced_search
+    )
+
+    # 【MemoryTool】记录到情景记忆
+    self.memory_tool.execute(
+        "add",
+        content=f"关于'{question}'的学习",
+        memory_type="episodic",
+        importance=0.7,
+        event_type="qa_interaction",
+        session_id=self.session_id
+    )
+
+    self.stats["questions_asked"] += 1
+
+    return answer
+```
+
+当我们调用`self.rag_tool.execute("ask", ...)`时，RAGTool内部执行了以下高级检索流程：
+
+1. **多查询扩展（MQE）**：
+
+   ```python
+   # 生成多样化查询
+   expanded_queries = self._generate_multi_queries(question)
+   # 例如，对于"什么是大语言模型？"，可能生成：
+   # - "大语言模型的定义是什么？"
+   # - "请解释一下大语言模型"
+   # - "LLM是什么意思？"
+   ```
+
+   MQE通过LLM生成语义等价但表述不同的查询，从多个角度理解用户意图，提升召回率30%-50%。
+
+2. **假设文档嵌入（HyDE）**：
+
+   - 生成假设答案文档，桥接查询和文档的语义鸿沟
+   - 使用假设答案的向量进行检索
+
+这些高级检索技术的内部实现在8.3.5节已经详细介绍过。
+
+### 8.4.4 其他核心功能
+
+除了加载文档和智能问答，我们还需要实现笔记记录、学习回顾、统计查看和报告生成等功能：
+
+```python
+def add_note(self, content: str, concept: Optional[str] = None):
+    """添加学习笔记"""
+    self.memory_tool.execute(
+        "add",
+        content=content,
+        memory_type="semantic",
+        importance=0.8,
+        concept=concept or "general",
+        session_id=self.session_id
+    )
+    self.stats["concepts_learned"] += 1
+
+def recall(self, query: str, limit: int = 5) -> str:
+    """回顾学习历程"""
+    result = self.memory_tool.execute(
+        "search",
+        query=query,
+        limit=limit
+    )
+    return result
+
+def get_stats(self) -> Dict[str, Any]:
+    """获取学习统计"""
+    duration = (datetime.now() - self.stats["session_start"]).total_seconds()
+    return {
+        "会话时长": f"{duration:.0f}秒",
+        "加载文档": self.stats["documents_loaded"],
+        "提问次数": self.stats["questions_asked"],
+        "学习笔记": self.stats["concepts_learned"],
+        "当前文档": self.current_document or "未加载"
+    }
+
+def generate_report(self, save_to_file: bool = True) -> Dict[str, Any]:
+    """生成学习报告"""
+    memory_summary = self.memory_tool.execute("summary", limit=10)
+    rag_stats = self.rag_tool.execute("stats")
+
+    duration = (datetime.now() - self.stats["session_start"]).total_seconds()
+    report = {
+        "session_info": {
+            "session_id": self.session_id,
+            "user_id": self.user_id,
+            "start_time": self.stats["session_start"].isoformat(),
+            "duration_seconds": duration
+        },
+        "learning_metrics": {
+            "documents_loaded": self.stats["documents_loaded"],
+            "questions_asked": self.stats["questions_asked"],
+            "concepts_learned": self.stats["concepts_learned"]
+        },
+        "memory_summary": memory_summary,
+        "rag_status": rag_stats
+    }
+
+    if save_to_file:
+        report_file = f"learning_report_{self.session_id}.json"
+        with open(report_file, 'w', encoding='utf-8') as f:
+            json.dump(report, f, ensure_ascii=False, indent=2, default=str)
+        report["report_file"] = report_file
+
+    return report
+```
+
+这些方法分别实现了：
+
+- **add_note**：将学习笔记保存到语义记忆
+- **recall**：从记忆系统中检索学习历程
+- **get_stats**：获取当前会话的统计信息
+- **generate_report**：生成详细的学习报告并保存为JSON文件
+
+### 8.4.5 运行效果展示
+
+接下来是运行效果展示，如图8.7所示，进入主页面后需要先初始化助手，也就是加载我们的数据库，模型，API之类的载入操作。后传入PDF文档，并点击加载文档。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-7.png" alt="" width="85%"/>
+  <p>图 8.7 问答助手主页面</p>
+</div>
+
+第一个功能是智能问答，将可以基于上传的文档进行检索，并返回参考来源和相关资料的相似度计算，这是RAG tool能力的体现，如图8.8所示。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-8.png" alt="" width="85%"/>
+  <p>图 8.8 问答助手主页面</p>
+</div>
+
+第二个功能是学习笔记，如图8.9所示，可以对于相关概念进行勾选，以及撰写笔记内容，这一部分运用到Memory tool，将会存放你的个人笔记在数据库内，方便统计和后续返回整体的学习报告。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-9.png" alt="" width="85%"/>
+  <p>图 8.9 问答助手主页面</p>
+</div>
+
+最后是学习进度的统计和报告的生成，如图8.10所示，我们将可以看到使用助手期间加载的文档数量，提问次数，和笔记数量，最终将我们的问答结果和笔记整理为一个JSON文档返回。
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-10.png" alt="" width="85%"/>
+  <p>图 8.10 问答助手主页面</p>
+</div>
+
+通过这个问答助手的案例，我们展示了如何使用RAGTool和MemoryTool构建一个完整的**基于Web的智能文档问答系统**。完整的代码可以在`code/chapter8/11_Q&A_Assistant.py`中找到。启动后访问 `http://localhost:7860` 即可使用这个智能学习助手。
+
+建议读者亲自运行这个案例，体验RAG和Memory的能力，并在此基础上进行扩展和定制，构建符合自己需求的智能应用！
+
+## 8.5 本章总结与展望
+
+在本章中，我们成功地为HelloAgents框架增加了两个核心能力：记忆系统和RAG系统。
+
+对于希望深入学习和应用本章内容的读者，我们提供以下建议：
+
+1. 从零到一，亲手设计一个基础记忆模块，并逐步迭代，为其增添更复杂的特性。
+
+2. 在项目中尝试并评估不同的嵌入模型与检索策略，寻找特定任务下的最优解。
+
+3. 将所学的记忆与 RAG 系统应用于一个真实的个人项目，在实战中检验和提升能力。
+
+进阶探索
+
+1. 跟踪并研究前沿memory，rag仓库，学习优秀实现。
+2. 探索将 RAG 架构应用于多模态（文本+图像）或跨模态场景的可能性。
+3. 参与HelloAgents开源项目，贡献自己的想法和代码
+
+通过本章的学习，您不仅掌握了Memory和RAG系统的实现技术，更重要的是理解了如何将认知科学理论转化为实际的工程解决方案。这种跨学科的思维方式，将为您在AI领域的进一步发展奠定坚实的基础。
+
+最后，让我们通过一个思维导图来总结本章的完整知识体系，如图8.11所示：
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/datawhalechina/Hello-Agents/main/docs/images/8-figures/8-10.png" alt="" width="85%"/>
+  <p>图 8.11 Hello-agents第八章知识总结</p>
+</div>
+
+本章展示了HelloAgents框架记忆系统和RAG技术的能力，我们成功构建了一个具有真正"智能"的学习助手。这种架构可以轻松扩展到其他应用场景，如客户服务、技术支持、个人助理等领域。
+
+在下一章中，我们将继续探索如何通过上下文工程进一步提升智能体的对话质量和用户体验，敬请期待！
+
+
+
+## 参考文献
+
+[1] Atkinson, R. C., & Shiffrin, R. M. (1968). Human memory: A proposed system and its control processes. In *Psychology of learning and motivation* (Vol. 2, pp. 89-195). Academic press.