Spring AI Alibaba 短期记忆与长期记忆实现原理

记忆系统概述

在 AI Agent 应用中，记忆系统是维持对话连贯性和个性化体验的核心能力：

• 短期记忆（Short-term Memory）：保存当前会话的对话历史，类似人类的'工作记忆'
• 长期记忆（Long-term Memory）：持久化存储关键信息，类似人类的'长时记忆'

Spring AI Alibaba 通过 MemorySaver 和 MemoryStore 两个组件实现了这两种记忆机制。

短期记忆实现原理

核心组件：MemorySaver

MemorySaver 是短期记忆的实现类，负责保存和恢复会话状态（Checkpoint）。其核心特点：

• 存储结构：ConcurrentHashMap<String, Map<String, Checkpoint>>
• 隔离维度：通过 threadId 隔离不同会话
• 生命周期：应用重启后数据丢失（内存存储）

实现机制

保存检查点

当 Agent 执行完一轮对话后，会调用 MemorySaver.save() 保存状态：

// MemorySaver.java
public class MemorySaver implements CheckpointSaver {
    private final ConcurrentHashMap<String, Map<String, Checkpoint>> storage = new ConcurrentHashMap<>();

    @Override
    public void save(Checkpoint checkpoint, RunnableConfig config) {
        String threadId = config.threadId().orElseThrow();
        String checkpointId = checkpoint.getId();
        // 按 threadId 分组存储
        storage.computeIfAbsent(threadId, k -> new ConcurrentHashMap<>()).put(checkpointId, checkpoint);
    }
}

关键要点：

• 每个 threadId 对应一个独立的 Map
• Checkpoint 包含完整的对话历史（messages）和状态（state）

恢复检查点

当用户继续对话时，Agent 会加载上一次的 Checkpoint：

@Override
public Optional<Checkpoint> load(RunnableConfig config) {
    String threadId = config.threadId().orElseThrow();
    Map<String, Checkpoint> threadCheckpoints = storage.get(threadId);
    if (threadCheckpoints == null || threadCheckpoints.isEmpty()) {
        return Optional.empty();
    }
    // 返回最新的 checkpoint
    return threadCheckpoints.values().stream().max(Comparator.comparing(Checkpoint::getCreatedAt));
}

使用示例

来自测试文件 ShortTermMemoryTest.java:82-116：

@Test
void testBasicShortTermMemory() throws Exception {
    // 1. 创建带 MemorySaver 的 Agent
    ReactAgent agent = ReactAgent.builder()
            .name("memory_agent")
            .model(chatModel)
            .saver(new MemorySaver()) // ← 启用短期记忆
            .build();
    // 2. 创建带 threadId 的配置
    RunnableConfig config = RunnableConfig.builder()
            .threadId("conversation_1") // ← 会话隔离标识
            .build();
    // 3. 第一轮对话：告诉名字
    agent.invoke("你好！我叫张三。", config);
    // 4. 第二轮对话：询问名字（依赖短期记忆）
    Optional<OverAllState> result = agent.invoke("我叫什么名字？", config);
    AssistantMessage response = extractLastMessage(result);
    // Agent 能记住之前的对话
    assertTrue(response.getText().contains("张三"));
}

执行流程：

1. 第一轮对话后，MemorySaver 保存 Checkpoint（包含用户消息 + 回复）
2. 第二轮对话时，Agent 加载 Checkpoint 恢复对话历史
3. 将新消息追加到历史中，发送给 LLM
4. LLM 基于完整历史回答问题

长期记忆实现原理

核心组件：MemoryStore

MemoryStore 用于存储结构化的长期信息，支持命名空间（namespace）组织数据：

• 存储结构：namespace + key + value（类似 K-V 数据库）
• 持久化：支持扩展到 Redis/MongoDB（当前版本为内存实现）
• 跨会话：不依赖 threadId，可在不同会话间共享

数据模型

// StoreItem.java
public class StoreItem {
    private List<String> namespace; // 命名空间：如 ["user_profiles"]
    private String key;             // 键：如 "user_001"
    private Map<String, Object> value; // 值：如 {"name": "张三", "age": 28}

    public static StoreItem of(List<String> namespace, String key, Map<String, Object> value) {
        return new StoreItem(namespace, key, value);
    }
}

实现机制

存储数据

// MemoryStore.java
public class MemoryStore implements Store {
    private final Map<String, Map<String, StoreItem>> storage = new ConcurrentHashMap<>();

    @Override
    public void putItem(StoreItem item) {
        String namespaceKey = String.join("/", item.getNamespace());
        storage.computeIfAbsent(namespaceKey, k -> new ConcurrentHashMap<>()).put(item.getKey(), item);
    }
}

检索数据

@Override
public Optional<StoreItem> getItem(List<String> namespace, String key) {
    String namespaceKey = String.join("/", namespace);
    Map<String, StoreItem> namespaceMap = storage.get(namespaceKey);
    if (namespaceMap == null) {
        return Optional.empty();
    }
    return Optional.ofNullable(namespaceMap.get(key));
}

使用示例

来自测试文件 LongTermMemoryTest.java:88-188：

@Test
void testLongTermMemoryWithInterceptor() throws Exception {
    // 1. 创建记忆拦截器
    ModelHook memoryInterceptor = new ModelHook() {
        @Override
        public CompletableFuture<Map<String, Object>> beforeModel(OverAllState state, RunnableConfig config) {
            // 从配置获取用户 ID
            String userId = (String) config.metadata("user_id").get();
            // 从长期记忆加载用户资料
            Optional<StoreItem> profile = memoryStore.getItem(List.of("user_profiles"), userId);
            if (profile.isPresent()) {
                Map<String, Object> data = profile.get().getValue();
                // 注入到系统消息
                String context = String.format("用户信息：姓名=%s, 年龄=%s, 邮箱=%s",
                        data.get("name"), data.get("age"), data.get("email"));
                // ... 后续逻辑
            }
            return CompletableFuture.completedFuture(state);
        }
    };
}