How to Add Claude Code’s Auto‑Memory Mechanism to Spring AI

1. Introduction

Spring AI’s ChatMemory stores the full conversation window and persists across restarts, but when the window is full the oldest messages are evicted. The upcoming Session API will add recursive summarisation, yet detailed facts can still be lost.

AutoMemoryTools and AutoMemoryToolsAdvisor provide a persistent, file‑based long‑term memory that can survive across sessions. Their design is inspired by Claude Code’s auto‑memory system and the Claude API Memory Tool specification.

2. Long‑term Memory vs. Conversation History

ChatMemory and AutoMemoryTools are complementary. A well‑configured agent uses ChatMemory for the current task (the sliding window) and AutoMemoryTools to store facts that must remain available later, such as user preferences, project decisions, or corrective feedback.

3. How It Works

The agent interacts with six sandboxed tools inside a memories directory. The request flow is:

User request – the prompt, combined with the memory system prompt, passes through the Spring AI advisor stack (ToolCallAdvisor + ChatMemoryAdvisor) to the LLM.

Tool call – the LLM invokes AutoMemoryTools, which read/write Markdown files (e.g., MEMORY.md, user_profile.md, project_auth.md).

Subsequent retrieval / update – the LLM may load a specific memory file or merge entries.

Final response – after all memory operations, the LLM generates the answer, which is returned through the advisor stack.

4. Memory System Prompts

Two prompt files are shipped in the JAR:

AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md – used for options A and B.

AUTO_MEMORY_FILESYSTEM_TOOLS_SYSTEM_PROMPT.md – used for option C.

Both encode the same memory model; the only difference is which operations the model is instructed to call.

5. MEMORY.md Index File

MEMORY.md

is a flat list of one‑line pointers to all memory files, for example:

- [User Profile](user_profile.md) — Backend engineer, prefers short answers
- [Feedback Testing](feedback_testing.md) — Always use a real database in integration tests
- [Project Auth Rewrite](project_auth.md) — Driven by compliance, not technical debt

At the start of each session the model reads this index and selectively loads relevant files, keeping the context window small even as memory grows.

6. Memory File Format

Each memory file is a Markdown document with a YAML front‑matter block, e.g.:

---
name: user profile
description: Alice — Backend engineer, prefers short answers
type: user
---
Backend engineer named Alice.
Prefers concise, direct replies without a closing summary.

7. Memory Types

The memory model defines four types, each with a clear saving guideline:

user – role, goals, expertise, communication style.

feedback – corrections and confirmed practices.

project – decisions and deadlines not stored in code or Git.

reference – pointers to external systems such as Linear boards or Grafana dashboards.

8. Integration Options

Three ways to add long‑term storage to a Spring AI agent:

Option A – AutoMemoryToolsAdvisor (zero template code)

@Bean
ChatClient chatClient(ChatClient.Builder builder) {
  ChatClient chatClient = builder
    .defaultAdvisors(
      // long‑term memory
      AutoMemoryToolsAdvisor.builder()
        .memoriesRootDirectory("E:/springai/.agent/memories")
        .build(),
      // conversation history
      MessageChatMemoryAdvisor.builder(
        MessageWindowChatMemory.builder().maxMessages(100).build()
      ).build(),
      // tool calling
      ToolCallAdvisor.builder().disableInternalConversationHistory().build()
    ).build();
  return chatClient;
}

The advisor automatically injects AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md and registers the six tools. A memoryConsolidationTrigger can be configured to insert a system reminder for consolidation.

Option B – Manual setup (direct use of AutoMemoryTools)

@Value("classpath:/prompt/AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md")
Resource memorySystemPrompt;
@Value("${agent.memory.dir:E:/springai/.agent/memories}")
String memoryDir;

@Bean
ChatClient chatClient(ChatClient.Builder builder) {
  ChatClient chatClient = builder
    .defaultSystem(p -> p.text(memorySystemPrompt).param("MEMORIES_ROOT_DIERCTORY", memoryDir))
    .defaultTools(
      AutoMemoryTools.builder().memoriesDir(memoryDir).build(),
      TodoWriteTool.builder().build()
    )
    .defaultAdvisors(new SimpleLoggerAdvisor(), ToolCallAdvisor.builder().build())
    .build();
  return chatClient;
}

Option C – FileSystemTools + ShellTools

@Value("classpath:/prompt/AUTO_MEMORY_FILESYSTEM_TOOLS_SYSTEM_PROMPT.md")
Resource memorySystemPrompt;
@Value("${agent.memory.dir}")
String memoryDir;

@Bean
ChatClient chatClient(ChatClient.Builder builder) {
  ChatClient chatClient = builder
    .defaultSystem(p -> p.text(memorySystemPrompt).param("MEMORIES_ROOT_DIERCTORY", memoryDir))
    .defaultTools(
      ShellTools.builder().build(),
      FileSystemTools.builder().build()
    )
    .defaultAdvisors(ToolCallAdvisor.builder().build())
    .build();
  return chatClient;
}

Option C relies on existing FileSystemTools and ShellTools, giving the agent full filesystem access without sandbox isolation.

9. Memory Consolidation

Option A can trigger consolidation automatically via a predicate. Example predicate merges duplicate entries after 60 seconds of inactivity or when the user says “bye”.

AutoMemoryToolsAdvisor memoryAdvisor = AutoMemoryToolsAdvisor.builder()
    .memoriesRootDirectory("E:/springai/.agent/memories")
    .memoryConsolidationTrigger((request, instant) -> {
        var previous = lastInteraction;
        lastInteraction = Instant.now();
        if (instant.isAfter(previous.plusSeconds(60))) {
            return true;
        }
        var msg = request.prompt().getLastUserOrToolResponseMessage().getText();
        return msg != null && msg.toLowerCase().contains("bye");
    })
    .build();

10. Keeping Memory Clean

Over time memory can accumulate stale or duplicate entries. Periodic consolidation—merging duplicates, deleting outdated facts, and simplifying descriptions—keeps the MEMORY.md index readable.

For manual consolidation the user can issue:

USER> 请整理你的记忆——合并重复项并删除所有过时内容。

11. Summary of Results

Running the three options produces persistent Markdown files under the configured memories directory, and the agent can retrieve and update them across restarts. The approach mirrors Claude Code’s automatic memory management, offering a flexible way to give Spring AI agents long‑term, typed memory.