# 记忆系统设计说明（怎么运作、怎么生效）

> 2026-08-18 ｜ 配套文档：`全链路验证记录-2026-08-18.md`（流程与结果）
> 一句话：**存储零代码（md 文件分层 + 约定），入口要插件（开局注入索引 + 按钮触发规范流程 + 强制格式写入工具）。**

## 一、设计定位

DSH 的记忆管家，检索式记忆（不是数据库、不是向量检索）：

- **不建库**：记忆 = 组织好的 markdown 文件，人可直接读、可 git 管理、换机器即拷即走
- **外挂式**：不碰你正常的项目文件，记忆文件全部收在独立目录（记忆根）
- **提醒式**：不强制、不自动联想，靠"索引注入 + 按钮触发 + 规则引导"让用户时不时记一笔
- **效果待测试**：核心链路已通，真实使用价值需长期观察（见验证记录"遗留/待观察"）

## 二、存储布局（方案 A，2026-08-18 定）

```
~/Documents/DSH/memory/          ← 记忆根（globalMemoryDir，设置页可改）
├── common/                      ← 全局通用经验（活跃区，跨项目复用）
├── projects/<项目名>/           ← 项目经验（每个项目一个目录，自动创建）
├── references/                  ← 冷区：参考资料（命中搜索才读）
├── archive/                     ← 冷区：被遗忘移出的旧记忆
├── staging.md                   ← 升格暂存池（跨项目复用候选）
├── README.md                    ← 目录说明
└── .git/                        ← 整个记忆根一个 git 仓库（回滚保障）
```

**为什么项目记忆不在项目目录里**（方案 A 的由来）：
- 项目 `.gitignore` 加 `memory/` 做发布隔离 → DSH 的 grep 工具尊重 .gitignore → **记忆内容搜不到**
- 改为记忆统一收全局根 → 项目目录干净、发布隔离天然成立、grep 全量可见

## 三、核心机制（怎么生效）

### 1. 索引注入（"想得起"的入口）
- 时机：**每个会话第一步**（agent/pre-step 钩子），只注入一次（按 session.id 记）
- 内容：**文件名清单**（不读全文），按分类分组：
  ```
  【记忆索引】相关时按需读全文（单文件 ≤2KB），先活跃后冷区：
  本项目记忆 projects/dsh-simple-memory/：踩坑类：xxx.md、yyy.md；决策类：zzz.md
  本项目文档 docs/：...
  全局通用经验 common/：...
  记忆根目录游离：...
  ```
- 生效路径：模型看到索引 → 相关时用 read 工具读全文（每条 ≤2KB）→ 内容才进上下文
- 原则：**注入文件名、不灌内容**；冷区（references/、archive/）不注入，命中搜索才读

### 2. memory-write 工具（"记得住"的入口）
- 强制格式：文件名 `分类-主题.md`、首行 `## 日期 分类-主题`、内容 ≤2KB
- 分类开放自造：内置 踩坑-/流程-/决策-/偏好-/背景- 起步
- scope 二选一：`project`（写 projects/<当前项目>/）或 `global`（写 common/）
- 沙箱：工作区外写入 → 自动弹审批（= 写入前用户确认的天然机制）
- 自动建目录：项目目录不存在时首次写入自动创建

### 3. 灯泡按钮（高频触发入口）
- 位置：输入框左侧（conversation.input.left）
- 行为：点击 → 输入框塞入固定"记忆流程指令"（自包含，不依赖任何外部文件）
- 指令流程：① 回顾 → ② 逐条提议并标明 scope（项目/全局）+ 理由 → ③ 用户确认 →
  ④ memory-write 写入 → ⑤ 贴产出物 → ⑥ git commit（mem: 记 xxx）

### 4. 设置页（低频管理入口）
- 状态行：全局活跃条数、staging 池条数
- 记忆根目录配置：可改（写 cordis.patch.yml，重启生效）
- 初始化记忆仓库：一键建骨架 + git init（幂等）
- 浏览记忆：平级项目列表 + 全局 common/，点开读全文

### 5. 检索（"找得到"的能力）
- 不建索引文件：直接靠 agent 的 grep 工具现场搜文件系统
- 覆盖范围：全部项目 + 全局 + 冷区（一个记忆根，grep 一次全搜）
- 顺序约定：先活跃后冷区（冷区命中搜索才读）

### 6. 升格机制（跨项目复用）
```
项目经验（projects/）→ 发现可复用 → 入池 staging.md（低摩擦）
→ 池子非空提醒 → 用户点头 → 提炼入 common/（全局活跃）
```
- 不强制当场决策：先低摩擦捞取，批量整理时再确认
- 出池后删 staging 条目

### 7. 遗忘机制（上下文保鲜）
- 活跃区（common/ + projects/）→ 过期 → 移入 archive/（软删除，还在硬盘）
- 索引不显示 archive/ → 上下文永远清爽，硬盘永远完整
- 配套：活跃索引 ≤200 条目触顶治理（整合→遗忘→升级→删除，全要人确认）

### 8. git 管理（回滚保障）
- 记忆根一个独立 git 仓库
- 每次记忆操作（记/升格/遗忘/整理/删除）后立即 commit：`mem: <操作> <对象>`
- 回滚：写错 git checkout、误删 git restore、整理改坏退到操作前 commit

## 四、职责边界

| 谁 | 干什么 | 不干什么 |
|---|---|---|
| 插件 | 注入索引、按钮触发、工具管格式、HTTP RPC | 不存内容（内容全在 md）、不搜索（grep 的事）、不自动联想 |
| AGENTS.md | （可选参考）判断标准、操作透明约定 | 插件不依赖它运行（指令已自包含） |
| 模型 | 按索引按需读、按规则判断值得记、执行流程 | — |
| 用户 | 确认写不写、scope 定夺、整理决策 | — |

## 五、已知边界

- 索引注入依赖会话有 cwd（无法定位项目根时静默跳过）
- 跨项目浏览记忆：设置页可看全部项目，但索引注入只含当前项目（省上下文的设计取舍）