Spring AI Agentic Patterns (Part 6): AutoMemoryTools

原文地址： https://spring.io/blog/2026/04/07/spring-ai-agentic-patterns-6-memory-tools

系列： Spring AI Agentic Patterns · Part 6/7

作者： Christian Tzolov · 2026-04-07

关键词： AutoMemoryTools、长期记忆、跨会话、文件记忆

Spring AI Agentic Patterns (Part 6): AutoMemoryTools

Persistent Agent Memory Across Sessions — 持久化的智能体跨会话记忆

智能体的价值取决于它记住了什么。 Spring AI 的 https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/chat-memory.html#page-title 存储完整的对话并可在重启之间持久化，但当窗口填满时，最旧的消息就会被淘汰。即将推出的 Session API 将通过递归摘要来缓解这一问题，但当细节被压缩时，精确的事实仍然会丢失。

AutoMemoryTools 和 AutoMemoryToolsAdvisor 是 https://github.com/spring-ai-community/spring-ai-agent-utils 工具包的一部分，为你的智能体提供持久的、基于文件的长期记忆，可在会话之间保持。其设计灵感来自 https://code.claude.com/docs/en/memory#auto-memory 和 https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool——移植到 Spring AI，使其可与任何 LLM 提供商配合工作。

长期记忆 vs. 对话历史

维度	ChatMemory	AutoMemoryTools
用途	当前任务 — 完整对话窗口	跨会话 — 值得永久保留的事实
生命周期	滑动窗口限定（淘汰最旧）	类型化 Markdown 文件，永久保存

ChatMemory 和 AutoMemoryTools 是互补的——一个配置良好的智能体会同时使用两者。对当前任务使用 ChatMemory；对下周仍然需要的事实使用 AutoMemoryTools。

这是我们 Spring AI Agentic Patterns 系列的第 6 篇。我们已经介绍了 https://spring.io/blog/2026/01/13/spring-ai-generic-agent-skills、https://spring.io/blog/2026/01/16/spring-ai-ask-user-question-tool、https://spring.io/blog/2026/01/20/spring-ai-agentic-patterns-3-todowrite/、https://spring.io/blog/2026/01/27/spring-ai-agentic-patterns-4-task-subagents 和 https://spring.io/blog/2026/01/29/spring-ai-agentic-patterns-a2a-integration。现在我们添加超越会话本身的记忆。

🚀 想直接上手？跳转到 Quick Start 部分。

它是如何工作的

智能体通过 AutoMemoryTools 中的六个目标工具管理自己的记忆，所有这些工具都被限定在一个沙箱化的 memories 目录中。下图显示了完整的请求流程：

步骤

说明

①

用户请求 —— 请求与 memory system prompt 一起，流经 Spring AI advisor 栈（ToolCallAdvisor + ChatMemoryAdvisor）到达 LLM。LLM 决定在回答之前是否要加载、创建或更新记忆。

②

工具调用 —— LLM 调用 AutoMemoryTools。这些工具在配置的 memory 目录中读写类型化的 Markdown 文件——MEMORY.md 作为索引，加上单独的主题文件（如 user_profile.md 或 project_history.md）。

③

后续的检索/更新 —— LLM 可以发出额外的工具调用来加载特定的 memory 文件或更新现有文件；例如，在 MEMORY.md 中找到指针后加载一个文件，或在合并过程中合并条目。

④

最终响应 —— 一旦所有 memory 操作完成，LLM 产生它的答案，该答案通过 advisor 栈返回给用户。

记忆系统提示（Memory System Prompt）

记忆系统提示驱动这种行为。jar 包中提供了两个变体：

AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md —— 与 Option A 和 Option B 一起使用；专用的、沙箱化的 AutoMemoryTools
AUTO_MEMORY_FILESYSTEM_TOOLS_SYSTEM_PROMPT.md —— 与 Option C 一起使用；通过 FileSystemTools 进行的通用 Read/Write/Edit

两个 memory system prompt 编码了相同的记忆模型，区别仅在于告诉模型调用哪些操作。

MEMORY.md —— 索引文件

MEMORY.md 是始终加载的索引。它是所有 memory 文件的单行指针列表：

模型在每个会话开始时读取此索引，然后有选择地加载看起来相关的文件——即使 memory 不断增长，也能保持上下文窗口精简。

记忆文件格式

每个 memory 是一个带有 YAML frontmatter 的 Markdown 文件：

记忆类型

类型

何时保存

user

角色、目标、专业知识、沟通风格

feedback

修正和确认的方法（

project

代码或 git 中没有的决策和截止日期（迁移目标、冻结日期）

reference

指向外部系统的指针（Linear boards、Grafana dashboards、Slack channels）

记忆操作

AutoMemoryTools 暴露了六个专用于目的、沙箱化的操作。Option C 通过通用目的的 FileSystemTools 和 ShellTools 操作实现相同的结果。

AutoMemoryTools

Option A 和 Option B 使用 AutoMemoryTools，它以一对一的方式实现 https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool：


AutoMemoryTools

工具	用途
MemoryView	读取带行号的文件，或列出两级深度的目录
MemoryCreate	创建一个新的 memory 文件（两步保存的第 1 步）
MemoryStrReplace	在现有文件中替换一个精确、唯一的字符串
MemoryInsert	在给定行号之后插入文本——主要用途：追加到 MEMORY.md
MemoryDelete	递归删除文件或目录
MemoryRename	重命名或移动文件；单独更新 MEMORY.md 链接

集成方式

有三种方法可以将长期记忆添加到 Spring AI 智能体中，从零样板代码到完全手动。根据你对 system prompt 的控制需求、安全性考虑以及你的智能体是否已经使用通用目的的文件系统工具来选择。

Option A：AutoMemoryToolsAdvisor（零样板代码）

向你的 ChatClient builder 中放入一个 advisor：

在每个请求中，advisor 会自动将 AUTO_MEMORY_TOOLS_ SYSTEM_PROMPT.md 注入到系统消息中，注册所有六个 AutoMemoryTools，并可选地在 memoryConsolidationTrigger 触发时附加合并提醒。

image.png

Option B：手动设置（直接使用 AutoMemoryTools）

将 AutoMemoryTools 接入到你的 ChatClient，并配合伴随的系统提示：

Option C：FileSystemTools + ShellTools

如果智能体已经将 FileSystemTools 和 ShellTools 用于其他任务，你可以在完全不添加 AutoMemoryTools 的情况下实现相同的 memory 模式。


方案比较

维度	AutoMemoryTools（A/B）	FileSystemTools（C）
路径模型	相对路径，沙箱化到 memories 根目录	绝对路径，完整的文件系统访问
安全性	内置的遍历保护	无沙箱
工具名称	专用于目的（MemoryCreate 等）	通用（Write、Read、Edit）

⚠️ 安全提示：使用 FileSystemTools 时，智能体可以在文件系统的任何位置读写。仅在受控的可信环境中使用此方法。

保持记忆整洁

随着时间推移，记忆存储会累积冗余、重叠或过时的条目。定期要求智能体进行合并——合并重复项、删除过时的事实、精简描述——可以让存储保持精简，并让 MEMORY.md 索引保持可读。

Option A（自动触发）：AutoMemoryToolsAdvisor 接受一个 memoryConsolidationTrigger 谓词。当它返回 true 时，一个 <system-reminder> 会被注入到下一个请求的系统消息中，提示模型进行合并。

快速上手

Step 1. 添加依赖

需要 Spring AI 2.0.0-M4+。

Step 2. 配置 memory 目录

Step 3. 接入它

Step 4. 看看它如何工作

第一个会话：

第二个会话（新的 JVM 进程）：


示例项目

项目	说明
https://github.com/spring-ai-community/spring-ai-agent-utils/tree/main/examples/memory/memory-tools-advisor-demo	Option A —— AutoMemoryToolsAdvisor + ToolCallAdvisor + MessageChatMemoryAdvisor
https://github.com/spring-ai-community/spring-ai-agent-utils/tree/main/examples/memory/memory-tools-demo	Option B —— AutoMemoryTools 手动接入 + TodoWriteTool
https://github.com/spring-ai-community/spring-ai-agent-utils/tree/main/examples/memory/memory-filesystem-tools-demo	Option C —— FileSystemTools + ShellTools 实现

所有三个示例都支持 Anthropic Claude、Google Gemini 和 OpenAI。

结论

AutoMemoryTools 是对 Anthropic 在 https://code.claude.com/docs/en/memory 和 https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool 中开创的 memory 模式的 Spring AI 移植。

长期记忆是无状态 LLM 调用与真正有用的智能体之间缺失的层次。添加 AutoMemoryToolsAdvisor，你的智能体就开始积累能够跨越会话生存的知识。

系列导航：

Part 1：https://spring.io/blog/2026/01/13/spring-ai-generic-agent-skills — 模块化、可复用的能力
Part 2：https://spring.io/blog/2026/01/16/spring-ai-ask-user-question-tool — 交互式工作流
Part 3：https://spring.io/blog/2026/01/20/spring-ai-agentic-patterns-3-todowrite/ — 结构化规划
Part 4：https://spring.io/blog/2026/01/27/spring-ai-agentic-patterns-4-task-subagents — 分层智能体架构
Part 5：https://spring.io/blog/2026/01/29/spring-ai-agentic-patterns-a2a-integration — Agent2Agent 协议
Part 7：Session API — 事件溯源短期记忆

资源

Spring AI Agent Utils

GitHub：https://github.com/spring-ai-community/spring-ai-agent-utils
AutoMemoryTools 文档：https://spring-ai-community.github.io/ spring-ai-agent-utils/latest-snapshot/tools/AutoMemoryTools
AutoMemoryToolsAdvisor 文档：https://spring-ai-community. github.io/spring-ai-agent-utils/latest-snapshot/tools/AutoMemory-ToolsAdvisor/
完整文档：https://spring-ai-community.github.io/spring-ai-agent-utils/latest-snapshot/