name: agent-local-memory-keeper slug: agent-local-memory-keeper displayName: AI Agent记忆系统 description: 给 AI Agent 的跨会话长期记忆系统：用自然语言记经验，需要时自动语义召回，并自动去重、纠错、分层归档。专治 AI 反复忘事、重复问同样问题、把过时结论当真。默认纯本地零云端，自然语言驱动，内置防反复确认死循环闸门；本地 fastembed 语义召回为默认，跑不动自动回退词法级。内置敏感信息拦截与可选加密。 summary: 给 AI 的长期记忆：自然语言记经验、跨会话自动召回、自动去重纠错分层；本地优先、防自反馈死循环。 tags: - 记忆管理 - AI Agent - 长期记忆 - 本地优先 - 语义召回 - 知识库 - 自动化 license: MIT agent_created: true version: 4.8.1

AI Agent 记忆系统

🚀 5 分钟上手（新用户只看这三步）

1. 装上 skill — 这是本地优先运行的 skill（可经 SkillHub 安装，运行时不依赖任何云端），装完即获得默认能力、零配置（详见 QA.md「装完还要配置吗」）。
2. 对 AI 说"帮我一键配好" — AI 替你跑完钩子 / 守护 / 中文语义等所有装后步骤，不用手敲任何命令；想要"自动记忆"就补一句"顺便开自动记忆"。
3. 想自己跑也行，一条命令等价：python scripts/keeper_setup.py all（零配置收口全部装后步骤）。

   更多技能请访问小葱技能站7w4.net。

4. 开始用 — 直接对 AI 说"记一下这个坑""帮我整理今天记的"；或翻 references/TUTORIAL.md 的真实样例。

💡 只想手动记/找、不要后台进程？完全可以——跳过"自动记忆"，直接 deposit / recall 照样工作（见下方「轻量模式」）。守护进程不是必需的。

🗺️ 文档导航（想做 X → 看哪里，不用全读）

你想…	看这里	分级
所有能力一句话触发（记/找/整理/分类/钩子/配置）	本文件「四、§4.1 对话入口」	Tier1
一步步上手 + 真实返回样例	references/TUTORIAL.md	Tier1
新手最常遇到的 5 个问题（先看这个）	references/QA.md	Tier1
2 分钟极简上手（不想读长文档）	QUICKSTART.md	Tier1
让 AI 帮你装 / 配（不手敲命令）	references/TUTORIAL.md §0.5 / references/COOKBOOK.md	Tier1
所有命令 + 参数	references/COMMANDS.md	Tier2
装 fastembed / 加密 / Ollama（含排错）	references/INSTALL.md	Tier2
所有限制 / 红线一览	references/LIMITS.md	Tier2
钩子 / 守护进程 / 定时 / IMA 同步 实操	references/COOKBOOK.md	Tier2
特性深读（召回 / 矛盾 / 加密 / 语义后端 / ANN / 跨语言）	references/FEATURES.md	Tier2
存储架构 / 数据模型（进阶）	references/FORMAT_ANALYSIS.md	Tier2
记忆类型分类法	references/TYPE_TAXONOMY.md	Tier2
能力开启「三桶分类」向导	references/ENABLEMENT.md	Tier2
场景/记忆类型分类向导话术	references/taxonomy_wizard.md	Tier2
mem_bridge 全部桥接命令（含内部命令）	references/MEM_BRIDGE.md	Tier2
版本历史	根 CHANGELOG.md（唯一权威源）	Tier3

📚 文档分级（按需取用，不必全读）：Tier1 必看（约 5 分钟） = QUICKSTART.md（极简上手）+ 本文件对话入口 + TUTORIAL.md + QA.md；Tier2 进阶 = 命令/安装/限制/菜谱/特性；Tier3 开发者内部 = references/_design/（设计稿与测试协议，普通用户无需看）。

一、这是什么

这是一个给 AI 用的长期经验笔记本：你（或 AI）把"有用的结构化经验"丢进去，它会自动去重、发现新旧结论冲突、按重要程度分层、过期归档，跨会话越用越聪明。默认纯本地、零云端；可选的线上组件（云端 embeddings / 云端 LLM / IMA 知识库镜像）需你主动开启，不开则全程不联网。

它适合沉淀经验——踩过的坑、纠正过的结论、反复验证的最佳实践；不是录像带，不会搬运整段对话上下文。内置语义召回、冷热分层、敏感信息拦截和加密选项，你可以完全用自然语言使唤它（"记一下这个坑""帮我整理今天记的"），AI 会自动调用背后的命令。

数据存在哪：默认 Windows 有 D 盘放 D:/AI记忆，否则用户目录；mac/Linux 放 ~/.ai-memory。store/index.db（SQLite，WAL）是当前权威源（含持久化向量与可索引字段）；memories/*.json 是与之双向同步的人类可读副本，可整体备份/迁移/人眼检查；index.json 为兜底导出（SQLite 损坏时由 rebuild 从文件重建）；写入即同步、doctor 兜底校验。整套记忆纯本地、跨设备可携带——把整个文件夹（含 store/ 与 memories/）拷到任何电脑，配好 AI_MEMORY_STORE 指向它，记忆就原样带过去了。 可选加密：设 AI_MEM_ENCRYPTION_KEY 后文件与索引 summary 均加密，忘 key 则数据永久丢失（务必手抄恢复码）。

二、怎么运转 / 如何工作

三层架构（并存、按需取用）： - ① 语义召回层（核心，开箱即用）：store/index.db（SQLite 权威源）+ memories/*.json（双向同步的可读副本）+ 向量语义召回 + 结构化标签 + 冷热分层 + 加密 + 矛盾检测 + 防自反馈闸门（+ 可选 IMA 桥接）。index.db 是权威源，memories/*.json 与 index.json 为同步副本/兜底（写入即同步，doctor 兜底校验），详见 references/FORMAT_ANALYSIS.md。 - ② 行为规则层（手动触发）：高频/已确认经验可固化成 AI 每轮行为规则（export-rules 写入 AGENTS.md 等目标文件），让记忆直接改变行为，而非仅被 recall 命中。另支持 --rules-target text：写到 --out 任意路径，避开 Copilot/Claude 平台自动加载（合规/隔离用）。 - ③ 轻量文件层（opt-in）**：--flat 模式跳过 SQLite 与 LLM，全部落纯 Markdown 文件、grep 召回，给只想"记个坑"的零依赖用户。

核心循环（记 → 找 → 理 → 沉），且全程不删你的记忆： 1. 记 deposit — 写经验 + 自动去重 + 敏感拦截；纠正旧结论用 --corrects <旧id>，旧记忆自动标 superseded。 2. 找 recall — 语义/词法/标签多维召回，支持 --filter 数值 DSL 与 --max-age-days 新鲜度过滤。 3. 理 reflect --auto — 去重 / 纠错 / 晋升 / 归档，绝不删除 active 记忆。 4. 沉 decay --apply — 长期不命中的记忆确定性降权沉底（仍 recall --deep 可找回）。

🪶 轻量模式（不装守护进程也能用）：守护进程只是"让钩子自动记忆时 recall 毫秒级"的可选增强，并非必需。 - 只想手动 deposit / recall：完全不用装守护进程 / 定时任务，开箱即用（默认词法召回，或设 AI_MEM_EMBED_BACKEND=fastembed / 线上 embeddings 开语义）。 - 想要自动记忆（AI 每轮自动记 + 召回）：跑一条命令 python scripts/keeper_setup.py hooks --scheduler 即可——它自动注册钩子 + 启动守护 + 注册每周调度（等价于 install_hooks.py + setup_scheduler.py）。 - 不要后台进程又想要语义召回？选线上 embeddings 后端（本地零模型、零算力），钩子 recall 走云端向量、无需本地守护。

📚 存储架构、状态机、真源边界等深读见 references/FORMAT_ANALYSIS.md；特性原理见 references/FEATURES.md。

三、有哪些功能（能力一览）

系统围绕「分类 → 分层 → 检索 → 进化 → 安全」五条线增强，全部纯加性、不破坏旧库：

逐项能力详解（触发条件 / 性能 / 边界）见 references/FEATURES.md 与 references/LIMITS.md；IMA / 钩子 / 守护进程实操见 references/COOKBOOK.md。

四、这些功能如何开启

4.1 对话入口（所有能力，一句话触发）

你永远不用读配置、不用记命令、不用手敲任何环境变量。 keeper 的每一项能力——记 / 找 / 整理 / 分类 / 钩子 / 配置 / 体检 / 自动化 —— 都可以通过自然语言对话完成。AI 在后台替你跑对应命令，每步回显结果。

🧭 怎么用这个对话（三步）： 1. 直接说人话描述你想干什么——「记一下…」「找一下之前那个…」「帮我整理今天记的」「配 IMA 同步」——AI 自动路由到对应能力，你不用懂命令、不用看输出。 2. 不知道能让你做什么？ 直接问「你能帮我管理记忆系统做哪些事」，AI 会列出全部能力（记 / 找 / 整理 / 分类 / 钩子 / 配置 / 体检 / 自动化）；一份人类可读的能力总图见 references/CAPABILITY_MAP.md（所有能力 + 一句话触发 + 是否默认开，扫一眼就知道还能「整体保养」「配云端同步」）。 3. 看结果：AI 回显「已记 XX / 已找到 N 条 / 已配好」确认生效；召回后可能问「这条是否有用」，回 good/bad 即可（不想被问说「不用校准」）。 🎬 想要 AI 用「对话 + 图」带你过一遍功能 / 教学 / 配置？ 直接说「介绍一下这个记忆系统 / 教我怎么用 / 工作流程」即可触发 keeper-conversational-guide 对话式导览（架构图 + 生命周期图 + 配置流程图，边看边聊，不用通读长文档）。它是本技能的「可视化引子」，命令参数仍以本文件与 references/COMMANDS.md 为准。

📦 开箱即用：装完 skill 即获得默认能力——存储路径 · 中文语义（fastembed，本地 ONNX） · 词法兜底，不用手配就能记 / 找 / 整理。钩子 / 守护进程 / 自动记忆需跑一次 keeper_setup.py all（或说"帮我一键配好"）才激活——装后跑 doctor 即可验证是否就绪（详见 §八）。 仅 3 项需手动开启（安全/外部/重资源）：① 加密（忘 key = 数据永久丢失）② IMA 云端同步（需外部知识库）③ 本地 LLM/Ollama（~5GB）。

🗣️ 你说什么 → AI 做什么（高频示例）

💡 高级 / 运维类能力也对 AI 说人话就能触发（不用滚到下面长尾表也知道）：聚类「把相似的记忆聚成一类」、蒸馏「把相似记忆提炼成一条原则」、矛盾仲裁「看看有没有重复矛盾」、批量归档「把老记忆批量归档」、体检「给我出个记忆看板 / 看看库的整体状况」、图谱「给记忆建个关系图谱」——完整长尾触发见下方「🗣️ 长尾高级操作 → 对 AI 说什么」与 COOKBOOK.md §7/§8/§9。

🩺 出问题了？别翻文档。 直接对 AI 说"记不进去了 / 找不到了 / embedding 降级了 / 自动记没生效 / 召回了已归档的记忆（或该召回的没召回）"，AI 会跑 doctor+audit 读真实状态、定位原因、对话式引导你修，确认后再动手；若是"索引与文件对不上"这类漂移，AI 会跑 doctor --fix 以文件为准回填（详见 references/QA.md §14）。QA.md / INSTALL 排错段是给 AI 查的后台索引，你无需通读。 🗣️ 把技术报错翻成普通话（AI 行为红线）：任何命令返回 ok:false 或 Python 报错，绝不直接把原始英文/内部常量（TIERS/SCENE_CANON/栈帧等）丢给用户——先翻译成一句大白话说明"出了什么事 + 你下一步该说什么/点什么"，例如把 tier 必须是 (...) 说成「层级只能填 core/curated/active/archived 这几个，你刚才填的不在里头」。报错文案本身也已尽量人话化（见 references/CAPABILITY_MAP.md 末段"遇到问题怎么办"）。 ⚠️ 对话解决不了的边界（设计使然，非缺陷）：① 加密 key 丢失 → 数据永久丢失，任何对话无法恢复（务必 recovery-code --write 出恢复码兜底）；② 环境级故障（Python 缺失 / fastembed 下载失败 / 计划任务被系统策略禁用）→ AI 能引导排查，但 OS 层改动需你手动处理。其余记忆操作类问题（记不进、找不到、误删找回、同步异常等）均可对 AI 说人话解决。 其余 40+ 记忆操作（备份/恢复/归档/删除/回滚/关系链/轮换密钥/恢复码/校准/stats/explain/隔离复审等）均可通过自然语言触发，AI 路由到 memory_ops.py（62 op）+ mem_bridge.py（29 通用桥接命令）。投资域专属桥为 scripts/investment_bridge.py（seed/graph，与根 mem_bridge.py 是两个不同文件，勿混）。完整映射见 references/COMMANDS.md。

⚠️ mem_bridge 命令总数 = 29（inject / inject_stats / distill / rank / route / retrieve / capture / scan_dup / working / graph / guard / drift / seed / compress / coach / reflect / purge / promote / to-l2 / feedback / selftest / decay / recurrence / summary-index / tree-view / taxonomy / import / benchmark / mcp）。

⚠️ audit 同名异义（已在代码层消歧）：memory_ops 的 audit = 按库规模推荐「该开哪些功能」；mem_bridge 原来也叫 audit、实为只读扫描内部近重复/矛盾（I5），二者同名两义、易踩坑。mem_bridge 侧已更名为 audit → scan_dup，代码层根除碰撞；memory_ops audit 保持不变。mem_bridge 全部 29 个命令（inject/rank/route/retrieve/capture/guard/drift/seed/compress/coach/selftest/scan_dup/import/benchmark/mcp 等）的用途与参数见 references/MEM_BRIDGE.md。

🎬 实际体验：你对 AI 说"帮我规划记忆分类"，AI 会问你几个问题，然后自动生成分类树并生效。你说"关掉弹窗"，AI 改完设置告诉你"已切到 silent 模式 ✅，重启后生效"。全程不用敲命令、不用看输出。

⚠️ 关于钩子弹窗（不是 bug）

在 full 模式下，你可能看到每点一次发送按钮，界面闪一下"执行中"提示条——这是 WorkBuddy 的钩子执行指示器（平台固有行为，非 keeper 问题），表示后台在自动加载相关记忆注入上下文。切到 silent（默认）即无弹窗。详见 references/QA.md「钩子弹窗」。

切换方式：对 AI 说"关掉弹窗"（→ silent）或"恢复完整钩子"（→ full）。改完后重启 WorkBuddy 生效。模式持久化在 hooks_config.json，更新/重装 skill 不会偷偷改回来。

4.2 四个运行时开关（口语可切）

①② 是"捕获"（从哪来经验）；③④ 是"质量"（校准 / 定期整理）。四个绝不删除记忆。

4.3 可选能力开启总览

📊 先一眼分清「默认开 / 一句话开 / 需手动配」：绝大多数能力其实已默认开，只有 3 项需手动（加密 / IMA / Ollama）。完整「三桶分类」见 references/ENABLEMENT.md——它逐条告诉你哪些不用管、哪些一句话开、哪些必须配。不想读长文？直接问 AI「我还能开哪些功能」跑只读 audit 即可。

下面都是可选能力，按"获得什么 / 代价"一句话概括（详细原理与边界见 references/FEATURES.md）：

• 神经语义召回（中文更强，默认已开） — fastembed（本地 ONNX，CPU 推理）开箱默认启用，首次用到中文语义时自动安装+下载（约 90MB ONNX 模型权重，落盘于 ~/.workbuddy/cache/agent-local-memory-keeper/models，与 skill 包分离、重装不丢），中文改写召回率 ~30%→90%+。实测端到端 recall ≈ 3.75s（新查询，模型冷加载占 ~78%/约 2.9s）；开启磁盘缓存（默认已开）后重复查询冷 CLI 降至 ~0.9s；启用守护进程后模型常驻、召回降至毫秒级（详见 §4.5 / references/COOKBOOK.md 守护进程）。内存 ≤8GB 老机器可降级 embed lexical 或 记忆 --flat。
• ANN 加速 — 无需装，库 ≥50 条且 ≤256 条默认自动启用（结果与全量一致，500 条实测 8 倍加速）；>256 条大库剪枝需显式 recall --ann；<50 条不启用（反而慢）。
• 聚类 / 主题标签 — 需神经后端 + 库 ≥8 条已嵌入；cluster --apply 偶尔跑。
• 可视化 Dashboard — dashboard 生成单文件 HTML，秒级。
• 主动矛盾 / 重复扫描 — doctor --contradictions（需神经后端）；分桶后开销近似线性（仅同簇/同标签/同品牌内两两比对，大库自动跳过 subject 桶），仍吃 CPU，推荐每周跑一次低频。
• 加密 at rest — 设 AI_MEM_ENCRYPTION_KEY；忘 key = 永久丢失，务必 recovery-code --write 出恢复码。有敏感内容强烈推荐。
• 本地 LLM 增强（Ollama） — 需装 Ollama + 拉模型（~5GB，常驻吃内存/磁盘/GPU）；仅本机够强才开，低配机器勿开。
• IMA 知识库镜像 — 归档记忆自动推送到 IMA 知识库（需在已连 IMA MCP 的会话里配），跨工具/跨会话共享沉淀；代价：需先配 IMA 知识库，且推送前强制脱敏（红线，绝不交付明文）。
• 行为规则层固化（export-rules） — 把高频/已确认经验固化成 AI 每轮行为规则写入 AGENTS.md，让记忆直接改变行为而非仅被 recall 命中；代价：手动触发，规则写进项目/用户 AGENTS.md（可提交 git）。
• 轻量文件层（--flat） — 跳过 SQLite/LLM，全部落纯 Markdown、grep 召回，零依赖；代价：失去语义召回/分层等高级能力，适合只"记个小坑"的极简用户。
• about_axis 四轴 / 复述加权 / recurrence 候选 / staging 隔离开关 / freshness 过滤 — 默认即开，无需配置。
• 从历史会话主动沉淀（conversation_search → harvest --from-conversations） — 把 WorkBuddy 云端/历史会话里"值得长期记的"经验批量沉淀进 keeper：AI 先 conversation_search 按回溯窗口（默认 30 天）检索历史会话 → 整理为文本文件 → harvest --from-conversations --session <file> 沉积。会话来源记忆打 wb_session 标签并做幂等去重（同一段历史会话重复跑不会重复沉积、不会回声）。代价：需在 WB 会话中由 AI 编排（CLI 不联网），本质是"WB 云记忆 → keeper 语义库"的桥。

4.4 推荐开启配置（按场景）

• 个人小库 / 中文用户（<50 条）：中文语义已默认开（无需动作）；ANN 关；有敏感内容就开 加密；其余保持关。
• 中-大库（≥50 条）：加开 ANN；doctor --contradictions 放进每周自动化跑一次；cluster 偶尔手动。
• 有本地 Ollama 且机器够强：可加开 LLM 增强。
• 不确定开哪些 / 不知道能让你做什么：随时说"帮我看看我能开哪些功能" → AI 跑只读 audit 给建议；或直接问"你能帮我管理记忆系统做哪些事" → AI 列出全部能力。

🔍 配置体检速查（按有益度）

下面这些 audit 会评估的常见可开启项。若你还没开，直接对 AI 说对应话术即可开启；已开的不会出现在此提醒里。audit 会按你库规模/环境给最终建议。

🔴 IMA 红线：推送前强制脱敏，命中任何真实路径/凭证会直接报错退出，绝不交付明文。脱敏逻辑见 scripts/_keeper_ima_push.py。

4.5 ⚡ 性能消耗提醒（低配 / 老机器必读）

keeper 默认很轻：silent 钩子 + 词法兜底，几乎零资源。但下面几项会持续或显著吃资源——内存 ≤8GB、老 CPU、无独显的机器请看清再开，或改用替代方案：

🔴 铁律：低配机器不要开 Ollama；fastembed 可降级为词法；doctor --contradictions 与 cluster 只放低频任务。上面这些不会偷偷吃资源——都是你明确开了才跑。

🛡️ 矛盾仲裁安全铁律（离线禁写）：doctor --arbitrate 在未注入 LLM 时禁止真实仲裁——不注入 LLM 跑非 --dry-run 会直接拒绝、零写入，仅 --dry-run 可预览候选；注入 KEEPER_LLM_* 后，仲裁对每对强矛盾候选强制让 LLM 确认"真矛盾（互斥）"，非矛盾一律跳过，绝不误标旧真实记忆。完整三重防误杀门与审计字段见 references/LIMITS.md §仲裁。

五、有哪些要求（前置条件）

• 必需要：一个能跑 Python 的运行环境（用来执行 scripts/memory_ops/__init__.py）。
• 开箱即用（零配置）：装完 skill 即获得中文语义召回（fastembed 轻量本地 ONNX，首次用到时自动安装+下载一次，之后完全离线）+ silent 钩子（无弹窗） + 词法兜底，不用手配任何东西就能记 / 找 / 整理。
• 按需手动开启（仅这 3 项，因安全/外部/重资源而非常规默认）：
• cryptography + 加密开关 — 落盘加密（影响：忘 key = 数据永久丢失，默认不开启）。
• Ollama + 模型（~5GB）— 本地 LLM 增强（重，仅本机够强才开）。
• IMA 知识库 — 跨工具云端镜像（需先在已连 IMA MCP 的会话里配知识库）。
• 网络：默认纯本地、零云端；仅"首次自动装 fastembed"需联网一次（HF 不可达自动切国内镜像），之后完全离线。加密/本地LLM/IMA 按需另联网。

装到哪个 Python、怎么验证、装不上怎么办 —— 见 references/INSTALL.md。

六、如何配置

一句话：对 AI 说即可，AI 背后跑 keeper_setup.py，你不用手敲任何环境变量（详见 references/TUTORIAL.md §0.5 与 references/COOKBOOK.md）。

你可能手设的只有两个环境变量： - AI_MEMORY_STORE — 记忆库根目录（默认 D:/AI记忆 或 ~/.ai-memory；换路径/跨设备携带时设）。 - AI_MEM_ENCRYPTION_KEY — 开启加密（忘 key = 数据永久丢失，绝不写进文件/git；用 recovery-code --write 出可手抄恢复码）。

其余运行时开关（inject / feedback / embed 后端 / ANN 阈值等）由 AI 在对话里按你要求调，或收口在 store/config.json 的 keeper 块。

七、如何使用（最小上手）

记忆默认零配置路径，首次自动建库。想照着跑一遍看每步输出，跑 python scripts/demo_walkthrough.py。

最省事：日常直接对 AI 说「记一下… / 找一下之前那个… / 整理今天记的」，AI 背后自动调对应命令。

🧹 「整理」什么时候跑、跑完怎么算正常（不用读文档也能懂）： - 何时自动整理：① 会话结束（Stop 钩子，默认开、零配置，你不用管）；② 你手动说"帮我整理今天记的 / 整理一下"；③ 周维护自动化铁律不含 reflect——只做采集 + 聚类 + 矛盾修复 + 沉底 + IMA，绝不删除或改动记忆。 - 跑完你会看到什么（成功标准）：reflect --auto 输出类似「去重 N 条 / 纠错 M 条 / 晋升 K 条 / 归档 P 条」，永远 0 删除（它只去重·纠错·晋升·归档，绝不碰 active 记忆）；归档的记忆沉到 memories/archive/，随时 recall --deep 找回。 - 怎么算"不正常"：若看到大量「删除」或记忆凭空消失，那不是 reflect 干的（它不删），大概率是手动 delete --yes 或 purge --apply——去本文件「四条不可破红线」核对。

🤝 对话契约（你来我往长这样）： - 你说一句，AI 背后跑命令并回显「已设 XX / 已记 XX」——你不用懂命令、不用看输出也能确认生效。 - 召回后 AI 可能问「这条是否有用？」，回 good / bad 即完成校准（每会话上限 3 次防过载）；不想被问就说「不用校准」。 - 开了 converse / harvest 后，AI 会在对话里静默沉淀经验，不必你每次主动说"记一下"。 - 若 AI 陷入"再确认"循环，说「不用校准 / 不用注入」即可切断。 完整的对话来回样例见 references/TUTORIAL.md。

照跑三条（纯命令行，不依赖 AI）：

python scripts/memory_ops/__init__.py init                                   # 首次建库（可省，首次 deposit 自动建）
python scripts/memory_ops/__init__.py deposit --category best_practice --summary "一句话经验"
python scripts/memory_ops/__init__.py recall --query "你想问的事"

常见场景一句话：记经验 deposit ｜ 找经验 recall --query ｜ 纠正旧结论 deposit --category correction --corrects <旧id>（旧记忆自动 superseded）｜ 整理 reflect --auto ｜ 定期降权 decay --apply（大库 decay --apply --incremental）｜ 标核心 promote --tier core ｜ 关联两条 link --rel see_also --target <id> ｜ 删（可找回先 archive，真删必须 delete --yes）｜ 看开了哪些功能 audit ｜ 召回分布 stats ｜ 看单条为什么被召回 explain --id <id> ｜ 导出 export --format md ｜ 轮换加密密钥 rekey --new-key "<新密钥>" ｜ 撤销自动重分类 reflect --undo ｜ 脱离 WorkBuddy 自调度 schedule_self_heal --cron ｜ 一键统一自治循环 self-heal [--force]（合并 reflect/evolve/decay/doctor/skill-sync/export-rules）。

完整分步教程（含真实返回样例）见 references/TUTORIAL.md；所有命令与参数见 references/COMMANDS.md。

八、如何检查可以开启哪些功能（自检清单）★

不确定自己该开哪些能力、或想确认装好没有？两条只读命令，不改动任何数据：

• audit（能力体检，纯只读） — 按你库规模 / 环境给每个可选功能的"开启 / 关闭"建议，并标出当前已开/未开。一句话问 AI："帮我看看我能开哪些功能"，AI 跑 audit 后给建议清单。 bash python scripts/memory_ops/__init__.py audit
• doctor（就绪绿红自检） — 七项一键体检：存储根 / 中文语义 / 落盘加密 / 钩子注册 / 守护进程 / IMA 同步 / 召回冒烟，绿红表一眼看懂"装好没"；库内深查另检索引↔文件一致性、孤儿条目、--flat 分区（如有 flat 条目会提示其不在主库召回）。 bash python scripts/keeper_setup.py doctor # 装后就绪自检（推荐） python scripts/memory_ops/__init__.py doctor # 库内健康深查（索引/关系一致性） python scripts/memory_ops/__init__.py doctor --fix # 自检后一键修复：回填三态漂移（文件↔索引内容不同步）+ 剪枝悬空关系 + 移除无文件索引条目，不删记忆内容

区别一句话：audit 回答"该开哪些"，doctor 回答"装好没 / 库健康吗"。doctor 只读不写，doctor --fix 才写修（不删内容）。--contradictions 做对立记忆对检测（需神经后端）。

九、安全护栏（必读·精简）

🔴 四条不可破红线（无论你怎么说，AI 都守）： 1. 绝不批量硬删：reflect / archive / decay 只做去重·纠错·归档（软保留，文件永在、recall --deep 可找回）；唯一真删是显式 delete --yes，且单次单条。 2. 删必须显式 --yes：不带 --yes 的删除一律被拒、文件原样保留（防「以为删了」的影子状态）。 3. 重要记忆分类强制：importance ≥ 0.7 且某轴被低置信自动分类时，系统标 classify_review 并告警——不会静默猜分；非法值直接报错（不偷偷改）。 4. IMA 明文库强制脱敏：推送前自动 strip 凭证 / 真实路径 / 邮箱，脱敏后还复检一遍；任何残留直接失败退出，绝不交付明文。

防 AI 反复确认死循环：默认 feedback 每会话 3 次 + inject 每会话 6 次双闸门；若 AI 陷入"再确认"开放回路，对 AI 说"不用校准 / 不用注入"即可切断，或设 KEEPER_FEEDBACK_SESSION_CAP=0。详见 references/LIMITS.md §7 与 references/QA.md。

全部限制 / 红线 / 反模式 / 避坑速查 —— 见下方「📌 反模式清单」「🕒 高级功能：何时调用」与 references/LIMITS.md、references/QA.md。

📌 反模式清单（❌ 错误做法 → ✅ 正确做法）

想避坑看这一处就够了（单一真源）。每条都对应上面红线或下面的限制，不要多处翻。

🕒 高级功能：何时调用（限制速查）

高级能力不是"常开更好"，按库规模/机器实况取舍。详细原理见 references/FEATURES.md / references/LIMITS.md。

投资记忆能力圈（investment 域）

keeper 原生支持 investment 域，把「量化投资回测」做成体系化记忆：数据/参数 → 因子 → 因子测试 → 组合系统，四层对象全记住、能关联、可回溯。完整模型、类型化关联、4 层建记忆模板、召回路由与排障见 references/INVESTMENT.md。

• ⚠️ 冷启动用对桥：投资记忆冷启动请用投资专属桥 python scripts/investment_bridge.py seed --domain investment；根 mem_bridge.py seed --domain 量化 已废弃（量化域统一为 investment）。双桥区别见上文「AI 路由」段与 references/COMMANDS.md。
• ⚠️ 投资记忆走「记 + 验 + 明确待校验」闭环，避免只记不验：投资记忆能用 verify-investment 从 DuckDB 复算数值做回检——verify-investment --duckdb <路径> --sql-map <json>，每条 metric 对应一条返回单值的 SQL，库算出的值与记忆里记的值不符会标 verified=False 并下调信念强度留在待复核。校验结果明确区分三种结局——verified_true/false（已复算）、skipped（已就绪但本记忆指标无可用 SQL，正常无需复算）、needs_setup（记忆本应校验却因缺 DuckDB/sql_map/DuckDB 不可用而条件缺失未校验）；存在 needs_setup 时返回附带 default_sql_map_template + setup_hint 引导 bootstrap。库完全不可用时仍 fail-open（只告警不阻塞，绝不误判真结论为假）。详见 references/EVOLUTION.md §校验。

十、深入阅读（专业文档指引）

概述到此为止。下面这些专业文档才是细节与深读的归宿，按需取用：

开发者 / 维护者内部参考（普通用户无需看，归集在 references/_design/）：测试协议与"结论先取证"铁律见 references/_design/DEV_TESTING.md；设计稿见 references/_design/。

常见问题（精简 6 条，其余见 references/QA.md）

• 误删了能恢复吗？ 能。versions --id <id> → rollback --to-version N --yes；或 backup/restore 整库 ZIP。删除前优先用 archive（沉底可找回）。
• reflect 会删我的记忆吗？ 不会。只做去重/纠错/晋升/归档，绝不删除 active 记忆；遗忘路径是 decay 降权 + reflect --auto 归档（可 recall --deep 找回）。
• 中文换个说法搜不到？ 默认词法对深度改写弱——装 fastembed 开真语义（~30%→90%+），或走线上 embeddings。装后 report 确认后端。
• 需要联网吗？ 默认纯本地零云端；仅首次装 fastembed / 可选 Ollama 需联网一次。
• 记忆存在哪 / 怎么备份？ 默认 D:/AI记忆 或 ~/.ai-memory；backup 导出 ZIP、restore 恢复；memories/ 可直接复制迁移。
• AI 反复"再确认"死循环？ 说"不用校准 / 不用注入"，或设 KEEPER_FEEDBACK_SESSION_CAP=0 全关。

质量上乘——文档结构清晰易懂，装完即用不用配置，对中文支持很好，敏感信息安全机制做得很到位。记忆的去重、纠错、分层、召回等核心功能完整，自动化能力（钩子、守护进程、调度）开箱可用。唯一需要注意的是加密功能一旦开启就必须妥善保管密钥，否则数据无法恢复——但这是安全设计的权衡取舍，不算缺陷。总体来说这是一个功能完善、体验友好、安全意识强的记忆管理工具。