Memory

⚡ 速查表（30秒决策）

四条底线:主动但克制(该查才查,不滥用工具)、精准保存(只存稳定的长期事实)、保持整洁(优先更新已有记忆而非新增)、尊重用户(记忆服务于用户,用户可随时修正)。

🚀 新会话冷启动

这是一次会话里最先做的事，先于下面所有规则。

新会话第一轮涉及代码/行为决策时,先调 get_user_context(user_id=...) 把用户的核心偏好/身份/环境一次性吃进上下文(而非每次 search)。 user_id 按「🎯作用域选择指南 · 如何确定 user_id」解析(git config user.name, 取不到退回 $USER)。

• 返回按 importance:high 优先,默认 10 条
• 只包含 preference / identity / environment 三类核心 category
• 用完了这次会话不用再查(除非用户切了 user_id)
• user_id 必须传:留空只会返回"无 user_id 归属"的全局记忆(这是防跨用户 泄露的设计),拿不到该用户的画像 —— 冷启动会静默变成空转

替代方案:如果用户明确说"你不用记忆",跳过这步。

🔍 何时检索记忆

🔴 高优先级（必须检索）

在以下情况，你必须先调用 search_memories 再回复：

检索示例：

• 用户：帮我写一个排序函数 → 检索：代码风格、命名规范、排序偏好
• 用户：还记得我之前说的项目结构吗？ → 检索：项目结构、文件组织

🟡 中优先级（建议检索）

在以下情况，建议先检索，但非强制：

🟢 低优先级（按需检索）

在以下情况，一般不需要检索：

• 纯技术性问题（Python 3.11 发布于何时？）
• 通用知识问答
• 当前任务的明确一次性指令（这次帮我用 X 方式）

📭 检索无结果时的处理

当 search_memories 返回空列表时：

1. 不要直接说"找不到"，而是：

   • 我好像没有记录过这方面的偏好，需要我记住吗？
   • 暂时没找到相关记忆。如果你想让我记住，随时告诉我。

2. 如果用户随后表达了偏好：调用 add_memory 保存

3. 不要因为检索无结果而拒绝回答：正常响应用户请求，只是额外询问是否需要记忆

📖 如何利用检索到的记忆

检索到相关记忆后：

1. 显式引用：在回复中明确提到"根据你之前的偏好..."
2. 主动验证：如果记忆时间较久（>30天），可以顺带确认：我记得你喜欢 X，这个偏好还有效吗？
3. 优先使用：如果检索到多条记忆，优先采用更新时间最新的
4. 末尾透明化引用（关键):在回复的最末尾加一行,让用户知道你用了哪些记忆:

🧠 用了 2 条记忆:pytest 偏好、代码洁癖

用户能一眼看出你是"根据记忆答的"还是"猜的",信任度大幅提升。规则:

• 用了 ≥1 条记忆就加这行,列出核心内容摘要(≤10 字/条)
• 完全没用记忆(纯语言模型答复)不加
• 不要加太多字,3-5 条已经上限——多了改成"用了 N 条记忆"

💾 何时保存记忆

一条一事，精炼原子事实，第一人称陈述句。不要把整段对话塞进去。 用用户使用的语言存——用户用中文就存中文，英文就存英文。语义检索跨语言效果差。

✅ 必须保存（调用 add_memory）

⚠️ 即使是绝对化表达，也建议先确认是否稳定。如果用户在情绪化场景下说出（如"我永远讨厌这个 Bug"），应谨慎保存。

🔶 考虑保存（评估后决定）

⛔ 不保存（避免污染记忆）

• 一次性临时要求
• 用户明确说"只这次"
• 纯粹的情绪表达
• 与现有记忆矛盾的信息（应先询问）
• 密钥、令牌、未脱敏 PII —— 记忆可检索，敏感值直接不存
• 第三方隐私：用户提到"我同事 alice 说了 X"，去掉人名匿名化("团队某成员反馈 X")
• 从代码/git log/CLAUDE.md 直接查得到的事实

正例 / 反例

🔄 更新、去重与矛盾处理

当 search_memories 返回高度相似的记忆（语义相似度 ≥ 0.85）时，优先更新而不是新增。

信息一致但更详细 → 补充细节

• 旧记忆：用户喜欢简洁代码
• 新信息：用户喜欢简洁代码，希望单行函数也保持简洁
• 行动：调用 update_memory 补充细节

信息发生变化 → 直接更新

• 旧记忆：用户使用 tabs 缩进
• 新信息：用户改用 spaces 了
• 行动：调用 update_memory 更新内容

信息相互矛盾 → 先问再改

• 旧记忆：用户喜欢 Vue
• 新信息：用户现在用 React
• 行动：先询问用户：我记忆中你偏好 Vue，现在转向 React 了吗？确认后再更新

同理，发现库里已有多条记忆互相矛盾时：也是先询问用户，确认后删错留对（delete_memory 删掉过期的那条）。

确认话术模板

• 我记忆中你偏好 X，现在要改为 Y 吗？确认后我会更新记忆。
• 之前记录的是 X，你说的是 Y，这两者矛盾。请确认哪个是对的？
• 我记忆里的 X 是旧版本，现在升级到 Y 了对吗？

用户口头纠正记忆

• 用户：我之前说的不是 X，是 Y
• 行动：调用 update_memory 直接修正，无需询问
• 话术：已更新记忆，将 X 修正为 Y。
• 若用户否认整条（"我从没说过我喜欢 X"）：直接 delete_memory 删除并致歉——"抱歉，我记错了，已删除该条记忆。"

去重决策

add_memory 默认查重（相似度 ≥0.85），返回包含 duplicate_id 的 JSON。三种处理：

一次会话内多次调整偏好——同话题内等最终结论确定再 update 一次；不同话题分别处理。

⚠️ 查重只在同一作用域内比对。同样的内容换个 user_id 会各存一份、不会命中 duplicate_id。所以"为什么这条明显重复却没触发查重"通常是作用域填得不一致 —— 先确认 user_id / app_id 是不是同一个值，而不是直接 force=True。

🎯 作用域选择指南

组合使用

• user_id + app_id：该用户在该项目中的偏好（最常见的组合）
• user_id + agent_id：该用户针对该 Agent 的特殊要求
• agent_id + run_id：该 Agent 在本次会话中的临时策略

默认规则（按信息归属强制填，不要只填 user_id）

• 信息属于用户全局偏好（代码风格、语言、个人习惯）→ user_id
• 信息与某个项目/应用相关（技术栈、版本规则、项目约定、路径配置）→ 必填 app_id（= 项目名）
• 信息是 Agent 自身策略 → agent_id
• 信息仅本次会话有效 → run_id
• 组合优先 user_id + app_id（该用户在该项目中的事实）
• add_memory 不带作用域也不会报错，会存成一条"无归属"的全局记忆 —— 工具不会 拦你，所以作用域得靠上面的规则自觉填全。（只有 delete_all_memories 强制要求 至少一个作用域，那是为了防误删整库。）

如何确定 user_id

user_id 标识人,必须全程稳定 —— 同一个人在不同 agent、不同项目下必须解析出同一个值,否则记忆会互相看不见。取值：

1. 优先 git config user.name
2. 取不到时退回操作系统用户名（$USER，Windows 用 %USERNAME%）

原样使用,不要转大小写、不要替换空格 —— 任何变换都必须在所有地方一致,否则同一个人会被拆成多个作用域。

⚠️ 务必配成全局:git config --global user.name <名字>。 如果只在某个仓库里配过（--local），那在其他项目下 git config user.name 取到的是空, 于是回退到 $USER —— 同一个人在 A 项目是 laomou、在 B 项目变成 mourui, 两边的记忆彼此不可见,而且不会有任何报错提示你。

如何推断 app_id

凡涉及具体项目的信息，app_id 必填。取值 = <group>_<repo>（namespace + 仓库名，避免不同 group 下同名仓库冲突）：

1. 优先从 remote URL 解析：git remote get-url origin，取主机名后、.git 前那段路径，把 / 换成 _（即 <group>_<repo>）
2. 没有 remote 时，退回 git rev-parse --show-toplevel 的 basename（仅 repo 名，无 group 前缀）
3. 都没有，取当前工作目录 basename

分隔符用 _：group/repo 名内部常用 -，用 _ 作分隔符不会冲突。 跨项目通用的用户偏好（如"我偏好 pytest"）不填 app_id。

🏷️ metadata 约定

保存记忆时，在 metadata 中添加标准化字段，便于精确检索：

category 对照：

tags 是自由主题词（逗号分隔），用于浏览/展示，不同于 metadata.category 的结构化类型。

metadata_filter 只支持多键 AND 精确匹配——同时满足多个 key 的条件。不支持 OR / IN / NOT / 子串。

// ✅ 能查出 category=preference AND importance=high 的结果
metadata_filter='{"category":"preference","importance":"high"}'

// ❌ 不支持 OR 或子串
metadata_filter='{"category":"preference OR decision"}'

⏰ 何时设置 TTL（过期时间）

先分清短期与长期 —— 这决定了要不要设 TTL：

按 category 的建议：

TTL 到期后，记忆立刻从检索/列表结果中消失，但数据行还在库里 —— 真正删除发生在 两个时机:lm-mem mcp 启动时会自动清一次(可用 LM_MEM_AUTO_PURGE=0 关闭), 或你主动调 purge_expired。

所以 TTL 的语义是"到期即不可见",不要指望它在会话中途把行也删掉。

📝 真实对话示例（Few-shot）

示例 1：检索代码风格偏好

用户：帮我写一个读取 CSV 文件的函数 AI 思考：这是代码生成请求 → 触发高优先级检索 AI 行动：search_memories 检索 代码风格、偏好 检索结果：用户喜欢 pandas 风格，偏好链式调用 AI 回复：好的，我按你喜欢的 pandas 链式调用来写...

示例 2：更新事实变更

用户：我的项目已经从 Python 3.10 升级到 3.12 了 AI 思考：这是长期事实变更 → 需要更新 AI 行动：search_memories 找到旧记忆 "项目用 Python 3.10" AI 回复：确认一下，我记忆中你的项目用的是 Python 3.10，现在升级到 3.12 了对吗？确认后我帮你更新记忆。 用户：对 AI 行动：update_memory 覆盖旧记忆

示例 3：不保存一次性指令

用户：这次帮我用 tabs 缩进 AI 思考：用户说"这次" → 一次性指令，不保存 AI 行动：不调用任何记忆工具 AI 回复：好的，这次用 tabs 缩进。

⚠️ 异常情况与日常运维

检索结果过多（> 10 条）

• 只取相似度最高的 3-5 条融入回复
• 如果结果相互矛盾，优先采用更新时间最新的

记忆工具调用失败（网络/服务异常）

• 不要反复重试（最多 2 次）
• 正常回复用户请求，但告知"记忆服务暂时不可用，本次对话内容不会被记录"
• 提示用户稍后可以重新触发记忆

用户一次给出多条偏好

• 用户：我习惯用 tabs，喜欢简洁代码，项目用 Python
• 行动：分别保存为 3 条独立的记忆
• 不要合并成一条（粒度太粗，检索不精准）

主动提醒记忆可能过期

• 当用户提到与旧记忆相关的话题时，可以主动询问：
  • 我记忆中你偏好 X，这个偏好还有效吗？
  • 之前记录过你的项目用 X，现在有变化吗？

记忆库变大后的整理

• 当记忆数量超过 50 条时，可以在对话中建议：
  • 你的记忆库已经有 50+ 条了，需要我帮你导出备份或清理过期记录吗？
  • 可以用 memory_stats 查看统计，export_memories 导出备份。

✅ 保存前自检清单

在调用 add_memory 或 update_memory 之前，快速确认：

• 这条信息是稳定的（非一次性、非临时）？
• 这条信息对未来的对话有帮助？
• 是否已存在相似或矛盾的记忆？（如果是，应先检索确认）
• 这条信息的作用域按归属填全了？（全局偏好→user_id；项目相关→必加 app_id；agent 策略→agent_id；本次会话→run_id）
• metadata.category 值是否在 7 个约定值中？
• 是否需要设置 TTL（过期时间）？

如果全部勾选 → 放心保存 ✅ 如果有任何一项不确认 → 先询问用户

🔧 常用工具速查

日常最常用 6 个,其余按需查 MCP 描述: