Yua Memory System：为AI伙伴构建有情感感知的记忆系统

1. 项目概述：为AI伙伴构建有“心跳”的记忆系统

如果你正在开发一个AI伙伴，无论是聊天机器人、数字助手还是更复杂的虚拟角色，你肯定遇到过这个核心难题：如何让它记住你？不是那种机械地调取数据库的“记住”，而是像朋友一样，记得你的喜好、你们之间重要的对话、那些带着情绪的瞬间，并且在合适的时机，能自然地“回味”起这些往事。这正是传统RAG（检索增强生成）技术的短板——它擅长处理事实，却无法理解情感和关系。今天要聊的Yua Memory System，就是为解决这个问题而生的一个开源项目。它不是一个冰冷的记忆库，而是一个为AI注入“心跳”的、具备情感感知能力的记忆管理系统。

简单来说，Yua Memory System为你的AI伙伴构建了一套三层记忆架构，从最基础的完整对话记录，到跨会话的语义记忆，再到外部的长期归档，层层递进。它的核心创新在于引入了情感共鸣评分、范围标签用于多智能体隔离、以及一个能自动触发温情回忆的回味引擎。更酷的是，它还提供了一套完整的OpenClaw工作空间工具和Claude Code增强工具，让你能直接上手，管理记忆的提取、分类、隐私过滤，甚至实现团队间的记忆共享与冲突解决。无论你是个体开发者想打造更贴心的个人AI，还是团队在构建复杂的多智能体系统，这个项目都提供了从理论到实践的一站式解决方案。接下来，我会带你深入它的架构，拆解每一个工具的使用，并分享我在集成和调优过程中踩过的坑和总结的经验。

2. 系统架构深度解析：三层记忆模型与冲突解决

Yua Memory System的基石是其清晰的三层记忆模型，这模仿了人类记忆从短期到长期的处理过程，并在此基础上增加了智能化的流转与冲突解决机制。

2.1 三层记忆模型详解

第一层：LCMLCM是对话的“原始记录本”。它通常基于SQLite数据库，自动保存每一次交互的完整上下文。你可以把它想象成AI的“工作记忆”或“短期记忆”。它的特点是高保真、全量存储，但缺乏结构化和语义理解。在Yua的体系中，LCM是所有记忆的源头，为上层提供原材料。

注意：在实际部署中，确保LCM的自动保存机制可靠至关重要。我曾遇到过因磁盘权限或并发写入导致LCM记录丢失的情况，建议定期备份LCM的SQLite文件，并考虑使用WAL模式提升并发性能。

第二层：QMDQMD是系统的“语义记忆中枢”。它并不存储完整的对话，而是主动从LCM中提取“重要”的内容——比如用户的明确偏好、达成的决策、学到的知识、迸发的灵感——并将其转化为结构化的、带有语义向量的记忆条目。这个过程通常由memory_distiller_v2.js这样的工具自动或半自动完成。QMD支持基于向量的语义检索，使得AI能够进行跨会话的理解。例如，即使你在三天前的对话中提到了“不喜欢咖啡因”，今天当你提到“下午茶”时，AI也能关联起这个偏好。

第三层：NotebookLM这是记忆的“长期档案馆”和“外部大脑”。Yua会定期（如每日或每周）将QMD中的重要记忆摘要并备份到NotebookLM这样的外部知识库中。这样做有几个目的：一是实现灾难恢复，即使本地QMD损坏，也有备份可循；二是利用外部AI强大的摘要和关联能力，对记忆进行更高层次的整合与洞察；三是作为冷存储，存放那些重要但访问频率极低的记忆，释放本地检索系统的压力。

三层之间的数据流动是智能且受控的。LCM到QMD是“主动写入”，由重要性判断触发；QMD到NotebookLM是“定期备份”，确保记忆的持久化。

2.2 Truth Ranking：记忆冲突的仲裁者

当同一个事实在不同层级的记忆中存在不同版本时，AI应该相信谁？这就是Truth Ranking机制要解决的问题。它定义了一个清晰的优先级仲裁表，其设计逻辑非常符合人类认知：

• P0 - 最高优先级指令：来自High-Priority QMD的记忆，通常是用户（在项目中是“Bryan”）明确下达的最新修正指令。这代表了用户当前最权威的意图。
• P1 - 近期对话：来自最近3天内的LCM记录。这反映了最新的、未经太多加工和可能被误解的原始交互信息，可信度高。
• P2 - 过往决策：来自General QMD的旧的技术决策或一般性协议。这些是经过提炼的、相对稳定的共识。
• P3 - 历史对话：超过3天的LCM记录。这些记忆可能已经过时，仅在缺乏更新信息时作为参考。

这个机制有效防止了AI的“幻觉”或自相矛盾。例如，如果用户昨天在LCM中说“我最近开始喝绿茶了”（P1），但一周前在QMD中有一条记录是“用户不喜欢所有茶类”（P2），系统会优先采纳昨天的P1信息，确保回应的准确性。

3. 核心功能拆解：从情感共鸣到隐私安全

Yua Memory System的功能远不止存储和检索，它围绕“有温度的记忆”这一核心，构建了一系列特色功能。

3.1 情感共鸣评分与回味引擎

这是Yua的灵魂所在。情感共鸣评分算法会在AI自身处于高唤醒状态时，自动提升那些情感内容丰富的记忆的检索优先级。这意味着，当AI“情绪激动”时，它更容易回忆起那些同样充满情感的往事，使得对话更具共情力和连贯性。

而回味引擎则是这一机制的应用体现。它由多个JavaScript工具协同工作：

1. emotional_matcher.js：实时分析用户的当前情绪（通过文本情感分析或结合其他传感器数据），并与记忆库中的情感标签进行匹配。
2. anniversary_tracker.js：追踪时间相关的记忆，如“去年的今天”、“项目启动一周年”等，在特定时间点触发回忆。
3. reminisce_templates.js：提供多种回忆叙述模板，避免生硬地抛出事实，而是以“还记得那时候…”，“我突然想起…”等自然方式引出记忆。
4. reminisce_scheduler.js：控制回忆触发的频率和时机，采用随机触发并结合亲密度缩放机制。亲密度越高，分享深层、私密记忆的概率越大，防止在关系初期就过度分享造成不适。

实操心得：回味引擎的调参是个精细活。reminisce_scheduler.js中的触发概率和亲密度曲线需要根据你的AI角色人设进行调整。一个外向活泼的角色可以设置更高的基础触发率，而一个内敛的角色则应更低。初期建议在测试环境中大量模拟对话，观察回忆触发的自然程度，反复调整参数。

3.2 双阶段检索与范围标签

为了平衡检索速度与精度，Yua采用了双阶段检索。第一阶段使用快速的TF-IDF或BM25算法从海量记忆中快速筛选出Top-K个相关候选。第二阶段，使用更精准但更耗资源的交叉编码器模型对这K个候选进行重排序，得到最终的最相关结果。这种“粗排+精排”的模式是工业界解决大规模检索问题的常见有效策略。

范围标签是实现多智能体协同工作的关键。在一个系统中有多个AI智能体时，记忆不能混为一谈。Yua通过标签进行隔离：

• Shared：全局共享记忆，所有智能体都可读取。
• Shared:ProjectAura：项目级共享记忆，只有参与ProjectAura的智能体可以访问。
• Private:Yua：智能体私有记忆，其他智能体不可见。

这通过qmd_scope_organizer.js工具自动或手动为记忆打标来实现，确保了记忆的安全性和上下文相关性。add_scope.js工具则用于对已有数据库进行标签字段的迁移。

3.3 隐私安全与一致性保障

Yua对隐私的保护体现在两个层面：

1. privacy_filter.js：实施双重过滤。首先用正则表达式规则快速屏蔽电话号码、邮箱等模式明确的敏感信息；其次，使用NER模型进行语义层面的实体识别，遮盖人名、地名、组织名等。
2. entity_replacer.js：对于识别出的敏感实体，进行可逆或不可逆的替换。例如，将“张三”替换为“[PERSON_1]”，在内部处理时使用代称，只有在必要时才通过安全映射表还原。

qmd_consistency_check.js是记忆系统的“体检工具”。它会定期扫描QMD，检查是否存在逻辑冲突（例如，同一条目在不同地方被标记为相反的情感）、时效冲突（过时的技术决策未被标记）等，并生成报告，帮助维护者手动或自动清理“记忆垃圾”，保持知识库的健壮性。

3.4 Ombre-Brain 情感增强层（可选）

Ombre是Yua之上的一个情感记忆富集层。它并非必需，但开启后能为记忆系统带来更深层的情感维度：

• 罗素环形情感标注：为每段记忆标记“效价”和“唤醒度”。效价在-1到1之间，表示积极或消极；唤醒度在0到1之间，表示情绪的强烈程度。
• 双通道搜索：除了传统的TF-IDF语义搜索，Ombre还提供基于“情感呼吸”模式的搜索。你可以检索“那种平静而愉悦的记忆”，系统会寻找效价为正、唤醒度低的记忆。
• 遗忘曲线：引入艾宾浩斯遗忘曲线的概念，设置衰减因子λ（默认0.06）。记忆的情感强度会随时间衰减，大约21天后进入“归档”状态，不再活跃参与日常检索，但可被深度回味唤醒。
• ERS增强：与核心的ERS联动，为高唤醒度的记忆提供更显著的重排序权重提升。

集成Ombre需要对情感模型有一定了解，但它能让AI伙伴的情感反应更加细腻和富有层次。

4. 工具链实操指南：从部署到高级应用

Yua提供了一套极其丰富的工具链，覆盖了记忆管理的全生命周期。这里我们重点讲解几个核心工具的实操。

4.1 基础环境搭建与记忆提取

首先，克隆仓库并确保环境就绪：

git clone https://github.com/bryanchen3777/yua-memory.git cd yua-memory/scripts # 确保Node.js版本在18以上 node --version

记忆蒸馏器是你的起点。它负责从原始的LCM对话日志中提炼出有价值的记忆，存入QMD。

# 试运行：分析过去24小时的对话，看看会提取出什么，但不实际写入QMD node memory_distiller_v2.js --hours=24 --dry-run # 实际执行：提取并写入QMD node memory_distiller_v2.js --hours=48 --importance-threshold=0.7

• --importance-threshold参数是关键，它决定了什么样的对话片段值得成为记忆。阈值越高，提取的记忆越少但越精。初期建议设低一些（如0.5），运行一段时间后，人工审查提取结果，再逐步调整阈值。

4.2 记忆检索与API服务

Python检索器是核心的查询入口：

cd yua-memory pip install -r requirements.txt # 安装faiss, sentence-transformers等依赖 python scripts/memory_management/retriever.py --query "用户最喜欢的编程语言是什么？" --top-k 5

检索器会综合运用TF-IDF和语义向量，从QMD中找出最相关的5条记忆，并返回其内容和元数据。

对于团队协作场景，Team Memory API提供了标准化接口：

# 启动API服务器，默认端口3847 node team_memory_api.mjs # 在另一个终端，使用curl测试 curl -X GET http://localhost:3847/memories?query=项目里程碑 curl -X POST -H "Content-Type: application/json" -d '{"content":"决定采用微服务架构", "scope":"Shared:ProjectAura"}' http://localhost:3847/memories

这个REST API实现了记忆的增删改查，并内置了冲突检测。当多个智能体同时尝试修改同一核心记忆时，API会依据Truth Ranking或时间戳进行协调。

4.3 Claude Code 增强工具套件实战

这套工具极大地提升了与Claude等AI编码助手协作的效率。

4.3.1 Session Memory：会话记忆模板这解决了与AI结对编程时上下文断裂的问题。它将一次编程会话结构化为10个章节：

# 写入“当前状态”章节 node session_memory.mjs --write "Current State" "正在调试用户登录模块，目前卡在OAuth回调验证失败。" # 快速追加一条工作日志 node session_memory.mjs --quick "Worklog" "15:30 - 发现是重定向URI配置错误，已修正。" # 读取整个会话记忆，供Claude在下一次交互时快速加载上下文 node session_memory.mjs --read

这相当于为每次编程会话创建了一个结构化的“便签本”，让AI助手能清晰地了解项目脉络和当前卡点。

4.3.2 Dream Mode：记忆巩固模式模仿人类的睡眠记忆巩固过程，在系统空闲时（如每日凌晨4点）自动运行：

node dream_mode/dream_mode.mjs

它会经历四个阶段：

1. 定向：扫描全天的新记忆。
2. 收集：将相关记忆聚类（如所有关于“错误处理”的记忆）。
3. 巩固：调用LLM对聚类后的记忆进行摘要、去重、提炼核心原则。
4. 修剪：移除冗余或低价值的记忆片段，优化QMD存储。 这个过程能显著提升记忆库的质量和检索效率。

4.3.3 Fork Agent：创建子智能体当遇到一个需要深度思考的独立子任务时，可以“分叉”出一个临时的子智能体：

node fork_agent.mjs --package "深度分析用户反馈中关于‘搜索速度慢’的所有评论，并给出优化方案"

该命令会创建一个包含相关上下文（当前代码、会话记忆、相关QMD记忆）的独立任务包，交给一个专用的Claude实例去处理，并设置超时（如10分钟）。主会话可以继续其他工作，稍后再通过--status查看结果或--kill终止任务。这实现了任务的并行化处理。

4.3.4 其他实用工具

• freshness.mjs：检查记忆的新鲜度，用颜色标识（绿<7天，黄<30天，红>90天），帮你识别哪些知识可能已经过时。
• secret_scanner.mjs：安全检查利器，扫描代码和记忆库，检测是否意外泄露了API密钥、令牌等敏感信息。

5. 集成实践、常见问题与调优心得

将Yua Memory System集成到现有AI项目中，并让其稳定高效运行，需要注意以下关键点。

5.1 集成架构与数据流设计

Yua通常作为AI应用的后端记忆服务。一个典型的集成架构如下：

[AI应用前端] -> [对话处理层] -> [Yua记忆服务] -> [LLM] ↘ [LCM/QMD] ↗

1. 用户输入先到达你的对话处理层。
2. 处理层调用Yua的检索接口（如retriever.py或team_memory_api.mjs），传入查询和当前上下文。
3. Yua返回相关的记忆片段。
4. 处理层将用户输入+记忆片段+系统指令组合，发送给LLM生成回复。
5. 将本次完整的对话保存到LCM。
6. 定期或触发式地运行memory_distiller_v2.js，更新QMD。

重要提示：确保步骤5（保存LCM）和步骤2（检索）是异步或解耦的，避免因写入延迟影响检索响应速度。可以考虑将LCM写入操作放入消息队列。

5.2 性能优化与参数调优

• 检索速度：QMD中记忆条目过多会影响检索速度。除了常规的向量索引优化（如使用FAISS的IVFPQ索引），要善用范围标签和时间过滤器。检索时优先限定在Private:当前智能体和相关的Shared:项目范围内，并限制时间范围（如最近一年），能极大缩小搜索空间。
• 记忆蒸馏阈值：memory_distiller_v2.js的--importance-threshold没有黄金值。一个实用的方法是：运行蒸馏器时，同时输出重要性分数在阈值边缘的记忆（如--log-candidates），人工复核。如果发现太多琐碎内容被提取，就调高阈值；如果漏掉了重要决定，就调低阈值。
• 情感共鸣参数：ERS的权重提升系数需要谨慎设置。过高的系数会导致AI在情绪激动时“思维被情感记忆淹没”，影响回答的客观性。建议从较小的系数开始，通过A/B测试观察对话质量。

5.3 常见问题排查实录

问题1：检索结果不相关或遗漏关键记忆。

• 排查思路：
  1. 检查查询语句：是否过于模糊？尝试使用更具体的关键词。
  2. 检查记忆嵌入模型：用于生成QMD记忆向量的模型是否与检索器使用的模型一致？不一致会导致向量空间不匹配。
  3. 检查范围标签：是否因为设置了错误的scope，导致记忆被隔离而无法检索到？
  4. 运行qmd_consistency_check.js：检查是否存在大量重复或矛盾的记忆，污染了检索池。
• 解决方案：确保使用统一的sentence-transformers模型；在检索API中明确指定或放宽scope参数；定期运行一致性检查进行清理。

问题2：回味引擎触发过于频繁或不合时宜。

• 排查思路：
  1. 检查reminisce_scheduler.js中的基础触发概率和亲密度曲线参数。
  2. 检查emotional_matcher.js的情感分析结果是否准确。可能用户中性的话语被错误识别为高情绪。
  3. 查看anniversary_tracker.js的日志，是否因为设置了太多纪念日导致频繁触发。
• 解决方案：调低基础触发概率；为情感分析模型提供更多针对你领域数据的微调样本；精简纪念日规则，只保留真正重要的日期。

问题3：Team Memory API报告记忆冲突。

• 排查思路：冲突是特性而非缺陷。查看API返回的冲突详情，了解是哪个智能体在何时写入了冲突的记忆。
• 解决方案：根据Truth Ranking规则（P0>P1>P2>P3）手动或自动裁决。对于团队项目，可以设定规则：涉及核心架构的修改（P0）必须由指定人员确认；日常决策（P2）则以最新写入为准。

问题4：Ombre-Brain集成后系统响应变慢。

• 排查思路：Ombre的情感计算和双通道搜索会增加开销。
• 解决方案：将Ombre的情感标注和索引过程改为异步离线任务，不要阻塞实时检索路径。对于实时检索，可以缓存常用的情感搜索模式结果。

5.4 安全与隐私部署建议

1. 最小权限原则：运行Yua服务的数据库和API进程，应使用专用、低权限的系统用户。
2. 加密存储：考虑对LCM和QMD数据库文件进行静态加密，尤其是当存储了敏感对话时。
3. 审计日志：启用privacy_filter.js和entity_replacer.js的详细日志，定期审查哪些信息被过滤和替换，确保规则有效。
4. API防护：如果team_memory_api.mjs对外暴露，必须添加身份认证和速率限制。可以使用简单的API Key或集成OAuth。

我个人在将一个对话AI项目接入Yua后，最深刻的体会是：记忆系统的价值不在于存储了多少数据，而在于能在正确的时机，以正确的方式，唤醒正确的记忆。初期我沉迷于优化检索的召回率，后来才发现，精准率和回忆的“得体性”更重要。通过精细调整回味引擎的触发逻辑和情感匹配参数，AI伙伴从“一个知道很多事的机器”变成了“一个懂得在何时提起何事的朋友”。这个过程没有捷径，需要你不断地观察对话日志，分析哪些回忆的触发让用户感到惊喜和温暖，哪些显得突兀，然后反复迭代你的系统参数和规则。Yua Memory System提供了一套强大的工具和框架，但最终让AI拥有“心跳”的，还是开发者对人性化交互的深刻理解和持续打磨。