尧图网页设计 
赛博小镇NPC记忆系统实战基于HelloAgents MemoryManager的双层记忆架构解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents在《从零开始构建智能体》第15章的赛博小镇Helloagents-AI-Town项目中NPC不仅会对话更拥有了记忆——能够记住与玩家的对话历史并在后续交流中自然引用。本文以 MEMORY_SYSTEM_GUIDE.md 为核心指南结合 agents.py、main.py 等源码实现完整讲解工作记忆与情景记忆的双层架构、MemoryConfig 参数调优、记忆检索与增强提示词构建、API 调试方法帮助读者掌握 HelloAgents Memory 系统在多智能体场景中的实战用法。一、记忆系统要解决什么问题没有记忆的 NPC 每次对话都是第一次见面无论玩家说过什么NPC 都会重新介绍自己对话体验生硬且割裂。赛博小镇的记忆系统让 NPC 具备两类人类式记忆能力工作记忆Working Memory短期记忆存储最近 10 条对话2 小时后自动过期用于支撑当前对话的上下文连贯性检索速度极快。情景记忆Episodic Memory长期记忆将重要对话持久化落盘支持语义检索最多存储 100 条记忆并会自动遗忘重要性低于 0.3 的记忆。同时系统实现了严格的记忆隔离每个 NPC 拥有独立记忆系统对应独立的存储目录与 user_idNPC 之间互不干扰不同玩家的对话也独立存储。从源码结构看这套记忆系统建立在 HelloAgents 框架的MemoryManager之上赛博小镇在 agents.py 中维护了self.memories: Dict[str, MemoryManager]为张三Python工程师、李四产品经理、王五UI设计师三个 NPC 各创建一个记忆管理器实例。第8章《记忆与检索》文档也印证了 HelloAgents Memory System 的四层架构基础设施层MemoryManager/MemoryItem/MemoryConfig、记忆类型层工作/情景/语义/感知记忆、存储后端层Qdrant 向量存储、Neo4j 图存储、SQLite 文档存储与 Embedding 服务层。二、系统架构NPCAgentManager 与记忆管理器的协作2.1 总体架构NPCAgentManager ├── agents: Dict[str, SimpleAgent] # NPC Agent ├── memories: Dict[str, MemoryManager] # NPC记忆管理器 └── chat(npc_name, message, player_id) # 对话接口 ├── 1. 检索相关记忆 ├── 2. 构建增强提示词 ├── 3. 调用Agent生成回复 └── 4. 保存对话到记忆NPCAgentManager是 NPC 系统的统一入口agents.py。初始化时它会为每个 NPC 创建两样东西SimpleAgent基于HelloAgentsLLM与create_system_prompt(name, role)生成的角色化系统提示词包含职位、性格、专长、说话风格、爱好、行为准则等MemoryManager通过_create_memory_manager(npc_name)为 NPC 单独初始化记忆系统。若 LLM 初始化失败例如未配置 API Key系统会降级为模拟模式运行此时 NPC 仅返回预设文案记忆系统功能保留但不产生真实 LLM 对话。2.2 记忆系统的初始化细节_create_memory_manager是理解整个记忆系统的钥匙agents.py其核心逻辑如下def _create_memory_manager(self, npc_name: str) - MemoryManager: # 创建记忆存储目录 memory_dir os.path.join(os.path.dirname(__file__), memory_data, npc_name) os.makedirs(memory_dir, exist_okTrue) # 配置记忆系统 memory_config MemoryConfig( storage_pathmemory_dir, working_memory_capacity10, # 最近10条对话 working_memory_tokens2000, # 最多2000个token max_capacity100, # 最多100条长期记忆 importance_threshold0.3, # 检索和整合时关注重要性较高的记忆 decay_factor0.95 # 时间衰减系数 ) # 创建记忆管理器 memory_manager MemoryManager( configmemory_config, user_idnpc_name, # 使用NPC名字作为user_id enable_workingTrue, # 启用工作记忆 (短期) enable_episodicTrue, # 启用情景记忆 (长期) enable_semanticFalse, # 不需要语义记忆 enable_perceptualFalse # 不需要感知记忆 ) return memory_manager关键设计点user_idnpc_name是记忆隔离的第一道屏障——每个 NPC 以自身名字作为独立命名空间检索与存储都限定在自己的空间内从源头杜绝跨 NPC 记忆串扰赛博小镇场景只启用working与episodic两类记忆semantic语义记忆/知识图谱与perceptual感知记忆/多模态保持关闭这正好对应第8章文档中 MemoryManager 按需装配四类记忆子模块的设计enable_working/enable_episodic/enable_semantic/enable_perceptual四个开关决定self.memory_types字典的装配内容存储路径统一收敛在backend/memory_data/{npc_name}目录下。三、对话全流程记忆如何参与每一次交流chat()方法agents.py完整展示了检索记忆 → 构建上下文 → 生成回复 → 保存记忆的闭环1. 获取当前好感度relationship_manager好感度上下文拼入提示词 2. 检索相关记忆: retrieve_memories(querymessage, memory_types[working, episodic], limit5, min_importance0.3) 3. 构建增强提示词好感度上下文 记忆上下文 当前对话 4. 调用 agent.run(enhanced_message) 生成回复 5. 分析并更新好感度 6. 保存玩家消息与NPC回复到记忆3.1 记忆检索策略relevant_memories memory_manager.retrieve_memories( querymessage, memory_types[working, episodic], limit5, min_importance0.3 # 只检索重要性0.3的记忆 )双类型混合检索同时检索工作记忆与情景记忆兼顾近期对话与重要历史min_importance0.3与MemoryConfig.importance_threshold保持一致低重要性记忆不进入上下文保证提示词质量limit5限制注入提示词的记忆条数防止上下文爆炸。3.2 记忆上下文构建_build_memory_context()agents.py将检索到的记忆格式化为带时间戳的文本块context_parts [【之前的对话记忆】] for memory in memories: time_str memory.timestamp.strftime(%H:%M) context_parts.append(f[{time_str}] {memory.content})最终拼接进 LLM 提示词的完整结构为【当前关系】 你与玩家的关系: 熟悉 (好感度: 50/100) 【对话风格】礼貌友善,正常交流,保持专业 【之前的对话记忆】 [10:30] 玩家说: 你好,你是做什么的? [10:31] 我说: 你好!我是Python工程师,主要负责多智能体系统开发。 【当前对话】 玩家: 还记得我刚才问你什么吗?这正是文档示例中第二次对话能引用第一次内容的实现原理工作记忆中的近期对话被检索并注入提示词LLM 据此生成连贯回复。3.3 记忆写入玩家与NPC双轨存储_save_conversation_to_memory()agents.py将一轮对话拆成两条记忆分别写入记忆内容memory_typeimportance说明玩家说: {player_message}working0.5中等玩家发言附带 speaker/player_id/session_id我说: {npc_response}working0.6稍高NPC回复importance 略高便于长期保留两条记忆的 metadata 中还会记录当时的affinity好感度、affinity_change好感度变化与sentiment情感倾向让记忆不只是对话文本还保留了关系演进的时序信息为后续好感度系统提供数据基础。这与文档中的记忆数据格式一一对应{ id: memory_uuid, content: 玩家说: 你好,你是做什么的?, type: working, # working/episodic importance: 0.5, # 0-1之间 timestamp: 2024-01-15T10:30:00, metadata: { speaker: player, player_id: player, session_id: player, context: { interaction_type: dialogue, npc_name: 张三 } } }3.4 从工作记忆到情景记忆遗忘与整合机制工作记忆是纯内存存储TTL 2 小时自动过期、容量 10 条重启即失情景记忆则由 SQLite 持久化落盘。两者之间通过重要性衔接当工作记忆中的对话重要性达到阈值时会被整合进长期记忆第8章文档中_consolidate(from_typeworking, to_typeepisodic, importance_threshold...)即描述这一过程。NPC回复的 importance 设为 0.6、玩家消息设为 0.5均高于遗忘线 0.3可被保留并进入后续整合判断。四、记忆系统配置MemoryConfig 参数详解4.1 完整配置示例源码原样memory_config MemoryConfig( storage_pathf./memory_data/{npc_name}, # 存储路径 working_memory_capacity10, # 工作记忆容量 working_memory_tokens2000, # 工作记忆token限制 max_capacity100, # 记忆总容量 importance_threshold0.3, # 重要性阈值 decay_factor0.95 # 时间衰减系数 )4.2 参数调整建议参数默认值建议范围说明working_memory_capacity105-20工作记忆容量越大越占内存working_memory_tokens20001000-4000Token限制影响上下文长度max_capacity10050-500记忆总容量越大越占磁盘importance_threshold0.30.1-0.5重要性阈值越高越偏向保留重要记忆decay_factor0.950.8-0.99时间衰减系数越低越强调近期记忆4.3 参数背后的机制解读decay_factor时间衰减第8章文档展示了其底层公式recency_score math.exp(-decay_factor * age_hours / 24)记忆越久远相关性得分越低。调低decay_factor会加快旧记忆衰减让 NPC 更健忘、更关注近期调高则让旧记忆在检索中保持权重。importance_threshold重要性过滤同时影响两条路径——检索时的min_importance过滤以及记忆整合时是否值得写入长期记忆的判断。调高它会过滤掉更多低价值记忆减少存储占用但可能丢失细节。working_memory_tokensToken 预算直接决定注入提示词的记忆文本长度上限与limit5的检索条数共同构成上下文长度约束防止超出模型上下文窗口。五、存储结构SQLite 与向量检索的双层持久化5.1 目录结构按文档设计与仓库实际文件backend/memory_data/下已存在张三、李四、王五三个子目录每个 NPC 的存储布局为backend/memory_data/ ├── 张三/ │ └── memory.db # SQLite数据库 (权威持久化存储) ├── 李四/ │ └── memory.db └── 王五/ └── memory.db注指南文档中以sqlite_store.db命名示例仓库实际运行生成的持久化文件名为memory.db二者指向同一存储目录实际以仓库生成的memory.db为准。5.2 双存储机制SQLite权威存储情景记忆的结构化落盘载体保证重启后长期记忆不丢失支持按条件查询与容量管理向量索引语义检索配合 Embedding 服务为记忆建立向量索引实现基于语义相似度的相关性检索。第8章文档明确情景记忆的存储方案为 SQLite QdrantQdrant 向量存储提供高性能语义检索能力双存储一致性写入时以 SQLite 为准向量索引服务语义查询二者协同支撑按时间检索与按相关性检索两种模式。六、API 接口记忆能力的完整调试入口后端基于 FastAPI 实现main.py记忆相关接口如下。6.1 对话接口自动触发记忆读写POST /chat Content-Type: application/json { npc_name: 张三, message: 你好,你是做什么的? }响应{ npc_name: 张三, npc_title: Python工程师, message: 你好!我是Python工程师,主要负责多智能体系统开发。, success: true }每次调用/chat都会走完第三节描述的完整记忆闭环检索 → 增强 → 生成 → 保存。6.2 获取NPC记忆GET /npcs/张三/memories?limit10响应{ npc_name: 张三, memories: [ { id: uuid-1, content: 玩家说: 你好,你是做什么的?, type: working, importance: 0.5, timestamp: 2024-01-15T10:30:00, metadata: {...} } ], total: 10 }该接口对应get_npc_memories()agents.py以空查询调用retrieve_memories返回全部记忆并转为字典列表输出。limit参数控制返回条数默认 10。6.3 清空NPC记忆测试用DELETE /npcs/张三/memories?memory_typeworking响应{ message: 已清空张三的记忆, npc_name: 张三, memory_type: working }memory_type可选working/episodic不传则清空全部。底层调用clear_npc_memory()agents.py遍历[working, episodic]执行clear_memory_type便于测试前重置状态。6.4 关联接口GET /npcs/{npc_name}/affinity获取 NPC 对玩家的好感度记忆与好感度联动AFFINITY_SYSTEM_GUIDE.md 有完整讲解GET /返回服务信息features字段明确列出NPC记忆系统能力完整接口文档可在服务启动后访问http://localhost:8000/docsSwagger UI。七、测试方法三种验证路径方法1测试脚本cd backend python test_memory.py覆盖用例基本对话记忆、长期记忆检索、记忆隔离、相关性检索。方法2API 手动测试cd backend python main.py访问 API 文档http://localhost:8000/docs测试对话接口先发你好,你是做什么的?再发还记得我刚才问你什么吗?观察 NPC 是否能引用第一轮内容查看记忆列表GET /npcs/张三/memories确认记忆条目已落盘。服务默认监听0.0.0.0:8000config.pyLLM 通过环境变量配置LLM_MODEL_ID默认Qwen/Qwen2.5-72B-Instruct、LLM_API_KEY、LLM_BASE_URL默认 ModelScope 推理服务地址可在backend/.env中配置。方法3Godot 客户端联测启动后端服务运行 Godot 游戏项目helloagents-ai-town目录Godot 场景与脚本位于 scenes 与 scripts其中 api_client.gd 封装了对后端的 HTTP 调用与 NPC 多次对话观察 NPC 是否能记住之前的对话内容。八、调试技巧1. 查看记忆检索日志在chat()方法中已内置日志埋点配合 logger.py 的log_memory_retrieval/log_memory_savedprint(f {npc_name}检索到{len(relevant_memories)}条相关记忆) print(f 对话已保存到{npc_name}的记忆中)2. 直接检查 SQLite 数据库cd backend/memory_data/张三 sqlite3 memory.db SELECT * FROM memories;3. 清空记忆重新测试# 方式一调用API DELETE /npcs/张三/memories # 方式二直接删除NPC的记忆目录后重启服务 # 仓库为只读实际操作时在本地副本中进行九、常见问题排查Q1: NPC 为什么记不住对话?可能原因记忆系统未正确初始化检查日志是否有记忆系统已初始化输出存储路径权限问题检查memory_data目录是否存在且可写记忆被遗忘机制清除工作记忆 2 小时 TTL 过期或重要性低于阈值被淘汰。解决方法检查日志中是否出现记忆系统已初始化检查memory_data目录是否存在降低importance_threshold参数让更多记忆通过重要性过滤。Q2: 记忆检索不准确?可能原因查询语句与记忆内容的语义相似度低记忆重要性太低被min_importance0.3过滤。解决方法降低min_importance参数增加检索limit数量如从 5 提升到 10使用更具体、更贴近记忆原文的查询语句。Q3: 记忆占用空间太大?解决方法降低max_capacity提高importance_threshold让低价值记忆尽早淘汰定期通过DELETE /npcs/{npc_name}/memories清理旧记忆。十、教学价值与后续演进10.1 学习要点MemoryManager 的使用初始化、按需配置记忆类型working/episodic/semantic/perceptual、添加与检索记忆记忆检索策略工作记忆的快速近期检索、情景记忆的语义相关检索、以及时间 相关性的混合检索记忆存储机制SQLite 权威存储 向量索引语义检索的双存储方案以及一致性保证记忆遗忘机制基于重要性的自动遗忘importance_threshold、基于时间的 TTL 过期工作记忆 2 小时、容量限制的优先级淘汰max_capacity。10.2 与后续系统的衔接记忆系统是赛博小镇 NPC 智能化的地基指南文档已预告并实际落地了三个延伸模块好感度系统NPC 与玩家的关系管理详见 AFFINITY_SYSTEM_GUIDE.md记忆 metadata 中的affinity字段即为两系统的衔接点情感分析使用 LLM 分析对话情感sentiment字段随记忆一同持久化关系等级陌生、熟悉、友好、亲密、挚友五级关系驱动 NPC 对话风格随关系动态变化chat()中的affinity_context即按等级注入不同对话风格提示词。10.3 总结赛博小镇的 NPC 记忆系统已成功集成短期记忆工作记忆 长期记忆情景记忆 语义检索 记忆隔离 自动遗忘五大能力齐备。从架构上看它完整示范了 HelloAgents Memory 系统的实战用法——多智能体按user_id隔离记忆、双存储保证可靠性与检索性能、重要性驱动的遗忘机制控制存储成本。对学习者而言这套系统是理解 Agent 记忆管理、向量数据库落地与记忆检索策略的最佳实战范本相关完整配置与运行细节可继续参考 backend/README.md、SETUP_GUIDE.md 与第8章《记忆与检索》文档Chapter8-Memory-and-Retrieval.md。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 赛博小镇NPC记忆系统实战：基于HelloAgents MemoryManager的双层记忆架构解析
赛博小镇NPC记忆系统实战基于HelloAgents MemoryManager的双层记忆架构解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents在《从零开始构建智能体》第15章的赛博小镇Helloagents-AI-Town项目中NPC不仅会对话更拥有了记忆——能够记住与玩家的对话历史并在后续交流中自然引用。本文以 MEMORY_SYSTEM_GUIDE.md 为核心指南结合 agents.py、main.py 等源码实现完整讲解工作记忆与情景记忆的双层架构、MemoryConfig 参数调优、记忆检索与增强提示词构建、API 调试方法帮助读者掌握 HelloAgents Memory 系统在多智能体场景中的实战用法。一、记忆系统要解决什么问题没有记忆的 NPC 每次对话都是第一次见面无论玩家说过什么NPC 都会重新介绍自己对话体验生硬且割裂。赛博小镇的记忆系统让 NPC 具备两类人类式记忆能力工作记忆Working Memory短期记忆存储最近 10 条对话2 小时后自动过期用于支撑当前对话的上下文连贯性检索速度极快。情景记忆Episodic Memory长期记忆将重要对话持久化落盘支持语义检索最多存储 100 条记忆并会自动遗忘重要性低于 0.3 的记忆。同时系统实现了严格的记忆隔离每个 NPC 拥有独立记忆系统对应独立的存储目录与 user_idNPC 之间互不干扰不同玩家的对话也独立存储。从源码结构看这套记忆系统建立在 HelloAgents 框架的MemoryManager之上赛博小镇在 agents.py 中维护了self.memories: Dict[str, MemoryManager]为张三Python工程师、李四产品经理、王五UI设计师三个 NPC 各创建一个记忆管理器实例。第8章《记忆与检索》文档也印证了 HelloAgents Memory System 的四层架构基础设施层MemoryManager/MemoryItem/MemoryConfig、记忆类型层工作/情景/语义/感知记忆、存储后端层Qdrant 向量存储、Neo4j 图存储、SQLite 文档存储与 Embedding 服务层。二、系统架构NPCAgentManager 与记忆管理器的协作2.1 总体架构NPCAgentManager ├── agents: Dict[str, SimpleAgent] # NPC Agent ├── memories: Dict[str, MemoryManager] # NPC记忆管理器 └── chat(npc_name, message, player_id) # 对话接口 ├── 1. 检索相关记忆 ├── 2. 构建增强提示词 ├── 3. 调用Agent生成回复 └── 4. 保存对话到记忆NPCAgentManager是 NPC 系统的统一入口agents.py。初始化时它会为每个 NPC 创建两样东西SimpleAgent基于HelloAgentsLLM与create_system_prompt(name, role)生成的角色化系统提示词包含职位、性格、专长、说话风格、爱好、行为准则等MemoryManager通过_create_memory_manager(npc_name)为 NPC 单独初始化记忆系统。若 LLM 初始化失败例如未配置 API Key系统会降级为模拟模式运行此时 NPC 仅返回预设文案记忆系统功能保留但不产生真实 LLM 对话。2.2 记忆系统的初始化细节_create_memory_manager是理解整个记忆系统的钥匙agents.py其核心逻辑如下def _create_memory_manager(self, npc_name: str) - MemoryManager: # 创建记忆存储目录 memory_dir os.path.join(os.path.dirname(__file__), memory_data, npc_name) os.makedirs(memory_dir, exist_okTrue) # 配置记忆系统 memory_config MemoryConfig( storage_pathmemory_dir, working_memory_capacity10, # 最近10条对话 working_memory_tokens2000, # 最多2000个token max_capacity100, # 最多100条长期记忆 importance_threshold0.3, # 检索和整合时关注重要性较高的记忆 decay_factor0.95 # 时间衰减系数 ) # 创建记忆管理器 memory_manager MemoryManager( configmemory_config, user_idnpc_name, # 使用NPC名字作为user_id enable_workingTrue, # 启用工作记忆 (短期) enable_episodicTrue, # 启用情景记忆 (长期) enable_semanticFalse, # 不需要语义记忆 enable_perceptualFalse # 不需要感知记忆 ) return memory_manager关键设计点user_idnpc_name是记忆隔离的第一道屏障——每个 NPC 以自身名字作为独立命名空间检索与存储都限定在自己的空间内从源头杜绝跨 NPC 记忆串扰赛博小镇场景只启用working与episodic两类记忆semantic语义记忆/知识图谱与perceptual感知记忆/多模态保持关闭这正好对应第8章文档中 MemoryManager 按需装配四类记忆子模块的设计enable_working/enable_episodic/enable_semantic/enable_perceptual四个开关决定self.memory_types字典的装配内容存储路径统一收敛在backend/memory_data/{npc_name}目录下。三、对话全流程记忆如何参与每一次交流chat()方法agents.py完整展示了检索记忆 → 构建上下文 → 生成回复 → 保存记忆的闭环1. 获取当前好感度relationship_manager好感度上下文拼入提示词 2. 检索相关记忆: retrieve_memories(querymessage, memory_types[working, episodic], limit5, min_importance0.3) 3. 构建增强提示词好感度上下文 记忆上下文 当前对话 4. 调用 agent.run(enhanced_message) 生成回复 5. 分析并更新好感度 6. 保存玩家消息与NPC回复到记忆3.1 记忆检索策略relevant_memories memory_manager.retrieve_memories( querymessage, memory_types[working, episodic], limit5, min_importance0.3 # 只检索重要性0.3的记忆 )双类型混合检索同时检索工作记忆与情景记忆兼顾近期对话与重要历史min_importance0.3与MemoryConfig.importance_threshold保持一致低重要性记忆不进入上下文保证提示词质量limit5限制注入提示词的记忆条数防止上下文爆炸。3.2 记忆上下文构建_build_memory_context()agents.py将检索到的记忆格式化为带时间戳的文本块context_parts [【之前的对话记忆】] for memory in memories: time_str memory.timestamp.strftime(%H:%M) context_parts.append(f[{time_str}] {memory.content})最终拼接进 LLM 提示词的完整结构为【当前关系】 你与玩家的关系: 熟悉 (好感度: 50/100) 【对话风格】礼貌友善,正常交流,保持专业 【之前的对话记忆】 [10:30] 玩家说: 你好,你是做什么的? [10:31] 我说: 你好!我是Python工程师,主要负责多智能体系统开发。 【当前对话】 玩家: 还记得我刚才问你什么吗?这正是文档示例中第二次对话能引用第一次内容的实现原理工作记忆中的近期对话被检索并注入提示词LLM 据此生成连贯回复。3.3 记忆写入玩家与NPC双轨存储_save_conversation_to_memory()agents.py将一轮对话拆成两条记忆分别写入记忆内容memory_typeimportance说明玩家说: {player_message}working0.5中等玩家发言附带 speaker/player_id/session_id我说: {npc_response}working0.6稍高NPC回复importance 略高便于长期保留两条记忆的 metadata 中还会记录当时的affinity好感度、affinity_change好感度变化与sentiment情感倾向让记忆不只是对话文本还保留了关系演进的时序信息为后续好感度系统提供数据基础。这与文档中的记忆数据格式一一对应{ id: memory_uuid, content: 玩家说: 你好,你是做什么的?, type: working, # working/episodic importance: 0.5, # 0-1之间 timestamp: 2024-01-15T10:30:00, metadata: { speaker: player, player_id: player, session_id: player, context: { interaction_type: dialogue, npc_name: 张三 } } }3.4 从工作记忆到情景记忆遗忘与整合机制工作记忆是纯内存存储TTL 2 小时自动过期、容量 10 条重启即失情景记忆则由 SQLite 持久化落盘。两者之间通过重要性衔接当工作记忆中的对话重要性达到阈值时会被整合进长期记忆第8章文档中_consolidate(from_typeworking, to_typeepisodic, importance_threshold...)即描述这一过程。NPC回复的 importance 设为 0.6、玩家消息设为 0.5均高于遗忘线 0.3可被保留并进入后续整合判断。四、记忆系统配置MemoryConfig 参数详解4.1 完整配置示例源码原样memory_config MemoryConfig( storage_pathf./memory_data/{npc_name}, # 存储路径 working_memory_capacity10, # 工作记忆容量 working_memory_tokens2000, # 工作记忆token限制 max_capacity100, # 记忆总容量 importance_threshold0.3, # 重要性阈值 decay_factor0.95 # 时间衰减系数 )4.2 参数调整建议参数默认值建议范围说明working_memory_capacity105-20工作记忆容量越大越占内存working_memory_tokens20001000-4000Token限制影响上下文长度max_capacity10050-500记忆总容量越大越占磁盘importance_threshold0.30.1-0.5重要性阈值越高越偏向保留重要记忆decay_factor0.950.8-0.99时间衰减系数越低越强调近期记忆4.3 参数背后的机制解读decay_factor时间衰减第8章文档展示了其底层公式recency_score math.exp(-decay_factor * age_hours / 24)记忆越久远相关性得分越低。调低decay_factor会加快旧记忆衰减让 NPC 更健忘、更关注近期调高则让旧记忆在检索中保持权重。importance_threshold重要性过滤同时影响两条路径——检索时的min_importance过滤以及记忆整合时是否值得写入长期记忆的判断。调高它会过滤掉更多低价值记忆减少存储占用但可能丢失细节。working_memory_tokensToken 预算直接决定注入提示词的记忆文本长度上限与limit5的检索条数共同构成上下文长度约束防止超出模型上下文窗口。五、存储结构SQLite 与向量检索的双层持久化5.1 目录结构按文档设计与仓库实际文件backend/memory_data/下已存在张三、李四、王五三个子目录每个 NPC 的存储布局为backend/memory_data/ ├── 张三/ │ └── memory.db # SQLite数据库 (权威持久化存储) ├── 李四/ │ └── memory.db └── 王五/ └── memory.db注指南文档中以sqlite_store.db命名示例仓库实际运行生成的持久化文件名为memory.db二者指向同一存储目录实际以仓库生成的memory.db为准。5.2 双存储机制SQLite权威存储情景记忆的结构化落盘载体保证重启后长期记忆不丢失支持按条件查询与容量管理向量索引语义检索配合 Embedding 服务为记忆建立向量索引实现基于语义相似度的相关性检索。第8章文档明确情景记忆的存储方案为 SQLite QdrantQdrant 向量存储提供高性能语义检索能力双存储一致性写入时以 SQLite 为准向量索引服务语义查询二者协同支撑按时间检索与按相关性检索两种模式。六、API 接口记忆能力的完整调试入口后端基于 FastAPI 实现main.py记忆相关接口如下。6.1 对话接口自动触发记忆读写POST /chat Content-Type: application/json { npc_name: 张三, message: 你好,你是做什么的? }响应{ npc_name: 张三, npc_title: Python工程师, message: 你好!我是Python工程师,主要负责多智能体系统开发。, success: true }每次调用/chat都会走完第三节描述的完整记忆闭环检索 → 增强 → 生成 → 保存。6.2 获取NPC记忆GET /npcs/张三/memories?limit10响应{ npc_name: 张三, memories: [ { id: uuid-1, content: 玩家说: 你好,你是做什么的?, type: working, importance: 0.5, timestamp: 2024-01-15T10:30:00, metadata: {...} } ], total: 10 }该接口对应get_npc_memories()agents.py以空查询调用retrieve_memories返回全部记忆并转为字典列表输出。limit参数控制返回条数默认 10。6.3 清空NPC记忆测试用DELETE /npcs/张三/memories?memory_typeworking响应{ message: 已清空张三的记忆, npc_name: 张三, memory_type: working }memory_type可选working/episodic不传则清空全部。底层调用clear_npc_memory()agents.py遍历[working, episodic]执行clear_memory_type便于测试前重置状态。6.4 关联接口GET /npcs/{npc_name}/affinity获取 NPC 对玩家的好感度记忆与好感度联动AFFINITY_SYSTEM_GUIDE.md 有完整讲解GET /返回服务信息features字段明确列出NPC记忆系统能力完整接口文档可在服务启动后访问http://localhost:8000/docsSwagger UI。七、测试方法三种验证路径方法1测试脚本cd backend python test_memory.py覆盖用例基本对话记忆、长期记忆检索、记忆隔离、相关性检索。方法2API 手动测试cd backend python main.py访问 API 文档http://localhost:8000/docs测试对话接口先发你好,你是做什么的?再发还记得我刚才问你什么吗?观察 NPC 是否能引用第一轮内容查看记忆列表GET /npcs/张三/memories确认记忆条目已落盘。服务默认监听0.0.0.0:8000config.pyLLM 通过环境变量配置LLM_MODEL_ID默认Qwen/Qwen2.5-72B-Instruct、LLM_API_KEY、LLM_BASE_URL默认 ModelScope 推理服务地址可在backend/.env中配置。方法3Godot 客户端联测启动后端服务运行 Godot 游戏项目helloagents-ai-town目录Godot 场景与脚本位于 scenes 与 scripts其中 api_client.gd 封装了对后端的 HTTP 调用与 NPC 多次对话观察 NPC 是否能记住之前的对话内容。八、调试技巧1. 查看记忆检索日志在chat()方法中已内置日志埋点配合 logger.py 的log_memory_retrieval/log_memory_savedprint(f {npc_name}检索到{len(relevant_memories)}条相关记忆) print(f 对话已保存到{npc_name}的记忆中)2. 直接检查 SQLite 数据库cd backend/memory_data/张三 sqlite3 memory.db SELECT * FROM memories;3. 清空记忆重新测试# 方式一调用API DELETE /npcs/张三/memories # 方式二直接删除NPC的记忆目录后重启服务 # 仓库为只读实际操作时在本地副本中进行九、常见问题排查Q1: NPC 为什么记不住对话?可能原因记忆系统未正确初始化检查日志是否有记忆系统已初始化输出存储路径权限问题检查memory_data目录是否存在且可写记忆被遗忘机制清除工作记忆 2 小时 TTL 过期或重要性低于阈值被淘汰。解决方法检查日志中是否出现记忆系统已初始化检查memory_data目录是否存在降低importance_threshold参数让更多记忆通过重要性过滤。Q2: 记忆检索不准确?可能原因查询语句与记忆内容的语义相似度低记忆重要性太低被min_importance0.3过滤。解决方法降低min_importance参数增加检索limit数量如从 5 提升到 10使用更具体、更贴近记忆原文的查询语句。Q3: 记忆占用空间太大?解决方法降低max_capacity提高importance_threshold让低价值记忆尽早淘汰定期通过DELETE /npcs/{npc_name}/memories清理旧记忆。十、教学价值与后续演进10.1 学习要点MemoryManager 的使用初始化、按需配置记忆类型working/episodic/semantic/perceptual、添加与检索记忆记忆检索策略工作记忆的快速近期检索、情景记忆的语义相关检索、以及时间 相关性的混合检索记忆存储机制SQLite 权威存储 向量索引语义检索的双存储方案以及一致性保证记忆遗忘机制基于重要性的自动遗忘importance_threshold、基于时间的 TTL 过期工作记忆 2 小时、容量限制的优先级淘汰max_capacity。10.2 与后续系统的衔接记忆系统是赛博小镇 NPC 智能化的地基指南文档已预告并实际落地了三个延伸模块好感度系统NPC 与玩家的关系管理详见 AFFINITY_SYSTEM_GUIDE.md记忆 metadata 中的affinity字段即为两系统的衔接点情感分析使用 LLM 分析对话情感sentiment字段随记忆一同持久化关系等级陌生、熟悉、友好、亲密、挚友五级关系驱动 NPC 对话风格随关系动态变化chat()中的affinity_context即按等级注入不同对话风格提示词。10.3 总结赛博小镇的 NPC 记忆系统已成功集成短期记忆工作记忆 长期记忆情景记忆 语义检索 记忆隔离 自动遗忘五大能力齐备。从架构上看它完整示范了 HelloAgents Memory 系统的实战用法——多智能体按user_id隔离记忆、双存储保证可靠性与检索性能、重要性驱动的遗忘机制控制存储成本。对学习者而言这套系统是理解 Agent 记忆管理、向量数据库落地与记忆检索策略的最佳实战范本相关完整配置与运行细节可继续参考 backend/README.md、SETUP_GUIDE.md 与第8章《记忆与检索》文档Chapter8-Memory-and-Retrieval.md。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考