Memory / State：管理上下文和长期信息

1. Memory / State 是什么#

Memory 指 AI 系统保存下来的长期信息。

常见 memory 包括：

• 用户常用语言
• 用户偏好的输出风格
• 项目技术栈
• 项目启动命令
• 常见错误处理方式
• 历史决策
• 常用模板
• 用户明确要求保存的信息

State 指当前任务或当前会话的运行状态。

常见 state 包括：

• 当前目标
• 已完成步骤
• 当前计划
• 工具调用结果
• 中间结论
• 等待用户确认的事项
• 失败次数
• 下一步动作

可以简单理解：

• Memory 更偏长期信息
• State 更偏当前进度

两者一起使用，AI 才能在任务中保持连续。

2. 为什么需要 Memory / State#

没有 Memory / State 的 AI，容易出现这些问题：

• 用户每次都要重复背景
• 项目启动命令反复询问
• 上一次任务进度丢失
• Agent 中断后无法继续
• 输出风格不稳定
• 常见错误反复排查
• 团队经验无法沉淀
• 隐私信息缺少管理入口

Memory / State 能带来几个直接收益：

• 减少重复解释
• 提升任务连续性
• 保持输出风格一致
• 复用项目经验
• 支持长任务恢复
• 让 Agent 更容易规划下一步
• 为审计和回放提供基础

AI 系统越长期使用，Memory / State 的价值越明显。

3. 短期上下文#

短期上下文是当前对话里模型可以直接看到的信息。

它通常包括：

• 最近的用户消息
• 最近的助手回复
• 当前任务说明
• 临时粘贴的代码、日志和文档
• 本轮工具调用结果

短期上下文的特点：

• 使用方便
• 更新很快
• 受上下文窗口限制
• 会随着对话变长而被压缩或丢弃

适合放在短期上下文里的内容：

• 当前问题
• 当前文件片段
• 当前错误日志
• 当前用户确认
• 当前工具输出摘要

不适合只放在短期上下文里的内容：

• 项目长期启动命令
• 用户长期偏好
• 关键历史决策
• 反复使用的流程模板

短期上下文适合处理当前任务，长期信息需要进入 memory。

4. 长期记忆#

长期记忆用于保存跨会话复用的信息。

常见长期记忆包括：

• 用户偏好
• 项目事实
• 常用命令
• 目录结构说明
• 历史问题解决方案
• 团队约定
• 常用输出格式
• 用户明确保存的笔记

示例：

1
{
2
  "type": "project_memory",
3
  "project": "example-api",
4
  "key": "start_command",
5
  "value": "npm run dev",
6
  "source": "用户确认",
7
  "updated_at": "2026-06-01"
8
}

长期记忆要有来源。没有来源的记忆容易引入错误。

建议记录：

• 记忆内容
• 适用范围
• 来源
• 更新时间
• 可信度
• 是否可删除
• 是否包含敏感信息

5. 用户偏好#

用户偏好能让 AI 更贴合使用习惯。

常见用户偏好包括：

• 使用简体中文
• 技术术语保留英文
• 回答要简洁
• 输出要带命令和路径
• 做完修改后说明改动点
• 测试优先跑真实命令
• 避免某些表达方式
• 对高风险操作先确认

示例：

1
{
2
  "scope": "global",
3
  "type": "user_preference",
4
  "content": "用户偏好简体中文，技术术语保留英文。",
5
  "source": "用户明确要求",
6
  "updated_at": "2026-06-01"
7
}

用户偏好要避免过度推断。适合保存用户明确说过、反复表现稳定、对后续任务有帮助的信息。

6. 项目记忆#

项目记忆用于保存特定仓库或项目的信息。

常见项目记忆包括：

• 技术栈
• 启动命令
• 测试命令
• 部署命令
• 目录说明
• 关键服务
• 常见错误
• 环境变量说明
• 本地验证方式

示例：

1
{
2
  "scope": "project",
3
  "project_path": "D:/myproject/example",
4
  "type": "command",
5
  "key": "health_check",
6
  "value": "curl http://localhost:3000/health",
7
  "source": "已运行验证",
8
  "updated_at": "2026-06-01"
9
}

项目记忆必须绑定项目路径或项目标识。用户经常切换项目时，跨项目误用记忆会带来风险。

7. 任务状态#

任务状态用于保存当前任务进度。

Agent 和长任务尤其需要任务状态。

常见字段：

• goal
• plan
• completed_steps
• current_step
• observations
• pending_questions
• blocked_reason
• next_action
• status

示例：

1
{
2
  "goal": "生成 AI 工程化学习路线剩余章节",
3
  "plan": ["生成 07", "生成 08", "生成 09"],
4
  "completed_steps": ["生成 07"],
5
  "current_step": "生成 08",
6
  "status": "in_progress"
7
}

任务状态要及时更新。状态过期后，Agent 会基于错误进度继续执行。

8. 会话状态#

会话状态用于记录当前对话中的临时信息。

常见会话状态包括：

• 当前工作目录
• 当前分支
• 当前用户目标
• 最近一次命令结果
• 当前打开的文件
• 用户刚刚确认或拒绝的事项

会话状态生命周期通常比任务状态更短。它服务于当前对话，不一定需要长期保存。

示例：

1
{
2
  "cwd": "C:/Users/admin/Documents/New project 14",
3
  "active_task": "生成 07-12 章节",
4
  "last_check": "已确认缺少 07-12 文件"
5
}

会话状态可以帮助 AI 减少重复检查，但关键操作前仍然要做当前环境验证。

9. 记忆更新#

记忆不能只新增，也要更新。

常见更新场景：

• 启动命令改变
• 项目目录调整
• 用户偏好改变
• 旧方案被废弃
• 依赖版本升级
• 历史问题有了新解决方法

更新策略：

• 同一 key 保留最新版本
• 历史版本可归档
• 记录更新时间
• 记录更新来源
• 对冲突记忆进行标注
• 用户明确纠正时优先采用新信息

示例：

1
{
2
  "old_value": "npm run dev",
3
  "new_value": "pnpm dev",
4
  "reason": "项目切换到 pnpm",
5
  "updated_by": "用户确认",
6
  "updated_at": "2026-06-01"
7
}

记忆更新要谨慎。错误记忆会比没有记忆更麻烦。

10. 隐私删除机制#

Memory / State 可能包含敏感信息，必须支持删除。

敏感信息包括：

• token
• API key
• 密码
• 手机号
• 身份证号
• 个人地址
• 内部客户数据
• 财务数据
• 未公开业务信息

隐私机制建议包含：

• 用户可以查看记忆
• 用户可以删除记忆
• 用户可以修改记忆
• 敏感字段默认不保存
• 保存前进行脱敏
• 删除后同步清理索引和缓存
• 访问记忆记录审计日志

示例规则：

1
1. 不保存完整 token。
2
2. 不保存用户密码。
3
3. 保存项目命令时去掉密钥参数。
4
4. 用户要求删除记忆时，必须删除对应条目。
5
5. 涉及隐私的记忆需要标记 sensitive=true。

隐私删除机制是 Memory 系统进入真实使用的底线。

11. Memory / State 实战练习#

可以按下面顺序练习：

1. 记录用户常用技术栈
2. 记录项目启动命令
3. 记录项目测试命令
4. 记录常见错误处理方式
5. 让 Agent 保存上一次任务进度
6. 给记忆增加来源字段
7. 给记忆增加更新时间
8. 给记忆增加查看入口
9. 给记忆增加更新入口
10. 给记忆增加删除入口

每个练习都可以检查三个问题：

• 这条记忆是否有明确来源
• 这条记忆是否绑定正确范围
• 这条记忆是否包含敏感信息

12. 阶段验收标准#

学完这一章，可以用下面的问题检查自己：

• 我能不能区分短期上下文、长期记忆和任务状态？
• 我能不能设计用户偏好的保存格式？
• 我能不能把项目记忆绑定到具体项目？
• 我能不能记录 Agent 的任务进度？
• 我能不能处理记忆冲突？
• 我能不能更新过期记忆？
• 我能不能让用户查看、修改和删除记忆？
• 我能不能避免保存敏感信息？
• 我能不能在使用记忆前判断是否适用当前项目？
• 我能不能让记忆真正减少重复解释成本？

如果这些问题大多数都能做到，说明 Memory / State 阶段已经基本合格。

13. 本章总结#

Memory / State 的核心是让 AI 在多次对话和多步骤任务之间保持连续。

一套可用的 Memory / State 设计，建议至少包含：

• 短期上下文
• 长期记忆
• 用户偏好
• 项目记忆
• 任务状态
• 会话状态
• 记忆来源
• 记忆更新
• 隐私删除机制
• 权限和审计

Memory / State 让 AI 从临时问答走向持续协作。它能减少重复解释，保留项目经验，并支持 Agent 在长任务中恢复进度。

这一章的目标很明确：让 AI 记住该记住的内容，忘掉该删除的内容，并在正确范围内使用记忆。