Agent Skill

AI Agent 记忆系统

同一个坑踩两遍,讲过的背景再问一遍——它每轮都从零开始。装上之后它记的是自己的失误:踩过的坑、被你纠的错、验过的结论;旧结论被推翻只标「已取代」、原文留着,半年后问「当初为什么那么判」,答得出。装完说「帮我一键配好」,重启一次就上岗——默认开场注入一次、之后不每句翻记忆,想让它每句先翻旧账就补一句「开全量模式」,代价是每轮闪一下。开会话它先把相关的旧经验摆上桌;中途踩的坑、收尾定下的结论自己挑出来存,只挑你认过是经验的那几句,不搬整段对话;只在想改它行为时出声:「记一下」「找一下之前关于 XX 的」「这条作废」。它还会自己保养:挡掉没判断的空话、给冷下来的降权、让矛盾的互撞一次;装了调度每周跑一次、漏了下次补,环境不让装(如计划任务被安全策略拦)就说「帮我保养」手动跑。做错了能退:只归档、从不静默删除,每一步都能回滚;说「帮我体检」它把状态摊开。记忆在你自己机器上,没有账号、没有云同步——不上云就没有能被拖走的副本,代价是换台电脑自己搬;想撤一条命令卸掉,记忆留着。

AI Agent·路人甲·来自 skill_hub·skillhub.cn ↗
skillhub install @user_7db0c006/agent-local-memory-keeper
10 Stars·7万 综合热度·15,413 字文档·源站更新 2026-11-22

README 文档

15,413 字

AI Agent 记忆系统

急着用? → 下方「🚀 现在就开始」3 步照抄即可;只要最短版 → QUICKSTART.md(2 分钟)。 界面闪了「执行中」? 那是平台的钩子指示器,不是本 skill 的弹窗,也关不掉——机制与四档取舍见下方「🪟 界面那个『执行中』提示条」一节,不关心可整节跳过。

它替你记住:踩过的坑、纠过的错、验过的结论、被推翻的旧判断。 它靠这些记录改进自己:记的是「我上次错在哪」而不是「你喜欢什么」——旧结论被推翻时标「已取代」而不删,所以还答得出「当初为什么那么判」;可每周抽样复判「这条现在还成立吗」,不成立的降权、含糊的进观察名单。没有联网学习,数据不出本机,唯一的进化来源就是这些记录。详见「🔁 它怎么改进自己」。 你日常只需说两句:「找一下之前关于 XX 的」「这条作废」——其余(捕获、去重、分类、分层、归档、体检)由钩子在会话结束时自动跑。「作废」有四种落点,见下方「🧩 改 / 删四选一」。 钩子是事件触发的一次性子进程(会话开始/工具调用后/会话收尾各跑一次),没有「一直盯着对话」的监听进程;召回加速用的本地 daemon(默认开)首次召回时懒启动并常驻,只服务召回、不盯对话,可 keeper.recallmode: "inprocess" 关掉。定时任务只有一个:setupscheduler.py 注册的 KeeperSelfHeal 每周日 03:00 跑一次 self-heal,routine/周/月由命令内部按水位分派(周档=距上次 ≥6 天,留一天容差;月档=跨自然月);漏跑不用管,下次运行会发现「上次没跑完」并补上。连调度都装不上(如计划任务被安全策略拦)时,会话开局会读水位、超过一周没保养就在后台补跑一次——所以别另建 reflect/衰减/周维护任务:三处各写各的频率,任一处错过窗口就是永久缺失。想立刻保养就说「帮我保养」。细节见 references/COOKBOOK.md §3。 纯本地零云端;整理只归档,永不静默删除。

🧩 改 / 删四选一:「这条作废 / 记错了」到底走哪条命令

全库最容易选错的一处:同一句话落到四个后果完全不同的命令,其中只有一个是不可逆的。先答三问,再动手;AI 也照这张表执行,不自行猜测。

你的情况对 AI 说落到命令后果能否撤销
有新结论,旧结论被它取代「这条被取代了:<新结论>」deposit --corrects <旧id>新建一条 + 旧条标 superseded + 连边,可回溯「谁取代了谁」能(rollback / 版本链)
没有新结论,只是不再成立「这条作废了」invalidate --id <id> --reason "…"软失效:写 invalid_at,默认不再召回;原文保留,仍可查「当时为真」能(uninvalidate)
它从一开始就是错的(误记 / 幻觉 / 判断不成立)「这条记错了」forget --id <id> --forget-reason "…"标 erroneous、belief_strength=0,停止召回,内容不删能(feedback / reclassify)
必须彻底消失(含敏感信息、写错了文件)「删掉这条」「永久销毁」delete --id <id> --yes物理删除❌ 不可逆,最后手段

三问定序:

  1. 手上有没有新结论?有 → 第一行(唯一会新增条目的一行,也是「取代」语义的正确入口)。
  2. 是「曾经对、现在不对」还是「从来就不对」?前者 invalidate,后者 forget。
  3. 真的不能留痕吗?只有这一条走 delete;本 skill 其余全部路径只归档、不删内容。

--by 的硬约束:invalidate --by <新id> 只接受已存在的 id。传不存在或含路径穿越的 id 会直接 bad_arg(rc=5)并给出替代命令,不再写出悬空关系边。所以「手上只有话、没有新 id」的场景必须走第一行——deposit --corrects 会先建新条目再连边,不需要你预先知道新 id。

🔁 它怎么改进自己(这是本技能的核心,不是附加功能)

普通「AI 记忆」记的是你:偏好、背景、约定。本技能记的是它自己:踩过的坑、被你纠过的错、 验过的结论、被推翻的旧判断。差别在于——前者让 AI 更懂你,后者让 AI 少犯同一个错。

闭环有四层,每层都有对应的命令,不是口号:

层做什么落在哪里
1 记只收「有判断」的句子:踩坑、纠偏、验证过的结论。工具调用失败也记一条坑(按退出码/沙箱拒绝判定,不记报错原文——平台不下发输出正文)钩子在会话收尾时跑,deposit
2 连新结论出现时给旧条目连 superseded 边,而不是删掉——所以「当时为什么那么判」永远查得到deposit --corrects <旧id>
3 判可每周抽样复判「这条现在还成立吗」,六种结论各有独立处置(下表)。判不出就叫 defer,不许猜。这一层需要 LLM:本地 Ollama 或任一在线端点;没有引擎时整层跳过并明示「未做任何判定」(刻意 fail-closed,不伪造结论)settle-probe
4 退判过的不再每天重判(冷却),但「该合并/该作废」的提醒一直挂在报告里,直到真的处置store/settle_state.json(首次真正判过一条后才生成;此前不存在是正常的)
5 回池「判过」不等于「永远不用再看」:按周档限量(默认每周 10 条)把最老、且从未复查过的放回复判池;每 id 另有 12 周冷却,防同一批每周打转requeue(默认预演)/ requeue --apply

第 3/4 层跑到哪了,别靠猜:doctor 的 settle 块会写「待判 N 条 / 引擎 有·无 / 上次判定日期」。 没有 LLM 时它会长期显示「待判 N 条、从未判定」——这是如实反映,不是坏了;装好引擎后下一次 周档自愈就会真正开判,settle_state.json 也才第一次出现。所以「没判过」只有两种可能: 引擎缺席,或还没到周档水位,doctor 一看便知。

复判的六种结论

verdict含义settledconfirmed冷却谁来做下一步
settled成立且证据足够定案置 True+1出池promote 可升 curated
correct成立,但证据不足以定案不置+130 天继续观测
defer信息不足以下结论不置不加7 天补上下文后重判
merge与另一条重复不置不加14 天reflect 合并
supersede已被新结论取代不置不加14 天deposit --corrects
reject内容不成立或垃圾不置不加7 天forget --id

为什么 correct 不置 settled:settled=true 是 promote 的唯一准入门,而 promote 会把它 升成 curated。「内容对」和「足以升到最高等级」是两件不同强度的证据——绑在一起就等于用一个词 表达两种证据强度,于是「正确但不够格」只能借 reject(语义是「垃圾」)表达。

为什么判不出必须有自己的落点:以前 prompt 写的是「判不准时输出 merge」,等于把「判不出」 记成「该合并」,下游真会去合并两条不相干的记忆。

边界(这是设计选择,不是能力不足):

  • 不联网学习:没有在线训练,没有把记忆发出去做 RLHF。唯一的输入是你和它的对话本身。
  • 复判结论(merge/reject)只写建议,处置动作由人(或会话内 Agent)显式执行——

「像不像重复」「够不够格」这种判断证据不足,擅自改 status 会造成「一条命令把条目弄丢」。

  • 但「强修正」会自动取代:deposit 时若三条同时成立——① 新条带旧条没有的具体信息;

② 是明确的否定式修正(含「作废/推翻/不成立」,或「已实测/复现 + 与旧说相反」); ③ 新条质量不低于旧条——旧条自动标 superseded。缺任一条就两条并存,交给人裁。 取代≠删除:原文保留、--include-superseded 可查、rollback 可回滚。 这条是故意放宽的:留着作废结论在 active 里,下一次召回就会把它和新结论一起端出来, 于是「同一个坑踩两遍」——宁可标错可回滚,也不让错的结论继续被当成事实。

  • 不删只降权:过时标 superseded,失效写 invalid_at,两者都可回滚、可查「当时为真」。

🔴 先读 3 条(动手前扫一眼,不读可能丢数据)

  1. 清理用 archive,别拿 delete --yes 当常规清理:delete --yes 是真删、不可找回;archive 软归档沉底,recall --deep 仍可找回。不确定先 --dry-run。
  2. 别把对话原文灌进记忆:只记提炼后的结论(坑 / 纠正 / 最佳实践),当录音笔用会让召回质量塌方。
  3. 更新完,对 AI 说一次「帮我一键配好」:钩子 / 守护进程的部署副本会在你下次跑命令时自检滞后并后台补刷,但那要等你恰好跑一次命令,且刷完必须重启 WorkBuddy 才生效;当场重跑能立刻收口,还顺带告诉你差在哪一版。

👉 红线完整版见下方「🔴 红线与边界」(唯一真源);用法避坑见「📌 反模式清单」(唯一真源)。看不懂的词(降级 / 幂等 / fail-closed / ANN 等)→ 查 references/GLOSSARY.md。

🚀 现在就开始(3 步,每步照抄对话)

步你做什么对 AI 说(照抄)
1装上 skill(装完即获默认能力,零配置)
2配好「帮我一键配好」 ← 钩子 / 守护 / 中文语义一次收口
3开用「记一下这个坑:……」 / 「找一下之前关于 XX 的记忆」

💡 只想手动记/找、不要后台进程? 完全可以——跳过自动记忆,直接说「记一下 / 找一下」照样工作。守护进程不是必需的。 💡 装完/更新完体检:对 AI 说「帮我体检」;重点看体检结果里「语义后端是否降级」这一项——若显示降级,说「帮我一键配好」即可修。

🧭 万能导航表(主轴 1 · 想做什么 → 去哪)

全文档唯一索引:先找「我想做/我遇到」,对 AI 说那句话;想深入再看对应文档。 不再多处翻。

我想做 / 我遇到对 AI 说(照抄)想深入看
记一条经验 / 纠正旧结论 / 作废「记一下:……」「这条被取代了:<新结论>」「这条作废了」本页「🧩 改 / 删四选一」
找记忆 / 换说法搜「找一下之前关于 XX 的」TUTORIAL.md
整理 / 去重 / 归档「帮我整理今天记的」TUTORIAL.md
搜不到 / 结果差 / 语义降级「为什么找不到……」「帮我一键配好」QA.md
记不进去 / 报错了「记不进去了」QA.md
弹窗太烦「关掉弹窗」本页「🔧 配置指引」
开自动注入 / 自动记忆「开启自动注入」「先别自动记」本页「🔧 配置指引」
配 IMA 云端同步「配 IMA 知识库同步」COOKBOOK.md
装本地大模型「帮我装本地大模型」INSTALL.md
跨电脑搬记忆「把记忆搬到 U 盘」COOKBOOK.md
备份 / 恢复「备份一下记忆库」COOKBOOK.md
看库整体状况 / 还能开啥「看看库的整体状况」「我还能开哪些功能」ENABLEMENT.md
查所有命令参数「XXX 命令有哪些参数」COMMANDS.md
看不懂黑话「降级是什么意思」GLOSSARY.md
特性原理(召回/矛盾/加速)「召回是怎么工作的」FEATURES.md
投资记忆「投资记忆怎么用」INVESTMENT.md

💬 场景对话实操(主轴 2 · 6 大类,每类都有演示)

格式统一:👤 你说什么 → 🤖 AI 做什么。所有能力都能说人话触发,AI 回显「已记 / 已找到」确认生效。 ①② 是每天都在用的两条,给完整演示;③–⑥ 各一句触发语,逐条演示与真实返回样例见 references/TUTORIAL.md。

① 记(存经验)

👤「记一下:DuckDB 同一文件两个进程同时开会锁住」
🤖 写入经验 + 自动去重 + 自动分类,回显「已记 1 条」
👤「这条结论被新方案取代了」
🤖 把旧结论标为「已取代」,不删除、可回溯

想一次记多条、纠正旧结论、放行自动暂存——直接说人话,AI 知道该调什么。

② 找(召回)

👤「找一下之前关于 DuckDB 锁的记忆」
🤖 按语义召回,回显命中条目;可能问「这条有用吗」,回「有用 / 没用」
👤「这条经验在 2026-08 那会儿还有效吗」
🤖 按时间点回溯查询,照「何时生效、何时失效」判定

想查「某条为什么被召回」也可以直接问 AI,它会拆给你看评分和来源。

③–⑥ 其余四类:一句话触发

类你说AI 做什么
③ 整理「帮我整理今天记的」「把相似的记忆归归类」去重 / 纠错 / 归档(永不删),回显「去重 N / 纠错 M / 归档 P」;归类只给候选组,逐组问要不要合并
④ 配置「关掉弹窗」「配 IMA 知识库同步」切静默档 / 配 IMA(推送前强制脱敏);改完钩子模式重启 WorkBuddy 生效
⑤ 排错「为什么找不到我之前记的?」跑体检读真实状态 → 定位根因 → 给解法 → 复检确认。6 类症状对照见 references/QA.md
⑥ 维护「备份一下记忆库」「把记忆搬到另一台电脑」打包备份(回显条目数与校验值)/ 合并式同步(保留两台电脑各自的新记忆)

工作区绑定为什么要你点头一次:开局注入的第一源是「结构化绑定」——字符串相等即命中,是唯一不需要相关性阈值的精确源。它要的是项目归属,而 subdomain 是主题词、cwd 是目录名,靠猜只会把整库都算成「本项目」;所以钩子只做两件事:认出项目根、把没确认过的登记成候选,匹配值必须你确认一次才生效。doctor 的 workspaces 块可查,给错值用 workspace --forget <路径>。完整说明(含「没有标志文件的目录也算候选」)见 references/TUTORIAL.md §10.1。

🗣️ 40+ 条低频操作的口语对照(看版本历史 / 建关系图谱 / 发布前查泄漏…)已移到 references/COMMANDS.md 末尾「口语 → 命令速查」——那是给 AI 查的表,你不用看,说人话即可。 🧭 CLI 入口(别混用):memoryops → 库管理全量;membridge → WB 集成层(标「仅 mem_bridge」的命令只在第二个入口存在)。查参数用 <命令> --help,只列该命令实际读取的参数。

🧬 蒸馏 ≠ 变 skill:这一步永远由你决定

很多人把这两件事混成一件事,于是担心「它会不会自己把我的经验打包成技能」。先把边界说死:

蒸馏(distill)变 skill(extract-skill)
做什么把多轮对话里的经验压缩成一条记忆入库把已达标的经验集合生成为一份可分发的 skill 脚手架
产出落在哪你的记忆库(memories/),形如 LRN-…json一个目录(默认 auto_skill/):SKILL.md + references/ + hooks/ + README.md
会不会自动发生会(收尾钩子 / distill 都可触发),且产物默认进待审队列,没人放行召回不到绝不自动发生:必须有人显式执行 extract-skill;自愈循环里那条「自动发现」分支(--discover)默认关闭
谁决定系统自动做,你事后可作废你。工具只负责把候选摆给你看

一句话判据:只有「同一类经验反复出现(recurrence ≥ 3)、已经稳定、换台机器照样成立」才值得固化;只是一条孤立的坑、经验还在快速变化、或只在你这台机器成立——都别变;只是想「让 AI 别忘了」,那正是记忆该干的事。

决定流程三步,随时可停在第一步:extract-skill --preview 看预览(只读库,回答「哪些 area 达标、会落到哪个目录」,不建目录、不写文件、不登记)→ 你按上面判据判断(不满意就到此为止,记忆一条没少)→ 确认要才去掉 --preview 跑一次。

🔴 本 skill 的任何自动流程都不会替你生成 skill:收尾沉淀、自愈循环、每周维护都不碰 extract-skill。唯一会自动「同步更新」的是你已经建过的 skill(skillsync 只改围栏内的模式清单,不新建、不改你的正文),可用 KEEPERAUTOEXPORTRULES=0 之类开关关掉自动写。决定权始终在你手上。

📖 意图(为什么值得升级)/ 好处 / 坏处与代价 / 四条否决的展开 / 五个常见误解 / 决定流程详版 / 「同意后怎么交给专家做扎实」——全在 references/SKILL_DISTILL.md,本节只留决策卡。 🧑‍🔧 真要变 skill,建议改用专家「资产设计与质量顾问」(戴明 / asset-architect)落地:脚手架只会「按技能造」,专家才会回答「这需求其实该做成专家」或「根本不值得固化」,并管住字段铁则、行为实测与发布前脱敏 / 真机路径 / 版本号残留。分工是:要不要变 —— 你决定;变成什么样才算合格 —— 专家负责。

🪟 界面那个「执行中」提示条:它是什么、谁管它、我们能改到哪一步

一、先定性:它是平台的行为,不是本 skill 的弹窗

装了本 skill 后,你可能会看到界面短暂显示一条「执行中」提示。这条提示不属于本 skill——本 skill 没有、也无法创建任何窗口:全部代码里没有任何 MessageBox / windll / startfile 调用,所有子进程启动都带 CREATENOWINDOW(0x08000000),由门禁 staticnopopupspawn 逐处守着——当前 42 个文件 / 13 处 spawn 点全绿,这组数字由 testpopupspawn_gate 实算比对,加了文件没更新会当场变红。所以它也不是 Windows 黑窗。

它是 WorkBuddy 客户端对「钩子正在执行」这一事实的可视化指示器。换任何别的 skill,只要挂了钩子,同样会显示。它的显示、停留、消失都由客户端控制——skill 侧既没有开关也没有协议字段能隐藏它(钩子输出协议只有 {"continue": ..., "hookSpecificOutput": {...}} 两种键)。

二、能力不能退:四档怎么选(附召回影响)

降低提示条频率的唯一手段是减少钩子触发次数,而每砍一次触发就少一次自动召回。这个代价必须写清楚:

模式注册钩子每轮自动召回召回能力影响提示条
full(能力最全)全部 5 个有无损失——AI 每轮都带着相关经验开口开场 + 每轮(现已缩短约一半)
minimal(出厂默认,也是「帮我一键配好」装的档)4 个(砍 UserPromptSubmit)仅开场一次⚠️ 有损失:对话中途不再自动补召回,改由 AI 主动 recall。实测每轮真命中率约 15%,这部分命中机会即丢失仅开场
silent3 个功能钩子无⚠️⚠️ 明显损失:连开场注入也没有,全靠主动提问基本不闪
off0无⚠️⚠️⚠️ 连「报错审计 / 收尾沉淀」也没了不闪

选择原则(默认求静,能力自己开):

  • 一键配置装 minimal:新用户第一分钟最怕「这玩意儿一直在动」,而 minimal 保留了 SessionStart 开场注入——装完第一次开会话就能看见「我记得你之前的坑」,产品价值一眼到手;代价是中途的那 15% 不自动补。
  • 想每轮都自动带着你的坑 → full。提示条无法消除,但最坏耗时已从 5.1 s 降到 约 1.7 s、短句(<6 字)降到 约 0.24 s,这个优化先吃掉再决定要不要升档。
  • silent / off 只在排查钩子故障时临时用,不作日常。

注意时序:--set-mode 是唯一会写档位的入口(写进 hooks_config.json)。all / 重装 / 更新都不会覆盖你已有的档位;连「从没写过配置」的老用户也不会被降档——没有配置时会先看 settings.json 里已经注册的钩子,按实际部署的档位沿用。想换档只能显式跑 hooks --mode ...。

对 AI 说「恢复完整钩子」→ full;「开场注入保留、别每轮闪」→ minimal;「关掉弹窗」→ silent。命令行等价:python scripts/keeper_setup.py hooks --mode full|minimal|silent|off。改完重启 WorkBuddy 生效。

🧭 5 个钩子分别做什么、提示条为什么必然存在、停多久、两层性能根因、为什么改不掉 → references/COOKBOOK.md §1.1。本节只回答「能不能关」(不能)和「我该选哪档」。

一句话:提示条是平台的,改不掉;钩子是我们的,已做到当前平台限制下的最快,且没有牺牲任何召回能力。

🔧 配置指引(哪些要配、怎么配、对 AI 说什么)

一句话:对 AI 说即可,AI 背后跑 scripts/keepersetup.py,不用手敲环境变量。你可能手设的只有一个:AIMEMORYSTORE(记忆库根目录;回退链 AIMEMORYSTORE → ~/.keeper/storeroot → 平台默认)。

钩子模式(弹窗开关)

四档与完整代价见上文「二、能力不能退:四档怎么选」那张表——这里不再重复第二张:同一份档位说明写两遍,两处必然各自漂移(此前正是如此:上面写 minimal 是装的档、下面写着 full(默认),用户读到的是自相矛盾)。

切换:说「恢复完整钩子」或「开全量模式」(→ full)/「开场注入保留、别每轮闪」(→ minimal)/「关掉弹窗」(→ silent),命令行等价 python scripts/keeper_setup.py hooks --mode full。改完重启 WorkBuddy 生效。

🔴 知道自己在换什么:砍掉 UserPromptSubmit 就少一次自动召回。实测每轮真命中率约 15%,minimal 丢的正是这部分机会。所以这条损失必须写进文档、写进安装输出,让用户自己按「安静 vs 15%」拍板——不许静默降档。

⚠️ scripts/keeper_setup.py all 装的不是「全开」:它装 minimal 档(SessionStart/PostToolUse/Stop/PreCompact 四个),不注册 UserPromptSubmit、也不挂定时调度。跑完 all 界面不闪是正常的(不是没装上)。要每轮注入得显式 hooks --mode full;要定时维护再加 --scheduler。

常用开关(说人话就切)

你可能想问对 AI 说落到哪个键(出厂默认)
太吵,不想每句都翻记忆「关掉自动注入」/「关掉弹窗」injectenabled(✅ 开)/ hooksmode: silent
不想让它自己记「先别自动记」/「每天上限改成 30 条」autocapture(✅ 开)/ autocapturedailycap(20)
工具报错要不要入库「把工具报错也记成记忆」pitfall_capture(⛔ 关——平台只给退出码,产出必是命令回显,实测零复用)
收尾整理太频 / 太疏「改成每 50 轮」converse_threshold(20;库 >500 条自适应 40)
召回太慢 / 想省内存「召回改回进程内」recall_mode(daemon,热路径 ~0.35 s/次,约 +90 MB)
想每周自动保养「建一个每周自动整理的定时任务」出厂关;setup_scheduler.py 注册每周日 03:00 跑

🔴 默认值不在本文件抄第二份:20 个键的含义 / 默认 / 何时动,唯一真源是 references/FEATURES.md §11;4 个「有键无引导」开关的验证方法在 §12。两处各写一份必然漂移——本仓就出过「同一张表写 injectdedupdays 默认 14、而代码与 FEATURES 都是 1」的事,本次已按代码修回。

需你动手的只有两处:配外部资源——IMA 云端同步(说「配 IMA 知识库同步」)、本地 LLM/Ollama(~5GB)。 另有 2 个出厂故意关闭的行为开关(conversewithworkbuddy、pitfall_capture)——都不是「没做」,是实测收益为负才默认关,想开说一句即可。 其余运行时开关收口在 store/config.json 的两个块里,优先级 env > store/config.json > 默认值:

  • keeper 块——行为开关(自动注入 / 自动记忆 / 写入门 / 嵌入后端),与代码 KEEPER_DEFAULTS 一一对应,见下方示例。
  • recall 块——召回排序与性能调参(semanticgate 离题门控、rankwsem/rankwjac 排序权重、rrfk、rerank*、frequencytracking),与 RRF_DEFAULTS 一一对应,全量清单见 references/FEATURES.md §5(不在此处写死条数——数字型承诺必漂移)。平时不用动,只在「召回不准」时才调;改完无需重启(缓存键含配置签名,配置一变缓存自动失效)。
{
  "keeper": {
    "embed_backend": "fastembed",
    "embed_online_url": "",
    "inject_enabled": true,
    "inject_fuse_cap": 100,
    "inject_daily_cap": 6,
    "inject_dedup": true,
    "inject_dedup_days": 1,
    "feedback_session_cap": 3,
    "rehearsal_alpha": 0.05,
    "ann_min_memories": 50,
    "ann_auto_large": false,
    "auto_capture": true,
    "converse_threshold": 20,
    "auto_capture_daily_cap": 20,
    "pitfall_capture": false,
    "converse_with_workbuddy": false,
    "write_gate": true,
    "layout_guard_enabled": true,
    "related_to_min_sim": 0.25,
    "link_scan_min_sim": 0.2
  }
}

⏱️ 改完什么时候生效(两个块不同):用环境变量(如 KEEPERINJECTENABLED=0)设的值走环境变量映射层,实时叠加、立即生效;写进 store/config.json 的 keeper 块按 root 缓存,需要新进程(重启 WorkBuddy / 重开 CLI)才读到新值。改完 JSON 当场没变化是正常的,别误判成「没改对」。

🎚️ 4 个「有键无引导」的开关(injectdedup / injectdedupdays / rehearsalalpha / writegate)动之前先看影响面——逐键说明并入 references/FEATURES.md §11 的 20 键全表(那里是配置键的唯一总览,本节不再抄第二份,避免两处漂移)。 ⚠️ 「每 N 轮自动沉淀」的边界(别当成纯自动):阈值只在「AI 真的在调 converse」时才有意义——钩子只在会话结束(Stop) 兜底跑一次 converse --end(每会话至多一次)。所以「20 轮」只在下限意义上成立(= 会话结束必有一次沉淀)。想让沉淀真按轮次发生,请把「每轮调 converse --text 记本轮要点」写进会话约定(如 AGENTS.md)。conversewith_workbuddy 只被会话结束钩子读取,手动跑 CLI 的 converse / harvest 不受它影响(要读 WB 原生记忆必须显式 --with-workbuddy)。详见 references/COOKBOOK.md §1。

🔴 红线与边界(唯一真源)

🔴 红线分两组:数据类(不可逆/会丢会泄)与质量类(数据还在,但你被误导)——两组都不可破,无论你怎么说 AI 都守。

A · 数据类红线

  • A1. 绝不批量硬删:reflect/archive/decay 只做去重·纠错·归档(软保留,recall --deep 可找回);唯一真删是显式 delete --yes,单次单条。
  • A2. 删必须显式 --yes:不带 --yes 的删除一律被拒、文件原样保留。
  • A3. IMA 明文库强制脱敏:推送前自动 strip 凭证/真实路径/邮箱,脱敏后复检;任何残留直接失败退出,绝不交付明文。

B · 质量类红线

  • B1. 静默质量退化必须显式可见:语义后端失败会退回词法(召回 ~90%→~30%)。recall --with-meta 返回 meta.fellbacktolexical,空结果附 emptyhint(含修复命令),注入时降级在上下文显式追加「⚠️ 请转告用户」提示——绝不允许「降级了但没人知道」。
  • B2. 重要记忆分类强制:importance ≥ 0.7 且低置信自动分类时,标 classify_review 并告警,不静默猜分。
  • B3. 召回必须带预算,不许把全库灌进上下文:recall --query 缺省已是 20 条 / 6000 token(--limit 改条数、--max-tokens 改预算)。不要习惯性加 --all——那是解除上限、把整库倒出来,只在明确要全量对账时才用。命中上限时输出会带 "total": <全量条数>, 看到它就知道「不是只有这些」,需要更多就翻页(提 --limit)而不是 --all。
  • B4. 自动蒸馏必须过人工闸:钩子捕获、distill、harvest、reflect 自动产出的条目一律带 pendingreview=true 写入——任何召回路径都读不到它(含 --include-auto、含两个注入钩子),直到你跑 review 逐条放行。这是硬闸不是标记:唯一解锁入口是 review --approve <id>(内部转 confirm:清 pendingreview + reviewed=true,可带 --tier 顺带升层)。review --reject <id> 进归档区(可 unarchive 回滚),不物理删除。

人工把关的完整闭环(review)

自动蒸馏省的是「写」的成本,不该省「判断」的成本。所以每条待审条目都配一张说明卡,四个问题一次说清:① 蒸馏的是什么(摘要 / 正文 / 类型 / 域 / 标签 / 来源 / 层级 / 时间)、② 什么作用(放行后走哪条链路 + 可复现的自检 query)、③ 利(补不补空白、是否与既有条目重复、几个可执行锚点、丢弃的代价)、④ 弊(占 TOP-N 与 token 预算、最相近条目、正文/锚点/悬空指代、置信度、敏感命中)。给出建议动作(approve / edit / reject / hold)与理由,多条判据同时命中时全部列出、动作取最严的一档;review 默认只读,不替你拍板。

待审队列会自动初审(review --triage),按可判定的形态分三档:reject(质量门判拒 / 「自动蒸馏:」前缀的对话残片)、approve(结构完整:有 category、summary ≥20 字、body ≥80 字、有 domain 或 subdomain)、manual(其余——principle 与 srcorigin=selfevolve 一律进此档,自动进化产物若也被自动放行,等于自己写自己批)。默认只读,--apply 才执行且只动前两档(reject 走 archive,可 unarchive 找回);self-heal 的 routine 档只巡检上报、恒定只读(自动归档几十条是删数据级动作,必须人拍板)。批量放行(不带 id)必须显式 --yes 且逐条回报——批量是不可逆动作里最容易出错的形态。

四段说明卡的字段依据、全部命令与参数、机读版与审阅报告导出 → references/COMMANDS.md「审阅与放行」。

待审条目不会被忘掉:doctor 的 review_queue 报数量与超期天数(>14 天标记 overdue),SessionStart 钩子每次开局注入一行待审提醒(独立于经验注入开关——否则关掉注入就等于把这件事永久静音)。reclaim 对长期(默认 365 天)未处理的暂存条目按既有 TTL 清理。

边界(设计使然,非缺陷)

  • 环境级故障(Python 缺失/模型下载失败) → 系统不会静默扛:每次调用都会提示分类原因 + 针对该原因的修复命令(默认 60s 一条防刷屏,AIMEMDEGRADEHINTINTERVAL=0 可每次必提),并指向 doctor --embed 一键诊断。首次体验三件事(等多久 / 占多少磁盘 / 降级了怎么修)集中在 references/INSTALL.md §1.1。
  • 清理类命令怎么选:purge 不是通用清理——只真删「已归档/已被取代」且超龄(180天)+低重要度(<0.4)的软删件,active 条目(含今天刚记的)永不在候选内。清「今天的」用 reflect --auto 或 archive。
  • 域分类落空 = domain=None,是设计不是缺陷:未命中域 → 存 domain=None(非丢失);想自动落域显式设 KEEPERDOMAINFALLBACK=<域>(默认关)。

防 AI 反复确认死循环:feedback 每会话 3 次校准闸 + 每日注入熔断闸(injectfusecap 默认 100 次/日)兜底;说「不用校准/不用注入」即切断。

📌 反模式清单(❌ 错误做法 → ✅ 正确做法)

❌ 反模式✅ 正确做法
把整段对话原文灌进记忆只记提炼后的结构化经验结论
用 delete --yes 当常规清理先 archive 软归档,真删才 --yes;不确定先 --dry-run
重要记忆不显式传 --scene/--type显式传值固化分类,否则 classify_review 告警
直接 rsync memories/ 跨设备同步用 backup ZIP + restore(避免 WAL/SHM 撕裂)
手动改/删 memories/*.json走 op;改坏用 rebuild / doctor --fix
AI 反复"再确认"死循环说「不用校准/不用注入」
直接拿 scripts/ima_bridge.py export 裸产物上传走 scripts/ima_sync.py(强制脱敏+复检)
把 secrets/明文密钥写进记忆只记方法不记 key;命中自动隔离 quarantine
库 <50 条硬开 ANN保持默认:50–256 条自动启用(等价全量、零损失),>256 条要显式开 annautolarge
benchmark 不指定 --root 就跑必须显式 --root <隔离目录>

📚 每条「为什么错、踩了会怎样」→ references/QA.md §四(14 个避坑详解),与上表互补。

📚 文档地图(每份一句话,按需查)

文档一句话
QUICKSTART.md2 分钟极简上手
references/CAPABILITY_MAP.md能力总图:想做 X → 跑哪条命令 → 看哪篇文档
references/TUTORIAL.md分步教程 + 真实返回样例
references/QA.md排错速查 + 14 条避坑详解
references/recovery_runbook.md四类高频故障(锁/索引/SQLite/向量)的处置步骤
references/COMMANDS.md所有命令 + 参数 + 真实返回样例
references/COOKBOOK.md钩子/守护/定时/IMA 实操配方
references/INSTALL.md安装、fastembed/Ollama 排错、旧版迁移
references/LIMITS.md限制、性能边界、红线详版
references/FEATURES.md特性原理(召回/矛盾/语义后端/ANN)
references/ENABLEMENT.md能力开启「三桶分类」向导
references/GLOSSARY.md黑话术语大白话速查
references/MEM_BRIDGE.mdmem_bridge 全部桥接命令
references/FORMAT_ANALYSIS.md存储架构/数据模型
references/TYPE_TAXONOMY.md记忆类型/场景/域 的分类体系
references/taxonomy_wizard.md用对话引导生成你专属的记忆分类树
references/INVESTMENT.md投资域专属(模型/模板/校验)
references/investment_templates.md投资域 4 层记忆(数据→因子→测试→组合)模板
references/investment_taxonomy.json投资分类树数据(域/关键词/热位预算,脚本读取)
references/SKILL_DISTILL.md蒸馏 ≠ 变 skill:意图、好处、坏处、判据、决定流程、同意后怎么交付给专家
根 CHANGELOG.md版本历史(唯一权威源)

投资记忆能力圈(投资域)

keeper 原生支持「投资」域:数据/参数 → 因子 → 因子测试 → 组合系统,四层对象全记住、能关联、可回溯。完整模型见 references/INVESTMENT.md。

  • 冷启动:对 AI 说「初始化投资记忆」即可(旧入口「量化」已废弃)。
  • 走「记 + 验」闭环:投资结论从 DuckDB 复算回检,对 AI 说「校验这条投资结论」。

常见问题(精简 6 条,其余见 references/QA.md)

  • 误删了能恢复吗? 能。查这条的历史版本一键回滚,或用备份包整库恢复;删除前优先归档(可找回)。
  • 「整理」会删记忆吗? 不会。只去重/纠错/晋升/归档,绝不删除;「遗忘」只是降权 + 归档,随时可找回。
  • 中文换说法搜不到? 多半是语义模型降级了。让 AI 跑 python memory_ops.py doctor --embed——它会打印后端状态、缓存占用、模型完整性,以及你该敲的那条修复命令(缺包/网络/损坏/内存四种原因修法不同,不会一律让你重装)。降级期间功能照常可用,只是漏召概率上升。
  • 需要联网吗? 默认纯本地零云端;仅首次装语义模型 / 可选本地大模型需联网一次。
  • 记忆存在哪/怎么备份? 默认在本地用户目录(Windows ~/AI记忆、mac/Linux ~/.ai-memory);说「备份一下」导出压缩包,「恢复一下」还原;跨电脑合并迁移说「搬到另一台电脑」。
  • AI 反复"再确认"死循环? 说「不用校准/不用注入」,或让 AI 关掉这个开关。

同分类其他技能

查看全部 ›