项目简介

Agent Memory Server（AMS）是由 Redis 官方开发的开源项目，旨在为 AI Agent 提供企业级的记忆（Memory）管理能力。该项目允许 Agent 在多轮对话中积累知识、保持上下文记忆，从而实现更智能、更个性化的交互体验。资料来源：README.md

核心定位

AMS 主要服务于两类应用场景：

• 研究助手（Research Assistants）：随着时间推移不断积累知识
• 聊天机器人（Chatbots）：维护对话上下文和个性化信息

资料来源：README.md

技术架构

整体架构图

graph TB
    subgraph "客户端层"
        JS["JavaScript 客户端<br/>agent-memory-client-js"]
        PY["Python 客户端<br/>agent-memory-client"]
        JAVA["Java 客户端<br/>agent-memory-client-java"]
        MCP["MCP 协议集成"]
        REST["REST API"]
    end
    
    subgraph "服务层"
        AMS["Agent Memory Server<br/>:8000"]
        WORKER["任务 Worker"]
        MCP_SRV["MCP Server"]
    end
    
    subgraph "存储层"
        REDIS["Redis 8 / Redis Stack"]
    end
    
    subgraph "UI 层"
        WB["AMS Workbench<br/>Web 可视化界面"]
    end
    
    JS --> REST
    PY --> REST
    JAVA --> REST
    MCP_SRV --> AMS
    AMS --> REDIS
    WORKER --> REDIS
    WB --> REST

核心组件

资料来源：workbench/README.md

部署架构

AMS 提供两种 Docker 部署模式：

graph LR
    subgraph "标准模式 (Standard)"
        A1["Docker: API + Worker"]
        A2["外部 Redis 实例"]
        A1 --> A2
    end
    
    subgraph "独立模式 (Standalone)"
        B1["Docker: All-in-One"]
        B1 --- B1
    end

标准模式：需要外部 Redis 实例，适合生产环境 独立模式：内置 Redis，适合快速试用和开发

资料来源：README.md

核心功能

1. 工作内存（Working Memory）

工作内存用于存储当前会话的对话历史，支持消息管理和自动摘要功能：

• 消息存储：自动保存用户和助手的对话消息
• 自动摘要：当 token 数量超过阈值时自动生成摘要
• 上下文管理：通过 memory_prompt() 获取相关上下文

# 工作内存核心数据结构
messages: List[MemoryMessage]      # 对话消息列表
tokens: int                       # 当前 token 数量
context: str                       # 上下文信息
session_id: str                    # 会话标识
user_id: str                       # 用户标识

资料来源：agent-memory-client/README.md

2. 长期记忆（Long-Term Memory）

长期记忆存储跨会话的持久化信息，支持语义搜索：

支持三种搜索模式：

• 语义搜索（Semantic）：基于向量相似度
• 关键词搜索（Keyword）：基于文本匹配
• 混合搜索（Hybrid）：结合语义和关键词

资料来源：workbench/src/pages/ExplorerPage.tsx:80-90

3. MCP 集成

支持 Model Context Protocol，可在 Claude Desktop 等工具中使用：

# stdio 模式（推荐用于 Claude Desktop）
uv run agent-memory mcp

# SSE 模式（开发模式）
uv run agent-memory mcp --mode sse --port 9000

资料来源：README.md

4. LangChain 集成

提供与 LangChain 的无缝集成，自动转换内存工具：

from agent_memory_client.integrations.langchain import get_memory_tools

# 自动转换为 LangChain 兼容工具
tools = get_memory_tools(
    memory_client=memory_client,
    session_id="my_session",
    user_id="alice"
)

资料来源：agent-memory-client/README.md

客户端支持

多语言 SDK 矩阵

资料来源：agent-memory-client/README.md, Java Client 0.1.0 Release Notes

Python 客户端示例

from agent_memory_client import create_memory_client
from agent_memory_client.models import ClientMemoryRecord, MemoryTypeEnum

async def main():
    client = await create_memory_client("http://localhost:8000")
    
    # 创建记忆
    memories = [
        ClientMemoryRecord(
            text="User prefers dark mode",
            memory_type=MemoryTypeEnum.SEMANTIC,
            topics=["preferences", "ui"]
        )
    ]
    await client.create_long_term_memory(memories)
    
    # 搜索记忆
    results = await client.search_long_term_memory(
        text="user interface preferences",
        limit=10
    )

资料来源：agent-memory-client/README.md

版本历史与重要变更

最新版本

v0.15.2 - 当前最新稳定版本

安装方式：

# PyPI
pip install agent-memory-server==0.15.2

# Docker 标准版
docker pull redislabs/agent-memory-server:0.15.2
docker pull ghcr.io/redis/agent-memory-server:0.15.2

# Docker 独立版（内置 Redis）
docker pull redislabs/agent-memory-server:0.15.2-standalone

资料来源：Server v0.15.2 Release Notes

版本演进要点

资料来源：Release Notes v0.12.0-v0.15.2

开发与贡献

环境准备

# 初始设置
make setup

# 完整验证（包含 lint 和服务测试）
make verify

# 运行各层测试
make pre-commit    # 代码检查
make test          # 单元测试
make test-api      # API 测试

开发栈启动

# 开发模式
docker compose up api redis

# 生产-like 模式
docker compose up api task-worker redis mcp

环境变量要求：OPENAI_API_KEY（用于运行 make test-api）

资料来源：README.md

已知限制与社区议题

活跃社区议题

资料来源：Community Issues

Redis 版本建议

推荐使用 Redis 8 而非 Redis Stack。Redis 8 内置了本项目所需的所有模块，文档和示例应优先使用 redis:8 镜像。

资料来源：Issue #287

许可证

Apache License 2.0 - 详见 LICENSE 文件

相关资源

• 官方文档：docs/development.md
• 多语言客户端文档
• 示例代码：examples/
• AMS Workbench 可视化界面

前置要求

在开始之前，请确保已安装以下依赖：

注意：Redis 8 已包含本项目所需的全部模块（如 RediSearch、JSON 等），无需使用 Redis Stack。资料来源：README.md:1-20

安装方式

方式一：通过 PyPI 安装

pip install agent-memory-server==0.15.2

安装后可通过 agent-memory 命令行工具启动服务：

# 标准模式（需要外部 Redis）
agent-memory server --redis-url redis://localhost:6379

# 独立模式（内置 Redis）
agent-memory server --standalone

资料来源：README.md:1-30

方式二：Docker 部署

#### 标准模式（需要外部 Redis）

# 启动 Redis 8
docker run -d --name redis -p 6379:6379 redis:8

# 启动 AMS
docker run -d --name ams -p 8000:8000 \
  -e REDIS_URL=redis://redis:6379 \
  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
  redislabs/agent-memory-server:0.15.2

#### 独立模式（All-in-One）

docker run -d --name ams-standalone -p 8000:8000 \
  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
  -e AMS_STANDALONE=true \
  redislabs/agent-memory-server:0.15.2

资料来源：docker-compose.yml

本地开发环境

使用 Docker Compose 快速启动

项目提供了开箱即用的 docker-compose.yml 配置：

# 克隆仓库
git clone https://github.com/redis/agent-memory-server.git
cd agent-memory-server

# 启动开发环境（基础模式）
docker compose up api redis

# 或启动完整生产环境
docker compose up api task-worker redis mcp

资料来源：README.md:15-25

开发环境初始化

# 初始设置
make setup

# 完整验证（包含 lint 和服务测试）
make verify

# 或运行单独层
make pre-commit    # 代码检查
make test          # 单元测试
make test-api      # API 测试

注意：make verify 需要设置 OPENAI_API_KEY 环境变量。资料来源：README.md:25-35

基础使用示例

Python 客户端

使用异步客户端快速集成内存功能：

from agent_memory_client import create_memory_client
from agent_memory_client.models import ClientMemoryRecord, MemoryTypeEnum
import asyncio

async def main():
    # 创建客户端
    client = await create_memory_client("http://localhost:8000")
    
    try:
        # 创建记忆记录
        memories = [
            ClientMemoryRecord(
                text="用户偏好深色模式",
                memory_type=MemoryTypeEnum.SEMANTIC,
                topics=["偏好", "界面"]
            ),
            ClientMemoryRecord(
                text="用户于2024-01-15完成新手引导",
                memory_type=MemoryTypeEnum.EPISODIC,
                topics=["新手引导", "里程碑"]
            )
        ]
        
        # 存储长期记忆
        await client.create_long_term_memory(memories)
        
        # 搜索记忆
        results = await client.search_long_term_memory(
            text="用户界面偏好",
            limit=10
        )
        
        print(f"找到 {len(results.memories)} 条相关记忆")
        
    finally:
        await client.close()

asyncio.run(main())

资料来源：agent-memory-client/README.md:1-50

工作记忆（Working Memory）

工作记忆用于存储会话上下文：

from agent_memory_client import create_memory_client
import asyncio

async def main():
    client = await create_memory_client("http://localhost:8000")
    
    try:
        # 获取或创建工作记忆
        session_id = "user_123_session"
        
        # 添加消息到工作记忆
        await client.put_working_memory(
            session_id=session_id,
            messages=[
                {"role": "user", "content": "我喜欢披萨"},
                {"role": "assistant", "content": "好的，我记住了"}
            ]
        )
        
        # 获取完整工作记忆
        wm = await client.get_working_memory(session_id)
        print(f"记忆数: {len(wm.memories)}")
        
    finally:
        await client.close()

asyncio.run(main())

资料来源：examples/README.md:1-40

LangChain 集成

AMS 客户端提供自动转换为 LangChain 工具的功能：

from agent_memory_client import create_memory_client
from agent_memory_client.integrations.langchain import get_memory_tools
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

# 获取 LangChain 兼容工具（自动转换）
memory_client = await create_memory_client("http://localhost:8000")
tools = get_memory_tools(
    memory_client=memory_client,
    session_id="my_session",
    user_id="alice"
)

# 创建带记忆功能的 Agent
llm = ChatOpenAI(model="gpt-4o")
agent = create_agent(llm, tools, system_prompt="你是带记忆功能的助手")

# 使用 Agent
result = await agent.ainvoke({"messages": [("human", "记住我爱吃披萨")]})

资料来源：README.md:50-80

MCP 集成

Model Context Protocol（MCP）提供另一种集成方式：

# 标准模式（推荐用于 Claude Desktop）
uv run agent-memory mcp

# SSE 模式（开发模式）
uv run agent-memory mcp --mode sse --port 9000

在 Claude Desktop 配置中使用：

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["agent-memory", "mcp"]
    }
  }
}

资料来源：README.md:80-100

环境变量配置

下一步

• 阅读 API 文档 了解更多接口详情
• 查看 SDK 文档 获取多语言客户端使用指南
• 参考 示例项目 了解完整应用场景

常见问题

启动失败：Redis 连接错误

确保 Redis 服务已启动并可访问：

# 检查 Redis 是否运行
docker ps | grep redis

# 或手动启动
docker run -d -p 6379:6379 redis:8

Embedding 请求失败

确认 OPENAI_API_KEY 设置正确且有效：

export OPENAI_API_KEY=sk-...

端口冲突

AMS 默认使用 8000 端口，可通过环境变量更改：

docker run -d -p 8080:8000 -e AMS_PORT=8000 redislabs/agent-memory-server:0.15.2

核心问题概览

LangChain 集成问题

问题背景

Issue #139 提出应考虑弃用当前的 LangChain 向量搜索适配器。社区认为当前的适配器实现存在局限性，限制了项目的灵活性。资料来源：github.com/redis/agent-memory-server/issues/139

当前适配器局限性

当前 LangChain 适配器的主要问题包括：

1. 元数据过滤不一致：向量搜索实现不保证具有共同的特性，包括元数据过滤功能
2. 适配器锁定风险：过度依赖适配器模式可能导致与特定实现紧密耦合
3. 功能差异：不同向量搜索后端的能力差异使得统一的适配器难以实现

资料来源：agent-memory-client/README.md

替代方案

建议的改进方向是直接基于项目自身接口进行构建，而非通过 LangChain 适配器。这种方式可以：

• 保持接口的稳定性和一致性
• 支持构建替代实现
• 减少对第三方库特定实现的依赖

# 推荐方式：直接使用原生工具
from agent_memory_client import create_memory_client
from langchain.agents import create_agent

# 获取原生内存工具
memory_client = await create_memory_client("http://localhost:8000")
tools = get_memory_tools(
    memory_client=memory_client,
    session_id="my_session",
    user_id="alice"
)

资料来源：README.md

Redis 版本迁移

问题描述

Issue #287 指出项目中部分面向用户的示例仍在使用 Redis Stack 镜像，应更新为使用 Redis 8（redis:8）。资料来源：github.com/redis/agent-memory-server/issues/287

迁移原因

Redis 8 已经包含了本项目所需的原自分离模块，因此文档和示例应反映当前的默认建议，避免引导用户使用过时的配置。资料来源：github.com/redis/agent-memory-server/issues/287

迁移检查清单

摘要功能控制

问题背景

Issue #193 指出当前版本的 AMS 无法干净利落地禁用工作内存摘要功能。在 PUT /v1/working-memory/{session_id} 接口上，摘要功能总是根据消息进行评估。资料来源：github.com/redis/agent-memory-server/issues/193

当前实现逻辑

当前摘要评估使用以下公式：

token_threshold = int(max_tokens * threshold_ratio)

这意味着只要存在消息，就会触发摘要评估机制。资料来源：github.com/redis/agent-memory-server/issues/193

v0.15.0 的改进

在 Server v0.15.0 版本中，已通过 PR #226 禁用了摘要功能。资料来源：github.com/redis/agent-memory-server/releases/tag/server/v0.15.0

配置建议

对于需要控制摘要行为的场景，建议通过配置参数进行管理：

# 通过环境变量或配置禁用摘要
SUMMARIZATION_ENABLED=false

# 或在 API 调用时指定
memory_config = {
    "summarization_enabled": False,
    "max_tokens": 4096
}

API 行为变更

废弃行为说明

Issue #136 要求移除 GET /v1/working-memory/{session_id} 中的废弃行为。当前当会话不存在时，API 会返回一个新的空 WorkingMemory 对象并标记 new_session: true，而非返回 404 错误。资料来源：github.com/redis/agent-memory-server/issues/136

当前行为

// 现有会话不存在的响应
{
  "messages": [],
  "memories": [],
  "data": {},
  "context": "",
  "userId": null,
  "tokens": 0,
  "sessionId": "non_existent_session",
  "namespace": "default",
  "longTermMemoryStrategy": {},
  "ttlSeconds": null,
  "lastAccessed": "2024-01-01T00:00:00Z",
  "new_session": true
}

预期变更

变更后，不存在的会话应返回标准的 404 响应：

{
  "error": "Session not found",
  "session_id": "non_existent_session"
}

资料来源：github.com/redis/agent-memory-server/issues/136

LLM 客户端统一

问题背景

Issue #105 讨论了将统一的 LLMClient 与 LiteLLM 进行整合的必要性。当前的 llms.py 模块存在多个痛点。资料来源：github.com/redis/agent-memory-server/issues/105

当前架构问题

#### 1. 多重包装类

现有的实现包含多个独立的包装类：

• OpenAIClientWrapper
• AnthropicClientWrapper
• BedrockClientWrapper

这些类之间存在大量重复逻辑。资料来源：github.com/redis/agent-memory-server/issues/105

#### 2. 手动提供商检测

当前使用自定义的 MODEL_NAME_MAP 字典来手动映射模型名称，这种方式需要持续的手动更新。资料来源：github.com/redis/agent-memory-server/issues/105

v0.12.7 的改进

在 v0.12.7 版本中，已引入了 LiteLLM Embeddings Wrapper，展示了向统一客户端架构迁移的方向。资料来源：github.com/redis/agent-memory-server/releases/tag/server/v0.12.7

预期改进

整合后的架构应实现：

• 统一的客户端接口
• 自动化的提供商检测
• 简化的模型名称映射
• 减少代码重复

# 目标架构示意
from agent_memory.llm import UnifiedLLMClient

client = UnifiedLLMClient(
    model="gpt-4o",
    provider="auto"  # 自动检测
)

Workbench UI 问题

UI 组件架构

Workbench 是项目的可视化界面，基于 React 和 TypeScript 构建，提供了两个主要页面：

资料来源：workbench/README.md

搜索功能问题

在 ExplorerPage.tsx 中，搜索功能支持多种模式：

• 语义搜索 (semantic)
• 关键词搜索 (keyword)
• 混合搜索 (hybrid)

interface SearchOptions {
  text: string;
  searchMode?: "semantic" | "keyword" | "hybrid";
  hybridAlpha?: number;
  sessionId?: SessionId;
  memoryType?: MemoryType;
  topics?: Topics;
  entities?: Entities;
}

资料来源：workbench/src/pages/ExplorerPage.tsx

内存类型显示

Workbench 使用颜色编码来区分不同类型的内存：

资料来源：workbench/src/pages/ExplorerPage.tsx

客户端支持问题

多语言客户端

项目提供了多个语言的客户端库，每个都有不同的成熟度和功能支持：

资料来源：github.com/redis/agent-memory-server/releases/tag/java-client-v0.1.0

Java 客户端问题

Java 客户端在 v0.1.0 版本中进行了 JVM 21 升级，提供了工作内存和长时记忆服务的完整支持。资料来源：github.com/redis/agent-memory-server/releases/tag/java-client-v0.1.0

JavaScript 客户端配置

JavaScript 客户端提供了灵活的配置选项：

interface ClientConfig {
  baseUrl?: string;
  timeout?: number;
  defaultModelName?: ModelNameLiteral;
  defaultContextWindowMax?: number;
  apiKey?: string;
  bearerToken?: string;
  fetch?: typeof fetch;
}

资料来源：agent-memory-client/agent-memory-client-js/src/client.ts

长期规划问题

架构演进方向

根据社区反馈，项目未来的发展方向包括：

1. 简化依赖：减少外部依赖，提高可维护性
2. 统一接口：提供一致的 API 体验
3. 灵活配置：支持更多定制化场景
4. 性能优化：改进缓存和搜索性能

迁移策略

对于现有用户，建议的关注点：

参与社区

贡献指南

项目欢迎社区贡献者，请参阅开发文档了解相关指南：

• 开发环境设置
• 代码规范要求
• Pull Request 流程

资料来源：README.md

本地开发

# 初始化设置
make setup

# 完整本地验证
make verify

# 运行各层测试
make pre-commit
make test
make test-api

资料来源：README.md

架构总览

Agent Memory Server 采用模块化架构，核心由 FastAPI 服务层、Redis 数据存储层、MCP 协议层和多客户端 SDK 组成。系统支持 REST API 和 MCP (Model Context Protocol) 两种通信协议，允许 AI 代理通过多种方式访问记忆功能。

graph TB
    subgraph 客户端层
        JS[JavaScript 客户端]
        PY[Python 客户端]
        JAVA[Java 客户端]
        MCP[MCP Client]
    end
    
    subgraph 服务层
        API[FastAPI REST API]
        MCP_SRV[MCP Server]
    end
    
    subgraph 核心引擎
        WM[Working Memory Engine]
        LTM[Long Term Memory Engine]
        EX[Extraction Engine]
        SUM[Summary Engine]
    end
    
    subgraph 数据层
        REDIS[(Redis 8)]
        HASH[Hash Storage]
        VSS[Vector Search]
        SORTED[Sorted Sets]
    end
    
    JS --> API
    PY --> API
    JAVA --> API
    MCP --> MCP_SRV
    API --> WM
    API --> LTM
    MCP_SRV --> WM
    MCP_SRV --> LTM
    WM --> EX
    WM --> SUM
    WM --> REDIS
    LTM --> REDIS
    EX --> REDIS

核心组件

API 服务层

API 服务层基于 FastAPI 构建，提供 RESTful 接口供客户端访问。服务层负责请求验证、路由分发和响应格式化。

MCP 协议层

MCP (Model Context Protocol) 服务器提供标准化的工具调用接口，支持 AI 模型直接调用记忆功能。MCP 服务支持两种运行模式：

• STDIO 模式：适用于 Claude Desktop 等本地集成场景
• SSE 模式：适用于远程开发环境，默认使用异步后端

graph LR
    A[MCP Client] -->|stdio/sse| B[MCP Server]
    B --> C[Tool Registry]
    C --> D[working_memory]
    C --> E[long_term_memory]
    C --> F[search]

MCP 服务启动命令：

# STDIO 模式（推荐用于 Claude Desktop）
uv run agent-memory mcp

# SSE 模式（开发模式）
uv run agent-memory mcp --mode sse --port 9000

记忆管理引擎

#### 工作记忆引擎

工作记忆引擎管理会话期间的短期对话上下文，采用 Redis Sorted Sets 存储消息序列，确保时间顺序和访问频率的精确追踪。

关键源码：agent_memory_server/working_memory.py:1-200

#### 长期记忆引擎

长期记忆引擎管理持久化的语义记忆，支持向量搜索和多种过滤条件。

关键源码：agent_memory_server/long_term_memory.py:1-150

客户端架构

多语言 SDK 支持

系统提供三种官方客户端 SDK，覆盖主流开发语言：

graph TB
    subgraph 客户端层
        PY[Python SDK]
        JS[JavaScript SDK]
        JAVA[Java SDK]
    end
    
    subgraph 通信层
        REST[REST API]
        MCP[MCP Protocol]
    end
    
    subgraph 集成层
        LC[LangChain 集成]
        LCX[LangGraph 集成]
    end
    
    PY --> REST
    PY --> MCP
    JS --> REST
    JAVA --> REST
    
    PY --> LC
    PY --> LCX

Python 客户端

Python 客户端提供异步 API 设计，与 FastAPI 和 LangChain 无缝集成：

from agent_memory_client import create_memory_client

memory_client = await create_memory_client("http://localhost:8000")

# 工作记忆操作
working_memory = await memory_client.get_working_memory(
    session_id="session_123",
    user_id="user_456"
)

# 长期记忆搜索
results = await memory_client.search_long_term_memory(
    text="用户偏好设置",
    limit=10,
    topics=["preferences"]
)

LangChain 集成

客户端提供自动化的 LangChain 工具转换功能，无需手动包装 @tool 装饰器：

from agent_memory_client.integrations.langchain import get_memory_tools

tools = get_memory_tools(
    memory_client=memory_client,
    session_id="my_session",
    user_id="alice"
)

# 直接创建 LangGraph Agent
agent = create_agent(llm, tools, system_prompt="You are helpful with memory.")

资料来源：agent_memory_client/integrations/langchain/__init__.py

数据存储架构

Redis 数据结构设计

系统充分利用 Redis 的多种数据结构实现高效记忆存储：

graph TB
    subgraph Redis 8
        subgraph Keys
            WM_SS[Sorted Set<br/>工作记忆]
            LTM_HS[Hash<br/>长期记忆]
            VEC[Vector Index<br/>向量索引]
            TOPIC_SET[Set<br/>主题索引]
        end
    end
    
    WM_SS --> |消息追加| API
    LTM_HS --> |CRUD| API
    VEC --> |向量搜索| API
    TOPIC_SET --> |标签过滤| API

向量搜索实现

系统使用 Redis 8 内置的向量搜索功能，无需额外模块。语义记忆通过嵌入向量实现相似度搜索，支持以下搜索模式：

• Semantic：纯语义向量搜索
• Keyword：传统关键词匹配
• Hybrid：语义+关键词混合搜索

资料来源：agent_memory_server/long_term_memory.py:50-100

部署架构

Docker 部署模式

系统支持两种 Docker 部署模式：

#### 标准模式（需要外部 Redis）

docker compose up api redis

#### 生产模式（含所有组件）

docker compose up api task-worker redis mcp

开发环境

# 初始设置
make setup

# 完整验证
make verify

# 启动开发栈
docker compose up api redis

安全与配置

认证机制

客户端支持多种认证方式：

配置参数

资料来源：agent_memory_client/agent_memory_client/client.ts:30-50

社区相关议题

系统架构方面，社区存在以下活跃讨论：

• #139：考虑弃用 LangChain 向量搜索适配器，认为直接构建接口更为灵活
• #105：集成统一 LLMClient 与 LiteLLM，整合多个包装类
• #193：工作记忆摘要功能的可配置性需求

技术栈总结

概述

AMS 采用双层记忆架构：

• 工作记忆 (Working Memory)：存储会话期间的即时消息和上下文数据
• 长期记忆 (Long-Term Memory)：存储从工作记忆提取的持久化语义记忆

这种设计使得 AI Agent 能够同时维护短期对话上下文和长期知识积累。

记忆类型

AMS 支持三种核心记忆类型，每种类型服务于不同的记忆目的：

资料来源：workbench/src/pages/ExplorerPage.tsx:120-130

工作记忆生命周期

创建与更新流程

graph TD
    A[用户/助手消息] --> B[PUT /v1/working-memory/{session_id}]
    B --> C{会话是否存在?}
    C -->|不存在| D[创建新会话]
    C -->|存在| E[追加消息]
    D --> F[初始化 WorkingMemory]
    E --> G[消息入队]
    F --> G
    G --> H[检查令牌数阈值]
    H --> I{是否超过阈值?}
    I -->|否| J[保存会话]
    I -->|是| K{摘要功能启用?}
    K -->|是| L[触发摘要生成]
    K -->|否| J
    L --> M[生成压缩摘要]
    M --> N[保存会话]
    J --> O[返回 WorkingMemory]
    N --> O

工作记忆数据模型

WorkingMemory 是核心数据结构，包含以下关键字段：

// 资料来源：agent-memory-client-java/.../WorkingMemory.java
public class WorkingMemory {
    private List<MemoryMessage> messages;           // 消息列表
    private List<MemoryRecord> memories;           // 提取的记忆
    private Map<String, Object> data;              // 自定义数据
    private String context;                          // 上下文摘要
    private String userId;                          // 用户标识
    private int tokens;                             // 当前令牌数
    private String sessionId;                       // 会话ID
    private String namespace;                       // 命名空间
    private MemoryStrategyConfig longTermMemoryStrategy;  // 长期记忆策略
    private Integer ttlSeconds;                     // 生存时间
    private Instant lastAccessed;                   // 最后访问时间
}

消息结构

// 资料来源：agent-memory-client-java/.../MemoryMessage.java
public class MemoryMessage {
    private String role;           // "user" 或 "assistant"
    private String content;        // 消息内容
    private String id;             // 消息唯一标识
    private Instant createdAt;     // 创建时间
    private Instant persistedAt;   // 持久化时间
    private boolean discreteMemoryExtracted;  // 是否已提取离散记忆
}

自动记忆提取

提取机制

当工作记忆中的消息满足特定条件时，系统会自动触发记忆提取：

1. 消息累积检测：系统监控消息数量和令牌数
2. 去重检查：对新消息进行语义相似度检测，避免重复记忆
3. 主题提取：使用 LLM 从消息中提取关键主题
4. 实体识别：自动识别并标记消息中的实体信息

提取配置

资料来源：agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/workingmemory/WorkingMemory.java

摘要功能

工作原理

摘要功能用于在对话过长时压缩工作记忆，保留关键信息：

# 伪代码示例
token_threshold = int(max_tokens * threshold_ratio)
if total_tokens > token_threshold:
    generate_summary()

版本变化说明

⚠️ 社区反馈：Issue #193 指出早期版本无法真正禁用摘要功能，v0.15.0 已修复此问题。

资料来源：社区 Issue #193

长期记忆管理

持久化策略

长期记忆存储在 Redis 中，采用向量检索实现语义搜索：

graph LR
    A[工作记忆消息] --> B[LLM 主题/实体提取]
    B --> C[记忆记录创建]
    C --> D[生成向量嵌入]
    D --> E[存储到 Redis]
    E --> F[向量索引更新]
    
    G[语义搜索查询] --> H[向量相似度计算]
    H --> I[Top-K 结果返回]
    F --> I

搜索选项

AMS 提供灵活的长期记忆搜索能力：

资料来源：agent-memory-client/agent-memory-client-js/src/client.ts:100-115

自动分页搜索

Java 客户端提供流式搜索接口，自动处理分页：

// 资料来源：agent-memory-client-java/.../LongTermMemoryService.java
public Iterator<MemoryRecord> searchAllLongTermMemories(
        String text,
        String sessionId,
        String namespace,
        List<String> topics,
        List<String> entities,
        String userId,
        int batchSize) {
    // 自动分页迭代器实现
}

public Stream<MemoryRecord> searchAllLongTermMemoriesStream(...) {
    // 返回 Java Stream 接口
}

检索与上下文注入

记忆提示 (Memory Prompt)

AMS 提供 memory_prompt() 功能，用于在生成响应时检索相关记忆：

# 资料来源：examples/README.md
memory_prompt_result = await memory_client.get_memory_prompt(
    query="用户偏好",
    session={"session_id": "xxx", "user_id": "user123"},
    long_term_search={"text": "偏好", "limit": 5}
)
# 返回相关消息和长期记忆

上下文注入流程

graph TD
    A[用户查询] --> B[构建 MemoryPromptParams]
    B --> C[检索工作记忆]
    C --> D[检索长期记忆]
    D --> E[合并上下文]
    E --> F[增强系统提示]
    F --> G[调用 LLM]
    G --> H[生成响应]

工作台可视化

Workbench 提供图形界面查看和管理记忆：

// 资料来源：workbench/src/pages/ExplorerPage.tsx
// 记忆详情展示
{selectedMemory.topics && selectedMemory.topics.length > 0 && (
  <div className="flex gap-1 mt-1 flex-wrap">
    {selectedMemory.topics.map((topic) => (
      <span className="px-2 py-1 text-xs bg-redis-blue-04 text-redis-blue-03 rounded">
        {topic}
      </span>
    ))}
  </div>
)}

配置与管理

核心配置选项

API 端点

常见问题

1. 记忆未正确提取

可能原因：

• 语义去重过滤了相似内容
• 提取 debounce 期间请求被合并

解决方案：调整 semantic_dedup_enabled 和 extraction_debounce_ttl 配置

2. 摘要功能异常

版本参考：v0.15.0 禁用了默认摘要功能，如需启用需显式配置

3. 会话 404 问题

⚠️ 待处理变更：Issue #136 提议移除"不存在的会话返回空对象"的行为，改为直接返回 404。

资料来源：社区 Issue #136

最佳实践

1. 合理设置 TTL：根据对话频率调整 ttlSeconds，避免过早过期
2. 主题标签：创建记忆时添加明确的 topics，提高检索精度
3. 定期清理：使用 compactMemories API 整理碎片化记忆
4. 使用混合搜索：复杂查询建议使用 hybrid 搜索模式

相关资源

• API 文档
• 客户端 SDK
• Workbench 使用指南
• 示例代码

核心概念

工作记忆本质上是一个以会话（Session）为中心的临时存储容器。每个工作记忆实例包含以下关键组件：

资料来源：WorkingMemory.java:15-35

数据模型

MemoryMessage

消息模型表示对话中的单条消息，包含角色、内容和时间戳信息：

public class MemoryMessage {
    private String id;
    private String role;        // "user" 或 "assistant"
    private String content;     // 消息内容
    private Instant createdAt;      // 创建时间
    private Instant persistedAt;    // 持久化时间
    private Boolean discreteMemoryExtracted;  // 是否已提取离散记忆
}

资料来源：MemoryMessage.java:10-35

WorkingMemory 结构

工作记忆支持会话级别的上下文管理和自动数据持久化：

public class WorkingMemory {
    private List<MemoryMessage> messages;
    private List<MemoryRecord> memories;
    private Map<String, Object> data;
    private String context;
    private String userId;
    private int tokens;
    private String sessionId;
    private String namespace;
    private MemoryStrategyConfig longTermMemoryStrategy;
    private Integer ttlSeconds;
    private Instant lastAccessed;
}

资料来源：WorkingMemory.java:35-50

API 端点

工作记忆管理提供以下 REST API 端点：

GET /v1/working-memory/{session_id}

获取指定会话的工作记忆：

响应：返回完整的 WorkingMemory 对象，如果会话不存在则返回 404。

PUT /v1/working-memory/{session_id}

创建或更新工作记忆：

资料来源：agent_memory_server/models.py

核心功能

自动摘要

当工作记忆中的消息 token 数超过阈值时，系统会自动触发摘要生成。摘要阈值基于配置的 max_tokens 参数计算：

token_threshold = int(max_tokens * threshold_ratio)

v0.15.0 更新：系统新增配置选项，允许更灵活地控制摘要功能。摘要过程将长消息序列压缩为简洁的上下文表示，减少 token 消耗同时保留关键信息。

语义去重

系统持续监控工作记忆中的内容相似度。当检测到语义重复的记忆条目时，自动触发合并操作。合并逻辑基于向量距离计算，相似度超过阈值的条目会被整合。

长时记忆策略

每个工作记忆可配置与长期记忆的交互策略：

MemoryStrategyConfig longTermMemoryStrategy = new MemoryStrategyConfig();

策略配置定义何时以及如何将工作记忆中的内容提取到长期记忆存储。

消息处理流程

graph TD
    A[接收消息] --> B{检查 token 阈值}
    B -->|未超阈值| C[直接存储消息]
    B -->|超过阈值| D[触发摘要生成]
    D --> E{检查语义重复}
    E -->|存在重复| F[合并重复记忆]
    E -->|无重复| G[提取离散记忆]
    G --> H[存储到工作记忆]
    C --> H
    F --> H
    H --> I[更新上下文]

客户端集成

Python 客户端

from agent_memory_client import create_memory_client

memory_client = await create_memory_client("http://localhost:8000")

# 获取工作记忆
working_memory = await memory_client.get_working_memory(
    session_id="my_session",
    user_id="alice"
)

# 更新工作记忆
await memory_client.put_working_memory(
    session_id="my_session",
    messages=[{"role": "user", "content": "Hello!"}],
    data={"key": "value"}
)

JavaScript 客户端

const client = new AgentMemoryClient({
  baseUrl: "http://localhost:8000",
  defaultModelName: "gpt-4o"
});

const workingMemory = await client.getWorkingMemory({
  sessionId: "my_session",
  userId: "alice"
});

资料来源：agent-memory-client-js/src/client.ts

Java 客户端

WorkingMemory memory = WorkingMemory.builder()
    .sessionId("my_session")
    .userId("alice")
    .messages(messages)
    .data(data)
    .build();

资料来源：WorkingMemory.java:50-70

工作台集成

AMS Workbench 提供了可视化的工作记忆管理界面：

聊天页面

聊天页面集成记忆开关，允许用户实时控制记忆功能：

const [memoryEnabled, setMemoryEnabled] = useState(true);

// 记忆开关 UI
<button onClick={() => setMemoryEnabled(!memoryEnabled)}>
  {memoryEnabled ? "记忆已启用" : "记忆已禁用"}
</button>

资料来源：workbench/src/pages/ChatPage.tsx

探索页面

探索页面提供工作记忆的搜索和过滤功能：

资料来源：workbench/src/pages/ExplorerPage.tsx

社区相关问题

摘要功能控制

Issue #193 报告了无法干净地禁用工作记忆摘要功能的问题。当前实现中，摘要基于 max_tokens 的比例自动评估，用户希望有更明确的开关控制。

会话缺失行为

Issue #136 讨论了移除"会话缺失时返回空会话"这一废弃行为的计划。当前实现对于不存在的会话返回空的 WorkingMemory 对象并标记 new_session: true，新版 API 计划改为返回 404。

配置选项

最佳实践

1. 会话隔离：为每个用户对话使用唯一的 session_id
2. 命名空间分离：多租户场景下使用 namespace 隔离数据
3. TTL 管理：为临时会话设置合理的过期时间
4. 上下文精简：避免在 data 字段中存储过大的数据
5. 记忆提取：利用自动记忆提取功能减少手动管理工作

概述

长期记忆（Long-term Memory）是 Agent Memory Server (AMS) 系统中用于持久化存储和检索语义化记忆的核心组件。与工作记忆（Working Memory）专注于即时对话上下文不同，长期记忆用于存储跨会话的重要信息，使 AI Agent 能够积累知识并在后续交互中调用历史数据。

长期记忆系统提供以下核心能力：

• 语义搜索：基于向量嵌入的相似度检索
• 多维度过滤：支持按主题、实体、用户、时间范围等条件筛选
• 混合搜索模式：支持语义搜索、关键词搜索以及两者的混合模式
• 自动去重：基于语义相似度的重复记忆合并

资料来源：examples/README.md

架构设计

记忆类型体系

AMS 中的记忆分为三种类型，每种类型具有不同的用途和存储策略：

资料来源：workbench/src/pages/ExplorerPage.tsx:180-189

搜索流程架构

graph TD
    A[搜索请求] --> B[解析查询参数]
    B --> C{搜索模式}
    C -->|语义| D[向量嵌入]
    C -->|关键词| E[全文索引]
    C -->|混合| F[向量 + 全文]
    D --> G[相似度计算]
    E --> H[相关性评分]
    F --> I[Alpha 加权合并]
    G --> J[结果排序]
    H --> J
    I --> J
    J --> K[应用过滤器]
    K --> L[返回结果]

客户端 SDK 使用

Python 客户端

Python 客户端提供同步和异步两种接口访问长期记忆服务。

#### 创建长期记忆

from agent_memory_client import create_memory_client
from agent_memory_client.models import ClientMemoryRecord, MemoryTypeEnum

async def main():
    client = await create_memory_client("http://localhost:8000")
    
    try:
        # 创建记忆记录
        memories = [
            ClientMemoryRecord(
                text="用户偏好深色模式",
                memory_type=MemoryTypeEnum.SEMANTIC,
                topics=["偏好", "界面"]
            ),
            ClientMemoryRecord(
                text="用户于 2024-01-15 完成入职培训",
                memory_type=MemoryTypeEnum.EPISODIC,
                topics=["入职", "里程碑"]
            )
        ]
        
        # 存储到长期记忆
        result = await client.create_long_term_memory(memories)
        print(f"创建了 {len(result.memories)} 条记忆")
        
    finally:
        await client.close()

资料来源：agent-memory-client/README.md

#### 搜索长期记忆

# 搜索相关记忆
results = await client.search_long_term_memory(
    text="用户界面偏好",
    limit=10
)

print(f"找到 {len(results.memories)} 条相关记忆")
for memory in results.memories:
    print(f"- {memory.text} (距离: {memory.dist})")

Java 客户端

Java 客户端提供类型安全的长期记忆服务接口。

#### 长期记忆服务

import com.redis.agentmemory.services.LongTermMemoryService;
import com.redis.agentmemory.models.MemoryRecord;

// 搜索长期记忆
Iterator<MemoryRecord> results = longTermMemoryService.searchAllLongTermMemories(
    "用户偏好",
    null,           // sessionId
    null,           // namespace
    List.of("偏好"), // topics
    null,           // entities
    "user_123",     // userId
    100             // batchSize
);

#### 流式搜索

Java 客户端支持流式搜索，适合处理大量结果：

public Stream<MemoryRecord> searchAllLongTermMemoriesStream(
    @NotNull String text,
    @Nullable String sessionId,
    @Nullable String namespace,
    @Nullable List<String> topics,
    @Nullable List<String> entities,
    @Nullable String userId,
    int batchSize
)

资料来源：agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java

搜索选项详解

搜索模式

AMS 支持三种搜索模式，通过 searchMode 参数指定：

高级过滤选项

interface SearchOptions {
  text: string;
  searchMode?: "semantic" | "keyword" | "hybrid";
  hybridAlpha?: number;                    // 混合模式权重
  textScorer?: string;                    // 自定义评分器
  
  // 身份过滤
  sessionId?: string | FilterCondition;
  namespace?: string | FilterCondition;
  userId?: string | FilterCondition;
  
  // 内容过滤
  topics?: Topics | FilterCondition;
  entities?: Entities | FilterCondition;
  
  // 时间过滤
  createdAt?: CreatedAt | FilterCondition;
  lastAccessed?: LastAccessed | FilterCondition;
  eventDate?: EventDate | FilterCondition;
  
  // 类型过滤
  memoryType?: MemoryType | FilterCondition;
}

资料来源：agent-memory-client/agent-memory-client-js/src/client.ts

过滤条件组合

过滤器支持丰富的条件组合：

工作台界面

AMS Workbench 提供可视化界面进行长期记忆的探索和管理。

记忆浏览器

记忆浏览器（ExplorerPage）支持以下功能：

• 记忆列表展示：显示所有长期记忆的摘要信息
• 过滤和搜索：按类型、主题、创建时间等条件筛选
• 记忆详情查看：查看单条记忆的完整内容
• 复制记忆 ID：方便在 API 调用中使用

记忆详情面板

interface MemoryDetail {
  id: string;           // 记忆唯一标识
  text: string;         // 记忆内容
  memory_type: 'semantic' | 'episodic' | 'message';
  topics?: string[];    // 关联主题
  entities?: string[];  // 关联实体
  created_at: Date;     // 创建时间
  access_count?: number; // 访问次数
}

搜索结果展示

工作台在显示搜索结果时提供丰富的上下文信息：

• 相似度分数：显示语义搜索的 dist 或 score
• 分数类型：指示使用的评分方式
• 时间信息：显示记忆创建时间（相对时间格式）
• 访问统计：显示记忆被访问的次数

{searchText && (memory.score !== undefined || memory.dist !== undefined) && (
  <span className="text-xs text-redis-dusk-05">
    Score: {(memory.score ?? (memory.dist !== undefined ? 1 - memory.dist : 0)).toFixed(3)}
    {memory.score_type ? ` (${memory.score_type})` : ''}
  </span>
)}

资料来源：workbench/src/pages/ExplorerPage.tsx:180-189

API 接口

创建长期记忆

POST /v1/long-term-memory

请求体：

{
  "memories": [
    {
      "text": "用户偏好深色主题",
      "memory_type": "semantic",
      "topics": ["偏好", "界面"],
      "entities": ["用户"],
      "metadata": {}
    }
  ],
  "session_id": "session_123",
  "namespace": "production",
  "user_id": "user_456"
}

搜索长期记忆

POST /v1/long-term-memory/search

请求体：

{
  "text": "用户界面偏好",
  "limit": 10,
  "offset": 0,
  "search_mode": "semantic",
  "filters": {
    "memory_type": { "eq": "semantic" },
    "topics": { "any": ["偏好"] }
  }
}

最佳实践

记忆组织策略

1. 合理划分主题：使用一致的标签体系组织记忆
2. 提取实体信息：将关键实体（人名、地点、事件）单独标记
3. 控制记忆粒度：避免过长的记忆，便于检索和去重
4. 定期去重维护：使用系统提供的去重功能合并相似记忆

搜索优化建议

去重功能

AMS 提供基于语义的自动去重功能，可合并哈希索引和向量索引中的重复记忆：

// 在工作台中点击 "Deduplicate" 按钮触发去重
{compactMutation.isPending ? (
  <Loader2 className="w-4 h-4 animate-spin" />
) : (
  <Merge className="w-4 h-4" />
)}
Deduplicate

资料来源：workbench/src/pages/ExplorerPage.tsx

相关资源

• SDK 安装指南
• 工作记忆管理
• 摘要视图
• API 参考文档

概述

Agent Memory Server 的搜索能力是系统的核心功能之一，支持对长期记忆（Long-Term Memory）进行多维度检索。该能力基于向量相似度搜索和关键词匹配的混合架构，为 AI Agent 提供语义级别的记忆检索能力。

搜索系统支持三种搜索模式：语义搜索（Semantic）、关键词搜索（Keyword） 和 混合搜索（Hybrid），用户可根据场景灵活选择。

搜索模式

语义搜索（Semantic Search）

语义搜索利用向量嵌入（Embeddings）技术，将文本转换为高维向量，通过计算向量间的余弦相似度（Cosine Similarity）来找到语义上最相关的记忆。

工作流程如下：

graph TD
    A[用户查询文本] --> B[嵌入模型转换]
    B --> C[生成向量表示]
    C --> D[向量相似度计算]
    D --> E[返回 Top-K 相似结果]

语义搜索特别适用于：

• 语义相似但词汇不同的查询
• 需要理解意图和上下文的场景
• 跨语言或同义词相关的搜索

关键词搜索（Keyword Search）

关键词搜索基于传统的全文匹配技术，直接在文本字段上进行模式匹配。该模式使用 Redis 的 FT.SEARCH 命令，支持 MATCH 查询语法。

关键词搜索适用于：

• 精确短语匹配
• 已知关键词的精确查找
• 需要排除特定词汇的场景

混合搜索（Hybrid Search）

混合搜索结合语义搜索和关键词搜索的优势，通过加权融合两种搜索结果来提供更全面的检索能力。

系统提供 hybridAlpha 参数控制两种模式的权重：

• hybridAlpha = 1.0：完全使用语义搜索
• hybridAlpha = 0.0：完全使用关键词搜索
• 0 < hybridAlpha < 1.0：按比例混合

搜索过滤器

搜索 API 支持丰富的过滤器，用于精确筛选目标记忆：

过滤器组合示例

const results = await client.searchLongTermMemory({
    text: "user preferences",
    searchMode: "hybrid",
    hybridAlpha: 0.7,
    filters: {
        sessionId: { eq: "my_session" },
        topics: { any: ["preferences", "settings"] },
        memoryType: { in_: ["semantic", "episodic"] },
        createdAt: { gte: "2024-01-01" }
    }
});

API 端点

REST API

MCP 工具

系统通过 MCP（Model Context Protocol）提供服务，搜索工具定义如下：

数据模型

搜索结果结构

interface SearchResults {
    memories: MemoryRecord[];  // 匹配的记录列表
    total: number;            // 符合条件的总数
    offset: number;           // 当前偏移
    limit: number;            // 每页限制
}

MemoryRecord 字段

分页与迭代

系统支持自动分页功能，客户端可以迭代获取所有匹配结果而无需手动管理偏移量。

Java 客户端自动分页

// 方式一：Stream 流式处理
Stream<MemoryRecord> stream = longTermMemoryService.searchAllLongTermMemoriesStream(
    "preferences", null, null, topics, null, null, 100
);
stream.forEach(memory -> process(memory));

// 方式二：Iterator 迭代
Iterator<MemoryRecord> iterator = longTermMemoryService.searchAllLongTermMemories(
    "preferences", null, null, topics, null, null, 100
);
while (iterator.hasNext()) {
    MemoryRecord memory = iterator.next();
    process(memory);
}

分页内部实现自动处理机制：

graph TD
    A[初始化 offset=0] --> B[获取当前批次]
    B --> C{有更多结果?}
    C -->|是| D[处理结果]
    D --> E[offset += batchSize]
    E --> B
    C -->|否| F[结束]

资料来源：LongTermMemoryService.java:82-120

Workbench 搜索界面

Agent Memory Workbench 提供可视化的搜索界面，位于 ExplorerPage 组件中。

搜索界面功能

• 搜索模式选择：支持 semantic、keyword、hybrid 三种模式切换
• 记忆类型过滤：可选择 semantic、episodic、message 或全部
• 结果数量限制：支持 10、25、50、100 多种限制选项
• 记忆详情查看：点击结果可查看完整记忆内容、主题、实体
• 批量去重：提供 Deduplicate 按钮，自动合并哈希和语义重复项
• 结果统计：显示当前页结果数和符合条件的总数

去重功能

去重（Deduplicate）功能通过 compact API 实现，自动识别并合并：

• 哈希去重：基于内容哈希值的精确重复检测
• 语义去重：基于向量相似度的语义近似合并

const compactMutation = useMutation({
    mutationFn: () => api.compactLongTermMemory(filters)
});

资料来源：ExplorerPage.tsx:1-100

性能优化

嵌入向量缓存

系统使用 Redis 作为向量存储后端，嵌入向量被缓存在内存中以提高检索性能。

向量索引配置

# memory_vector_db.py 中的索引配置
FT.CREATE index_name ON hash 
    PREFIX 1 "prefix:" 
    SCHEMA 
        text TEXT WEIGHT 1.0
        embedding VECTOR HNSW 6 DIM 1536 DISTANCE_METRIC COSINE

资料来源：memory_vector_db.py:1-50

批量写入优化

在创建记忆时，系统支持批量写入模式，减少网络往返次数：

# long_term_memory.py 中的批量处理
results = await asyncio.gather(*[
    self.create_long_term_memory(memory, ...) 
    for memory in memories
])

资料来源：long_term_memory.py:150-200

CLI 搜索命令

v0.14.0 版本新增了 CLI 搜索和删除命令：

# 搜索长期记忆
agent-memory search "user preferences" --limit 10

# 带过滤条件搜索
agent-memory search "preferences" --topic "settings" --session-id "my_session"

# 删除匹配的记录
agent-memory delete --session-id "old_session"

常见问题

Q: 语义搜索返回结果不准确？

确保嵌入模型配置正确，尝试调整 hybridAlpha 参数以混合关键词搜索结果。

Q: 如何搜索特定用户的所有记忆？

使用 userId 过滤器：

await client.searchLongTermMemory({
    text: "*",
    filters: { userId: { eq: "target_user_id" } }
});

Q: 去重功能是否会影响原始记忆？

去重是逻辑合并，原有记录会被标记或软删除，系统保留所有操作记录。

概述

MCP（Model Context Protocol，模型上下文协议）是一种标准化的通信协议，允许 AI 模型与外部工具和服务进行交互。Agent Memory Server 通过 MCP 协议暴露其核心功能，使 AI 代理（如 Claude Desktop）能够直接访问记忆系统的全部能力。

Agent Memory Server 的 MCP 集成提供：

• 标准化接口：通过 MCP JSON-RPC 协议提供统一的工具调用机制
• 双传输模式：支持 stdio（进程标准输入/输出）和 SSE（Server-Sent Events）两种传输方式
• 完整工具集：暴露搜索、创建、更新、删除等所有记忆操作工具
• 会话管理：支持多会话、多用户、多命名空间的记忆管理

资料来源：docs/mcp.md:1-20

架构设计

协议层次

graph TD
    A[MCP 客户端] -->|JSON-RPC 2.0| B[传输层]
    B --> C[MCP 服务端]
    C --> D[记忆服务]
    D --> E[Redis 数据库]
    
    F[stdio 模式] -.->|进程通信| B
    G[SSE 模式] -.->|HTTP/EventSource| B
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style E fill:#f3e5f5

SSE 传输模式工作流程

sequenceDiagram
    participant C as MCP 客户端
    participant S as MCP 服务端
    participant API as REST API
    
    C->>S: GET /sse
    S-->>C: EventSource 连接建立
    Note over C,S: 接收 endpoint 事件
    S-->>C: endpoint: /messages/{client_id}
    
    C->>S: POST /messages/{client_id}
    Note over S: JSON-RPC Request
    S->>API: 处理请求
    API-->>S: 响应数据
    S-->>C: SSE message 事件
    Note over C: JSON-RPC Response
    
    loop 持续通信
        C->>S: POST 请求
        S-->>C: SSE 响应
    end

资料来源：workbench/src/lib/mcp-client.ts:1-50

传输模式

Agent Memory Server 支持两种 MCP 传输模式，适用于不同的部署场景。

Stdio 模式

Stdio 模式通过进程标准输入/输出进行通信，是推荐的生产环境模式，特别适用于 Claude Desktop 集成。

# 启动 MCP 服务器（stdio 模式）
uv run agent-memory mcp

特点：

• 进程内通信，延迟最低
• 无需网络配置，安全性高
• 适合本地集成和桌面应用
• MCP 服务器作为子进程运行

资料来源：README.md:1-50

SSE 模式

SSE 模式基于 HTTP Server-Sent Events，适用于需要远程访问或 Web 前端集成的场景。

# 启动 MCP 服务器（SSE 模式）
uv run agent-memory mcp --mode sse --port 9000

SSE 客户端实现：

// workbench/src/lib/mcp-client.ts
export class McpSseClient {
  private eventSource: EventSource | null = null
  private postEndpoint: string | null = null
  private pending = new Map<
    number,
    { resolve: (v: unknown) => void; reject: (e: Error) => void }
  >()

  // GET /sse → 建立 EventSource 连接
  // POST <endpoint> → 发送 JSON-RPC 请求
  // SSE message 事件 → 接收 JSON-RPC 响应
}

特点：

• 基于 HTTP 长连接
• 支持浏览器环境运行
• 默认使用 asyncio 后端
• 适合开发和调试

资料来源：workbench/src/lib/mcp-client.ts:1-60

传输模式对比

MCP 客户端集成

Claude Desktop 配置

在 Claude Desktop 的 MCP 配置文件中添加以下配置：

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["agent-memory", "mcp"]
    }
  }
}

Web 前端集成

Workbench 应用使用 McpSseClient 类实现浏览器端的 MCP 通信：

import { McpSseClient, type McpStatus } from '@/lib/mcp-client'

// 创建客户端实例
const client = new McpSseClient('http://localhost:8000', (status: McpStatus) => {
  console.log('连接状态:', status)
})

// 监听连接状态变化
// 'disconnected' | 'connecting' | 'connected' | 'error'

资料来源：workbench/src/lib/mcp-client.ts:1-45

Python SDK 集成

Python 应用可以直接调用 MCP 服务器：

import subprocess

# 启动 MCP 服务器进程
process = subprocess.Popen(
    ["uv", "run", "agent-memory", "mcp"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE
)

# 通过标准输入/输出发送 JSON-RPC 请求

提供的工具

MCP 服务器暴露以下核心工具，涵盖记忆系统的全部操作。

搜索工具

记忆管理工具

工作记忆工具

上下文工具

资料来源：agent_memory_server/mcp.py:1-100

工具参数详解

search_long_term_memory 参数

update_working_memory 参数

get_memory_prompt 参数

interface MemoryPromptParams {
  query: string
  session?: {
    session_id: string
    namespace?: string
    user_id?: string
  }
  long_term_search?:
    | {
        text?: string
        namespace?: Filter
        limit?: number
      }
    | boolean
}

资料来源：workbench/src/context/BackendContext.tsx:1-80

配置选项

MCP 服务器配置

通过命令行参数或环境变量配置 MCP 服务器：

# 基本启动
uv run agent-memory mcp

# 指定模式和端口
uv run agent-memory mcp --mode sse --port 9000

# 指定主机地址
uv run agent-memory mcp --host 0.0.0.0 --port 8000

环境变量配置

MCP 配置参数

资料来源：agent_memory_server/cli.py:1-50

最佳实践

生产环境部署

1. 使用 Stdio 模式：在生产环境中优先使用 stdio 模式，避免网络开销和安全风险
2. 配置资源限制：为 MCP 进程设置合理的内存和 CPU 限制
3. 监控连接状态：实现连接状态监控，及时处理断连情况

开发调试

1. 启用 SSE 模式：开发时使用 SSE 模式便于调试和日志查看
2. 配置日志级别：设置详细的日志级别以便追踪请求流程
3. 使用 Workbench：利用 Workbench 界面的 MCP 客户端进行可视化调试

性能优化

1. 批量操作：使用 delete_memories 进行批量删除而非单条删除
2. 合理分页：对大结果集使用分页参数，避免内存溢出
3. 缓存热点数据：对频繁访问的会话使用短期缓存

故障排除

常见问题

调试模式

启用详细日志以便排查问题：

# 启动带调试日志的 MCP 服务器
RUST_LOG=debug uv run agent-memory mcp --mode sse

连接状态检查

// 检查 MCP 客户端连接状态
const status = client.status
// 'disconnected' | 'connecting' | 'connected' | 'error'

if (status === 'error') {
  console.error('MCP 连接错误，请检查服务器配置')
}

资料来源：workbench/src/lib/mcp-client.ts:30-40

相关资源

• MCP 协议规范
• Agent Memory Server 官方文档
• Workbench 应用
• Python 客户端 SDK

核心架构

graph TD
    A[Python 应用] --> B[agent_memory_client SDK]
    B --> C[REST API 调用]
    C --> D[Agent Memory Server]
    D --> E[Redis 数据库]
    
    F[LangChain/LangGraph] --> B
    
    B --> G[工作内存模块]
    B --> H[长时记忆模块]
    B --> I[工具发现模块]

安装与初始化

安装方式

# 通过 pip 安装
pip install agent-memory-client

# 或使用 uv
uv add agent-memory-client

创建客户端

import asyncio
from agent_memory_client import create_memory_client

async def main():
    # 方式一：基础连接
    client = await create_memory_client("http://localhost:8000")
    
    # 方式二：配置 API 密钥
    client = await create_memory_client(
        "http://localhost:8000",
        api_key="your-api-key"
    )
    
    # 方式三：配置默认模型
    client = await create_memory_client(
        "http://localhost:8000",
        default_model_name="gpt-4o",
        default_context_window_max=128000
    )
    
    # 使用完毕记得关闭
    await client.close()
    
asyncio.run(main())

客户端支持以下配置参数：

工作内存（Working Memory）

工作内存用于存储当前会话的上下文信息，支持消息历史、结构化数据和自动摘要功能。

创建或获取工作内存会话

# 获取或创建会话
created, working_memory = await client.get_or_create_working_memory(
    session_id="user-123-session",
    user_id="user-123",
    namespace="production"
)

if created:
    print("新会话已创建")

存储消息

from agent_memory_client.models import ClientMessage

# 添加消息到工作内存
working_memory = await client.put_working_memory_message(
    session_id="user-123-session",
    message=ClientMessage(
        role="user",
        content="我想要预订明天去纽约的机票"
    )
)

更新结构化数据

# 存储键值对数据
working_memory = await client.update_working_memory_data(
    session_id="user-123-session",
    data={
        "travel_date": "2024-03-15",
        "destination": "纽约",
        "trip_type": "单程"
    }
)

控制返回的消息数量

import httpx

# 仅返回最近 10 条消息
working_memory = await client.get_working_memory(
    session_id="user-123-session",
    params={"recent_messages_limit": 10}
)

工作内存数据模型

长时记忆（Long-term Memory）

长时记忆支持语义、关键词和混合搜索模式，提供持久化的知识存储能力。

创建记忆

from agent_memory_client.models import ClientMemoryRecord, MemoryTypeEnum

# 创建语义记忆
memories = [
    ClientMemoryRecord(
        text="用户偏好深色模式界面",
        memory_type=MemoryTypeEnum.SEMANTIC,
        topics=["偏好", "界面"]
    ),
    ClientMemoryRecord(
        text="用户于 2024-01-15 完成入职培训",
        memory_type=MemoryTypeEnum.EPISODIC,
        topics=["入职", "里程碑"]
    )
]

# 延迟创建（稍后提升到长时存储）
result = await client.create_long_term_memory(
    memories,
    user_id="user-123"
)

# 立即创建
result = await client.create_long_term_memory(
    memories,
    user_id="user-123",
    promotion="eager"
)

语义搜索

from agent_memory_client.models import SearchOptions, SearchMode

# 基础语义搜索
results = await client.search_long_term_memory(
    text="用户界面偏好",
    limit=10
)

# 高级搜索选项
results = await client.search_long_term_memory(
    text="项目更新",
    search_mode=SearchMode.HYBRID,
    hybrid_alpha=0.7,
    session_id="session-123",
    user_id="user-123",
    topics={"any": ["工作", "项目"]},
    memory_type={"eq": "semantic"},
    distance_threshold=0.8,
    limit=20
)

搜索模式说明

时效性感知搜索

from agent_memory_client.models import RecencyConfig

recency_config = RecencyConfig(
    recency_boost=True,
    semantic_weight=0.8,              # 语义相似度权重
    recency_weight=0.2,              # 时效性权重
    freshness_weight=0.6,            # 新鲜度权重
    novelty_weight=0.4,             # 稀缺性权重
    half_life_last_access_days=7,   # 访问时间衰减半衰期
    half_life_created_days=30,      # 创建时间衰减半衰期
    server_side_recency=True         # 启用服务端优化
)

results = await client.search_long_term_memory(
    text="项目更新",
    recency=recency_config,
    limit=10
)

编辑和删除记忆

# 编辑记忆
updated_memory = await client.edit_long_term_memory(
    memory_id="memory-uuid-123",
    text="更新后的记忆内容",
    topics=["新话题", "更新"]
)

# 删除记忆
await client.delete_long_term_memories(
    memory_ids=["memory-uuid-123", "memory-uuid-456"]
)

工具发现与调用

SDK 提供自动工具发现功能，可获取所有可用内存工具的 schema 定义。

获取所有工具 Schema

from agent_memory_client import get_all_memory_tool_schemas

# 获取所有工具的 schema
schemas = await get_all_memory_tool_schemas(
    memory_client=client,
    session_id="default-session",
    user_id="default-user"
)

for schema in schemas:
    print(f"工具: {schema.name}")
    print(f"描述: {schema.description}")

统一工具调用解析

# SDK 提供统一的工具调用解析接口
result = await client.resolve_tool_call(
    tool_name="search_long_term_memory",
    arguments={"text": "用户偏好", "limit": 5}
)

LangChain 集成

SDK 支持与 LangChain/LangGraph 无缝集成，自动将内存工具转换为 LangChain 兼容格式。

基础集成

from agent_memory_client import create_memory_client
from agent_memory_client.integrations.langchain import get_memory_tools
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

async def setup_agent():
    # 创建内存客户端
    memory_client = await create_memory_client("http://localhost:8000")
    
    # 获取 LangChain 兼容工具
    tools = get_memory_tools(
        memory_client=memory_client,
        session_id="my_session",
        user_id="alice"
    )
    
    # 创建 LangGraph agent
    llm = ChatOpenAI(model="gpt-4o")
    agent = create_agent(
        llm, tools,
        system_prompt="你是一个有帮助的助手，具有记忆功能。"
    )
    
    return agent

# 使用 agent
asyncio.run(setup_agent())

与 LangGraph 状态管理集成

from langgraph.checkpoint.memory import MemorySaver

# 使用 MemorySaver 实现多轮对话状态持久化
checkpointer = MemorySaver()
agent = create_agent(
    llm, tools,
    checkpointer=checkpointer
)

错误处理

SDK 定义了清晰的异常层次结构，便于针对性处理错误。

from agent_memory_client.exceptions import (
    MemoryClientError,
    MemoryValidationError,
    MemoryServerError
)

try:
    created, memory = await client.get_or_create_working_memory("my-session")
except MemoryValidationError as e:
    print(f"参数验证错误: {e}")
except MemoryServerError as e:
    print(f"服务端错误 {e.status_code}: {e}")
except MemoryClientError as e:
    print(f"客户端错误: {e}")

异常类型说明

上下文管理器用法

推荐使用上下文管理器自动处理连接关闭：

async with create_memory_client("http://localhost:8000") as client:
    working_memory = await client.get_or_create_working_memory("session-1")
    results = await client.search_long_term_memory(text="查询内容")
# 自动关闭连接

完整使用示例

import asyncio
from agent_memory_client import create_memory_client
from agent_memory_client.models import (
    ClientMemoryRecord,
    ClientMessage,
    MemoryTypeEnum
)

async def main():
    async with create_memory_client("http://localhost:8000") as client:
        # 1. 获取工作内存会话
        _, wm = await client.get_or_create_working_memory(
            session_id="travel-session",
            user_id="user-123"
        )
        
        # 2. 添加对话消息
        wm = await client.put_working_memory_message(
            session_id="travel-session",
            message=ClientMessage(
                role="user",
                content="我想去东京旅游"
            )
        )
        
        # 3. 存储偏好到长时记忆
        await client.create_long_term_memory(
            memories=[
                ClientMemoryRecord(
                    text="用户喜欢日本文化，计划去东京",
                    memory_type=MemoryTypeEnum.SEMANTIC,
                    topics=["旅行", "日本", "东京"]
                )
            ],
            user_id="user-123"
        )
        
        # 4. 搜索相关记忆
        results = await client.search_long_term_memory(
            text="日本旅行计划",
            user_id="user-123",
            limit=5
        )
        
        print(f"找到 {len(results.memories)} 条相关记忆")

asyncio.run(main())

常见问题

连接认证问题

确保设置正确的 API 密钥：

# 方式一：环境变量
# OPENAI_API_KEY=xxx python your_script.py

# 方式二：客户端参数
client = await create_memory_client(
    "http://localhost:8000",
    api_key="your-key"
)

性能优化建议

1. 使用上下文管理器：确保连接正确释放
2. 批量操作：多个记忆创建时考虑批量接口
3. 设置距离阈值：在搜索时设置 distance_threshold 减少返回量
4. 服务端时效性：启用 server_side_recency=True 优化时效性搜索性能

Pitfall Log / 踩坑日志

项目：redis/agent-memory-server

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -p 8000:8000 -e REDIS_URL=redis://your-redis:6379 -e OPENAI_API_KEY=your-key redislabs/agent-memory-server:latest agent-memory api
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 建议检查：标注 Docker 前置条件，并提供非 Docker 路径或失败提示。
• 复现命令：docker run -p 8000:8000 -e REDIS_URL=redis://your-redis:6379 -e OPENAI_API_KEY=your-key redislabs/agent-memory-server:latest agent-memory api
• 防护动作：Docker 前置条件未说明时，不把项目标成普通用户低门槛。
• 证据：identity.distribution | github_repo:948774854 | https://github.com/redis/agent-memory-server | docker run -p 8000:8000 -e REDIS_URL=redis://your-redis:6379 -e OPENAI_API_KEY=your-key redislabs/agent-memory-server:latest agent-memory api

2. 安装坑 · 来源证据：Switch examples from Redis Stack to Redis 8

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Switch examples from Redis Stack to Redis 8
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a01992ad9518466a818525b303de01aa | https://github.com/redis/agent-memory-server/issues/287 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:948774854 | https://github.com/redis/agent-memory-server | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:948774854 | https://github.com/redis/agent-memory-server | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:948774854 | https://github.com/redis/agent-memory-server | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:948774854 | https://github.com/redis/agent-memory-server | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:948774854 | https://github.com/redis/agent-memory-server | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:948774854 | https://github.com/redis/agent-memory-server | release_recency=unknown