# AI 记忆

index1 的认知记忆模块（cognition）让 AI 跨会话记住工作经验。

## 为什么需要 AI 记忆

AI 有两个硬伤：
- **容量有限**：上下文窗口只能装这么多
- **会话隔离**：关了就全忘，下次重新来过

index1 的认知模块补偿这两个缺陷：
- 跨会话持久化 — 上次修 bug 的根因、踩过的坑、做过的决定，下次自动恢复
- 按需检索 — 不是塞满上下文，而是只加载当前最相关的记忆

## 记忆架构

index1 管理两种记忆：

| 模块 | 记忆类型 | 存什么 |
|------|----------|--------|
| **corpus** | 语义记忆 | 项目有哪些文件、函数、类（代码索引） |
| **cognition** | 情节记忆 | 学到了什么、踩了什么坑、做了什么决定 |

## 认知事实类型

认知模块存储的"事实"按类型分类：

| 类型 | 说明 | 示例 |
|------|------|------|
| `bug_fix` | Bug 修复记录 | "FTS5 contentless 模式需要手动同步索引" |
| `decision` | 技术决策 | "选择 SQLite 而非 PostgreSQL，因为单文件零部署" |
| `constraint` | 项目约束 | "Python 3.14 环境需要 --break-system-packages" |
| `preference` | 偏好/惯例 | "commit 信息用中文" |
| `pattern` | 行为模式 | "搜索流程：先 index1 recall → 再 Grep 精确查找" |
| `discovery` | 技术发现 | "CJK 查询向量搜索效果远好于 BM25" |
| `architecture` | 架构知识 | "双数据库隔离：index.db + cognitive.db" |

## 自动学习（Hook 系统）

认知模块通过 Claude Code Hook 自动采集经验，无需手动操作：

| 事件 | Hook | 作用 |
|------|------|------|
| 会话开始 | `awaken` | 注入上下文 — 最近事实 + 决策原则 + 苏醒指引 |
| 用户提问 | `orient` | 搜索相关记忆，辅助当前问题 |
| 工具执行 | `observe` | 从 Write/Edit/Bash 输出提取认知事实 |
| 会话结束 | `reflect` | 启动离线维护（衰减、合并、推断） |

这意味着：
- AI 写完代码 → 自动记录改了什么文件
- AI 修完 bug → 自动记录根因和修复方法
- AI 做了决策 → 自动记录选择和原因
- 下次新会话 → 自动恢复相关上下文

## 手动记录

通过 MCP `learn` 工具主动记录：

```
learn("SQLite FTS5 contentless 模式需要手动同步索引",
      "在 index1 项目中发现删除文档后 FTS5 索引不同步")
```

只需 2 个参数（insight + context），类型、置信度、作用域全部自动推断。

通过 CLI：

```bash
index1 cog recall "FTS5 问题"     # 搜索认知记忆
index1 cog list                    # 列出最近事实
index1 cog status                  # 查看统计
index1 cog doctor                  # 诊断填充率
```

## 记忆分层

认知事实按重要性分层，不同层有不同的遗忘策略：

| 层级 | 包含类型 | 衰减策略 |
|------|----------|----------|
| **L3b** | constraint, preference | 永不衰减 — 项目约束和偏好不能忘 |
| **L3a** | architecture, pattern | 缓慢衰减 — 架构知识月级别遗忘 |
| **L2** | 其他所有 | 正常衰减 — 使用越多衰减越慢 |

衰减公式基于 Ebbinghaus 遗忘曲线，访问次数提供保护力（使用越多，忘得越慢）。

## 跨项目知识

高价值的经验可以跨项目共享：

- 置信度 >= 0.85 且被访问 >= 3 次的事实，自动提升为"通用知识"
- 通用知识在所有项目的会话中可见
- 例如："Python 3.14 需要 --break-system-packages" 对所有 Python 项目有用

## 离线维护

每次会话结束时，index1 自动在后台运行维护引擎：

1. **置信度衰减** — 长期未访问的事实降低置信度
2. **去重合并** — 合并语义相似的事实
3. **因果推断** — 发现事实之间的因果关系
4. **心智模型更新** — 更新对项目的整体理解
5. **策略提取** — 从重复行为中提取策略
6. **模式提取** — 从同类事实中提取通用模式
7. **邻居演化** — 为高价值事实关联相关知识
8. **通用知识提升** — 高价值事实升级为跨项目共享
9. **苏醒指引** — 生成下次会话的上下文简报
10. **垃圾回收** — 清理低价值事实

维护引擎在独立进程中运行，不影响正常使用。

## 从 Git 重建

如果认知数据库损坏或需要从零开始，可以从 git 历史重建：

```bash
index1 cog rebuild --dry-run     # 预览：不写入，只统计
index1 cog rebuild               # 实际重建
index1 cog rebuild --since "3 months ago"  # 只重建最近 3 个月
```
