work-ally 0.2.0-alpha.1

package/docs/planning/FEATURE-memory-system.md

@@ -0,0 +1,748 @@
+# Memory System
+
+## Status
+
+- Target project: `work-ally`
+- Audience: implementation engineer / product architect
+- Scope: assistant desk memory system
+- Status: partially shipped / contract not fully closed
+- Goal: define a file-first, inspectable, low-complexity memory system for one assistant desk
+
+## Summary
+
+这份文档定义 `work-ally` 的 identity + memory feature。
+
+当前状态补充：
+
+- assistant desk 文件集合、archive raw layer、`journal/`、`MEMORY.md`、`NOW.md`、`MISTAKES.md` 与 nightly digest 已经进入 shipped baseline
+- 当前未收口的重点不再是“是否存在记忆系统”，而是注入合同、纠错合同、删除/更正语义与文件职责边界的进一步产品化
+
+结论先行：
+
+1. `work-ally` 现在已经有 **黑匣子归档** 和 **nightly digest 雏形**，但还不是完整的记忆系统。
+2. 真正要做的，不是再加一堆目录，而是把 **原材料、人格承载、短期工作记忆、日记、长期记忆、错题本、注入规则** 这几件事定义清楚。
+3. 当前阶段坚持 **纯文本文件**，不引入向量数据库、不引入额外 memory platform。
+4. 项目知识属于项目，不属于 assistant desk；assistant desk 当前重点只承接 **助理自己的记忆系统**。
+
+一句话定义：
+
+> `work-ally` 的 identity + memory system = 以 assistant desk 为边界、以文本文件为载体、以 archive 为稳定原材料、以 assistant 工作中主动更新为主写入路径、以启动/续聊时的明确注入规则为读取路径的系统。
+
+---
+
+## Background
+
+### 为什么现在要单独定义 memory
+
+`work-ally` 已经把 assistant desk 从项目中分离出来，这一步决定了一个事实：
+
+- 项目负责项目制度与代码资产
+- assistant desk 负责 assistant 的身份、连续性与记忆
+
+如果这个边界不清楚，就会出现两个问题：
+
+1. memory 会和项目知识混在一起
+2. digest 虽然在写文件，但运行时并不知道该读什么、何时读、为什么读
+
+所以 memory 现在最需要的不是“更多数据”，而是**角色清晰、读写闭环清晰**。
+
+### 当前实现现状
+
+当前 `work-ally` 已有这些基础：
+
+- `.system/archive/`：黑匣子原材料归档
+- `journal/`：每日记忆输出目录
+- `MEMORY.md`：长期记忆文件
+- `NOW.md`：当前说明文件
+- `MISTAKES.md`：错题本文件
+- nightly routine：`nightly-memory-digest`
+- digest prompt/parser：`work-ally/bridge/src/memory-digest.ts`
+
+但当前实现仍存在明显缺口：
+
+1. `NOW.md` 的角色还没有产品化定义清楚
+2. `MISTAKES.md` 还没有明确“双写路径”
+3. nightly digest 只是基于原材料的提炼机制，而且未来可能演进
+4. 最关键的 **memory injection contract** 还没有固定
+5. `AGENTS.md` 与 memory files 的协作关系还需要明确写入
+
+因此，当前最准确的判断是：
+
+> 现状是 memory pipeline prototype，不是完整 memory system。
+
+---
+
+## Product Goal
+
+本 feature 要完成的不是“让 assistant 记住一切”，而是完成一个稳定、低复杂度、可人工检查的 identity + memory 闭环：
+
+```text
+archive -> active updates -> memory files -> prompt injection
+
+archive -> digest -> journal / MEMORY
+```
+
+系统目标分成四层：
+
+1. **保真留痕**
+   - 所有真实过程先进入黑匣子 archive
+2. **结构化沉淀**
+   - 不同重要度的信息进入不同 memory 文件
+3. **运行时可用**
+   - assistant 在启动、续聊、关键 turn 时知道该读什么
+4. **可纠偏**
+   - assistant 明确犯错时，能立即更新 `NOW.md` / `MISTAKES.md`
+5. **原材料稳定**
+   - archive 的内部结构先拍板稳定，未来提炼机制可以替换，但原材料协议不轻易变动
+
+---
+
+## Scope
+
+### In scope
+
+- assistant desk 内的记忆文件结构
+- 各文件的职责边界
+- 各文件的读写时机
+- nightly digest 与工作中随手更新的边界关系
+- runtime 读取 memory 的注入契约
+- `AGENTS.md` 与 `SOUL.md` 的职责边界
+- `AGENTS.md` 中应明确说明的 memory 使用规则
+
+### Out of scope
+
+- 项目知识库平台化
+- 向量数据库 / embeddings / semantic retrieval
+- “所有聊天全文都当作可直接检索记忆”的大而全系统
+- 复杂权限模型
+- 多 assistant 共享记忆
+
+---
+
+## Memory Boundary
+
+### 1. assistant desk 是记忆边界
+
+记忆属于 assistant desk，而不是项目目录。
+
+原因：
+
+- assistant 是“来到项目里工作”的，不是项目本体的一部分
+- 一个 assistant 的连续人格、工作习惯、错误复盘，应放在 desk 上
+- 项目自己的制度、代码、文档，继续归项目自己管理
+
+### 2. memory 不等于 knowledge
+
+当前阶段必须明确区分：
+
+- **memory**：assistant 自己经历过、沉淀过、需要带到未来的东西
+- **knowledge**：项目文档、制度、代码事实、用户提供资料
+
+项目知识应继续从项目工作区读取，例如：
+
+- `AGENTS.md`
+- README
+- 项目内文档
+- 代码本身
+
+当前不单独产品化 assistant desk 的 `knowledge/` 目录。
+
+### 3. archive 不等于 memory
+
+`archive` 是稳定原材料，不是直接拿来当 prompt 的长期记忆。
+
+它的职责是：
+
+- 忠实记录过程
+- 作为当前及未来各种 digest / compression 机制的事实来源
+- 为人工排查提供依据
+
+它不承担：
+
+- 直接暴露给 assistant 作为常规热路径记忆
+- 人工频繁编辑
+- 替代 `MEMORY.md` / `NOW.md` / `MISTAKES.md`
+
+### 4. `AGENTS.md` 不等于 memory body
+
+`AGENTS.md` 是规则与使用契约，不是记忆正文。
+
+它负责告诉 assistant：
+
+- 有哪些身份与 memory 文件
+- 这些文件分别是什么意思
+- 启动时先读什么
+- 什么时候应该更新什么
+
+真正的记忆内容，仍然放在各自文件中。
+
+### 5. `SOUL.md` 不等于 `AGENTS.md`
+
+`SOUL.md` 用来承载 assistant 的名字、使命、人格、表达风格与做事方式。
+
+它适合放：
+
+- 助理是谁
+- 助理怎么说话
+- 助理怎么做事
+- 助理的价值取向与禁忌
+
+它不适合放：
+
+- 产品边界
+- 文件职责契约
+- 长期记忆正文
+
+因此，推荐模型不是二选一，而是：
+
+- `AGENTS.md` 负责稳定规则与读取契约
+- `SOUL.md` 负责人格与风格
+- memory 文件负责连续性记忆
+
+### 6. 对 Codex 而言，主规则入口只有两个 `AGENTS.md`
+
+从产品设计上，不应把 `SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md` 设计成和 `AGENTS.md` 并列的规则层。
+
+对 Codex 来说，真正的主规则入口只有两个：
+
+- 当前项目的 `AGENTS.md`
+- assistant desk 的 `AGENTS.md`
+
+其中：
+
+- 项目 `AGENTS.md` 定义“在这个项目里如何工作”
+- desk `AGENTS.md` 定义“这个 assistant 是谁、desk 在哪、还要继续读哪些 desk 资产”
+- `SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md` 都是 desk `AGENTS.md` 引导读取的资产，不是并列规则入口
+
+这意味着：
+
+- 不需要额外发明复杂的优先级矩阵
+- 项目 `AGENTS.md` 如对角色、风格、协作方式有明确要求，可以覆盖 desk 的默认人格基线
+- desk 负责提供默认人格与长期连续性，项目负责定义当前工作现场的约束
+
+---
+
+## Canonical File Set
+
+assistant desk 的 memory v1 采用以下最小集合：
+
+```text
+<assistant-desk>/
+  AGENTS.md
+  SOUL.md
+  NOW.md
+  MEMORY.md
+  MISTAKES.md
+  journal/
+  conversations/
+  .system/
+    archive/
+```
+
+其中 identity + memory feature 的核心文件角色如下。
+
+### `AGENTS.md`
+
+**定位**：稳定规则 / 加载器 / 宪法。
+
+它负责声明：
+
+- assistant desk 的文件契约
+- desk 资产的读取顺序
+- 哪些文件允许工作中更新
+- `SOUL.md` 是人格与风格来源
+- 它自己与项目 `AGENTS.md` 一起构成 Codex 的两个主规则入口
+
+要求：
+
+- 中文
+- 短、小、稳定
+- 尽量少让用户编辑
+
+### `SOUL.md`
+
+**定位**：人格、名字、气质、做事风格的承载文件。
+
+它适合承载：
+
+- 助理名称
+- 使命
+- 性格与表达风格
+- 做事原则
+- 用户希望长期保留的人设偏好
+
+要求：
+
+- setup 默认生成中文模板
+- 产品可预设骨架，但必须给用户留明显空白
+- 允许用户自由编辑
+- 默认不允许 assistant 在无明确授权时静默自改
+
+原则：
+
+> memory 可以自更新，soul 不应静默漂移。
+
+
+### `NOW.md`
+
+**定位**：热路径、当下态、工作中随手记。
+
+它记录：
+
+- 现在正在推进什么
+- 当前阻塞点是什么
+- 下一步准备做什么
+- 刚刚形成、但还不应进入长期记忆的重要提醒
+
+它不是：
+
+- 每日总结
+- 长期人生记忆
+- 完整聊天记录副本
+
+关键要求：
+
+- `NOW.md` 不是只靠 nightly digest 生成
+- assistant 在工作过程中可以主动更新它
+- 它允许短、碎、任务导向
+
+可以把它理解为：
+
+> assistant 醒来先看的床头便签。
+
+### `journal/YYYY-MM-DD.md`
+
+**定位**：每日工作日记 / 当日沉淀。
+
+它记录：
+
+- 当天发生了什么重要事情
+- 做了哪些关键决策
+- 形成了哪些当日结论
+- 哪些内容值得流向长期记忆或错题本
+
+它是：
+
+- digest 的主要日级产物
+- 从 archive 原材料提炼出的可读总结
+
+它不是：
+
+- 原始聊天记录
+- 长期稳定规则总表
+
+### `MEMORY.md`
+
+**定位**：长期稳定记忆。
+
+它只保留跨天仍然有价值、可复用、相对稳定的信息，例如：
+
+- assistant 的长期工作偏好
+- 用户长期稳定的协作习惯
+- 反复出现、已经稳定下来的项目协作规则
+- 未来应持续记住的背景事实
+
+它不应写入：
+
+- 当天临时任务
+- 易过期的待办
+- 一次性的聊天细节
+- 没有跨天价值的过程性碎片
+
+原则：
+
+> 只有“未来还值得继续记住”的东西，才进 `MEMORY.md`。
+
+### `MISTAKES.md`
+
+**定位**：高价值错题本。
+
+它记录：
+
+- 犯过什么错
+- 判断失误发生在什么场景
+- 原因是什么
+- 下次应如何避免
+
+它的价值不在“责备”，而在**防止重复犯错**。
+
+关键要求：
+
+- `MISTAKES.md` 有两条写入路径：
+  1. nightly / periodic digest 可追加或整理
+  2. assistant 明确意识到自己犯错时，可立即更新
+- 它不是普通日志；只收高价值、可复用的错误经验
+
+### `conversations/`
+
+**定位**：对话可读视图层。
+
+这里不应被定义成稳定原材料本体，而应被定义成：
+
+> 从 raw archive 派生出的、人和 assistant 都更容易阅读与分析的对话视图。
+
+它的角色是：
+
+- 给人查看完整聊天链路
+- 给 assistant 在必要时回看较长对话主线
+- 给复盘、排错、摘要提供比 raw archive 更低噪音的阅读界面
+
+它不是：
+
+- source of truth
+- 长期记忆本体
+- 默认热路径注入材料
+
+这里要明确区分：
+
+- `.system/archive/` = 稳定原材料层
+- `conversations/` = 可读视图层
+
+当前阶段它不是 memory 注入热路径的主来源，但它应成为“查看完整对话链路”的首选界面，而不是让人或 assistant 直接长期扫描 raw archive。
+
+### `.system/archive/`
+
+**定位**：append-only 稳定原材料归档。
+
+它应满足：
+
+- 自动写入
+- 忠实记录
+- 不要求人工整理
+- 可作为当前及未来压缩机制的第一事实来源
+
+它不应承担长期记忆的语义责任。
+
+---
+
+## Write Paths
+
+### Path A: system automatic archive
+
+写入方：bridge / runtime integration
+
+时机：
+
+- inbound message
+- outbound message
+- routine execution
+- approvals / user input / failures / progress
+
+产物：
+
+- `.system/archive/**/*.ndjson`
+
+要求：
+
+- append-only
+- 忠实保真
+- 不做摘要式改写
+
+### Path B: active work updates
+
+写入方：assistant 自己
+
+时机：
+
+- 明确完成了一个阶段，想给未来自己留便签
+- 明确识别到当前阻塞、下一步、注意事项发生变化
+- 明确发现自己犯了一个值得记录的错误
+
+产物：
+
+- `NOW.md`
+- `MISTAKES.md`（仅在错误明确且高价值时）
+
+这是本 feature 最重要的新增理念之一：
+
+> 记忆不是只靠夜里压缩；assistant 在工作中也要能随手写关键记忆。
+
+### Path C: nightly / periodic digest
+
+写入方：memory digest routine
+
+时机：
+
+- 夜间
+- 或固定周期回顾
+
+读取：
+
+- `.system/archive/`
+- 现有 `NOW.md`
+- 现有 `MEMORY.md`
+- 现有 `MISTAKES.md`
+- 必要时 `journal/` 近期内容
+
+产物：
+
+- `journal/YYYY-MM-DD.md`
+- `MEMORY.md`
+
+这里要强调几条边界：
+
+- digest 可以整理和提炼
+- 但 V1 不应回写 `NOW.md`
+- `NOW.md` 的 owner 是 assistant 本身，不是夜间压缩流程
+- `MISTAKES.md` 的即时更新属于工作流本身；digest 是否参与写入，属于未来可扩展项，不作为当前 v1 硬承诺
+
+### Path D: user manual edits
+
+写入方：用户
+
+时机：
+
+- 用户直接修正事实
+- 用户补充长期规则
+- 用户人工整理错题本
+
+允许人工编辑的原因：
+
+- 这些文件是产品资产，不是模型私有黑盒
+- 用户应当能直接检查与修正
+
+---
+
+## Read Paths
+
+### Read A: startup / wake-up
+
+assistant 启动或恢复工作时，运行时应遵守这样的读取模型：
+
+1. 先进入 Codex 的两个主规则入口：项目 `AGENTS.md` 与 desk `AGENTS.md`
+2. 再由 desk `AGENTS.md` 引导读取 `SOUL.md`、`NOW.md`、`MISTAKES.md`、`MEMORY.md`
+
+其中 desk 资产的推荐顺序是：
+
+1. `SOUL.md`
+2. `NOW.md`
+3. `MISTAKES.md`
+4. `MEMORY.md`
+
+理由：
+
+- 先知道当前工作现场规则
+- 再知道 assistant 自己是谁
+- 再知道现在在做什么
+- 再避免重复犯错
+- 最后补长期背景
+
+### Read B: new session bootstrap
+
+当 `work-ally` 为 assistant 新开会话时，应有明确注入规则，但不要把 desk 资产误设计成与 `AGENTS.md` 并列的规则层。
+
+v1 推荐模型：
+
+1. Codex 先吃到项目 `AGENTS.md` 与 desk `AGENTS.md`
+2. desk `AGENTS.md` 再要求 assistant 读取 `SOUL.md`、`NOW.md`、`MISTAKES.md`、`MEMORY.md`
+
+其中 desk 资产的推荐顺序是：
+
+1. `SOUL.md`
+2. `NOW.md`
+3. `MISTAKES.md`（可截断到高价值部分）
+4. `MEMORY.md`（按大小与规则做裁剪）
+
+关键结论：
+
+> memory feature 的关键，不是再写多少文件，而是定义运行时到底读哪些文件、如何注入。
+
+### Read C: key-turn spot check
+
+在较长工作过程中，assistant 应允许按需回看：
+
+- `NOW.md`
+- `MISTAKES.md`
+- 必要时最近的 `journal/`
+
+这不是每个 turn 都全文注入，而是一个明确可操作的工作规则。
+
+### Read D: nightly digest input
+
+nightly digest 应读取：
+
+- 当日 archive
+- memory 当前快照
+- 必要的近期上下文
+
+但它的目标是提炼，不是把所有历史重新总结一遍，也不是改写 assistant 的当下工作便签。
+
+---
+
+## Memory Injection Contract
+
+这是当前最缺、也最关键的一块。
+
+### Problem
+
+即使 `NOW.md`、`MEMORY.md`、`MISTAKES.md` 都存在，如果 runtime 没有固定的读取与注入约定，记忆系统仍然只是“桌上有文件”，而不是“assistant 真会使用”。
+
+### V1 requirement
+
+必须定义一个最小、稳定的 identity + memory injection contract，使 assistant 在开始工作时明确知道：
+
+- Codex 的两个主规则入口是什么
+- desk 下还有哪些必须继续读取的资产
+- 这些文件路径在哪里
+- 它应该按什么顺序继续读取
+- 这些文件分别扮演什么角色
+
+### Product implication
+
+这件事不能只靠实现层偷偷做，还必须在 desk 的 `AGENTS.md` 里明确写出来。
+
+也就是说：
+
+- `AGENTS.md` 负责声明 identity + memory contract
+- runtime / bootstrap 负责尽可能把这些文件作为开局上下文提供给 assistant
+
+如果缺一边，这个系统都会变成“理论上有记忆，实际上没在用”。
+
+---
+
+## Working Rules For `AGENTS.md`
+
+assistant desk 的 `AGENTS.md` 在这一模型下应承担稳定规则职责：它不是唯一规则入口，但它负责把 desk 资产接进 Codex 的主规则面。
+
+至少应明确这些规则：
+
+1. `SOUL.md` 是人格与风格来源；assistant 必须读取，但默认不应静默改写
+2. `NOW.md` 是当前态文件，进入工作后应优先查看
+3. `MISTAKES.md` 是错误复盘文件，回应高风险问题前应留意相关条目
+4. `MEMORY.md` 是长期稳定记忆，不写日常碎片
+5. `journal/` 是每日沉淀，可按需回看，但不等于长期记忆
+6. `.system/archive/` 是低优先级的稳定原材料留档，通常不需要主动阅读或编辑；只有在追溯事实、核对历史过程、排查异常时才按需查阅
+7. assistant 在工作中可以按需更新 `NOW.md`
+8. assistant 明确发现自己犯错时，可以立即更新 `MISTAKES.md`
+9. 如果项目 `AGENTS.md` 对角色、风格、协作方式有明确要求，应以项目要求为准
+10. V1 中 nightly digest 不负责改写 `NOW.md`
+
+另外，`AGENTS.md` 不应展开 archive 的“黑匣子”概念、目录细节或实现机制，只需把它定义为按需追溯的事实来源即可。
+
+这部分是产品规则，不是可有可无的文档装饰。
+
+---
+
+## Non-goals And Rejections
+
+### 不做向量数据库
+
+当前阶段明确不做：
+
+- embeddings
+- semantic search platform
+- external memory DB
+
+原因很直接：
+
+- 当前数据规模远未到必须引入这套复杂度的程度
+- 可读、可审、可 Git 管理的文本文件更符合当前产品阶段
+
+### 不把全部聊天直接当长期记忆
+
+原始对话很重要，但它首先是**过程材料**，不是已经提炼好的长期记忆。
+
+所以当前采用的原则是：
+
+- 对话可留档
+- archive 可保真
+- 但长期记忆必须经过提炼与选择
+
+### 不单独产品化 assistant knowledge 库
+
+当前不增加 `knowledge/` 之类产品承诺目录，也不让 `SOUL.md` 承担项目知识库职责。
+
+原因：
+
+- 项目知识本来就应当留在项目中
+- 当前最需要补齐的是 memory，而不是再造一层知识库系统
+
+---
+
+## V1 Implementation Focus
+
+基于当前实现现状，memory v1 建议只做下面几件事。
+
+### 1. 固定 file roles
+
+把 `AGENTS.md`、`SOUL.md`、`NOW.md`、`MEMORY.md`、`MISTAKES.md`、`journal/`、`archive/` 的产品定义彻底写实，并同步到：
+
+- `README.md`
+- `docs/user-quickstart.md`
+- assistant desk `AGENTS.md` template
+
+### 2. 补齐 `NOW.md` 的工作中更新语义
+
+不再把 `NOW.md` 仅视为 digest 产物。
+
+需要明确：
+
+- assistant 可在工作中更新它
+- digest 只能审慎整理，不能无脑覆盖
+
+### 3. 补齐 `MISTAKES.md` 的即时更新路径
+
+实现层和提示层都要承认：
+
+- assistant 明确犯错时也会写
+
+是否让 digest 在未来协助整理 `MISTAKES.md`，后续再评估；不作为当前 v1 硬要求
+
+### 4. 固定 identity + memory injection contract
+
+这是 v1 最重要的实现任务之一。
+
+至少要让 assistant 启动/新会话时，稳定接触到：
+
+- 项目 `AGENTS.md`
+- desk `AGENTS.md`
+- `SOUL.md`
+- `NOW.md`
+- `MISTAKES.md`
+- `MEMORY.md`
+
+### 5. 保持 archive 简单稳定
+
+archive 继续作为稳定原材料，不给它叠加“长期记忆 API”职责。
+
+并且 archive 的内部协议应单独拍板冻结；未来允许替换 digest，但不轻易改变 archive 结构。
+
+### 6. 保持文本优先与 Git 友好
+
+memory 文件应继续保持：
+
+- 纯文本
+- 可 diff
+- 可人工审阅
+- 可进入 assistant desk 的 Git 历史
+
+---
+
+## Acceptance Criteria
+
+memory feature 进入可验收状态，至少要满足以下标准：
+
+1. assistant desk 的 identity / memory 文件角色定义清楚且文档一致
+2. 项目 `AGENTS.md` 与 desk `AGENTS.md` 的双入口模型被明确写清
+3. `SOUL.md` 被定义为人格文件，允许用户编辑，但默认不允许 assistant 静默自改
+4. `NOW.md` 被定义为工作中可更新的当前态文件，不再只是 nightly output
+5. `MISTAKES.md` 被定义为 assistant 可即时更新的高价值错题本
+6. nightly digest 输出目标与边界明确，不再被误解为“完整 memory system 本身”，且 V1 不改写 `NOW.md`
+7. runtime 存在最小可验证的 identity + memory injection contract
+8. archive 被定义为稳定原材料层，后续压缩机制可以更换，但 archive 契约不轻易变动
+9. 用户可以直接检查、编辑、版本管理这些文件
+10. 不引入向量数据库或额外复杂存储层
+
+---
+
+## Review Notes
+
+在开始代码实现前，这份 spec 需要特别确认三件事：
+
+1. `NOW.md` 的更新粒度是否接受“工作中随手记”模式
+2. `MISTAKES.md` 是否只记录高价值可复用错误，而不是泛化成日志
+3. identity + memory injection contract 的 v1 范围是否先收敛到双 `AGENTS.md` + desk assets 读取，而不急着做复杂检索
+4. `SOUL.md` 是否采用“用户可自由编辑、assistant 默认不可静默自改”的策略
+5. archive 是否单独作为稳定原材料协议冻结，而把 digest 明确视为可替换机制
+
+如果这几项确认，memory feature 就可以进入实现阶段。