AI Agent 记忆系统

技能文档

---
name: agent-local-memory-keeper
title: AI Agent 记忆系统
description: 给 AI Agent 的跨会话长期记忆系统：用自然语言记经验，需要时自动语义召回，并自动去重、纠错、分层归档。专治 AI 反复忘事、重复问同样问题、把过时结论当真。默认纯本地零云端，自然语言驱动，内置防反复确认死循环闸门；本地 fastembed 语义召回为默认，跑不动自动回退词法级；内置敏感信息拦截与可选加密。当用户需要让 AI 记住经验教训、跨会话保留知识、建立个人知识库时使用。触发词：记忆系统、长期记忆、记经验、知识沉淀、跨会话记忆、语义召回。
category: 通用技能
---
# AI Agent 记忆系统

> ## 🔴 先读这 3 条（不读可能丢数据）
> **1. 开了加密 = 必须存恢复码**：跑 `recovery-code --write`。**忘记 key/恢复码 = 数据永久丢失**，任何对话都找不回来、无后门。
> **2. 清理用 `archive`，别拿 `delete --yes` 当常规清理**：`delete --yes` 是**真删、不可找回**；`archive` 软归档沉底，`recall --deep` 仍可找回。不确定的先 `--dry-run`。
> **3. 别把对话原文灌进记忆**：只记**提炼后的结论**（坑/纠正/最佳实践）；当录音笔用会让召回质量塌方。
>
> 👉 红线完整版见 **§九「红线与边界」**（唯一真源）；用法类避坑见文末 **「📌 反模式清单」**（唯一真源，只看那一处就够）。看不懂的词（降级/幂等/fail-closed/ANN 等）→ 查 **`references/GLOSSARY.md`**。

> ## 🔰 新手 5 大雷区（动手前先扫一眼，省得踩坑）
> 下面 5 条是新手最容易「吃过亏才知道」的点，按危险度排序；每条只给**指针**，不重复正文，避免多头翻。
> 1. 🔴 **默认就在自动记**——`auto_capture` 默认开、每 20 轮自动沉淀，会话结束 Stop 钩子也会自动整理。不想自动记：说「先别自动记」或设 `KEEPER_AUTO_CAPTURE=0`（详解见 §4.2「两个高频误解」）。
> 2. 🔴 **开加密前必须备恢复码（不可逆）**——忘 key 且无恢复码 = 永久丢失、无后门。AI 不会在你没确认时就开（硬门见「对话路由契约」第 4 条）。
> 3. ⚠️ **完整「不该怎么做」清单**——文末 **「📌 反模式清单」**（11 条唯一真源）+ `references/QA.md` §四（14 个避坑详解）；想系统看所有 don't 就看这两处。
> 4. ⚠️ **命令真实返回长啥样**——`references/COMMANDS.md` 只有参数；**真实 JSON 返回样例在 `references/COMMANDS.md` 末尾「常见命令真实返回样例」** + `references/TUTORIAL.md`（教程里贴了少量）。
> 5. 🩺 **召回变差先自查（现多已自动回显，无需手动查）**——搜不到多半是语义后端静默降级到词法（召回 ~90%→~30%）。**现已自动回显**：`recall` 会随带 `meta.fell_back_to_lexical` + 空结果 `empty_hint`（含修复命令），注入时若降级还会在上下文里显式追加「⚠️ 已降级」提示——「降级了却没人知道」已堵死。仍想手动确认：让 AI 跑 `doctor`，看 `embed_backend.fell_back_to_lexical` 是否为 `false`。

> ## 🧭 其余边界速查（次要限制 · 一行一条 · 完整版见 §九「红线与边界」）
> 除上面 3 条红线外，还有这些「不读会踩」的边界，每条只给一行结论 + 指针：
> 1. **清理命令怎么选**：清「今天新增的噪音」→ `reflect --auto` 或 `archive`；`purge` **只**处理「早已软删、且超龄（默认 180 天）沉淀」的旧物——拿它清当天噪音只会得到「0 条候选」，**这不是 bug**。对照表见 §九。
> 2. **归档 ≠ 真删**：`reflect` / `archive` / `decay` 全是**软保留**（`recall --deep` 仍可找回）；**唯一真删**是显式 `delete --yes`（单条、不可逆、无后门）。
> 3. **「衰减」只降权**：`decay --apply` 不移动、不删除——条目还在库里、还能召回，只是排序变低。
> 4. **域分类落空是设计**：未命中任何域 → 存为 `domain=None`（由 `report` 的「域分布 → none」桶体现），**不是丢失**；想让落空自动落域，显式设 `KEEPER_DOMAIN_FALLBACK=<域>`（默认关）。
> 5. **加密是字段级**：`summary`/`body` 为密文，`id`/`category`/时间戳仍明文；**忘 key 且无恢复码 = 永久丢失**（红线 A1）。
## 技能工作流总览（30 秒速览）
- **它是什么**：给 AI 的跨会话长期记忆——你用大白话「记一下…」「找一下…」，AI 自动存、需要时自动召回，并去重/纠错/分层。**装完即用**，不用读配置、不用记命令。
- **最关键铁律**：🔴 开加密前**必须先备 recovery 兜底**（恢复码 + 库外 keyfile），否则忘 key 又无兜底 = 永久丢失；红线全文见 §九。
- **守护进程不是必需的**：钩子/守护进程只是可选增强，不开也能正常记/找。
- **三个隐藏条件**：① **召回质量看语义后端**——默认就是语义后端（`fastembed`），换说法也能召回（~90%+）；但它**会降级**：模型加载/下载失败时退回词法级（换说法召回掉到 ~30%）。**降级已不再静默**——`recall` 返回的 `meta.fell_back_to_lexical` / 空结果 `empty_hint`、以及注入上下文里的「⚠️ 已降级」标注会主动提示，仍可让 AI 跑 `doctor` 复核 `embed_backend.fell_back_to_lexical`。② **"整理"永不删记忆**——`reflect`/`decay`/`archive` 只归档沉底、`recall --deep` 可找回，唯一真删是显式 `delete --yes`。③ 开加密必须备 recovery 兜底（见上）。
- **出问题别翻文档**：直接对 AI 说「记不进去了 / 找不到了 / embedding 降级了」，AI 会跑 `doctor`+`audit` 定位并对话式引导你修。
- **新手完整路径**：下面「🚀 5 分钟上手」三步即可；深度需求再查 `references/` 专业文档。

## 🔧 安装/更新后体检（必做，约 3 分钟）
> 初次配置或升级后，以下 5 项全过才算部署成功；任何一项不过都意味着**静默降级**（不报错、但召回质量塌方）。

1. `python mem_bridge.py selftest` → 须全部通过（回归基线）。
2. `python mem_bridge.py retrieve --task "<已存经验关键词>" --include-auto` → stderr **不得**出现 DEGRADED/lexical 降级字样。
3. `python scripts/memory_ops/__init__.py doctor`（设 AI_MEMORY_STORE）→ `embed_backend.fell_back_to_lexical` 须为 false、`coverage.rate` 须为 1.0、`model_detail` 应指向 skill 外持久目录。
4. **`HF_ENDPOINT` 必须带协议前缀** → `echo $HF_ENDPOINT` 须以 `http://` 或 `https://` 开头。裸域名（如 `hf-mirror.com`）会让 httpx 抛 `UnsupportedProtocol` → 下载失败 → 降级；`embed._ensure_hf_mirror` 会**自动补全协议并告警**，且 **`report`/`doctor` 独立判定 `fell_back_to_lexical` 并纳入 `embed` 回显——即便同时显示「已走镜像」也会一并亮出降级告警，假绿灯（验收显示绿灯、实际已降级）已消除**。
5. 自动捕获钩子判定：exitCode=0 的成功命令**不得**入库（修复前 100% 误判，详见 CHANGELOG）。

**环境要求**：用户级 env `HF_ENDPOINT=https://hf-mirror.com`（**必须带 https:// 协议**）；`FASTEMBED_CACHE_PATH` 指向 **skill 目录外**的持久目录（升级不丢 90MB 权重）。缺协议时会自动补全并告警，但**存量配置仍需人工改一次**。

> ⚠️ **为什么必须体检**：本 skill 的降级是 fail-open 的——语义召回挂了会自动退回词法级，功能「看起来正常」但召回质量大幅下降，且无醒目报错。上面 5 项是唯一能主动发现它的手段。

## 🔄 跨设备同步（多台电脑 / 一周用一次）
> 多台机器各有一份本地记忆库时，用 `scripts/keeper_sync.py` 搬，不要直接用 `export` + `import`——后者有 5 个静默坑（详见 CHANGELOG 相关条目），同步脚本已全部封死。

```bash
python scripts/keeper_sync.py out --dest <U盘或同步盘目录>   # 源机导出全量同步包
python scripts/keeper_sync.py in --dir <同步盘目录>           # 目标机先预演（默认 dry-run）
python scripts/keeper_sync.py in --dir <同步盘目录> --execute  # 确认数字无误再落盘（自动先备份目标库）
```

**三条铁律（代码硬拦截，逃生须显式加 flag）**：
1. **必须 `--keep-ids`**（默认开启）：不带时每次导入都会生成新 id，库会 19→38→57 无限膨胀。`--no-keep-ids` 配 `--execute` 会被**直接拒绝（rc=8）**；确属特殊修复场景须再加 `--i-know-id-bloat`。
2. **同步是单向的**（包 → 目标库，后导入者为准）。同一轮里 A→B 又 B→A 会互相回滚；要双向就在 B 机干完活后 `out`，再回 A 机 `in`。
3. **落盘前自动备份 + 完整性校验**：`--no-backup` 可关（不推荐，会红字警告）；包缺同名 `.meta.json`（含 sha256）时 `--execute` **直接拒绝（rc=7）**，须加 `--allow-unverified` 才放行。

> 预演（不带 `--execute`）不受任何拦截——永远可以先看数字再决定。退出码：`0` 成功 ｜ `2` 包损坏 ｜ `4` 导入失败 ｜ `5` 部分导入失败 ｜ `6` 幂等校验失败 ｜ `7` 未经完整性校验 ｜ `8` 未确认 id 膨胀。

## 🚀 5 分钟上手（新用户只看这三步）
1. **装上 skill** — 本地优先运行的 skill（运行时不依赖任何云端），装完即获得默认能力、零配置。
2. **对 AI 说"帮我一键配好"** — AI 替你跑完钩子 / 守护 / 中文语义等所有装后步骤；想自己跑：`python scripts/keeper_setup.py all`（零配置收口全部装后步骤）。
3. **开始用** — 直接对 AI 说"记一下这个坑""帮我整理今天记的"；或翻 `references/TUTORIAL.md` 的真实样例。

> 💡 **只想手动记/找、不要后台进程？完全可以**——跳过"自动记忆"，直接 `deposit` / `recall` 照样工作。守护进程不是必需的。

## 🔀 可选功能开关表（想开什么 → 一句话 / 一条命令 → 注意）
> keeper **装完即用**，绝大多数能力已默认开；下表只列「你需要知道开关在哪」的部分。三桶完整分类见 `references/ENABLEMENT.md`。

| 可选能力 | 一句话收益 | 怎么开 | 注意 |
|---|---|---|---|
| 后台自动记忆 `auto_capture` | 会话结束自动沉淀，不必手动记 | ✅ 默认开；关：设 `KEEPER_AUTO_CAPTURE=0` | 说一句「先别自动记」即可 |
| 上下文自动注入 `inject_enabled` | 会话开头自动把相关记忆塞给 AI | 默认**关**（省 token）；开：`KEEPER_INJECT_ENABLED=1` 或说「开启自动注入」 | 另有每日注入上限（`KEEPER_INJECT_DAILY_CAP`，默认 6） |
| 守护进程（召回加速） | `recall` 由 ~5s 降到 ~150ms | `python scripts/keeper_setup.py all`（已含） | **非必需**；单例、可空闲退出 |
| 静态加密 | `summary`/`body` 落盘密文 | 说「开加密」→ 触发**强制门禁** | 🔴 **A1：必须先备恢复码 + 库外 keyfile**，否则永久丢失 |
| 语义后端（换说法也能召回） | 换说法召回率 ~30% → ~90%+ | ✅ 默认开（fastembed） | 装不上/失败会**显式降级告警**（红线 B1） |
| 多设备搬库 | 多台电脑共用一份记忆 | `python scripts/keeper_sync.py out` / `in` | 单向同步；**别裸用 `export`+`import`** |
| 发布账本核对 | 一查就知道「线上到底发到几版」，防多机并行「双主」 | `python scripts/memory_ops.py release-audit` | 联网查平台；**断网 = 「未知」不是「有问题」**（退出码 3） |
| 域分类 / `KEEPER_DOMAIN_FALLBACK` | 记忆按域归档、可回溯 | ✅ 默认开；让落空域自动落域需显式设该 env | 落空 = `domain=None` **是设计不是缺陷** |
| IMA 云端同步 | 记忆同步到 IMA 知识库 | 说「配 IMA 知识库同步」 | 🔴 **A4：推送前强制脱敏**，绝不明文交付 |
| Ollama 本地 LLM | 离线跑矛盾修复等 | 见 `references/FEATURES.md` | 需装 ~5GB 模型，吃内存 |

> 🔑 **「开加密三步门」（唯一不可逆项，开前必读）**：① 确认「**忘 key 且无恢复码 = 永久丢失**」→ ② 先跑 `recovery-code --write`，把恢复码/keyfile 落到**库外**（手抄或密码管理器）→ ③ 确认落盘后，才设 `AI_MEM_ENCRYPTION_KEY` 开加密。**顺序不可颠倒、不可跳过**（硬门见 §七「对话路由契约」第 4 条）。

> 🧾 **维护 / 退出的三个收口命令**（都在 `scripts/` 下，**默认只预览**、要加 `--yes` / `--apply` 才动手）：`keeper_setup.py uninstall`（一条收口卸载：停钩子 + 停守护进程 + 移除调度）、`memory_ops.py keys-gc`（清理库外**孤儿** keyfile，默认 dry-run）、`memory_ops.py release-audit`（对账线上版本）。🔴 卸载前注意：库已加密、而库外 keyfile 缺失时它会**拒绝执行**——那等于把加密库变成永久不可读。

## 🗺️ 文档导航（想做 X → 看哪里，不用全读）
| 你想… | 看这里 | 分级 |
|---|---|---|
| 所有能力一句话触发（记/找/整理/分类/钩子/配置） | 本文件「四、§4.1 对话入口」 | Tier1 |
| 一步步上手 + 真实返回样例 | `references/TUTORIAL.md` | Tier1 |
| 新手最常遇到的 5 个问题 | `references/QA.md` | Tier1 |
| 看不懂的黑话 / 术语（大白话速查） | `references/GLOSSARY.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 |
| 卸载 / 退出 / 迁移 | `references/COOKBOOK.md` §10 | Tier2 |
| 更新/重装后要同步什么 | `references/INSTALL.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 |
| 投资域专属（模型/模板/校验） | `references/INVESTMENT.md` | Tier2 |
| 智能进化与互补协同设计（开发者内部） | `references/EVOLUTION.md` | Tier3 |
| 契约层四件套（开发者内部） | `references/CONTRACT.md` | Tier3 |
| 测试协议 / 压测方法论（开发者内部） | `references/_design/` | Tier3 |
| 版本历史 | 根 `CHANGELOG.md`（唯一权威源） | Tier3 |

> 📚 **文档分级**：**Tier1 必看（约 5 分钟）** = `QUICKSTART.md` + 本文件对话入口 + `TUTORIAL.md` + `QA.md`；**看到不懂的词查 `GLOSSARY.md`**（当词典翻，不用通读）；**Tier2 进阶** = 命令/安装/限制/菜谱/特性；**Tier3 开发者内部** = `references/_design/`（设计稿与测试协议，普通用户无需看）。

---

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

> **数据存在哪**：默认回退链 `AI_MEMORY_STORE` → `~/.keeper/store_root` → 平台默认（Windows `~/AI记忆`、mac/Linux `~/.ai-memory`）。**`store/index.db`（SQLite，WAL）是当前权威源**（含持久化向量与可索引字段）；`memories/*.json` 是与之双向同步的人类可读副本，可整体备份/迁移/人眼检查；`index.json` 为兜底导出（SQLite 损坏时由 `rebuild` 从文件重建）；写入即同步、doctor 兜底校验。整套记忆纯本地、跨设备可携带。
> **可选加密**：设 `AI_MEM_ENCRYPTION_KEY` 后 `summary`/`body` **字段级**加密（`id`/`category` 仍明文以便检索）；**忘 key 且无恢复码 = 永久丢失**——开前必先备兜底，红线见 §九。

## 二、怎么运转
**三层架构（并存、按需取用）**：
- **① 语义召回层（核心，开箱即用）**：`store/index.db`（SQLite 权威源）+ `memories/*.json`（双向同步副本）+ 向量语义召回 + 结构化标签 + 冷热分层 + 加密 + 矛盾检测 + 防自反馈闸门（+ 可选 IMA 桥接）。`index.db` 是权威源，`memories/*.json` 与 `index.json` 为同步副本/兜底。
- **② 行为规则层（手动触发）**：高频/已确认经验可固化成 AI 每轮行为规则（`export-rules` 写入 `AGENTS.md` 等），让记忆直接改变行为；另支持 `--rules-target text` 写到任意路径，避开平台自动加载（合规/隔离用）。
- **③ 轻量文件层（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` 完全不用装守护进程；想要自动记忆跑一条 `python scripts/keeper_setup.py hooks --scheduler` 即可。存储架构/状态机深读见 `references/FORMAT_ANALYSIS.md`；特性原理见 `references/FEATURES.md`。

## 三、有哪些功能（能力一览）
系统围绕「分类 → 分层 → 检索 → 进化 → 安全」五条线增强，全部纯加性、不破坏旧库：

| 维度 | 你能感知到什么 |
|---|---|
| **分类** | 多轴 taxonomy（category + scene + about_axis 四轴 user/self/relationship/world + state/priority/area），AI 调用更精准；偏好类自动编入人格层 |
| **分层** | 冷热分层 + 域隔离 + 复述加权 + 配额保护；常用记忆召回更快，高 importance 不易沉底 |
| **检索** | RRF 多信号融合 + ANN 加速（≥50 条）+ freshness 过滤 + 关联联想；改写 query 也能召回 |
| **进化** | 自整理 + 矛盾处理 + recurrence 候选 + 噪声过滤；**evolve 自主形成原则**；**信念强度校准 + 错误遗忘**；**投资记忆 DuckDB 自动校验**；千条库也能快速去重/纠错/晋升 |
| **安全** | 敏感拦截 + 隔离复审 + 并发守卫 + 加密可选 + 防自反馈闸门；secrets 一票否决或 quarantine 待审 |
| **集成** | **IMA 知识库镜像**（归档记忆自动推送，跨工具共享，推送前强制脱敏）；**行为规则固化**（`export-rules`→`AGENTS.md`/`CLAUDE.md` 等）；**经验萃取成 skill**（`extract-skill`）；轻量文件层（`--flat`） |

> 逐项能力详解见 `references/FEATURES.md` 与 `references/LIMITS.md`；IMA / 钩子 / 守护进程实操见 `references/COOKBOOK.md`。

## 四、这些功能如何开启

### 4.1 对话入口（所有能力，一句话触发）
你**永远不用读配置、不用记命令**。 keeper 每一项能力都可通过自然语言对话完成，AI 在后台替你跑对应命令，每步回显结果。

> 🧭 **怎么用**：① **直接说人话**——「记一下…」「找一下之前那个…」「帮我整理今天记的」「配 IMA 同步」——AI 自动路由，你不用懂命令。② **不知道能做什么？** 问「你能帮我管理记忆系统做哪些事」，AI 会列出全部能力（总图见 `references/CAPABILITY_MAP.md`）。③ **看结果**：AI 回显「已记 XX / 已找到 N 条」确认生效；召回后可能问「这条是否有用」，回 good/bad 即可（不想被问说「不用校准」）。
> 🎬 想要 AI 用「对话 + 图」带你过一遍功能 / 教学 / 配置？说「介绍一下这个记忆系统 / 教我怎么用」触发 **keeper-conversational-guide 对话式导览**（架构图 + 生命周期图 + 配置流程图）。命令参数仍以本文件与 `references/COMMANDS.md` 为准。
> **📦 开箱即用**：装完即获默认能力——存储路径 · 中文语义（fastembed） · 词法兜底 · 会话钩子自动注册（重启宿主应用后生效）。仅 3 项需手动开启（安全/外部/重资源）：① **加密** ② **IMA 云端同步** ③ **本地 LLM/Ollama**。

#### 🗣️ 你说什么 → AI 做什么（高频示例）
| 你对 AI 说 | AI 背后执行 |
|---|---|
| "记一下：XXX 是个坑 / XXX 的结论是…" | `deposit` 写入 + 自动去重 + 自动分类（纠正旧结论用 `deposit --corrects <旧id>`） |
| "找一下之前关于 XXX 的记忆" | `recall --query "XXX"`；`--top N` 按域、`--max-age-days N` 按新鲜度 |
| "帮我整理一下今天的记忆" | `reflect --auto`（不删）+ `doctor --contradictions` + `decay --apply` |
| "帮我规划记忆分类" | AI 引导四步走生成 `taxonomy.json`；`reclassify` 单条改域 |
| "关掉弹窗 / 不自动注入" | `hooks --mode silent`（默认）/ `full`（有弹窗）/ `off` |
| "帮我一键配好记忆系统" | `keeper_setup.py all`；"配 IMA"→`keeper_setup.py ima --kb-id <ID>`。**🔴 "开加密"不在此列**——它是强制门禁动作（不可逆、无后门），AI 不会直接执行；必须先走「对话路由契约」第 4 条三步确认（复述 §九 A1 红线 → 你明确说"继续" → 已落盘 keyfile+手抄恢复码），详见 §七硬门与 §九 A1 |
| "建一个每天自动整理的定时任务" | `automation_update` 注册每日 reflect；`dashboard` 出可视化；`cluster --apply`；`ima_sync.py` 推 IMA |
| "看看库的整体状况 / 还能开哪些功能" | `audit`（能力体检+开关建议）/ `doctor`（就绪绿红自检） |
| "你最近自动记了什么？给我看看" | `working --top 20`；`confirm --id <id>` 放行入库；`list_quarantine` / `review_quarantine --id <qid> --action release` |
| "更新完怎么生效 / 我升级了 keeper" | `scripts/keeper_setup.py hooks --scheduler`（部署物不随技能更新自动刷新） |
| "记不进去 / 找不到了 / embedding 降级了" | AI 跑 `doctor`+`audit` 读真实状态、对话式引导你修（详见 `references/QA.md` §14） |

> 💡 **高级 / 运维类能力也对 AI 说人话就能触发**：聚类、蒸馏、矛盾仲裁、批量归档、体检、图谱、关系链、轮换密钥、恢复码、校准、stats、explain、隔离复审等——完整长尾触发见下方折叠表与 `COOKBOOK.md` §7/§8/§9。
> 🩺 **出问题了？别翻文档。** 直接对 AI 说人话，AI 跑 `doctor`+`audit` 定位并对话式引导你修，确认后再动手。
> ⚠️ **对话解决不了的边界（设计使然，非缺陷）**：① **忘 key 且无恢复码** → 永久丢失（红线 A1）；② **环境级故障**（Python 缺失 / fastembed 下载失败 / 计划任务被系统策略禁用）→ AI 能引导排查，但 OS 层改动需你手动。其余记忆操作类问题均可对 AI 说人话解决。
> ⚠️ **`audit` 同名异义（已代码层消歧）**：`memory_ops` 的 `audit` = 按库规模推荐「该开哪些功能」；`mem_bridge` 原 `audit` 已更名 **`scan_dup`**（只读扫描内部近重复/矛盾）。**mem_bridge 命令总数 = 29**（inject/rank/route/retrieve/capture/guard/drift/seed/compress/coach/selftest/scan_dup/import/benchmark/mcp 等），用途与参数见 `references/MEM_BRIDGE.md`。投资域专属桥为 `scripts/investment_bridge.py`（与根 `mem_bridge.py` 是两个不同文件，勿混）。

<details>
<summary>🗣️ 长尾高级操作 → 对 AI 说什么（40+，低频但实用，点开看）</summary>

| 你对 AI 说 | AI 执行（真实命令） | 备注 / 限制 |
|---|---|---|
| "看看这条记忆的版本历史" | `timeline --id <id>` 或 `timeline --query "主题"` | 任何写入都自动留版本，不再只有 overwrite 才有历史 |
| "把这条经验固化成项目的行为规则" | `export-rules --rules-target project` | 选已确认/高频条目写入 `AGENTS.md`；`--dry-run` 先预览 |
| "把 AGENTS.md 里的规则逆向回灌记忆库" | `import-rules --rules-target project` | 仅灌入新增条目，不重复 |
| "轮换 / 更换加密密钥" | `rekey --new-key <新密钥>` | 全库重加密+重建索引；空密钥/降级明文被拒（fail-closed） |
| "生成恢复码 / 把密钥写成 keyfile" | `recovery-code --write` | 忘 key 也能凭恢复码自救 |
| "我忘了密钥，用恢复码找回" | `recover-key --code <码>` | 还原到 `store/enc_key.txt` |
| "给记忆建关系图谱 / 清理悬空边" | `graph --build` / `graph --clean` / `graph --rebuild` | 只标不删；均支持 `--dry-run` |
| "把相似的记忆蒸馏成一条原则" | `distill --review`（预览）/ `distill --apply` | 需 LLM；`--apply` 才落盘，原记忆只降权不删 |
| "看看我的用户画像" | `profile` | 离线，不跨域泄漏 |
| "找出反复出现的重复模式" | `recurrence --auto-candidate` | 跨≥2任务+30天的组标为晋升候选 |
| "把沉了/超额的记忆批量软删归档" | `reclaim`（预览）/ `reclaim --apply` | 180 天沉淀；**只归档不删** |
| "整库备份 / 从备份恢复" | `backup --zip <路径>` / `restore <zip> --yes` | `restore --verify` 校验条目数与索引一致性 |
| "把某条记忆归档（不删）/ 取消归档" | `archive --id <id>` / `unarchive` | 沉底 `archive/`，永不删除；**单条用 `archive`，批量用 `reclaim`**（边界见 §九） |
| "物理删除某条记忆（不可逆）" | `delete --id <id> --yes` | 必须 `--yes`，有 `--dry-run` 预览 |
| "回滚到某历史版本 / 看版本链" | `rollback --to-version N` / `versions --id <id>` | 写入门禁强制覆盖前留快照，rollback 前也会先留档 |
| "确认一条自动暂存的记忆入库" | `confirm --id <mid>` | `auto_sourced` 隔离项放行 |
| "批量导入记忆（JSONL/CSV/MD）" | `import --file <路径> --execute`（两入口同名） | **默认仅 dry-run 预览，必须加 `--execute` 才落盘**（import 无 `--dry-run` 参数） |
| "升级某条记忆的层级 / 看晋升候选" | `promote --auto` / `promote --review`（两入口同名） | `--review` 只列候选不修改 |
| "重新分类某条 / 看缺标注的注入队列" | `reclassify --type X --yes` / `reclassify --pending` | `--pending` 只读 |
| "出一张可视化看板 HTML" | `dashboard --out <路径>` | 树 + 聚类 + 矛盾高亮 + 召回策略 |
| "按主题聚类打标签" | `cluster --apply` | 需神经后端且 ≥8 条已嵌入记忆 |
| "强矛盾自动仲裁（标旧不删）" | `doctor --contradictions --fix --arbitrate` | 离线禁真实仲裁，仅 `--dry-run` 预览 |
| "跑性能基准（别污染真库）" | `benchmark --root <隔离目录>`（两入口同名） | **必须 `--root` 隔离目录**，禁止对真库跑 |
| "把 keeper 暴露成 MCP 服务" | `mcp` | 供 Claude Desktop / Cursor 连接；长驻进程 |
| "整库导出 Markdown / JSONL" | `export --format md\|jsonl --out <路径>` | **默认仅导出 active**——全量加 `--include-archived` 或 `--include-superseded` |
| "把记忆搬到另一台电脑" | `scripts/keeper_sync.py out\|in` | 见上方「🔄 跨设备同步」；**不要用裸 export+import** |
| "把记忆导出成 learnings 文件" | `export --format learnings [--out <目录>]` | 每条渲染为 date/trigger/lesson/recurrence_count/status |
| "把高频经验萃取成 skill 脚手架" | `extract-skill [--min-count 3 --out-dir <dir>]` | 生成 SKILL.md+references/+hooks/ |
| "看健康摘要 / 能力体检 / 召回分布" | `report` / `audit` / `stats` | 只读、零模型依赖 |
| "看记忆树 / 变更审计日志" | `tree-view`（仅 mem_bridge）/ `audit-log --top N` | 只读 |
| "建每日/每周自动整理" | `schedule_reflect` / `schedule_self_heal` | 只输出配置，不偷偷建任务 |
| "一键跑完整自治循环" | `self-heal [--force] [--discover]` | 合并 reflect/evolve/decay/doctor/skill-sync/export-rules，dirty 驱动 |
| "开 / 关本地 LLM 自进化" | `llm-setup --enable-llm` / `--disable-llm` | 默认关，Ollama 优先 |
| "初始化记忆库 / 看所有命令" | `init` / `commands` / `quickstart` | 首次建库/加密/索引 |
| "解释这条记忆为什么被召回" | `explain --id <id>` | 评分拆解、召回路径、来源 provenance |
| "给两条记忆建立关系" | `link --id <源id> --target <目标id> --rel see_also` | 关系图谱基础；`--rel` ∈ see_also/superseded_by/corrected_by/consumes/test_of/composed_of/validated_by/audits；不删原记忆 |
| "生成分层摘要索引" | `summary-index`（仅 mem_bridge） | 只读；Layer2 紧凑视图 |
| "看注入上下文统计（调试）" | `inject_stats`（仅 mem_bridge） | 只读 |
| "看 working 层待蒸馏记忆" | `working --top 20`（仅 mem_bridge） | 只读 |
| "清理过期 / 低价值记忆（先预览）" | `purge --older 180 --min-imp 0.4`（仅 mem_bridge） | **默认 dry-run**，加 `--apply` 才真删（不可逆）；**只筛「已归档/已被取代」且超龄的软删件——`active`（含今天新记的）不在候选内**，清当天噪音请用 `reflect --auto` / `archive`（边界见 §九） |
| "把高价值经验导出成 L2 草稿" | `to-l2 --min-importance 0.8 --min-access 3` | 只读预览；加 `--export <库内路径>` 写盘（禁写库外） |
| "复审被 secrets 隔离的候选" | `list_quarantine` / `review_quarantine --id <qid> --action release` | 命中敏感自动隔离，不删 |
| "让记忆自己进化：提炼原则" | `evolve`（预览）/ `evolve --apply` | 复发印证→提炼原则（provenance=auto、限期复核） |
| "把 keeper 高层原则回流到 宿主应用 记忆" | `distill-to-wb`（预览）/ `distill-to-wb --apply` | keeper→宿主 单向蒸馏，幂等去重 |
| "校验我记的投资结论对不对" | `verify-investment --duckdb <路径> --sql-map <json>` | 从 DuckDB 复算校验（fail-open：库不可用只告警） |
| "这条记忆是错的，忘掉它" | `forget --id <id> --forget-reason "..."` | 显式判错归档（erroneous=True、belief_strength=0），永不静默删内容 |
| "这条记忆有用 / 没用（校准信念）" | `feedback --id <id> --signal good\|bad`（两入口同名） | good→提 belief_strength；bad→下调，低于阈值标可能过时 |

> 🧭 **CLI 入口（2026-09-13 实测校准，别混用）**：上表命令分属**两个**可执行入口——
> - `memory_ops` → `python scripts/memory_ops.py <命令>`：库管理全量命令（记/查/改/删/归档/图谱/体检/导出…）。
> - `mem_bridge` → `python mem_bridge.py <命令>`：宿主 集成层（注入/蒸馏/清理/跨设备/统计）。
>
> 标「**仅 mem_bridge**」的命令**只在第二个入口存在**（对 `memory_ops` 跑会报 `invalid choice`）：`purge`、`to-l2`、`inject_stats`、`working`、`summary-index`、`tree-view`。
> 标「**两入口同名**」者两边都注册（`import`/`promote`/`benchmark`/`mcp`/`feedback`），具体参数以各自 `--help` 为准。
>
> 💡 完整 `memory_ops` 命令 + 参数见 `references/COMMANDS.md`；命令行跑 `python mem_bridge.py --help` 可列出当前全部子命令——以代码为准，不迷信文档数字。对话里说不清时，直接问 AI「XXX 这个需求该用哪个命令」。

</details>

> ⚠️ **关于钩子弹窗（不是 bug）**：`full` 模式下每点一次发送按钮界面闪一下"执行中"提示条——这是 宿主应用 钩子执行指示器（平台固有行为），切到 `silent`（默认）即无弹窗。详见 `references/QA.md`「钩子弹窗」。

| 模式 | 弹窗 | 自动加载记忆 | 适合谁 |
|---|---|---|---|
| `full` | 有（每次发送/开场闪一下） | ✅ 每轮自动浮现相关记忆 | 不介意闪条、想要"保证浮现"的用户 |
| `silent`（**默认**） | **无** | 改由 AI 按需 recall | **大多数用户**——零弹窗、不阻塞 |
| `off` | 无 | 无 | 想完全手动的用户 |

切换方式：对 AI 说"关掉弹窗"（→ silent）或"恢复完整钩子"（→ full）。**改完后重启宿主应用生效**。模式持久化在 `hooks_config.json`。

### 4.2 四个运行时开关（口语可切）
| 开关 | 默认 | 怎么开 / 关（自然语言） |
|---|---|---|
| ① 原生记忆打通（宿主应用→keeper 自动沉淀） | ✅ 开（会话结束自动） | 只读 宿主、只写 keeper、幂等不重复；想关 → `KEEPER_AUTO_CAPTURE=0` |
| ② 对话内自主沉淀（converse） | ✅ 开（默认 20 轮，无弹窗） | "改成每 50 轮" / "先别自动记" → `converse --set-threshold 50` / `KEEPER_AUTO_CAPTURE=0` |
| ③ 置信度校准闭环（feedback） | ✅ 开 | 召回后问"这条是否有用"，回 `good`/`bad` 即生效；每会话上限 3 次防过载 |
| ④ 每日 reflect 自动化 | ⛔ 关 | "建一个每天自动整理的定时任务" → `automation_update` 注册 |

> ①② 是"**捕获**"（从哪来经验）；③④ 是"**质量**"（校准 / 定期整理）。四个绝不删除记忆。
> ⚠️ **两个高频误解**：① **默认不是「不自动记」**——`auto_capture` 默认开、每 20 轮自动整理；想改说"改成每 50 轮"。② **「没看到注入段落」≠ 钩子没装**——注入由 `inject_enabled` 单独门控，**默认关**（省 token）。想开说"开启自动注入"。改完 `hooks` 模式需**重启 宿主应用** 生效；`auto_capture` 等开关改完即刻生效。

#### 🧭 我该选哪种模式？
| 模式 | 适合谁 | 你会看到什么 | 怎么切 |
|---|---|---|---|
| **silent（默认）** | 绝大多数人：想被自动记住，但讨厌被打断 | 后台静默沉淀、无弹窗；靠你问或 `recall` | 装完即此态 |
| **full（完整）** | 想让经验每轮自动注入上下文 | 会话开局可能弹一次确认框 | 说"恢复完整钩子" → `hooks --mode full` |
| **只手动** | 只想「我说记才记」 | 没有任何自动动作 | 说"先别自动记" → `KEEPER_AUTO_CAPTURE=0` |
| **全关** | 排障 / 临时静音 | 钩子与自动沉淀都停 | `hooks --mode off` + `KEEPER_AUTO_CAPTURE=0` |

### 4.3 可选能力 · 性能 · 高级功能（合并总表）
> 绝大多数能力**已默认开**，只有 3 项需手动（加密 / IMA / Ollama）。完整「三桶分类」见 `references/ENABLEMENT.md`；不想读长文直接问 AI「我还能开哪些功能」跑只读 `audit`。

**能力清单（获得什么 / 代价）**：
- **神经语义召回（中文更强，默认已开）** — `fastembed`（本地 ONNX，CPU）开箱默认启用，首次用到中文语义时自动下载约 **90MB** 权重（落盘在用户缓存目录（重装不丢），重装不丢），中文改写召回率 ~30%→90%+。实测端到端 recall ≈ 3.75s（冷加载占 ~78%）；开磁盘缓存后重复查询降至 ~0.9s；守护进程常驻后毫秒级。内存 ≤8GB 老机器可降级 `embed lexical` 或 `记忆 --flat`。
- **ANN 加速** — 库 ≥50 条且 ≤256 条默认自动启用（结果与全量一致）；>256 条大库剪枝需显式 `recall --ann`；<50 条不启用（反而慢）。
- **聚类 / 主题标签** — 需神经后端 + 库 ≥8 条已嵌入；`cluster --apply` 偶尔跑。
- **可视化 Dashboard** — `dashboard` 生成单文件 HTML，秒级。
- **主动矛盾 / 重复扫描** — `doctor --contradictions`（需神经后端）；推荐每周一次低频，库 >500 条别放高频。
- **加密 at rest** — 设 `AI_MEM_ENCRYPTION_KEY`；**开前必先备 recovery 兜底**（红线 A1）。有敏感内容强烈推荐。
- **本地 LLM 增强（Ollama）** — 需装 Ollama + 拉模型（~5GB，常驻吃内存/磁盘/GPU）；**仅本机够强才开，低配机器勿开**。
- **IMA 知识库镜像** — 归档记忆自动推送（需已连 IMA MCP 会话配知识库）；推送前**强制脱敏**（红线 A4，绝不交付明文）。
- **行为规则层固化（export-rules）** — 高频/已确认经验固化成 AI 每轮行为规则写入 `AGENTS.md`，可提交 git。
- **轻量文件层（`--flat`）** — 跳过 SQLite/LLM，纯 Markdown、grep 召回，零依赖；代价：失去语义召回/分层，适合极简用户。
- **about_axis 四轴 / 复述加权 / recurrence 候选 / staging 隔离开关 / freshness 过滤** — 默认即开，无需配置。
- **从历史会话主动沉淀（harvest --from-conversations）** — 把 宿主 历史会话里值得长期记的经验批量沉淀；会话来源打 `wb_session` 标签并幂等去重。⚠️ 无 LLM 时 `harvest --self-learn` 只产 `corrections` 建议、`candidates` 恒空，沉积条数 0 属正常（详见 `references/LIMITS.md` LLM 配置节）。

**性能消耗与库规模边界（低配 / 老机器必读）**：
| 项 | 吃资源表现 | 低配替代方案 |
|---|---|---|
| **Ollama 本地 LLM** | 模型 ~5GB 常驻占内存+磁盘+GPU | 用默认线上 LLM，或不开 |
| **神经语义 fastembed（默认开）** | 常驻 100–150MB 内存；冷启动 ~2.9s | 改 `embed lexical` 或 `--flat` |
| **矛盾扫描 `doctor --contradictions`** | 随库规模近似线性，>500 条可跑几分钟吃满 CPU | 每周/每月一次，<300 条再开 |
| **聚类 `cluster --apply`** | 全量向量计算，数十秒 | 偶尔手动，别放每日 |
| **ANN 加速** | 首次建索引一次性开销（落盘复用） | 默认已自动开；要穷举用 `--no-ann` |

| 库规模 | 召回行为 | 你该做什么 |
|---|---|---|
| **< 50 条** | 线性全量扫描，最快最准；ANN 自动不启用 | 无需动作 |
| **50–256 条** | 自动启用 ANN（结果与全量一致） | 默认即开 |
| **> 256 条** | ANN 仍是默认；超大库可 `--ann` 剪枝 | `doctor --contradictions`/`cluster` 放进周/月低频 |
| **> 1000 条** | 建议给高频域独立热位 | `promote --tier core` 钉住核心 |
| **≈ 1 万条** | 🔴 冷召回分钟级（超线性） | 定期 `reflect --auto` + `decay`，召回走向量化/守护进程常驻 |

> 🔴 铁律：低配机器**不要开 Ollama**；**fastembed 可降级为词法**；`doctor --contradictions` 与 `cluster` **只放低频**。最后一行是实测，精确数字见 `references/LIMITS.md` §12。`benchmark` 必须 `--root <隔离目录>`，禁止对真库跑。
> 🛡️ **矛盾仲裁安全铁律（离线禁写）**：`doctor --arbitrate` 未注入 LLM 时禁止真实仲裁，仅 `--dry-run` 可预览；注入 `KEEPER_LLM_*` 后强制让 LLM 确认"真矛盾"才标旧。详见 `references/LIMITS.md` §仲裁。

### 4.4 推荐开启配置（按场景）
- **个人小库 / 中文用户（<50 条）**：中文语义已默认开；有敏感内容就开 `加密`；其余保持关。
- **中-大库（≥50 条）**：加开 `ANN`；`doctor --contradictions` 放进每周自动化；`cluster` 偶尔手动。
- **有本地 Ollama 且机器够强**：可加开 `LLM 增强`。
- **不确定开哪些**：说"帮我看看我能开哪些功能" → AI 跑只读 `audit`；或"你能帮我管理记忆系统做哪些事" → AI 列出全部能力。

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

## 五、有哪些要求（前置条件）
- **必需要**：一个能跑 Python 的运行环境（执行 `scripts/memory_ops/__init__.py`）。
- **开箱即用（零配置）**：装完即获**中文语义召回** + **silent 钩子** + 词法兜底，不用手配就能记 / 找 / 整理。
- **仅 3 项需手动开启**（安全/外部/重资源）：`cryptography`+加密开关（忘 key 且无恢复码=永久丢失）；`Ollama`+模型（~5GB）；IMA 知识库（需先配）。
- **网络**：默认**纯本地零云端**；仅首次装 fastembed 需联网一次（HF 不可达自动切国内镜像），之后完全离线。

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

## 六、如何配置
**一句话**：对 AI 说即可，AI 背后跑 `keeper_setup.py`，你不用手敲任何环境变量。你可能手设的只有两个：
- `AI_MEMORY_STORE` — 记忆库根目录（回退链见下；换路径/跨设备携带时设）。
- `AI_MEM_ENCRYPTION_KEY` — 开启加密（**绝不写进文件/git**；开前先 `recovery-code --write` 备兜底，红线 A1 见 §九）。

**记忆库位置（回退链，从高到低）**：① `AI_MEMORY_STORE` ② `~/.keeper/store_root` ③ 平台默认（Windows `~/AI记忆`、mac/Linux `~/.ai-memory`）。换盘/换机只改任一层，**不要把本机路径写进代码或配置**。

其余运行时开关收口在 `store/config.json` 的 `keeper` 块（**全量 13 键**，与代码 `KEEPER_DEFAULTS` 一一对应）：

```json
{
  "keeper": {
    "embed_backend": "fastembed",
    "embed_online_url": "",
    "inject_enabled": false,
    "inject_daily_cap": 6,
    "inject_dedup": true,
    "inject_dedup_days": 14,
    "feedback_session_cap": 3,
    "rehearsal_alpha": 0.05,
    "ann_min_memories": 50,
    "ann_auto_large": false,
    "auto_capture": true,
    "converse_threshold": 20,
    "write_gate": true
  }
}
```

| 键 | 默认 | 作用 | 对应环境变量（优先级最高） |
|---|---|---|---|
| `embed_backend` | `fastembed` | 语义后端；填 `lexical` 走纯词法 | `AI_MEM_EMBED_BACKEND` |
| `embed_online_url` | 空 | 线上 embeddings 端点 | `AI_MEM_EMBED_ONLINE_URL` |
| `inject_enabled` | `false` | 是否自动注入记忆到上下文（默认关，靠显式 `retrieve`）。**会话启动钩子也守此开关**，优先级 env > `store/config.json` > 默认 `false`，异常 fail-closed。想恢复：`store/config.json` 设 `true` 或 env `KEEPER_INJECT_ENABLED=1` | `KEEPER_INJECT_ENABLED` |
| `inject_daily_cap` | `6` | 每日自动注入条数上限 | `KEEPER_INJECT_DAILY_CAP` |
| `inject_dedup` | `true` | 注入去重开关 | `KEEPER_INJECT_DEDUP` |
| `inject_dedup_days` | `14` | 注入去重窗口天数 | `KEEPER_INJECT_DEDUP_DAYS` |
| `feedback_session_cap` | `3` | 每会话自反馈次数上限（防自反馈死循环） | `KEEPER_FEEDBACK_SESSION_CAP` |
| `rehearsal_alpha` | `0.05` | 复述加权系数 | `KEEPER_REHEARSAL_ALPHA` |
| `ann_min_memories` | `50` | 启用 ANN 的最小记忆条数 | `AI_MEM_ANN_MIN_MEMORIES` |
| `ann_auto_large` | `false` | 大库（>256 条）是否自动开高召回 ANN | `AI_MEM_ANN_AUTO_LARGE` |
| `auto_capture` | `true` | 对话内自动沉淀（converse）开关 | `KEEPER_AUTO_CAPTURE` |
| `converse_threshold` | `20` | 每多少轮跑一次 harvest+self-learn+reflect | `KEEPER_CONVERSE_THRESHOLD` |
| `write_gate` | `true` | **写入门禁**：覆盖旧内容前必须先留版本快照，留不下就**中止写入**（fail-closed）。旧内容解不开时（典型密钥轮换）不中止，改原样快照密文再放行。逃生：`KEEPER_WRITE_GATE=0` | `KEEPER_WRITE_GATE` |

> env 名 → 键映射见代码 `_KEEPER_ENV_MAP`；**优先级：env > `store/config.json` > `KEEPER_DEFAULTS`**。改完可用 `python scripts/verify_claims.py` 校验「文档键 ↔ 代码键」对称。配置文件标准位是 `<记忆根>/store/config.json`，`<记忆根>/config.json` 仍作兼容兜底（store 优先、root 兜底、逐键合并）。

## 七、如何使用（最小上手）
记忆默认零配置，首次自动建库。想照跑看每步输出：`python scripts/demo_walkthrough.py`。**最省事**：日常直接对 AI 说「记一下… / 找一下之前那个… / 整理今天记的」。

> 🧹 **「整理」什么时候跑、跑完怎么算正常**：
> - **何时自动整理**：① 会话结束（Stop 钩子，默认开）② 你手动说"帮我整理今天记的" ③ 周维护自动化只做采集+聚类+矛盾修复+沉底+IMA，**绝不删除或改动记忆**。
> - **成功标准**：`reflect --auto` 输出「去重 N / 纠错 M / 晋升 K / 归档 P」，**永远 0 删除**；归档沉到 `memories/archive/`，`recall --deep` 找回。
> - **怎么算不正常**：看到大量「删除」或记忆凭空消失，那是手动 `delete --yes` 或 `purge --apply`，去 §九 核对。

> **🤝 对话契约**：你说一句，AI 背后跑命令并**回显「已设 XX / 已记 XX」**；召回后 AI 可能问「这条是否有用？」，回 `good`/`bad` 即校准（每会话上限 3 次）；开了 converse/harvest 后 AI 会静默沉淀。若 AI 陷入"再确认"循环，说**「不用校准 / 不用注入」**即可切断。完整样例见 `references/TUTORIAL.md`。

> **🧭 对话路由契约（AI 必须守的消歧规则）**：
> 1. **模糊动词必须消歧，不许猜**：听到「清理 / 清空 / 整理 / 删掉 / 瘦身」，先判断指哪一个，**有歧义就先回问**，绝不直接执行破坏性操作。
> 2. **破坏性操作先预览、再确认**：凡 `delete` / `purge` / `reclaim --apply` / `decay --apply`，**先跑 `--dry-run`** 把影响面摆给你看，确认后才落 `--yes`/`--apply`；真删一律单次单条。
> 3. **意图不在能力表内，先回问**：没听过的需求先问清效果，再映射到最近命令；宁可多问一句，也不臆测执行。
> 4. **🔴 开加密 = 强制门禁动作（最高危险级）**：用户说「开加密 / 加密记忆 / 设个密钥」时，AI **不得直接执行** `keeper_setup.py encrypt`。必须先走三步：**① 完整复述 🔴 §九 A1 红线**（忘 key 且无恢复码 = 永久丢失、无后门）→ ② 必须收到用户明确「我已知风险，继续」的确认 → ③ 先跑 `recovery-code --write` 并**确认库外 keyfile（`store/enc_key.txt`）已落盘 + 恢复码已手抄**后，才设 `AI_MEM_ENCRYPTION_KEY`**。**任一步未完成即中止，绝不静默跳过兜底。**
>
> **消歧对照（最容易踩的四个）**：
> - 「清理一下」→ `reflect --auto`（不删）/ `decay --apply`（降权）/ `reclaim --apply`（归档）/ `purge --apply`（**真删·不可逆**）→ 先问："要整理去重，还是归档老的？真删不可逆，确定吗？"
> - 「删掉这条」→ `archive`（可找回）vs `delete --yes`（**不可逆**）→ 先问："先归档，还是真删？"
> - 「整理一下」→ 今日新增去重 / 全库重分类 / 聚类打标签 → 先问："整理今天记的，还是全库分类？"
> - 「同步到另一台电脑」→ `keeper_sync.py`（**合并式**，保留目标机新记忆）vs `backup`+`restore --yes`（**覆盖式**）→ 先问："要合并，还是整库覆盖？"

> 🔴 **【开加密硬门 · 数据丢失最高危】**：加密不是普通开关——它**不可逆且无后门**。AI 替你开加密前，会强制走上面「对话路由契约」第 4 条三步确认（复述红线 → 你明确说"继续" → 已落盘 keyfile + 手抄恢复码），**任何一步没完成都不会动手**。你自己手设 `AI_MEM_ENCRYPTION_KEY` 时同样务必先 `recovery-code --write`。忘 key 又无恢复码 = 库里加密内容**永远读不出**，任何对话/工具都救不回。

**照跑三条（纯命令行，不依赖 AI）**：
```bash
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>` ｜ 整理 `reflect --auto` ｜ 降权 `decay --apply` ｜ 标核心 `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` ｜ 脱离 宿主 自调度 `schedule_self_heal --cron` ｜ 一键自治 `self-heal [--force]`。

> 完整分步教程见 `references/TUTORIAL.md`；所有命令与参数见 `references/COMMANDS.md`。

## 八、如何检查可以开启哪些功能（自检清单）★
两条只读命令，不改动任何数据：
- **`audit`（能力体检，纯只读）** — 按库规模/环境给每个可选功能的"开启/关闭"建议。
  ```bash
  python scripts/memory_ops/__init__.py audit
  ```
- **`doctor`（就绪绿红自检）** — 七项一键体检：存储根 / 中文语义 / 落盘加密 / 钩子注册 / 守护进程 / IMA 同步 / 召回冒烟。
  ```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` 只读不写，`--fix` 才写修（不删内容）。`--contradictions` 做对立记忆对检测（需神经后端）。

## 九、安全护栏 · 红线与边界（唯一真源）
> 🔴 **红线分两组：数据类（不可逆 / 会丢会泄）与质量类（数据还在，但你被误导）——两组都不可破，无论你怎么说 AI 都守。其他文档里同类说法一律只留指针指回这里，不另立说法。**
> 🧭 **次要边界（非红线，但最常被误用）**：① 清理类命令怎么选（`purge` 不是通用清理）——见下方「清理类命令怎么选」；② 域分类落空（`domain=None`）是设计不是缺陷。**这两条已上提到文首「其余边界速查」。**

**A · 数据类红线（不可逆、会丢或会泄）**
- **A1. 开加密必须先备兜底**：开加密前先跑 `recovery-code --write`，确认**库外 keyfile 已落盘 + 恢复码已手抄**；两者缺一就**不开加密**。**忘 key 且无恢复码 = 数据永久丢失**，无后门。
- **A2. 绝不批量硬删**：`reflect` / `archive` / `decay` 只做去重·纠错·归档（**软保留**，`recall --deep` 可找回）；唯一真删是显式 `delete --yes`，且单次单条。
- **A3. 删必须显式 `--yes`**：不带 `--yes` 的删除一律被拒、文件原样保留。
- **A4. IMA 明文库强制脱敏**：推送前自动 strip 凭证 / 真实路径 / 邮箱，脱敏后复检；任何残留直接失败退出，**绝不交付明文**。

**B · 质量类红线（数据没丢，但你会被误导）**
- **B1. 静默质量退化必须显式可见**：语义后端失败会**自动退回词法**（召回率 ~90%→~30%）且不报错。因此召回/写入回显必须带 `embedding_status`，`doctor` 必须暴露 `fell_back_to_lexical`——**绝不允许「降级了但没人知道」**。**运行时已闭环**：`recall`（`--with-meta`）返回 `meta.fell_back_to_lexical`，空结果附 `empty_hint`（含修复命令）；`mem_bridge` 的 inject/retrieve 会消费该 meta，降级时**同时**向 stderr 告警并在注入上下文追加「⚠️ 已降级」标注；`report`/`doctor` 独立判定降级，避免「已走镜像=绿灯」的假绿灯。
- **B2. 重要记忆分类强制**：`importance ≥ 0.7` 且某轴被低置信自动分类时，系统标 `classify_review` 并告警——**不会静默猜分**；非法值直接报错。

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

> **边界（设计使然，非缺陷）**：① **忘 key 且无恢复码** → 加密记忆永久丢失（A1）。② **加密是字段级**：`summary`/`body` 密文，`id`/`category`/时间戳仍明文。③ **环境级故障**（Python 缺失 / 模型下载失败）→ 需你补环境。

> **边界（清理类命令怎么选 · 最常被误用的一处）**：`purge` **不是**通用清理——它只真删「**已归档 / 已被取代**」且**超龄（默认 180 天）+ 低重要度（默认 <0.4）**的软删记忆，`active` 条目（**含今天刚记的**）**永不在候选内**，所以拿它清当天噪音只会得到「0 条候选」，**这不是 bug**。
> 对照：`reflect --auto` = 去重 / 纠错 / 归档（**永不删除**）｜`archive --id <id>` = 单条软归档（可 `unarchive` 撤回、`recall --deep` 找回）｜`decay --apply` = 只降权（不移动不删除）｜`reclaim --apply` = 批量软归档（按沉淀阈值）｜`purge --apply` = 受控真删（**不可逆**）。
> ⇒ **清「今天的」用 `reflect --auto` 或 `archive`；`purge` 只处理早就软删、且放置超龄的沉淀物。**

> **边界（域分类落空 = `domain=None`，是设计不是缺陷）**：未命中任何域的记忆**存为 `domain=None`**，由 `report` 的「域分布 → none」桶体现（taxonomy 里的 `fallback_domain`（默认 `general`）只是**兜底筐的名字**，**不会自动写进域字段**；`reclassify_by_taxonomy` 明文拒绝「强行推到 fallback」）。想让落空记忆自动落到具体域，**显式**设 `KEEPER_DOMAIN_FALLBACK=<域>`（如 `general`）——开启后落域并打 `domain:fallback` 标签（与用户**显式**指定的同名域区分），且 `reclassify --pending` 仍会把你捞出来待人工归类。**默认关，行为与旧版逐字一致。**

## 📌 反模式清单（❌ 错误做法 → ✅ 正确做法）
> §九管「AI 必须守什么」，本清单管「你该怎么做」，两处各是各的单一真源，**不要多处翻**。

| ❌ 反模式 | ✅ 正确做法 |
|---|---|
| 把整段对话原文灌进记忆 | 只记提炼后的结构化经验结论，别当录音笔 |
| 用 `delete --yes` 当常规清理 | 先用 `archive` 软归档，真删才 `--yes`；不确定先 `--dry-run` |
| 重要记忆（`importance≥0.7`）不显式传 `--scene/--type` | 显式传值固化分类，否则 `classify_review` 告警 |
| 直接 `rsync memories/` 跨设备同步 | 用 `backup` 导出 ZIP + `restore`（避免 WAL/SHM 撕裂） |
| 手动改/删 `memories/*.json` | 走 op；改坏用 `rebuild` / `doctor --fix` 重建 |
| 开了加密却没存恢复码/keyfile | `recovery-code --write`；**忘 key 且无恢复码 = 永久丢失** |
| AI 反复"再确认"死循环 | 说"不用校准 / 不用注入"，或设 `KEEPER_FEEDBACK_SESSION_CAP=0` |
| 直接拿 `ima_bridge.py export` 裸产物上传 IMA | 走 `ima_sync.py`（强制脱敏 + 复检） |
| 把 secrets / 明文密钥写进记忆 | 只记方法不记 key；命中自动隔离 `quarantine` |
| 库 <50 条硬开 ANN | 保持默认，≥50 条自动启用 |
| `benchmark` 不指定 `--root` 就跑 | 必须显式 `--root <隔离目录>` |

> 📚 **反模式总索引**：本表 11 条是唯一真源；**想看每条「为什么错、踩了会怎样、完整 14 个避坑详解」→ `references/QA.md` §四「避坑详解 / 反模式清单」**。两处互补，不用到处翻。

## 投资记忆能力圈（investment 域）
> keeper 原生支持 `investment` 域，把「量化投资回测」做成体系化记忆：数据/参数 → 因子 → 因子测试 → 组合系统，四层对象全记住、能关联、可回溯。完整模型见 `references/INVESTMENT.md`。

- ⚠️ **冷启动用对桥**：投资记忆冷启动用 `python scripts/investment_bridge.py seed --domain investment`；根 `mem_bridge.py seed --domain 量化` 已**废弃**。双桥区别见 `references/COMMANDS.md`。
- ⚠️ **投资记忆走「记 + 验 + 明确待校验」闭环**：用 **`verify-investment`** 从 DuckDB 复算数值做回检——`verify-investment --duckdb <路径> --sql-map <json>`。校验结果区分 `verified_true/false` / `skipped`（已就绪但无可用 SQL）/ `needs_setup`（本应校验却因缺 DuckDB/sql_map 未校验）；存在 `needs_setup` 时返回 `default_sql_map_template` + `setup_hint` 引导 bootstrap。库不可用时仍 **fail-open**（只告警不阻塞）。详见 `references/EVOLUTION.md` §校验。

## 常见问题（精简 6 条，其余见 `references/QA.md`）
- **误删了能恢复吗？** 能。`versions --id <id>` → `rollback --to-version N --yes`；或 `backup`/`restore` 整库 ZIP。删除前优先用 `archive`。
- **`reflect` 会删我的记忆吗？** 不会。只去重/纠错/晋升/归档，**绝不删除**；遗忘路径是 `decay` 降权 + `reflect --auto` 归档（`recall --deep` 找回）。
- **中文换个说法搜不到？** 多半已降级到词法——对 AI 说「看看语义后端状态」，看 `doctor` 的 `embed_backend.fell_back_to_lexical`：为 `true` 即降级态，修好即回 ~90%+。
- **需要联网吗？** 默认纯本地零云端；仅首次装 fastembed / 可选 Ollama 需联网一次。
- **记忆存在哪 / 怎么备份？** 默认回退链（Windows `~/AI记忆`、mac/Linux `~/.ai-memory`）；`backup` 导出 ZIP、`restore` 恢复；跨设备合并式迁移用 `keeper_sync.py`。
- **AI 反复"再确认"死循环？** 说"不用校准 / 不用注入"，或设 `KEEPER_FEEDBACK_SESSION_CAP=0` 全关。

使用说明

# AI Agent 记忆系统

给 AI 的跨会话长期记忆：用大白话「记一下…」「找一下…」，自动存储、语义召回、去重纠错、分层归档。本地优先、零云端。

## 快速上手

1. 对 AI 说：「记一下：这个项目部署前必须先跑 lint」——经验自动入库
2. 下次会话说：「之前部署有什么要注意的？」——自动召回相关经验
3. 定期让 AI 跑 `reflect --auto` 整理沉淀，避免记忆库噪音堆积

## 三条红线

- 开加密前必须先跑 `recovery-code --write` 备好恢复码（忘 key 且无恢复码 = 数据永久丢失）
- 清理用 `archive`（软归档可找回），`delete --yes` 是真删不可逆
- 只记提炼后的结论，别把对话原文灌进记忆

## 依赖与环境

- Python 3，详见 requirements.txt；语义召回默认本地 fastembed，需设置 `HF_ENDPOINT`（带 https:// 协议）
- 安装/升级后让 AI 跑一遍 SKILL.md中的「5 项体检」，防止召回静默降级

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。