AI Agent 记忆系统
同一个坑踩两遍,讲过的背景再问一遍——它每轮都从零开始。装上之后它记的是自己的失误:踩过的坑、被你纠的错、验过的结论;旧结论被推翻只标「已取代」、原文留着,半年后问「当初为什么那么判」,答得出。装完说「帮我一键配好」,重启一次就上岗——默认开场注入一次、之后不每句翻记忆,想让它每句先翻旧账就补一句「开全量模式」,代价是每轮闪一下。开会话它先把相关的旧经验摆上桌;中途踩的坑、收尾定下的结论自己挑出来存,只挑你认过是经验的那几句,不搬整段对话;只在想改它行为时出声:「记一下」「找一下之前关于 XX 的」「这条作废」。它还会自己保养:挡掉没判断的空话、给冷下来的降权、让矛盾的互撞一次;装了调度每周跑一次、漏了下次补,环境不让装(如计划任务被安全策略拦)就说「帮我保养」手动跑。做错了能退:只归档、从不静默删除,每一步都能回滚;说「帮我体检」它把状态摊开。记忆在你自己机器上,没有账号、没有云同步——不上云就没有能被拖走的副本,代价是换台电脑自己搬;想撤一条命令卸掉,记忆留着。
skillhub install @user_7db0c006/agent-local-memory-keeper
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 | 物理删除 | ❌ 不可逆,最后手段 |
三问定序:
- 手上有没有新结论?有 → 第一行(唯一会新增条目的一行,也是「取代」语义的正确入口)。
- 是「曾经对、现在不对」还是「从来就不对」?前者
invalidate,后者forget。 - 真的不能留痕吗?只有这一条走
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 | 含义 | settled | confirmed | 冷却 | 谁来做下一步 |
|---|---|---|---|---|---|
settled | 成立且证据足够定案 | 置 True | +1 | 出池 | promote 可升 curated |
correct | 成立,但证据不足以定案 | 不置 | +1 | 30 天 | 继续观测 |
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 条(动手前扫一眼,不读可能丢数据)
- 清理用
archive,别拿delete --yes当常规清理:delete --yes是真删、不可找回;archive软归档沉底,recall --deep仍可找回。不确定先--dry-run。- 别把对话原文灌进记忆:只记提炼后的结论(坑 / 纠正 / 最佳实践),当录音笔用会让召回质量塌方。
- 更新完,对 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%,这部分命中机会即丢失 | 仅开场 |
silent | 3 个功能钩子 | 无 | ⚠️⚠️ 明显损失:连开场注入也没有,全靠主动提问 | 基本不闪 |
off | 0 | 无 | ⚠️⚠️⚠️ 连「报错审计 / 收尾沉淀」也没了 | 不闪 |
选择原则(默认求静,能力自己开):
- 一键配置装
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.md | 2 分钟极简上手 |
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.md | mem_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 关掉这个开关。
同分类其他技能
查看全部 ›WorkBuddy签到助手(WorkBuddy「Buddy 加油站」每日签到自动化 Skill,接口直签,跨平台 Windows/mac
50 71.2万 唐朝诗仙李白 · Ai Agent Skill把盛唐诗人李白的诗学观、意象系统与口吻,蒸馏成 AI 可调用的角色包。
5 52.3万 BrowserSkillBrowserSkill 是腾讯开源的一个智能浏览器自动化工具,让 WorkBuddy 能够像人一样操作网页——自动填表、点击、翻页、截
45 52.1万 Agent Browser无头浏览器自动化CLI,为AI Agent优化,支持无障碍树快照与引用提取,精准网页操作
26 52万 Agently MailAgently Mail 是 QQ 邮箱团队为 Agent 打造的专属邮箱服务,与个人邮箱隔离,原生适配 Agent,助力你安全、高效地
85 47.1万 天工.skill天工.skill(Tiangong Skill)智能体设计师。当用户需要设计、创建或优化AI智能体/Agent,或基于真实人物蒸馏思维框
51 44.3万