记忆面包🍞 Skill

这个 Skill 是什么

这是 AI 助手内部使用的记忆增强引擎，核心使用者是 AI 助手本身，不是用户。

AI 在对话中通过 exec 调用 Python 脚本写入/检索记忆，把检索结果注入回复上下文。用户感知到的是"AI 记住了我说过的话"，而不是直接操作这些脚本。

设计原则：可用性优先，渐进扩展。

• 文字记忆：核心功能，开箱即用，零额外依赖
• 图片/音频/视频：可选扩展，不需要触发词，AI 主动感知上下文询问

⚠️ 重要：安装后必须更新 AGENTS.md

与其他 Skill 不同，记忆面包不完全依赖用户触发词，而是每轮对话自动执行。

安装完成后，必须将集成规则追加到用户的 AGENTS.md，否则记忆系统不会自动工作。

操作步骤：

1. 读取 references/agents-integration.md
2. 将其中的规则块追加到用户 AGENTS.md 的 ## Tools 章节
3. 将 替换为实际安装路径
4. 告知用户："记忆面包已集成，从下次对话起自动生效"

首次安装

# 1. 安装核心依赖（仅文字记忆，体积小，约 200MB 模型缓存）
pip install -r scripts/requirements.txt

# 2. 检测环境
python3 scripts/check_env.py

# 3. 迁移历史记忆（把 memory/YYYY-MM-DD.md 导入向量数据库，可选）
python3 scripts/migrate_memory.py

# 4. 验证
python3 scripts/migrate_memory.py --status

> ⚠️ 首次运行会下载语言模型（~192MB），需要几分钟，check_env.py 会提前告知。

AI 调用方式

> ⚠️ 有两种写入方式，场景不同，必须区分使用。详见 references/agents-integration.md。

每轮对话：检索相关记忆

cd <skill_scripts_dir> && python3 -c "
from memory_store import search_memory
results = search_memory('<query>')
for r in results:
    print(r['score'], r['display_text'])
"

把 display_text 以 🍞 记忆召回：XXX 格式注入回复上下文。

单轮重要内容：直接写入

当用户说出重要决策、目标、偏好等单条信息时，直接用 add_memory() 写入，不要等话题结束：

cd <skill_scripts_dir> && python3 -c "
from memory_store import add_memory
add_memory(
    text='[用户说] <内容摘要>',
    memory_type='decision',  # decision / preference / goal / fact / insight / exchange
    source='conversation',
    importance_score=8.0
)
print('[Memory] 已写入 1 条')
"

多轮话题结束时：批量提炼写入

> ⚠️ on_user_message() 需要缓冲区至少累积 2 轮才会触发，单轮必须用上面的 add_memory()。

cd <skill_scripts_dir> && python3 -c "
from topic_memory import on_user_message, on_assistant_message
on_assistant_message('''<assistant_reply>''')
written = on_user_message('''<user_message>''')
if written:
    print(f'写入 {written} 条')
"

收到图片/音频/视频时：主动询问用户

（正常解析/回复图片/音频内容）

---
要把这张图片存入记忆库吗？存入后可以随时语义检索回溯。
📸 存入 / 不用了

用户选择存入后，根据媒体类型判断是否已安装对应模块：

# 检查图片模块是否可用
try:
    from image_memory import add_image_memory
    add_image_memory(file_path="<path>", description="<描述>", context="<对话背景>")
except ImportError:
    # 模块未安装，提示用户
    print("图片记忆模块未安装，请运行：")
    print("pip install Pillow>=10.0 transformers>=4.0 torch>=2.0")

音频/视频同理，触发时检查 audio_memory / video_memory 模块是否可用，缺失则提示安装命令。

检索配置（经评测优化）

效果：召回率 100%，每轮注入少量记忆上下文，实际开销因检索结果数量和内容长度而异

环境变量覆盖：

export MULTIMODAL_MEMORY_TOP_K=3
export MULTIMODAL_MEMORY_MIN_IMPORTANCE=5

与现有记忆系统的关系

• memory/YYYY-MM-DD.md：人类可读的日记，继续保留，不影响
• 向量数据库：机器可检索的语义记忆，是对日记的增强，不是替代
• migrate_memory.py：把历史日记批量导入向量库的桥梁

核心原则

• 不强迫用户：多模态存入是询问，不是自动触发，用户有选择权
• 存原件，描述只是标签：图片/音频不折叠成文字，向量负责检索，原件负责回放
• 双向记忆：用户说的和 AI 说的都值得记，speaker 字段区分
• 操作日志不是记忆：「已存入/已写入」这类系统回复不写入记忆
• 情绪背景比事实本身重要：写入时保留情绪/动机背景

可观测性（重要）

记忆 Skill 后台运行，用户看不到它是否在工作。必须在每次回复末尾追加运行日志：

---
🍞 memory: 检索到 2 条 | 本轮写入 1 条（「用户下周有重要计划」）

• 检索 0 条也要显示（证明运行了，只是没相关记忆）
• 写入 0 条也要显示（话题还在继续中）
• 绝对不能省略，这是用户判断 Skill 是否在运行的唯一信号

模块说明

详细文档

• references/architecture.md：完整架构说明、向量维度、存储策略
• references/agents-integration.md：AGENTS.md 集成规则模板（安装后必读）