Cross-session memory（yyuan）· 跨会话持久记忆

> 持久记忆技能：让 agent 在多次会话间保留上下文——记录「发生了什么」，未来再用自然语言回忆并注入。

目录

> 本文件只写每天都要用的部分（468 行）。进阶与低频内容全在
> references/REFERENCE.md（随包分发），文末有指引表。

触发方式（自动优先，无需硬编码触发词）

本技能默认不依赖任何触发词。加载后按下方工作流自动执行，不需要用户说特定的话：

> 诚实说明（重要）："自动"的前提是宿主在会话开头按「记忆协议」执行了 session-start 等命令——协议写在用户级 MEMORY.md（第十四节），由宿主保证每轮注入。若宿主未加载本技能、也未执行协议，则这些动作不会发生。
> 因此触发率取决于宿主是否遵循描述，而非 100% 由系统强制保证。这是当前架构的边界，已在「与 WorkBuddy 原生记忆的分工」一节写明。

> 开场注入是本技能最高杠杆的一步：只要协议被执行，用户多数时候根本不需要「触发」——记忆已经在上下文里了。

用户也可以用自然语言直接说（如「记一下…」「回忆一下…」），这只是可选捷径，不是触发条件。

可选别名（y 开头）

想显式指定走记忆，消息以 y 开头即可：

> y 与正文可连写或空一格：「y记住」「y 记一下」「y回忆」「y 想一下」均识别。
> 别名只用于显式指定，不写也照常自动生效——两者不冲突。

快速上手（5 分钟，按这个顺序做一遍）

# 1) 装完先自检环境（9 项：版本/文档版本/文档行数/数据库/FTS5/表结构/配置/记忆库/隐私残留）
python scripts/mem.py doctor          # 期望 ok=true；任一项失败会给出 detail

# 2) 装稳定入口（技能目录改名/重装也不失效），并拿到协议里该写的那行路径
python scripts/mem.py install-entry
# => {"installed": "~/.yyuan/yyuan.py", "protocol_entry": "python \"...\" session-start"}

# 3) 把记忆协议直接写进用户级 MEMORY.md（只动协议块，其他内容原样保留；幂等）
python scripts/mem.py install-protocol --dry-run   # 先看将写入什么
python scripts/mem.py install-protocol             # 实际写入

# 4) 写一条试试，确认落库
python scripts/mem.py capture --type decision --content "选用 SQLite+FTS5，零依赖" --project demo

# 5) 检索回来（3 层检索，先 search 再 get）
python scripts/mem.py search "SQLite" --limit 5

> 第 2、3 步做完就装好了——不需要手工复制协议块、自己拼路径。
> 想手动控制，也可以只跑第 2 步，然后照「十四、记忆协议」那段代码块自己粘贴。

> 只想用 → 看完本节 + 「三、Agent 工作流」即可；
> 想排错 → 翻 references/REFERENCE.md 的「三、常见反模式与排查」和「五、安装校验」；
> 想接入 → 看本文「十四、记忆协议」和 REFERENCE 的「五、安装校验」；
> 想迁移/备份 → 看 REFERENCE 的「六、备份恢复与跨设备迁移」。

与 WorkBuddy 原生记忆的分工（互补，不打架）

三处记忆各管一段，同一件事不要到处抄：

为什么这样分：原生 MEMORY.md 每轮必定进入上下文，而本技能是「模型判断相关才加载」。把协议放前者、把内容放后者，等于用确定性的入口去拉起概率性的技能——这是当前架构下把触发率拉到接近 100% 的唯一办法。

一条硬规则：同一事实只在一处当家。两边都出现同一句话时，以 updated_at 较新者为准。

双向打通：import-native 把原生记忆吸收为索引（幂等，重复跑是合并而非复制）；gen-context 反向产出项目上下文文件，给没有本技能的会话兜底。

一、它解决什么

• 金鱼脑：每次会话从零开始，过去的决策、修复、踩坑全忘。
• 检索贵：把全部历史塞进上下文太浪费 token。
• 解法：记录为结构化 observation，用 3 层渐进披露检索——先拿索引（省 token），确认相关后再取全文。
• 检索不准：只按时间倒序会把不相关条目顶到前面，v1.2 改为 相关性 + 重要性 + 新鲜度 综合排序。
• 重复堆积：同一结论反复记录会稀释信噪比，v1.2 按内容哈希 自动合并 并提升权重。

二、存储位置

• 默认数据库：~/.yyuan/mem.db（跨项目共享的用户级记忆）。
• 覆盖：--db /path/to/mem.db 或 --data-dir /dir（每个项目独立记忆）。
• 配置：~/.yyuan/config.json（config 子命令读写）。

三、Agent 工作流（何时调用）

> 脚本位于本 SKILL.md 同级的 scripts/mem.py。在本技能目录下执行：
> python scripts/mem.py capture --type bugfix --content "修复了登录超时：根因是 token 未刷新"

四、observation 类型

decision(决策) · bugfix(修复) · error(报错) · learning(学到的) · refactor(重构) ·
question(疑问) · usage(用法) · file(文件) · note(笔记) · request(需求) ·
pitfall(踩过的坑) · security_alert(安全告警) · sensitive(敏感)。可接受任意值，但建议用上表。

重要性 --importance 1–5（默认 3），直接参与检索排序（权重 0.25），并随重复出现自动提升。

记忆分层（--layer）

按 type 自动推断，也可显式指定：

检索时可 --layer semantic 只看结论，跳过过程噪声。

项目隔离（--project）

每条记录都能挂一个项目名，写入时 --project <名>，检索时用同名筛出，做到多项目共用一个库也互不串味：

capture --type decision --content "改用 WAL 模式" --project yyuan
search "" --project yyuan          # 只看该项目
session-start --project yyuan      # 开场只注入该项目的关键记忆

project 为空表示「通用记忆」，任何项目都能检索到。隔离靠筛选而非分库，
好处是一个库就能回答跨项目问题（「上次那个配置问题在哪个项目出现过」），代价是漏写 --project 的条目会变成全局可见。

匹配口径（v1.3.6 起）：项目名按精确匹配（忽略大小写）筛选，--project Alpha 不会命中 AlphaLegacy；
同时通用记忆（--project 为空）始终可见——所以按项目筛出的结果 = 该项目条目 + 通用条目。
要模糊找就用 search 的全文检索（内容里出现项目名即可），别指望 --project 做模糊匹配。

实体（--entity）

给观察挂实体标签（项目、技术、模块名），可重复：

capture --type decision --content "选用 SQLite+FTS5，不上向量库" --entity SQLite --entity 架构
search "" --entity SQLite        # 只出与该实体相关的条目

去重合并

同一内容（忽略大小写与空白）再次写入不会新增行，而是：
importance 在较高值上 +1（封顶 5）、times_seen +1、updated_at 刷新。
返回 {"status": "merged", "times_seen": 2} 即为合并。确需重复行时加 --no-dedupe。

> 去重键是「内容哈希 + 私有标记」，不包含 type——同一句话换个 type 再写，
> 仍然合并成一条（并按重要度升级把类型也提上去），不会变成两条。
> 这是有意的：换了 type 通常意味着「对同一事实的认知升级」，不是新事实。
> 反过来，内容不同就一定是两条，哪怕 type 和 importance 完全一样。

踩坑与复习排程（防复发）

踩过的坑最容易被忘掉，也最贵。用 pitfall 记成六段式，它会被排进复习队列：

python scripts/mem.py pitfall \
  --scene "用 Edit 改函数定义" --wrong "old_string 漏了一个换行" \
  --impact "语法错误，脚本跑不起来" --root "改前没读原文，凭记忆写的" \
  --fix "先 Read 目标区域确认缩进与换行" --signal "替换后首行与下一行粘连"

六段拼成一段文本存进 content（场景 / 错误做法 / 后果 / 根因 / 正确做法 / 触发信号），
不新增六列——FTS 照样全文可搜，代价是内容读起来是文本而不是结构化字段。
type=pitfall、默认 importance=4、自动进复习队列。

复习按 Leitner 记忆箱推进，间隔 1 / 2 / 4 / 7 / 15 / 30 天：

python scripts/mem.py review                 # 只列到期项
python scripts/mem.py review --all           # 队列全貌
python scripts/mem.py mark 12 remember       # 记得 → 进下一箱，间隔变长
python scripts/mem.py mark 12 fuzzy          # 模糊 → 箱位不动，明天再考
python scripts/mem.py mark 12 forget         # 忘了/又犯了 → 回第 1 箱，lapses+1

mark 也接受中文：记得 / 模糊 / 忘了 / 又犯了。

默认不入队。 只有 pitfall 和显式加 --review 的 capture 才进队列，普通流水账不参与，
否则每次开场都被一堆旧事占满。lapses 记的是「同一个坑又犯了」的次数，与 times_seen
（内容被重复记录）语义不同，别混用。

复习项在 session-start 里单独成小节（最多 3 条），不改动主排序权重——
注入优先级仍是 0.6 相关性 + 0.25 重要度 + 0.15 新鲜度。

五、3 层检索（核心，省 token）

# 第 1 层：紧凑索引（~50 token/条），按综合分排序，拿 id + 一行摘要
python scripts/mem.py search "登录超时" --type bugfix --limit 10
# 返回 [{id, type, date, project, summary, layer, importance, times_seen, score}]

# 收窄结果：只看某层 / 某实体 / 只留高分
python scripts/mem.py search "超时" --layer semantic --min-score 0.6
python scripts/mem.py search "" --entity SQLite

# 第 2 层：时间上下文，看某条前后的来龙去脉
python scripts/mem.py timeline --id 42 --window 5
# 或按查询展开时间线：timeline --query "登录" --days 7

# 第 3 层：只对筛选后的 id 取完整内容
python scripts/mem.py get 42,45

> 排序公式：0.6×相关性 + 0.25×重要性 + 0.15×时间衰减。
> 时间衰减是严格半衰期 30 天：0.5 ** (天数 / 30)，即 0 天=1.0、30 天=0.5、60 天=0.25、90 天=0.125。
> 相关性优先用 FTS5 bm25；中文无分词场景自动降级为子串命中兜底，不会出现"全 0 分"。
> 原则：先用 search/timeline 缩小范围，绝不一开始就把全文灌进上下文。

中文检索怎么用：FTS5 的 unicode61 不给中文分词，连续中文被当成一个 token，
所以本技能用「子串命中」兜底。多词查询（如 "登录 超时"）另有命中词数阈值——
2 词须全中、3 词须中 2 个，以此类推，避免只沾上一个词的噪音条目混进来；
若一条都没达标，会放宽为「命中任一词」，宁可多召回也不漏召回。

score 怎么读：0–1 区间的综合分，不是概率，只能横向比大小。经验刻度——
≥0.8 命中正文且重要性高，可直接引用；0.5–0.8 沾边，建议再 get 看全文；
<0.5 多半只在项目名或标签上沾到，别当结论用。每条返回都带 importance / times_seen / layer，
就是为了让你能自己复核「它凭什么排前面」，而不是盲信排序——记忆要可解释，才敢拿来当依据。

六、写入示例

# 决策
capture --type decision --content "采用 SQLite+FTS5 而非向量库，零依赖" --project yyuan --tags arch

# 修复（带文件与重要性）
capture --type bugfix --content "修复 WAL 锁：open 时加 journal_mode=WAL" --file scripts/mem.py --importance 5

# 敏感内容：两种方式隔离
capture --type sensitive --content "API key: sk-xxxx" --private          # 整条不进检索/注入
capture --type note --content "用户说 <private>他的银行卡号</private> 已更新"  # 片段脱敏，且整条按私有处理

七、会话生命周期

session-init  --prompt "为 yyuan 加 Web Viewer" --project yyuan   # -> {"session_id": 7}
# ... 干活，多次 capture ...
summarize --session 7 --text "新增 serve 子命令与 viewer.html"      # 或留空自动汇总
session-end --session 7

下次会话开头跑 session-start，注入的是按「重要度 + 新鲜度」挑出来的关键记忆（不是单纯最近 N 条）：
重要度达阈值（默认 ≥3）或落在近 3 天窗口内的条目才有资格入选，再按综合分取前 N 条。可调：

session-start --limit 12 --min-importance 3 --fresh-days 3
session-start --project yyuan --limit 8      # 只注入某个项目

若复习队列里有到期项，session-start 末尾会附一个「到期复习」小节（最多 3 条），
与上面的关键记忆分开统计、互不挤占。它不改动上述挑选口径——到期项单独列，不进主排序。

八、隐私

• <private>...</private>：捕获时该片段原文被替换为 [REDACTED]（原敏感内容不入库），
  并且整条 observation 按私有处理——不进入 search/timeline/session-start/gen-context/export。
• --private：整条 observation 标记为私有并排除；即使内容里没有 <private> 片段，整条也不可见。
• security_alert、sensitive 类型默认私有。
• import-native 导入原生记忆时遵守同一套规则：先剥离 <private> 片段，含片段的条目整条按私有入库。
• 历史残留（旧版本导入路径未剥离片段）用 purge-fragments 就地脱敏，doctor 会检出并提示。

九、Web Viewer

python scripts/mem.py serve --port 37710
# 浏览器打开 http://localhost:37710

实时记忆流：搜索框 + 类型筛选 + 时间线，数据来自 /api/observations、/api/search、/api/stats。

十、配置

python scripts/mem.py config --key inject_limit --value 12            # session-start 注入条数
python scripts/mem.py config --key inject_min_importance --value 3   # 注入的重要度门槛
python scripts/mem.py config --key inject_fresh_days --value 3       # 新鲜窗口天数
python scripts/mem.py config --key port --value 37710                # viewer 端口
python scripts/mem.py config                                         # 查看全部

十一、命令速查

「详见」列指向 references/REFERENCE.md 里的具体小节——本表只说命令做什么，详细参数与样例在那边。

> 完整参数一律 python scripts/mem.py <命令> --help 查，本文不抄一遍。
>
> 错误输出统一为结构化 JSON（stderr，退出码非 0）：
> {"code": "<错误码>", "error": "<消息>", "hint": "<修复指引>"}。
> 全部错误码清单见 references/REFERENCE.md 第六节末。
>
> 排查入口：出问题先看 references/REFERENCE.md 的「三、常见反模式与排查」——
> 里面有反模式清单、边缘情况与修复引导、高频排查表、FAQ 六问。
> 调用方可按 code 分支，hint 直接给出下一步该做什么。

十二、与 claude-mem 的差异（诚实说明）

• 捕获：claude-mem 靠 IDE hooks 后台自动捕获；WorkBuddy 未暴露等效 hook，yyuan 改用「常驻描述 +
  固定工作流」——模型在关键节点主动执行 session-start / capture / summarize，无需关键词。
  差别只在触发者（模型判断 vs 系统事件）。
• 语义检索：claude-mem 用 Chroma 向量库；yyuan 默认用 FTS5 全文检索（零依赖），
  需要语义检索可在 config 接入外部向量服务（本版未内置）。
• 存储、3 层检索、隐私、Viewer、上下文注入等核心能力已对齐；并额外提供
  综合排序、去重合并、分层、实体索引、原生记忆导入。

十三、导入 WorkBuddy 原生记忆（避免两套记忆打架）

WorkBuddy 本身已有常驻记忆（用户级 MEMORY.md、工作区 .workbuddy/memory/YYYY-MM-DD.md），
而 yyuan 是独立 SQLite 库——不打通就是两套记忆各说各话。import-native 负责一次性对齐：

python scripts/mem.py import-native --dry-run      # 先看会扫到哪些文件、共多少条
python scripts/mem.py import-native                # 实际写入
python scripts/mem.py import-native --source <WORKSPACE>/.workbuddy/memory/YYYY-MM-DD.md --project proj

规则：自动发现 ~/.workbuddy/user-*/MEMORY.md 与当前工作目录下 .workbuddy/memory/*.md；
MEMORY.md → semantic（基准 5）、日期日志 → episodic（基准 2）；
按内容加成（含「铁律/必须」→ learning、含「决策/架构」→ decision、含「修复/根因」→ bugfix，各 +1~+2）；
列表项一行一条、段落（≥8 字）也算一条，标题/分隔线丢弃；
幂等（bump=False，重复只 merged，重要度不变）；本技能写入的协议块自动跳过；--private 整批私有。

> 日志基准 2 分永挤不进开场注入、规则/决策基准 5 分必靠前；两者同级会退化成「最近 N 条流水账」——最易复发的失效。

十四、把触发率拉到接近 100%：记忆协议

技能是「模型判断相关才加载」，存在概率性漏载。而用户级 MEMORY.md 由宿主保证每轮注入。
把一段 5 行协议写进 MEMORY.md，就等于给这个技能装了一个确定性入口——即使技能没被加载，协议里的命令照样会被执行。

把下面这段（含哨兵注释，便于导入时跳过）追加到 ~/.workbuddy/user-*/MEMORY.md：

> 其中 <YYUAN_HOME> 是记忆根目录：Linux/macOS 为 ~/.yyuan，Windows 为 %USERPROFILE%\.yyuan。复制前请替换为你机器上的实际路径，不要用示例中的绝对路径。

<!-- yyuan:protocol:begin -->
【记忆协议 · 每次会话开场执行，不依赖技能是否被加载】
1. 开场必须跑并原文贴出：python "<YYUAN_HOME>/yyuan.py" session-start
   将整段输出原文（不改写、不缩写、不省略）作为开场回复的第一块贴出，确保用户可见。输出为空或检索无结果时，如实写"没有相关记录"，不得编造。
2. 用户提到"上次/之前/当时/我记得/我们定过/怎么修的/为什么这么改"→ 先 python "<YYUAN_HOME>/yyuan.py" search <关键词>，再 python "<YYUAN_HOME>/yyuan.py" timeline --query <关键词>，最后 python "<YYUAN_HOME>/yyuan.py" get <id,id> 取全文，再回答。
3. 完成决策、修复、踩坑、需求变更后 → python "<YYUAN_HOME>/yyuan.py" capture --type <decision|bugfix|error|note> --content "…" --importance 1-5。
4. 会话收尾 → python "<YYUAN_HOME>/yyuan.py" summarize --text "…"。
5. 不该长期留存的内容放进 <private>…</private>，技能会自动脱敏。
<!-- yyuan:protocol:end -->

> 协议里每条命令都带完整执行前缀——它是给宿主直接执行的，
> 裸命令名（search / capture）在 shell 里跑不起来。

<YYUAN_HOME>/yyuan.py 是稳定入口：它总是找到最新的 skills/yyuan*/scripts/mem.py 并转发。
技能目录被重装、改名、加 __skillhub 后缀都不影响——这个协议不会因为目录变动而失效。

稳定入口随包分发（scripts/yyuan.py）：install-entry 复制到 ~/.yyuan/yyuan.py
并给出协议里该写的绝对路径（命令见「快速上手」第 2 步）；install-protocol（推荐）一步把
上面的协议块写进 ~/.workbuddy/user-*/MEMORY.md 的 yyuan:protocol:begin/end
之间，其他内容原样不动，幂等可重跑。不想动用户目录时，也可
python scripts/yyuan.py <命令> 转发到同目录 mem.py。

> 退化说明（重要）：若宿主不按协议执行 session-start，本技能不会自动注入记忆，
> 但仍是完整可用的——你可直接说「记一下…」「回忆一下…」、消息以 y 开头，
> 或手动跑 python scripts/mem.py <命令>。协议只是把触发率拉到接近 100%，不是唯一入口。

参考文档（进阶内容按需查阅）

以下内容在 references/REFERENCE.md（随包分发），日常使用不必读：

> 主文档只留每天都要用的部分：定位、触发、上手、分工、存储、工作流、
> 类型与分层、3 层检索、写入、会话、隐私、Viewer、配置、命令速查、记忆协议。
> 完整命令参数一律 python scripts/mem.py <命令> --help 查，不在文档里抄一遍。