Claude Code v2.1.33 引入了 Agent memory 功能，通过 subagent frontmatter 中的 memory: 字段为每个 agent 提供独立的持久化知识库。agent 在执行过程中自主读写 MEMORY.md，每次启动时前 200 行自动注入到上下文。三种 scope（user/project/local）对应不同的共享需求，让 agent 能在 session 间积累和运用知识。

Claude Code Agent Memory：跨 session 持久化记忆的配置与使用

什么是 Agent Memory

在 Claude Code v2.1.33（2026 年 2 月）之前，每次 subagent 被调用都从头开始，没有任何跨 session 的知识积累。

memory: frontmatter 字段改变了这一点：每个 subagent 可以拥有自己的持久化 Markdown 知识库，跨会话读写，在每次启动时自动将 MEMORY.md 的前 200 行注入上下文。

三种 Memory Scope

Scope	存储位置	是否纳入 git	是否共享	适用场景
`user`	`~/.claude/agent-memory/<agent-name>/`	否	否	跨项目的个人知识（推荐默认）
`project`	`.claude/agent-memory/<agent-name>/`	是	团队共享	团队应该共同继承的项目知识
`local`	`.claude/agent-memory-local/<agent-name>/`	否（git-ignored）	否	个人项目知识，不与团队共享

这三种 scope 与 settings 层级体系镜像对应：~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json。

配置方法

yaml

---
name: code-reviewer
description: 代码审查 agent，学习和记忆项目特有的模式
tools: Read, Write, Edit, Bash
model: sonnet
memory: user
---

你是一个代码审查 agent。在审查代码时，把你发现的模式、规范和反复出现的问题更新到你的 memory 中。
下次启动时，先读取 memory 中积累的经验再开始工作。

Memory 的工作机制

~/.claude/agent-memory/code-reviewer/    # user scope 示例
├── MEMORY.md                             # 主文件（每次启动注入前 200 行）
├── react-patterns.md                     # 主题文件（超出 200 行后抽取）
└── security-checklist.md                 # 主题文件

启动时：MEMORY.md 前 200 行自动注入 agent 的系统提示
工具自动授权：Read、Write、Edit 工具自动启用，agent 可以自由管理 memory 目录
执行中：agent 自主读写 memory 目录下的文件
超出容量时：若 MEMORY.md 超过 200 行，agent 将详细内容迁移到主题专属文件

与其他 Memory 系统的关系

Agent memory 是 Claude Code 多层记忆体系的一部分：

系统	写入者	读取者	作用域
CLAUDE.md	你（手动维护）	主 Claude + 所有 agents	项目级
Auto-memory	主 Claude（自动）	仅主 Claude	每项目每用户
`/memory` 命令	你（通过编辑器）	仅主 Claude	每项目每用户
Agent memory	agent 自己	仅该特定 agent	可配置（user/project/local）

这些系统是互补的：agent 同时读取 CLAUDE.md（项目上下文）和自己的 memory（agent 特定知识）。

实战案例：API 开发 Agent

yaml

---
name: api-developer
description: 按照团队规范实现 API 接口
tools: Read, Write, Edit, Bash
model: sonnet
memory: project
skills:
  - api-conventions
  - error-handling-patterns
---

实现 API 接口时，遵循预加载 skills 中的规范。
工作过程中，把架构决策和发现的模式保存到 memory。
下次调用时，先检查 memory 中记录的已有决策，保持一致性。

这个配置组合了两种知识管理机制：

Skills（静态知识）：启动时注入 API 规范，相当于"入职手册"
Memory（动态知识）：随时积累，相当于"工作日记"

memory: project 表示这些知识提交到 git，整个团队的 api-developer 实例共享同一份知识库。

如何触发 Agent 使用 Memory

在调用 agent 时给出明确指令，效果比隐式期望更好：

启动时读取 memory：

/agents → 调用 code-reviewer
提示词：在开始之前，先检查你的 memory，看看之前发现过哪些模式。

结束时更新 memory：

提示词：审查完成后，把你在这次审查中学到的新模式更新到 memory 中。

请求 memory 比对：

提示词：审查这个 PR，并检查你的 memory 看是否之前见过类似问题。

FAQ

Q: Agent memory 和 CLAUDE.md 有什么区别？ A: CLAUDE.md 是你手工维护的项目规范，整个团队和所有 agents 都会读取；Agent memory 是特定 agent 在工作中自主积累的知识，只有那个 agent 自己读取。前者是"规章制度"，后者是"个人工作笔记"。

Q: memory: project 会把密钥或敏感信息提交到 git 吗？ A: 需要谨慎配置。.claude/agent-memory/ 目录会随项目 git 提交。如果 agent 在 memory 中写入了 API key 等敏感内容，这些内容会进入版本历史。建议在 agent 的指令中明确要求不要在 memory 中存储敏感数据，或者改用 memory: local 避免敏感内容进入 git。

Q: 200 行限制是硬限制吗？ A: 200 行是 MEMORY.md 的自动注入上限，超出的内容不会在启动时自动加载。但 agent 可以在执行中主动读取更多文件。推荐做法是让 MEMORY.md 只保留最重要的摘要和索引，详细内容放在主题专属文件中，用 MEMORY.md 指向它们。

Q: 多个 agent 实例能共享同一份 memory 吗？ A: 通过 memory: project 可以实现团队内不同人的同名 agent 共享 memory（因为存在 .claude/agent-memory/<name>/，提交到 git）。但如果两个人同时运行同一个 agent 并写入 memory，可能产生 git 冲突，需要手动解决。

Claude Code Agent Memory：跨 session 持久化记忆的配置与使用 ​

什么是 Agent Memory ​

三种 Memory Scope ​

配置方法 ​

Memory 的工作机制 ​

与其他 Memory 系统的关系 ​

实战案例：API 开发 Agent ​

如何触发 Agent 使用 Memory ​

FAQ ​