project-memory-management.md 22 KB
项目记忆管理 -- 跨会话项目记忆沉淀
输入要求
- 记录类型（必填）：session总结 / 决策记录 / 规范沉淀 / 已知问题清单 / 换机交接 / 记忆恢复
- 内容详情（必填）：具体要记录的信息
- 项目标识（可选）：项目名称或标识符
记忆文件存储位置
记忆沉淀和恢复遵循"项目记忆跟随项目，用户偏好跟随用户"原则：L3/L2/L1 记忆存储在项目根目录下的 .ai-memory/ 目录（跟随项目迁移、可团队共享），L4 用户级记忆存储在用户主目录（跨项目复用）。严禁硬编码任何绝对路径，确保跨 IDE（Trae CN / Trae / Marvis / VSCode 等）可用。
路径根目录探测协议
LLM 在首次写入或读取记忆前，必须按以下优先级链探测两个根目录：
{PROJECT_ROOT} 项目根目录（L3/L2/L1 记忆使用）
| 优先级 | 探测源 | 适用场景 | 示例 |
|---|---|---|---|
| 1 | 环境变量 PROJECT_ROOT |
用户显式指定，跨 IDE 通用 | set PROJECT_ROOT=D:\my-project |
| 2 | Git 仓库根目录 | 已纳入 Git 管理的项目 | git rev-parse --show-toplevel |
| 3 | IDE 当前工作区根目录 | IDE 打开的项目目录 | 工作区路径 / cwd |
| 4 | 询问用户并写入 PROJECT_ROOT |
以上均未命中时，强制询问，不得自行假设 | 用户确认后写入环境变量 |
{USER_PROFILE} 用户主目录（L4 记忆使用）
| 优先级 | 探测源 | 适用场景 | 示例 |
|---|---|---|---|
| 1 | 环境变量 USER_PROFILE |
用户显式指定 | set USER_PROFILE=C:\Users\username |
| 2 | 系统用户主目录 | 默认场景，跨平台自动识别 | Windows: %USERPROFILE% / macOS/Linux: $HOME |
| 3 | 询问用户 | 以上均未命中时，强制询问 | 用户确认后写入环境变量 |
记忆文件相对路径
探测到根目录后，4 层记忆文件按以下路径组织：
| 层级 | 路径 | 用途 | 跟随 |
|---|---|---|---|
| L4 用户级 | {USER_PROFILE}/.ai-memory/user_profile.md |
跨项目用户偏好、技术栈、禁忌 | 用户 |
| L3 项目级 | {PROJECT_ROOT}/.ai-memory/project_memory.md |
项目规则、约束、约定、教训 | 项目 |
| L3 交接级 | {PROJECT_ROOT}/.ai-memory/handoff.md |
未完成任务的换机/换 IDE 交接 | 项目 |
| L2 会话级 | {PROJECT_ROOT}/.ai-memory/{YYYYMMDD}/session_memory_{session-id}.jsonl |
单次会话的任务/TODO/相关文件 | 项目 |
| L1 工作级 | {PROJECT_ROOT}/.ai-memory/{YYYYMMDD}/daily.md |
当日逐条操作日志（append-only） | 项目 |
| L1 对话级 | {PROJECT_ROOT}/.ai-memory/{YYYYMMDD}/topics.md |
当日会话主题摘要 | 项目 |
路径变量解析：
{PROJECT_ROOT}：按上述探测协议动态获取，禁止硬编码{USER_PROFILE}：按上述探测协议动态获取，禁止硬编码{YYYYMMDD}：当日日期，目录不存在时由记忆系统自动创建{session-id}：会话标识，格式为YYYYMMDD-HHmm（本次会话首次进入 Step 1 的本地时间戳，到分钟）。唯一生成/存储约定以references/execution-safety.md「session_memory 标识（id）生成规则」为准：写进当日daily.md顶部session-id: {YYYYMMDD-HHmm}行作为真相源，新会话先读该行再定位session_memory_{session-id}.jsonl。
.ai-memory/ 目录结构示例
{PROJECT_ROOT}/
├── .ai-memory/ # 项目记忆根目录（跟随项目）
│ ├── project_memory.md # L3 项目级：规则、约束、教训
│ ├── handoff.md # L3 交接级：未完成任务恢复点
│ ├── 20260705/ # L2/L1 按日期组织
│ │ ├── topics.md # L1 当日会话主题摘要
│ │ ├── daily.md # L1 当日逐条操作日志（append-only）
│ │ ├── session_memory_20260813-1430.jsonl # L2 单次会话记录（id=YYYYMMDD-HHmm）
│ │ └── session_memory_20260813-1510.jsonl
│ └── 20260706/
│ └── ...
├── .gitignore # 建议 .ai-memory/daily/ 加入忽略
└── ...（项目其他文件）
版本控制策略
| 路径 | 是否提交 Git | 原因 |
|---|---|---|
.ai-memory/project_memory.md |
✅ 提交 | 项目规则和约定，团队共享，版本追溯 |
.ai-memory/handoff.md |
✅ 提交 | 换电脑/换 IDE 时恢复未完成任务 |
.ai-memory/{YYYYMMDD}/topics.md |
❌ 忽略 | 当日会话摘要，含个人上下文，不团队共享 |
.ai-memory/{YYYYMMDD}/daily.md |
❌ 忽略 | 当日逐条操作日志，含个人上下文，不团队共享 |
.ai-memory/{YYYYMMDD}/session_*.jsonl |
❌ 忽略 | 单次会话详情，含个人上下文，不团队共享 |
{USER_PROFILE}/.ai-memory/ |
不适用 | 用户主目录，不在项目仓库内 |
.gitignore 建议添加：
.ai-memory/*/
!.ai-memory/project_memory.md
!.ai-memory/handoff.md
探测执行规则
首次执行时输出探测过程：[MEMORY-PROBE] PROJECT_ROOT: 优先级X→命中/未命中; USER_PROFILE: 优先级X→命中/未命中。命中后缓存当前会话。优先级1-3均未命中时禁止自行创建目录，必须询问用户：未找到项目根目录，请指定 PROJECT_ROOT 路径（如 D:\my-project）。
写入规则
- 探测到根目录后，写入前必须确认
.ai-memory/目录存在，不存在时先创建 - 写入必须使用 UTF-8 无 BOM 编码，禁止使用 PowerShell 的
Set-Content/Out-File - L1/L2 每日一个目录，L3 每项目一个文件，L4 每用户一个文件
- Windows 环境下路径分隔符为
\，macOS/Linux 为/，写入时按当前系统规范化
即时写入规则（写后即记）
daily.md 采用 append-only 模式，在每次实质性操作完成后立即追加，不经用户确认、不等待会话结束。写入触发条件、写入格式和运行位置见主 SKILL.md「Step 0: 工作记忆加载 → 写后即记协议」。
实现规则：
- 每次追加前仅读取
daily.md末尾 20 行确认已有记录（避免全量读取浪费上下文），然后直接 append - 写入使用 UTF-8 无 BOM 编码，Windows 换行符
\r\n - 若
daily.md不存在，先创建带# 工作日志 - [YYYY-MM-DD]标题头的新文件再追加 - 同一条记录的多个文件修改合并到一行
daily.md条目，不拆条 daily.md内容超过 8000 字符时，Agent 应在 Step 6 出示精简提醒，建议用户将旧记录蒸馏入project_memory.md
读取规则
- 新会话开始时，按"记忆恢复"章节的三层加载策略读取
- 不得预读全量记忆，必须按当前任务相关性按需加载
- 总 token 预算控制在 1000 以内，超过时优先丢弃最旧记录
- 读取失败时不阻塞流程，正常进入意图识别
执行流程
第一步：会话结束记录（Session Summary）
会话结束时生成结构化summary：
## Session Summary
**日期**: [YYYY-MM-DD]
**会话目标**: [本次会话原计划完成什么]
### 已完成
- [任务1]: [简要说明] → [相关文件]
- [任务2]: [简要说明] → [相关文件]
### 关键决策
- **决策**: [决策内容]
- **上下文**: [为什么做这个决策]
- **影响**: [影响哪些后续工作]
### 遗留问题 / Blockers
- [问题1]: [描述] → [下一步行动]
### 下一步计划
1. [下一步任务]
2. [下一步任务]
### 规范更新
- [新发现的项目规范]
模板必填项缺一不可。Session Summary 全文写入
{PROJECT_ROOT}/.ai-memory/{YYYYMMDD}/session_memory_{session-id}.jsonl；同时向{PROJECT_ROOT}/.ai-memory/{YYYYMMDD}/topics.md写入「5 字段主题摘要」（项目 / 当前阶段 / 活跃任务 / 上次会话 / 交接状态，格式见第五步 Layer 1），供新会话快速恢复，不写全文。
第二步：决策记录（Decision Record）
重要技术决策时记录：
## Decision Record: [决策名称]
**日期**: [YYYY-MM-DD]
**问题**: [需要解决什么问题]
### 选项分析
| 选项 | 优势 | 劣势 | 复杂度 |
| ------- | ---- | ---- | -------- |
| [选项A] | ... | ... | 低/中/高 |
| [选项B] | ... | ... | 低/中/高 |
### 决策
**选择**: [最终选项]
**理由**: [为什么选这个]
**Trade-offs**: [接受了什么代价]
### 影响范围
- [影响的模块/文件]
- [需要同步更新的文档]
### 撤销条件
[什么情况下可以重新考虑这个决策]
模板必填项缺一不可。写入位置：
{PROJECT_ROOT}/.ai-memory/project_memory.md的 Decision Record 章节
第三步：规范沉淀（Convention Capture）
发现项目特定规范时记录：
## Project Convention: [规范名称]
**类型**: [编码规范/命名规范/架构约束/工具配置]
**适用范围**: [哪些模块/文件适用]
### 规范内容
[具体规则]
### 示例
**正确**:
`[代码示例]`
**错误**:
`[代码示例]`
### 发现来源
[哪次会话/哪个任务中发现]
模板必填项缺一不可。
第三步点五：术语表维护（Glossary）
当对话中出现领域术语漂移（同一概念被多个名称指代、或不同概念被同一名称覆盖）时，记录到项目级术语表。
触发条件：
- 同一概念在本次会话中被 ≥ 2 种不同名称指代
- 代码中出现的术语与需求文档中的术语不一致
- 跨模块调用时对同一概念使用了不同命名
- 用户纠正了 Agent 对某个术语的理解
记录格式：
## Glossary Entry: [术语名称]
**规范名称**: [唯一推荐名称]
**别名/变体**: [同义但不推荐的名称列表]
**定义**: [一句话定义]
**适用范围**: [哪些模块/文件使用此术语]
**禁止使用**: [明确不应使用的名称]
**来源**: [需求文档/用户口头约定/行业标准]
写入位置：追加到 {PROJECT_ROOT}/.ai-memory/project_memory.md 的 Glossary 章节（首次写入时创建该章节）。
使用规则：
- 后续代码生成和讨论中，Agent 必须使用术语表的规范名称
- 发现术语表与当前使用不一致时，以术语表为准并提醒用户
- 新会话 Step 1.1 加载 project_memory.md 时，Glossary 章节随 Section Headers 一并加载
第三步点六：已知问题清单（Known Issues）
发现新 Bug 模式、兼容性陷阱、第三方依赖风险时记录到 {PROJECT_ROOT}/.ai-memory/project_memory.md 的"Lessons Learned"章节：
## Known Issue: [问题名称]
**发现日期**: [YYYY-MM-DD]
**问题类型**: [Bug模式 / 兼容性陷阱 / 依赖风险 / 性能反模式 / 安全漏洞]
**严重度**: [致命 / 严重 / 一般 / 提示]
### 现象
[具体表现，含错误信息或日志片段]
### 根因
[根本原因分析]
### 规避方案
[具体的代码层面规避措施]
### 相关文件
- [文件路径:行号]
### 状态
[未修复 / 已修复 / 已规避 / 待验证]
模板必填项缺一不可。
第四步：换机/换 IDE 交接（Handoff Protocol）
当任务未完成且用户准备关闭 IDE、切换电脑、切换 IDE 或长时间暂停时，必须生成可迁移交接点。交接点写入 {PROJECT_ROOT}/.ai-memory/handoff.md，并提示用户随代码一起提交或同步。handoff.md 只记录恢复工作所需的最小上下文，不写入账号、密钥、个人聊天细节或临时 IDE 缓存路径。
## Handoff Checkpoint
**更新时间**: [YYYY-MM-DD HH:mm]
**当前目标**: [用户原始需求的核心交付物]
**当前阶段**: [需求/设计/实现/验证/交付]
**完成度**: [按已验证主线数计算的百分比]
### 已完成
- [已完成项]: [验证证据] -> [相关文件]
### 未完成
- [未完成项]: [下一步动作] -> [相关文件]
### 关键决策
- [决策]: [理由 / 影响范围 / 撤销条件]
### 恢复入口
- **首读文件**: [恢复时优先读取的文件]
- **关键命令**: [lint/test/build/启动命令]
- **验证路径**: [继续前必须跑的验证]
### 阻塞项
- [阻塞原因]: 需 [角色] 提供 [具体输入]
写入触发条件：
- 用户明确说“暂停/下次继续/换电脑/关闭 IDE/稍后接着做”
- 本轮存在未完成主线任务，且已产生文件修改或关键决策
- 任务依赖本地环境状态、运行命令、验证结果或人工确认
- 多 IDE 协同开发时，任何会影响下一位执行者的上下文变化
同步规则：
- 写入
handoff.md前先读取现有内容，保留仍有效的未完成项，删除已验证完成项。 handoff.md必须随.ai-memory/project_memory.md一起纳入 Git 或共享存储同步。- 新电脑恢复时，先执行
[MEMORY-PROBE]，再读取handoff.md、project_memory.md和当前任务相关文件。 - 恢复后若发现代码状态与
handoff.md不一致，以工作区实际文件和测试结果为准，并更新交接点。 - 任务完成后清空或改写
handoff.md为“无未完成交接项”，避免旧任务污染新会话。
模板必填项缺一不可。写入位置：
{PROJECT_ROOT}/.ai-memory/handoff.md，且不含敏感值。
第五步：新会话记忆恢复（Progressive Disclosure）
新会话开始时，按三层加载记忆：
Layer 1: Metadata（~50 tokens）
项目: [名称]
当前阶段: [阶段]
活跃任务: [任务名]
上次会话: [日期]
交接状态: [无 / 存在 handoff.md 未完成项]
Layer 2: Body（~200 tokens）
## 上次Session Summary
[最近一次的summary核心内容]
## Handoff Checkpoint
[handoff.md 中与当前任务相关的未完成项]
## 活跃决策
- [与当前任务相关的决策]
Layer 3: References（按需加载，~500 tokens each）
## 相关决策记录
[与当前任务相关的完整决策记录]
## 相关规范
[与当前任务相关的项目规范]
加载策略：
- 始终加载Layer 1
- 如果存在
handoff.md且含未完成项，优先加载与当前任务相关的 Handoff Checkpoint - 如果当前任务与上次会话连续，加载Layer 2
- 如果涉及历史决策或规范，按需加载Layer 3
- 总token预算控制在1000以内，避免context rot
记忆来源文件不存在时不阻塞流程，正常进入意图识别。
记忆治理原则
记忆按 L1(对话级)/L2(会话级)/L3(项目级)/L4(用户级)四层组织（对应上表路径）。未验证信息只留在 L1，不得沉淀为 L3；只影响本轮的临时路径不得写入 L4；L4 用户偏好与 L3 项目约束冲突时优先遵守更具体、更高风险的项目约束。
记忆默认静默应用——用户长期偏好、项目固定路径、已验证技术约束、上轮已确认的下一步可静默使用；记忆与当前请求冲突、可能过期、会影响文件修改范围或交付判断时必须显式说明。
敏感信息（健康/财务/身份/凭据/密钥）不得在无关上下文中引用，不得写入普通规范。开发场景例外：可记"位置与访问方式"，不记"值"。
记忆膨胀/冲突/透明度不足时按时间、证据强度、风险等级收敛，旧规则标注过期。失败模式与主 SKILL.md「对话流异常处理边界」对齐。
读取截断规则
从 Step 0 / Step 1.1 新会话恢复调用，用于控制单次加载量，避免上下文溢出：
| 文件 | 阈值 | 读取动作 |
|---|---|---|
daily.md |
≤ 8000 字符 | 全量读取 |
daily.md |
> 8000 字符 | 读取末尾 120 行（最新操作），并出示精简提醒 |
project_memory.md |
≤ 8000 字符 | 全量读取 |
project_memory.md |
> 8000 字符 | 先读目录结构 + Decision Record 章节，其余按需加载 |
Step 1.1 三层策略的截断优先级：总 token > 1000 时优先丢弃 Layer 3（references），保留 Layer 1（topics）和 Layer 2（session_memory）+ handoff 检查点。
记忆维护协议
30 天蒸馏周期
每超过 30 天的 {YYYYMMDD}/ 日志目录，其 daily.md 内容必须在下一个维护窗口中蒸馏入 project_memory.md：
- 蒸馏时机：Step 6 复盘时检查，若存在 >30 天的日志目录且仍未处理，触发蒸馏
- 蒸馏规则：
- 提取
daily.md中的关键决策 → 写入project_memory.md的 Decision Record 章节 - 提取新发现的 Bug 模式/陷阱 → 写入
project_memory.md的 Known Issues 章节 - 提取项目约定/偏好 → 写入
project_memory.md的 Project Convention 章节 - 纯操作流水不蒸馏，直接丢弃
- 提取
- 清理规则：蒸馏完成后删除该
{YYYYMMDD}/目录及其内的daily.md、topics.md和所有session_*.jsonl - 防冲突：若
daily.md中的记录与project_memory.md现有条目冲突，追加修正条目并标注来源日期，不覆盖原有记录
daily.md 精简阈值
| 阈值 | 动作 |
|---|---|
| ≤ 8000 字符 | 正常追加，无需处理 |
| > 8000 字符 | Step 6 出示精简提醒，询问用户是否蒸馏当日旧记录 |
| > 12000 字符 | 强制精简：取最近 30 条记录保留，其余蒸馏入 project_memory.md |
三层记忆生命周期
daily.md（逐条操作日志）
↓ 会话结束
session_memory_{id}.jsonl（会话总结）+ topics.md（主题摘要）
↓ >30 天
project_memory.md（长期精选项目记忆）
↓ 跨项目
user_profile.md（用户级偏好，手动提炼）
输出格式
各记忆类型的模板已在执行流程(第一/二/三/三点五/四/五步)中定义,输出时按对应模板填写。所有记忆写入 {PROJECT_ROOT}/.ai-memory/ 或 {USER_PROFILE}/.ai-memory/ 对应路径(见"记忆文件相对路径"表)。
质量标准
- Session Summary 会话结束时立即生成,含会话目标/已完成/关键决策/遗留问题/下一步
- Decision Record 必须含"撤销条件",避免过早固化
- Convention Capture 必须有正/反例,不能只有文字描述
- Handoff Checkpoint 必须能让新电脑在不依赖旧 IDE 会话的情况下恢复当前主线
- 记忆恢复优先加载与当前任务最相关的内容,总 token ≤ 1000
- 记忆默认静默应用,影响交付边界时显式说明依据
- 敏感记忆上下文隔离,开发场景可记位置不记值
- 记忆写入按 L1-L4 分层,不得跨层污染
失败回退机制
| 步骤 | 失败条件 | 回退目标 | 最大重试 |
|---|---|---|---|
| 第一步 Session Summary | 会话信息不完整或多次中断 | 基于已有信息生成骨架,标注"信息可能不全" | 2 |
| 第二步 Decision Record | 决策选项信息不足 | 记录已知选项,标注"待补充" | 1 |
| 第三步 Convention Capture | 规范来源不清晰或正反例难提炼 | 仅记录规范内容,标注"示例待补充" | 2 |
| 第四步 Handoff | 交接信息不完整或验证缺失 | 保留当前目标、未完成项、首读文件和阻塞项 | 1 |
| 第五步 记忆恢复 | Layer 加载超 token 预算 | 优先丢弃 Layer 3,保留 Layer 1+2 和 handoff | 1 |
| 敏感记忆污染 | 敏感信息被写入普通摘要 | 立即隔离,只保留任务必要风险描述 | 0 |
| 记忆膨胀 | 加载大量低价值历史 | 执行记忆瘦身,仅保留有效目标/决策/约束/阻塞项 | 1 |
| 记忆冲突 | 多个互斥规范 | 按时间/证据强度/风险等级裁决,旧规则标注过期 | 1 |
关联 reference
- spec-driven-development（Spec驱动开发）— 将spec和design决策记录到项目记忆
- software-project（软件项目总控）— 将通用项目边界、架构、发布和交付记录到项目记忆
- website-project（网站项目总控）— 将站点配置、部署路径、交付材料和运维清单记录到项目记忆
- task-decomposition-and-execution（任务拆解与执行）— 将task summary记录到项目记忆
- tech-selection（技术选型）— 选型决策自动记录到项目记忆
- code-generation（代码生成）— 编码前加载项目规范，编码后记录新发现规范