Three Tier Memory

三层记忆系统

三个记忆文件，为 AI 提供跨会话的持久上下文。每一层有不同的范围、更新频率和目的。

---

为什么需要三层？

单一记忆文件行不通：

• 太细 → 臃肿，难以浏览
• 太粗 → 遗漏重要细节
• 所有内容同一更新频率 → 要么过时，要么噪音

三层按时间跨度和稳定性分离关注点：

graph TD
    subgraph "长期记忆"
        PM[project-memory.md<br/>架构、约束<br/>更新：很少]
    end
    subgraph "中期记忆"
        DL[decisions-log.md<br/>ADR、权衡理由<br/>更新：架构变更时]
    end
    subgraph "短期记忆"
        TH[task-history.md<br/>最近 30 条任务摘要<br/>更新：每次任务]
    end
    PM -->|指导| DL
    DL -->|指导| TH
    TH -->|积累进入| DL
    DL -->|稳定进入| PM

Loading

---

第一层：长期记忆 — project-memory.md

文件： .github/agent/memory/project-memory.md

用途： 项目的基本事实，很少变化。

内容：

• 项目名称、类型、业务场景
• 技术栈（语言、框架、数据库、测试框架）
• 架构图与模块列表
• 设计原则
• 关键约束（不可违反的硬规则）
• 已知问题与常见坑
• 开发环境配置

更新频率： 很少——当项目根本性变化时（新模块、技术栈变更、新约束）。

示例条目：

## ⚠️ 关键约束

1. 未经用户明确许可不得 git push
2. 所有 API 接口必须有输入校验
3. 数据库迁移必须可逆
4. 测试覆盖率必须保持在 80% 以上

大小建议： 保持在 500 行以内。如果文件过大，将旧事实迁移到 decisions-log.md 中作为 ADR。

---

第二层：中期记忆 — decisions-log.md

文件： .github/agent/memory/decisions-log.md

用途： 技术决策记录，包含上下文和理由。使用 ADR（架构决策记录） 格式。

内容：

• 决策标题和日期
• 状态（已采纳 / 已废弃 / 已替代）
• 背景（为什么需要这个决策）
• 方案对比（含优缺点表）
• 决策与理由
• 影响（这个决策会影响什么）

更新频率： 当做出架构或技术决策时。

示例条目：

### ADR-003：使用 SQLite FTS5 做全文搜索

- **日期**：2026-06-15
- **状态**：✅ 已采纳

#### 背景
需要商品搜索功能。考虑了 Elasticsearch、PostgreSQL 全文搜索和 SQLite FTS5。

#### 方案对比

| 方案 | 优点 | 缺点 |
|------|------|------|
| Elasticsearch | 功能强大、可扩展 | 依赖重、运维成本 |
| PostgreSQL FTS | 已有 PG | 正在从 PG 迁移到 SQLite |
| SQLite FTS5 | 零依赖、够快 | 不如 ES 强大 |

#### 决策
SQLite FTS5。

#### 理由
单用户应用，<10 万条商品。FTS5 轻松应对，无需新增服务依赖。

#### 影响
搜索查询走 FTS5 虚拟表。不需要新基础设施。

---

第三层：短期记忆 — task-history.md

文件： .github/agent/memory/task-history.md

用途： 近期任务运行日志。为下一次会话提供即时上下文。

内容：

• 任务 ID 和标题
• 日期
• 类型（feat / fix / refactor / chore）
• 做了什么
• 变更文件
• 后续注意事项

更新频率： 每次任务。这是不可协商的 Act 阶段输出。

保留策略： 保留最近 30 条。旧条目归档到 docs/task-history-archive-YYYY-QN.md。

---

三层如何协作

会话 1：  安装 ai-coding-ok
          → project-memory：技术栈、架构
          → decisions-log：ADR-001（SQLite 选择）
          → task-history：TASK-001（安装）

会话 5：  添加搜索功能
          → AI 读取全部 3 个文件，知道 SQLite FTS5 决策
          → task-history：TASK-005（搜索功能）

会话 20： 重构数据库层
          → AI 读取全部 3 个文件，看到 20 条任务上下文
          → decisions-log：ADR-004（新数据库模式）
          → task-history：TASK-020（重构）

会话 50： 新成员加入
          → AI 读取全部 3 个文件，有 50 条历史
          → 可以解释："我们用 SQLite 因为 ADR-001。在 TASK-020 重构了数据库。"

---

对比：手写 AGENTS.md vs ai-coding-ok 记忆

	手写 AGENTS.md	ai-coding-ok 记忆
初始设置	手动填占位符	一句话描述，AI 推断其余
中期决策	丢失（或散落在 PR 描述中）	以 ADR 格式记录在 decisions-log.md
近期任务上下文	会话间丢失	task-history.md 中最近 30 条
记忆更新	手动（经常忘记）	通过 PDCA Act 阶段自动执行
10 轮迭代后的状态	过时的快照	10 条记录的活文档

---

记忆文件大小预算

文件	建议上限	原因
project-memory.md	500 行	超过后 AI 会跳过而非阅读
decisions-log.md	50 条 ADR	废弃的 ADR 归档到单独文件
task-history.md	30 条	旧条目 → docs/task-history-archive-YYYY-QN.md

三个文件合计通常 <10KB，在 AI 上下文窗口中可以忽略不计。

---

下一步

• PDCA 工作流 — 记忆如何被读取和写入
• 四种模式 — Mode B 何时读记忆，Mode C 何时写记忆
• 日常开发流程 — 日常记忆使用