# https://github.com/redis/agent-memory-server 项目说明书

生成时间：2026-05-31 18:57:27 UTC

## 目录

- [项目概述](#page-overview)
- [快速开始](#page-quick-start)
- [社区重点问题](#page-community-issues)
- [系统架构](#page-architecture)
- [记忆生命周期](#page-memory-lifecycle)
- [工作记忆管理](#page-working-memory)
- [长期记忆与检索](#page-long-term-memory)
- [搜索能力](#page-search-capabilities)
- [MCP 协议集成](#page-mcp-integration)
- [Python SDK](#page-python-sdk)

<a id='page-overview'></a>

## 项目概述

### 相关页面

相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/redis/agent-memory-server/blob/main/README.md)
- [pyproject.toml](https://github.com/redis/agent-memory-server/blob/main/pyproject.toml)
- [agent-memory-client/README.md](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/README.md)
- [workbench/README.md](https://github.com/redis/agent-memory-server/blob/main/workbench/README.md)
- [examples/README.md](https://github.com/redis/agent-memory-server/blob/main/examples/README.md)
</details>

# 项目概述

## 项目简介

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

### 核心定位

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

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

资料来源：[README.md]()

## 技术架构

### 整体架构图

```mermaid
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
```

### 核心组件

| 组件 | 名称 | 描述 | 技术栈 |
|------|------|------|--------|
| Server | Agent Memory Server | 核心服务，提供 REST API 和后台任务处理 | Python (FastAPI) |
| Clients | 多语言客户端 | Python、JavaScript、Java 三种语言的 SDK | 各语言原生实现 |
| Workbench | AMS Workbench | 内存可视化与管理 Web UI | React + TypeScript |
| MCP Server | MCP 协议服务器 | 支持 Model Context Protocol 的工具调用 | Python |
| Storage | Redis | 底层数据存储，支持向量搜索 | Redis 8 |

资料来源：[workbench/README.md]()

### 部署架构

AMS 提供两种 Docker 部署模式：

```mermaid
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()` 获取相关上下文

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

资料来源：[agent-memory-client/README.md]()

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

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

| 记忆类型 | 说明 | 使用场景 |
|----------|------|----------|
| Semantic | 语义记忆 | 存储用户偏好、背景知识 |
| Episodic | 情景记忆 | 存储重要事件和里程碑 |
| Message | 消息记忆 | 归档重要对话片段 |

支持三种搜索模式：

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

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

### 3. MCP 集成

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

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

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

资料来源：[README.md]()

### 4. LangChain 集成

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

```python
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 矩阵

| 语言 | 包名 | 状态 | 主要功能 |
|------|------|------|----------|
| Python | agent-memory-client | 稳定 | 完整功能支持 |
| JavaScript | @redis/agent-memory-client-js | 稳定 | 完整功能支持 |
| Java | agent-memory-client-java | Beta | 核心功能支持 |

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

### 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")
    
    # 创建记忆
    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** - 当前最新稳定版本

安装方式：

```bash
# 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]()

### 版本演进要点

| 版本 | 主要变更 |
|------|----------|
| v0.15.x | 默认禁用摘要功能、修复 sorted set session 问题 |
| v0.14.x | 添加 CLI 搜索/删除命令、AMS Workbench 正式发布 |
| v0.13.x | 添加 per-task 超时、Summary Views 文档 |
| v0.12.x | LiteLLM 集成、LLM 提取主题/实体 |

资料来源：[Release Notes v0.12.0-v0.15.2]()

## 开发与贡献

### 环境准备

```bash
# 初始设置
make setup

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

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

### 开发栈启动

```bash
# 开发模式
docker compose up api redis

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

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

资料来源：[README.md]()

## 已知限制与社区议题

### 活跃社区议题

| 议题 | 描述 | 状态 |
|------|------|------|
| #287 | 示例从 Redis Stack 迁移到 Redis 8 | 待处理 |
| #139 | 考虑弃用 LangChain 向量搜索适配器 | 讨论中 |
| #193 | 无法真正禁用摘要功能 | 待处理 |
| #136 | 移除 GET working-memory 的空会话返回行为 | 计划中 |
| #105 | 统一 LLMClient 与 LiteLLM 集成 | 讨论中 |

资料来源：[Community Issues]()

### Redis 版本建议

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

资料来源：[Issue #287]()

## 许可证

Apache License 2.0 - 详见 [LICENSE](LICENSE) 文件

## 相关资源

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

---

<a id='page-quick-start'></a>

## 快速开始

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/redis/agent-memory-server/blob/main/README.md)
- [docker-compose.yml](https://github.com/redis/agent-memory-server/blob/main/docker-compose.yml)
- [Dockerfile](https://github.com/redis/agent-memory-server/blob/main/Dockerfile)
- [examples/README.md](https://github.com/redis/agent-memory-server/blob/main/examples/README.md)
- [agent-memory-client/README.md](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/README.md)
</details>

# 快速开始

本页面帮助开发者快速上手 Redis Agent Memory Server（AMS），涵盖环境准备、安装部署、基础配置及首个应用示例。

## 前置要求

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

| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| Python | ≥ 3.10 | 服务器和 Python 客户端需要 |
| Redis | 8.0+ | 使用 `redis:8` 镜像（包含所需模块） |
| Docker | Latest | 用于容器化部署 |
| OpenAI API Key | 有效密钥 | 用于 LLM 和 Embeddings 功能 |

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

## 安装方式

### 方式一：通过 PyPI 安装

```bash
pip install agent-memory-server==0.15.2
```

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

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

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

资料来源：[README.md:1-30]()

### 方式二：Docker 部署

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

```bash
# 启动 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）

```bash
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](https://github.com/redis/agent-memory-server/blob/main/docker-compose.yml)

## 本地开发环境

### 使用 Docker Compose 快速启动

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

```bash
# 克隆仓库
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]()

### 开发环境初始化

```bash
# 初始设置
make setup

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

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

> **注意**：`make verify` 需要设置 `OPENAI_API_KEY` 环境变量。资料来源：[README.md:25-35]()

## 基础使用示例

### Python 客户端

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

```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）

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

```python
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 工具的功能：

```python
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）提供另一种集成方式：

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

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

在 Claude Desktop 配置中使用：

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

资料来源：[README.md:80-100]()

## 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `OPENAI_API_KEY` | - | OpenAI API 密钥（必需） |
| `REDIS_URL` | `redis://localhost:6379` | Redis 连接地址 |
| `AMS_PORT` | `8000` | 服务监听端口 |
| `AMS_STANDALONE` | `false` | 是否启用独立模式 |
| `LOG_LEVEL` | `INFO` | 日志级别 |

## 下一步

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

## 常见问题

### 启动失败：Redis 连接错误

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

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

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

### Embedding 请求失败

确认 `OPENAI_API_KEY` 设置正确且有效：

```bash
export OPENAI_API_KEY=sk-...
```

### 端口冲突

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

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

---

<a id='page-community-issues'></a>

## 社区重点问题

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/redis/agent-memory-server/blob/main/README.md)
- [agent-memory-client/README.md](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/README.md)
- [workbench/README.md](https://github.com/redis/agent-memory-server/blob/main/workbench/README.md)
- [examples/README.md](https://github.com/redis/agent-memory-server/blob/main/examples/README.md)
- [workbench/src/pages/ExplorerPage.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ExplorerPage.tsx)
- [workbench/src/pages/ChatPage.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ChatPage.tsx)
</details>

# 社区重点问题

本文档整理了 Redis Agent Memory Server 项目中最受关注的社区问题，涵盖功能改进、行为变更和技术债务等关键议题。了解这些问题有助于开发者更好地理解项目发展方向和潜在的使用注意事项。

## 核心问题概览

| Issue 编号 | 标题 | 优先级 | 状态 |
|------------|------|--------|------|
| #139 | 考虑弃用 LangChain 向量搜索适配器 | 高 | 讨论中 |
| #287 | 将示例从 Redis Stack 迁移到 Redis 8 | 中 | 待处理 |
| #193 | 无法真正禁用摘要功能 | 中 | 待处理 |
| #136 | 移除 GET working-memory 中缺失时返回空会话的废弃行为 | 中 | 待处理 |
| #105 | 整合统一 LLMClient 与 LiteLLM | 中 | 讨论中 |

## LangChain 集成问题

### 问题背景

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

### 当前适配器局限性

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

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

资料来源：[agent-memory-client/README.md](agent-memory-client/README.md)

### 替代方案

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

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

```python
# 推荐方式：直接使用原生工具
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](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]()

### 迁移检查清单

| 组件类型 | 当前镜像 | 推荐镜像 | 状态 |
|----------|----------|----------|------|
| 开发环境 | redis-stack | redis:8 | 待更新 |
| 示例文档 | redis-stack | redis:8 | 待更新 |
| Docker Compose | redis-stack | redis:8 | 待更新 |

## 摘要功能控制

### 问题背景

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

### 当前实现逻辑

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

```python
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]()

### 配置建议

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

```python
# 通过环境变量或配置禁用摘要
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]()

### 当前行为

```json
// 现有会话不存在的响应
{
  "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 响应：

```json
{
  "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]()

### 预期改进

整合后的架构应实现：

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

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

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

## Workbench UI 问题

### UI 组件架构

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

| 页面 | 功能 | 路由 |
|------|------|------|
| ExplorerPage | 内存浏览与搜索 | `/` |
| ChatPage | 对话与交互 | `/chat` |

资料来源：[workbench/README.md](workbench/README.md)

### 搜索功能问题

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

- **语义搜索** (`semantic`)
- **关键词搜索** (`keyword`)
- **混合搜索** (`hybrid`)

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

资料来源：[workbench/src/pages/ExplorerPage.tsx](workbench/src/pages/ExplorerPage.tsx)

### 内存类型显示

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

| 内存类型 | 颜色 | CSS 类 |
|----------|------|--------|
| Semantic | 蓝色 | `badge-semantic` |
| Episodic | 绿色 | `badge-episodic` |
| Message | 紫色 | `badge-message` |

资料来源：[workbench/src/pages/ExplorerPage.tsx](workbench/src/pages/ExplorerPage.tsx)

## 客户端支持问题

### 多语言客户端

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

| 客户端 | 版本 | 状态 |
|--------|------|------|
| Python Client | 稳定 | 生产可用 |
| JavaScript Client | v0.3.1 | 生产可用 |
| Java Client | 0.1.0 | 早期版本 |

资料来源：[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 客户端提供了灵活的配置选项：

```typescript
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](agent-memory-client/agent-memory-client-js/src/client.ts)

## 长期规划问题

### 架构演进方向

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

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

### 迁移策略

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

| 时间范围 | 关注事项 |
|----------|----------|
| 短期 | Redis 8 迁移 |
| 中期 | API 行为变更（404 vs 空对象） |
| 长期 | LLM 客户端统一 |

## 参与社区

### 贡献指南

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

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

资料来源：[README.md](README.md)

### 本地开发

```bash
# 初始化设置
make setup

# 完整本地验证
make verify

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

资料来源：[README.md](README.md)

---

**最后更新**：本文档基于社区讨论和 Issue 追踪整理，详情请访问 [GitHub Issues](https://github.com/redis/agent-memory-server/issues)。

---

<a id='page-architecture'></a>

## 系统架构

### 相关页面

相关主题：[记忆生命周期](#page-memory-lifecycle), [项目概述](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent_memory_server/api.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/api.py)
- [agent_memory_server/mcp.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/mcp.py)
- [agent_memory_server/working_memory.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/working_memory.py)
- [agent_memory_server/long_term_memory.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/long_term_memory.py)
- [agent_memory_client/agent_memory_client/client.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_client/agent_memory_client/client.py)
- [agent_memory_client/agent_memory_client/integrations/langchain/__init__.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_client/agent_memory_client/integrations/langchain/__init__.py)
- [docker-compose.yml](https://github.com/redis/agent-memory-server/blob/main/docker-compose.yml)
</details>

# 系统架构

Agent Memory Server 是一个基于 Redis 的智能代理记忆系统，为 AI 代理提供持久化记忆能力。该系统采用分层架构设计，涵盖 API 服务、MCP 协议集成、记忆管理引擎和多语言客户端 SDK。

## 架构总览

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

```mermaid
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 接口供客户端访问。服务层负责请求验证、路由分发和响应格式化。

| 组件 | 功能 | 源码位置 |
|------|------|----------|
| FastAPI App | HTTP 服务入口 | `agent_memory_server/api.py` |
| Working Memory Routes | 工作记忆 CRUD 操作 | `agent_memory_server/working_memory.py` |
| Long Term Memory Routes | 长期记忆搜索与管理 | `agent_memory_server/long_term_memory.py` |
| Background Tasks | 异步任务处理 | Docket 任务队列 |

### MCP 协议层

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

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

```mermaid
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 服务启动命令：
```bash
# STDIO 模式（推荐用于 Claude Desktop）
uv run agent-memory mcp

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

### 记忆管理引擎

#### 工作记忆引擎

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

| 功能 | 描述 |
|------|------|
| 消息存储 | 支持 user/assistant/system 三种角色 |
| 自动摘要 | 消息超过阈值时触发摘要生成 |
| 记忆提取 | 从消息中提取实体和主题 |
| 会话管理 | 支持 TTL 和命名空间隔离 |

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

#### 长期记忆引擎

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

| 记忆类型 | 存储方式 | 搜索方式 |
|----------|----------|----------|
| Semantic | Redis Hash + Vector | 语义向量相似度 |
| Episodic | Redis Hash | 关键词/混合搜索 |
| Message | Redis Hash | 时间范围过滤 |

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

## 客户端架构

### 多语言 SDK 支持

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

```mermaid
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 无缝集成：

```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="session_123",
    user_id="user_456"
)

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

### LangChain 集成

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

```python
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 的多种数据结构实现高效记忆存储：

| 数据类型 | 用途 | Key Pattern |
|----------|------|-------------|
| Sorted Set | 工作记忆消息序列 | `wm:{session_id}:messages` |
| Hash | 记忆详情存储 | `ltm:{memory_id}` |
| Vector | 语义搜索向量 | `ltm:idx:vector` |
| Set | 实体/主题标签 | `ltm:{session_id}:entities` |
| Stream | 事件追踪 | `events:{namespace}` |

```mermaid
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）

```bash
docker compose up api redis
```

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

```bash
docker compose up api task-worker redis mcp
```

### 开发环境

```bash
# 初始设置
make setup

# 完整验证
make verify

# 启动开发栈
docker compose up api redis
```

| 环境 | 组件 |
|------|------|
| 开发环境 | api + redis |
| 生产环境 | api + task-worker + redis + mcp |

## 安全与配置

### 认证机制

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

| 参数 | 说明 |
|------|------|
| `apiKey` | API 密钥认证 |
| `bearerToken` | Bearer Token 认证 |
| `OPENAI_API_KEY` | LLM 服务认证（环境变量） |

### 配置参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `defaultModelName` | gpt-4o | 默认模型名称 |
| `defaultContextWindowMax` | 128000 | 默认上下文窗口大小 |
| `extractionDebounceTTL` | 30 | 记忆提取防抖 TTL |

资料来源：[agent_memory_client/agent_memory_client/client.ts:30-50]()

## 社区相关议题

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

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

## 技术栈总结

| 层级 | 技术选型 |
|------|----------|
| API 框架 | FastAPI |
| 数据存储 | Redis 8 |
| 异步任务 | Docket |
| 协议接口 | REST + MCP |
| 客户端 SDK | Python / JavaScript / Java |
| AI 集成 | OpenAI / Anthropic / Bedrock |

---

<a id='page-memory-lifecycle'></a>

## 记忆生命周期

### 相关页面

相关主题：[工作记忆管理](#page-working-memory), [长期记忆与检索](#page-long-term-memory), [系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent-memory-client/README.md](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/README.md)
- [agent-memory-client/agent-memory-client-js/src/client.ts](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-js/src/client.ts)
- [agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/workingmemory/WorkingMemory.java](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/workingmemory/WorkingMemory.java)
- [agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java)
- [workbench/src/pages/ExplorerPage.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ExplorerPage.tsx)
- [workbench/src/context/BackendContext.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/context/BackendContext.tsx)
</details>

# 记忆生命周期

Agent Memory Server (AMS) 的记忆生命周期涵盖了从消息输入到长期记忆存储的完整数据流转过程。本页面详细说明记忆的创建、存储、检索、自动提取、摘要生成以及最终归档的各个阶段。

## 概述

AMS 采用双层记忆架构：

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

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

## 记忆类型

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

| 记忆类型 | 英文标识 | 说明 | 典型用途 |
|---------|---------|------|---------|
| 语义记忆 | `semantic` | 通过向量嵌入存储的语义相关内容 | 存储事实、偏好、概念 |
| 情景记忆 | `episodic` | 记录事件和经历的时序记忆 | 存储会话历史、重要事件 |
| 消息记忆 | `message` | 直接存储的原始对话消息 | 存储用户/助手对话记录 |

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

## 工作记忆生命周期

### 创建与更新流程

```mermaid
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` 是核心数据结构，包含以下关键字段：

```java
// 资料来源：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;                   // 最后访问时间
}
```

### 消息结构

```java
// 资料来源：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. **实体识别**：自动识别并标记消息中的实体信息

### 提取配置

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `extraction_debounce_ttl` | 提取去重 TTL（秒） | 10 |
| `semantic_dedup_enabled` | 启用语义去重 | true |

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

## 摘要功能

### 工作原理

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

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

### 版本变化说明

| 版本 | 变更内容 |
|-----|---------|
| v0.15.0 之前 | 摘要功能默认启用，无法完全禁用 |
| v0.15.0 | 摘要功能默认禁用，提供更清晰的配置选项 |

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

资料来源：[社区 Issue #193](https://github.com/redis/agent-memory-server/issues/193)

## 长期记忆管理

### 持久化策略

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

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

### 搜索选项

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

| 参数 | 类型 | 说明 |
|-----|------|------|
| `text` | string | 搜索查询文本 |
| `searchMode` | enum | `semantic`、`keyword`、`hybrid` |
| `hybridAlpha` | float | 混合搜索权重 |
| `sessionId` | string/Filter | 按会话筛选 |
| `topics` | string[]/Filter | 按主题筛选 |
| `entities` | string[]/Filter | 按实体筛选 |
| `createdAt` | datetime/Filter | 按创建时间筛选 |
| `memoryType` | enum | `semantic`、`episodic`、`message` |

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

### 自动分页搜索

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

```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()` 功能，用于在生成响应时检索相关记忆：

```python
# 资料来源：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}
)
# 返回相关消息和长期记忆
```

### 上下文注入流程

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

### 工作台可视化

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

```tsx
// 资料来源：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>
)}
```

## 配置与管理

### 核心配置选项

| 配置项 | 环境变量 | 说明 |
|-------|---------|------|
| 记忆服务器 URL | `MEMORY_SERVER_URL` | 默认 `http://localhost:8000` |
| API 密钥 | `OPENAI_API_KEY` | LLM 调用认证 |
| 提取去重 TTL | `EXTRACTION_DEBOUNCE_TTL` | 控制提取频率 |
| 摘要阈值 | `SUMMARIZATION_THRESHOLD` | 触发摘要的令牌比例 |

### API 端点

| 方法 | 端点 | 功能 |
|-----|------|------|
| PUT | `/v1/working-memory/{session_id}` | 创建/更新工作记忆 |
| GET | `/v1/working-memory/{session_id}` | 获取工作记忆 |
| POST | `/v1/memory/search` | 搜索长期记忆 |
| POST | `/v1/memory` | 创建长期记忆 |
| DELETE | `/v1/memory/{id}` | 删除记忆 |
| GET | `/v1/memory-prompt` | 获取记忆上下文 |

## 常见问题

### 1. 记忆未正确提取

**可能原因**：
- 语义去重过滤了相似内容
- 提取 debounce 期间请求被合并

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

### 2. 摘要功能异常

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

### 3. 会话 404 问题

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

资料来源：[社区 Issue #136](https://github.com/redis/agent-memory-server/issues/136)

## 最佳实践

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

## 相关资源

- [API 文档](../api-reference)
- [客户端 SDK](../sdks)
- [Workbench 使用指南](../workbench)
- [示例代码](../examples)

---

<a id='page-working-memory'></a>

## 工作记忆管理

### 相关页面

相关主题：[长期记忆与检索](#page-long-term-memory), [记忆生命周期](#page-memory-lifecycle)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent_memory_server/working_memory.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/working_memory.py)
- [agent_memory_server/models.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/models.py)
- [workbench/src/pages/ChatPage.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ChatPage.tsx)
- [agent-memory-client/agent-memory-client-js/src/client.ts](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-js/src/client.ts)
- [agent-memory-client/agent-memory-client-java/.../WorkingMemory.java](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/workingmemory/WorkingMemory.java)
- [agent-memory-client/agent-memory-client-java/.../MemoryMessage.java](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/workingmemory/MemoryMessage.java)
</details>

# 工作记忆管理

工作记忆（Working Memory）是 Agent Memory Server 的核心功能模块，用于在单个对话会话期间存储和管理用户与 AI 之间的交互数据。与长期记忆不同，工作记忆专注于会话内的即时上下文，使 AI 代理能够保持对话连贯性并基于当前会话状态进行响应。

## 核心概念

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

| 组件 | 类型 | 说明 |
|------|------|------|
| `session_id` | String | 会话唯一标识符 |
| `user_id` | String | 关联的用户标识 |
| `namespace` | String | 命名空间，用于多租户隔离 |
| `messages` | List[MemoryMessage] | 对话消息列表 |
| `memories` | List[MemoryRecord] | 已提取的语义记忆 |
| `data` | Map | 自定义上下文数据 |
| `context` | String | 聚合的上下文摘要 |
| `tokens` | Integer | 当前 token 计数 |

资料来源：[WorkingMemory.java:15-35]()

## 数据模型

### MemoryMessage

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

```java
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 结构

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

```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;
    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}

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

| 参数 | 类型 | 位置 | 说明 |
|------|------|------|------|
| `session_id` | String | Path | 会话唯一标识符 |
| `user_id` | String | Query | 用户标识（可选） |
| `namespace` | String | Query | 命名空间（可选） |

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

### PUT /v1/working-memory/{session_id}

创建或更新工作记忆：

| 参数 | 类型 | 位置 | 说明 |
|------|------|------|------|
| `session_id` | String | Path | 会话唯一标识符 |
| `messages` | Array | Body | 消息列表 |
| `data` | Object | Body | 自定义上下文数据 |
| `ttl_seconds` | Integer | Body | 会话过期时间（秒） |

资料来源：[agent_memory_server/models.py]()

## 核心功能

### 自动摘要

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

```python
token_threshold = int(max_tokens * threshold_ratio)
```

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

### 语义去重

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

### 长时记忆策略

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

```java
MemoryStrategyConfig longTermMemoryStrategy = new MemoryStrategyConfig();
```

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

### 消息处理流程

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

## 客户端集成

### Python 客户端

```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 客户端

```typescript
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 客户端

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

资料来源：[WorkingMemory.java:50-70]()

## 工作台集成

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

### 聊天页面

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

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

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

资料来源：[workbench/src/pages/ChatPage.tsx]()

### 探索页面

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

| 过滤条件 | 选项 |
|----------|------|
| 搜索模式 | semantic / keyword / hybrid |
| 记忆类型 | semantic / episodic / message |
| 时间范围 | 创建时间、最后访问时间 |

资料来源：[workbench/src/pages/ExplorerPage.tsx]()

## 社区相关问题

### 摘要功能控制

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

### 会话缺失行为

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

## 配置选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `default_model_name` | gpt-4o | 默认 LLM 模型 |
| `default_context_window_max` | 128000 | 最大上下文窗口 |
| `extraction_debounce_ttl` | 60 | 提取防抖 TTL（秒） |
| `token_threshold_ratio` | 0.8 | 摘要触发阈值比例 |

## 最佳实践

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

---

<a id='page-long-term-memory'></a>

## 长期记忆与检索

### 相关页面

相关主题：[搜索能力](#page-search-capabilities), [工作记忆管理](#page-working-memory)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent_memory_server/long_term_memory.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/long_term_memory.py)
- [agent_memory_server/filters.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/filters.py)
- [agent-memory-client/agent_memory_client/client.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/client.py)
- [agent-memory-client/agent_memory_client/models.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/models.py)
- [agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java)
- [workbench/src/pages/ExplorerPage.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ExplorerPage.tsx)
- [examples/README.md](https://github.com/redis/agent-memory-server/blob/main/examples/README.md)
</details>

# 长期记忆与检索

## 概述

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

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

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

资料来源：[examples/README.md]()

## 架构设计

### 记忆类型体系

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

| 记忆类型 | 说明 | 典型用途 |
|---------|------|---------|
| `semantic` | 语义记忆 | 存储事实、偏好、概念性知识 |
| `episodic` | 情景记忆 | 存储事件、经历、时间序列数据 |
| `message` | 消息记忆 | 存储对话消息及其元数据 |

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

### 搜索流程架构

```mermaid
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 客户端提供同步和异步两种接口访问长期记忆服务。

#### 创建长期记忆

```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]()

#### 搜索长期记忆

```python
# 搜索相关记忆
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 客户端提供类型安全的长期记忆服务接口。

#### 长期记忆服务

```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 客户端支持流式搜索，适合处理大量结果：

```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` 参数指定：

| 模式 | 说明 | 适用场景 |
|------|------|---------|
| `semantic` | 向量相似度搜索 | 语义理解、概念匹配 |
| `keyword` | 关键词全文搜索 | 精确词匹配、术语查找 |
| `hybrid` | 语义+关键词混合 | 平衡精确性和相关性 |

### 高级过滤选项

```typescript
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]()

### 过滤条件组合

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

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `eq` | 等于 | `sessionId: { eq: "session_123" }` |
| `in_` | 包含于 | `sessionId: { in_: ["a", "b"] }` |
| `not_eq` | 不等于 | `userId: { not_eq: "admin" }` |
| `not_in` | 不包含于 | `namespace: { not_in: ["test"] }` |
| `any` | 任意匹配 | `topics: { any: ["A", "B"] }` |
| `all` | 全部匹配 | `topics: { all: ["A", "B"] }` |
| `none` | 都不匹配 | `entities: { none: ["X"] }` |
| `gte/lte` | 范围比较 | `createdAt: { gte: "2024-01-01" }` |

## 工作台界面

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

### 记忆浏览器

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

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

### 记忆详情面板

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

### 搜索结果展示

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

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

```typescript
{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
```

**请求体**：

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

### 搜索长期记忆

```
POST /v1/long-term-memory/search
```

**请求体**：

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

## 最佳实践

### 记忆组织策略

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

### 搜索优化建议

| 场景 | 推荐配置 |
|------|---------|
| 精确事实检索 | `searchMode: "keyword"` |
| 概念理解检索 | `searchMode: "semantic"` |
| 平衡精确与语义 | `searchMode: "hybrid"`, `hybridAlpha: 0.5` |
| 限制结果数量 | 配合 `limit` 参数避免返回过多结果 |
| 分页加载 | 使用 `offset` 参数进行分页 |

### 去重功能

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

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

资料来源：[workbench/src/pages/ExplorerPage.tsx]()

## 相关资源

- [SDK 安装指南](../getting-started/installation.md)
- [工作记忆管理](./working-memory.md)
- [摘要视图](./summary-views.md)
- [API 参考文档](../api/reference.md)

---

<a id='page-search-capabilities'></a>

## 搜索能力

### 相关页面

相关主题：[长期记忆与检索](#page-long-term-memory)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent_memory_server/long_term_memory.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/long_term_memory.py)
- [agent_memory_server/memory_vector_db.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/memory_vector_db.py)
- [agent_memory_server/llm/embeddings.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/llm/embeddings.py)
- [agent_memory_client/agent-memory-client-js/src/client.ts](https://github.com/redis/agent-memory-server/blob/main/agent_memory_client/agent-memory-client-js/src/client.ts)
- [agent_memory_client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java](https://github.com/redis/agent-memory-server/blob/main/agent_memory_client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java)
- [workbench/src/pages/ExplorerPage.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ExplorerPage.tsx)
</details>

# 搜索能力

## 概述

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

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

## 搜索模式

### 语义搜索（Semantic Search）

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

工作流程如下：

```mermaid
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 支持丰富的过滤器，用于精确筛选目标记忆：

| 过滤器 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| `sessionId` | string \| object | 按会话 ID 过滤 | `{ eq: "session_123" }` 或 `{ in_: ["s1", "s2"] }` |
| `namespace` | string \| object | 按命名空间过滤 | `{ eq: "prod" }` |
| `topics` | array \| object | 按主题过滤 | `{ any: ["ai", "ml"] }` |
| `entities` | array \| object | 按实体过滤 | `{ all: ["Alice", "Bob"] }` |
| `memoryType` | string \| object | 按记忆类型过滤 | `{ eq: "semantic" }` |
| `createdAt` | datetime \| object | 按创建时间过滤 | `{ gte: "2024-01-01", lte: "2024-12-31" }` |
| `lastAccessed` | datetime \| object | 按最后访问时间过滤 | `{ gte: "2024-06-01" }` |
| `userId` | string \| object | 按用户 ID 过滤 | `{ eq: "user_456" }` |

### 过滤器组合示例

```javascript
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

| 方法 | 端点 | 说明 |
|------|------|------|
| `POST` | `/v1/search/long-term-memory` | 搜索长期记忆 |
| `DELETE` | `/v1/search/long-term-memory` | 删除匹配的长期记忆 |

### MCP 工具

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

| 工具名称 | 参数 | 说明 |
|----------|------|------|
| `search_long_term_memory` | text, filters | 执行记忆搜索 |
| `delete_long_term_memory` | filter | 删除匹配的记录 |

## 数据模型

### 搜索结果结构

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

### MemoryRecord 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 记忆唯一标识符 |
| `text` | string | 记忆内容文本 |
| `memory_type` | string | 记忆类型（semantic/episodic/message） |
| `topics` | string[] | 主题标签 |
| `entities` | string[] | 提取的实体 |
| `created_at` | datetime | 创建时间 |
| `last_accessed` | datetime | 最后访问时间 |
| `access_count` | number | 访问次数 |
| `pinned` | boolean | 是否置顶 |
| `dist` | float | 向量距离（语义搜索） |
| `score` | float | 搜索得分 |

## 分页与迭代

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

### Java 客户端自动分页

```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);
}
```

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

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

资料来源：[LongTermMemoryService.java:82-120](https://github.com/redis/agent-memory-server/blob/main/agent_memory_client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java)

## Workbench 搜索界面

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

### 搜索界面功能

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

### 去重功能

去重（Deduplicate）功能通过 `compact` API 实现，自动识别并合并：
- **哈希去重**：基于内容哈希值的精确重复检测
- **语义去重**：基于向量相似度的语义近似合并

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

资料来源：[ExplorerPage.tsx:1-100](https://github.com/redis/agent-memory-server/blob/main/workbench/src/pages/ExplorerPage.tsx)

## 性能优化

### 嵌入向量缓存

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

### 向量索引配置

```python
# 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](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/memory_vector_db.py)

### 批量写入优化

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

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

资料来源：[long_term_memory.py:150-200](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/long_term_memory.py)

## CLI 搜索命令

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

```bash
# 搜索长期记忆
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` 过滤器：

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

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

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

---

<a id='page-mcp-integration'></a>

## MCP 协议集成

### 相关页面

相关主题：[项目概述](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent_memory_server/mcp.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/mcp.py)
- [docs/mcp.md](https://github.com/redis/agent-memory-server/blob/main/docs/mcp.md)
- [agent_memory_server/cli.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/cli.py)
- [workbench/src/lib/mcp-client.ts](https://github.com/redis/agent-memory-server/blob/main/workbench/src/lib/mcp-client.ts)
- [workbench/src/context/BackendContext.tsx](https://github.com/redis/agent-memory-server/blob/main/workbench/src/context/BackendContext.tsx)
</details>

# MCP 协议集成

## 概述

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]()

## 架构设计

### 协议层次

```mermaid
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 传输模式工作流程

```mermaid
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 集成。

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

**特点**：

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

资料来源：[README.md:1-50]()

### SSE 模式

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

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

**SSE 客户端实现**：

```typescript
// 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]()

### 传输模式对比

| 特性 | Stdio 模式 | SSE 模式 |
|------|-----------|----------|
| 传输方式 | 进程标准输入/输出 | HTTP Server-Sent Events |
| 推荐场景 | Claude Desktop、生产环境 | Web 前端、远程访问 |
| 延迟 | 最低 | 低 |
| 网络依赖 | 无需 | 需要网络连接 |
| 配置复杂度 | 简单 | 中等 |
| 浏览器支持 | 不支持 | 支持 |

## MCP 客户端集成

### Claude Desktop 配置

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

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

### Web 前端集成

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

```typescript
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 服务器：

```python
import subprocess

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

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

## 提供的工具

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

### 搜索工具

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `search_long_term_memory` | 搜索长期记忆 | `text`, `session_id`, `namespace`, `limit` |
| `search_semantic` | 语义搜索 | `text`, `filters`, `limit` |
| `search_keyword` | 关键词搜索 | `text`, `filters`, `limit` |
| `search_hybrid` | 混合搜索 | `text`, `alpha`, `filters`, `limit` |

### 记忆管理工具

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `create_long_term_memory` | 创建长期记忆 | `text`, `memory_type`, `topics`, `entities` |
| `update_long_term_memory` | 更新记忆内容 | `id`, `text`, `topics`, `entities` |
| `delete_long_term_memory` | 删除记忆 | `id` |
| `delete_memories` | 批量删除 | `ids[]` |
| `compact_memories` | 记忆去重合并 | `namespace`, `user_id` |

### 工作记忆工具

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `get_working_memory` | 获取工作记忆 | `session_id`, `user_id`, `namespace` |
| `update_working_memory` | 更新工作记忆 | `session_id`, `messages`, `user_id` |
| `delete_working_memory` | 删除工作记忆 | `session_id` |

### 上下文工具

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `get_memory_prompt` | 获取记忆提示 | `query`, `session`, `long_term_search` |
| `health` | 健康检查 | 无 |

资料来源：[agent_memory_server/mcp.py:1-100]()

## 工具参数详解

### search_long_term_memory 参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| `text` | string | 是 | 搜索查询文本 |
| `session_id` | string | 否 | 按会话 ID 过滤 |
| `namespace` | string | 否 | 命名空间过滤 |
| `user_id` | string | 否 | 用户 ID 过滤 |
| `topics` | string[] | 否 | 主题过滤 |
| `entities` | string[] | 否 | 实体过滤 |
| `limit` | integer | 否 | 返回结果数量限制 |
| `offset` | integer | 否 | 分页偏移量 |
| `search_mode` | string | 否 | 搜索模式：`semantic`、`keyword`、`hybrid` |

### update_working_memory 参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| `session_id` | string | 是 | 会话标识符 |
| `messages` | array | 是 | 消息列表 |
| `messages[].role` | string | 是 | 角色：`user` 或 `assistant` |
| `messages[].content` | string | 是 | 消息内容 |
| `user_id` | string | 否 | 用户标识符 |
| `namespace` | string | 否 | 命名空间 |
| `summarize` | boolean | 否 | 是否启用自动摘要（默认关闭） |

### get_memory_prompt 参数

```typescript
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 服务器：

```bash
# 基本启动
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
```

### 环境变量配置

| 变量名 | 描述 | 默认值 |
|-------|------|--------|
| `MEMORY_SERVER_URL` | 记忆服务器地址 | `http://localhost:8000` |
| `REDIS_URL` | Redis 连接地址 | `redis://localhost:6379` |
| `OPENAI_API_KEY` | OpenAI API 密钥 | - |

### MCP 配置参数

| 参数 | 描述 | 可选值 | 默认值 |
|------|------|--------|--------|
| `--mode` | 传输模式 | `stdio`, `sse` | `stdio` |
| `--port` | SSE 模式端口 | 1024-65535 | 8000 |
| `--host` | 监听主机地址 | - | `127.0.0.1` |

资料来源：[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. **缓存热点数据**：对频繁访问的会话使用短期缓存

## 故障排除

### 常见问题

| 问题 | 可能原因 | 解决方案 |
|------|---------|----------|
| 连接超时 | 服务器未启动或端口被占用 | 检查服务状态，确认端口可用 |
| 认证失败 | API 密钥配置错误 | 验证 `OPENAI_API_KEY` 环境变量 |
| 工具调用失败 | 参数格式错误 | 检查 JSON-RPC 请求格式 |
| SSE 连接断开 | 网络不稳定或超时 | 实现自动重连机制 |

### 调试模式

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

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

### 连接状态检查

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

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

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

## 相关资源

- [MCP 协议规范](https://modelcontextprotocol.io/)
- [Agent Memory Server 官方文档](https://github.com/redis/agent-memory-server)
- [Workbench 应用](../workbench/README.md)
- [Python 客户端 SDK](../agent-memory-client/README.md)

---

<a id='page-python-sdk'></a>

## Python SDK

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agent-memory-client/agent_memory_client/client.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/client.py)
- [agent-memory-client/agent_memory_client/__init__.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/__init__.py)
- [agent-memory-client/agent_memory_client/models/__init__.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/models/__init__.py)
- [agent-memory-client/agent_memory_client/integrations/langchain/__init__.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/integrations/langchain/__init__.py)
- [agent-memory-client/agent_memory_client/exceptions.py](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/agent_memory_client/exceptions.py)
- [agent-memory-client/README.md](https://github.com/redis/agent-memory-server/blob/main/agent-memory-client/README.md)
</details>

# Python SDK

Python SDK (`agent_memory_client`) 是 Agent Memory Server 的官方 Python 客户端库，提供对工作内存（Working Memory）和长时记忆（Long-term Memory）的便捷访问能力。该 SDK 封装了 REST API 调用，支持与 LangChain、LangGraph 等主流 AI 框架无缝集成。

## 核心架构

```mermaid
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[工具发现模块]
```

## 安装与初始化

### 安装方式

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

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

### 创建客户端

```python
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())
```

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

| 参数 | 类型 | 说明 |
|------|------|------|
| `url` | `str` | 服务器地址（必需） |
| `api_key` | `str` | API 认证密钥 |
| `default_model_name` | `str` | 自动摘要默认模型 |
| `default_context_window_max` | `int` | 默认上下文窗口大小 |
| `fetch` | `Callable` | 自定义 fetch 函数 |

## 工作内存（Working Memory）

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

### 创建或获取工作内存会话

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

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

### 存储消息

```python
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="我想要预订明天去纽约的机票"
    )
)
```

### 更新结构化数据

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

### 控制返回的消息数量

```python
import httpx

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

### 工作内存数据模型

| 字段 | 类型 | 说明 |
|------|------|------|
| `session_id` | `str` | 会话唯一标识 |
| `user_id` | `str` | 用户标识 |
| `namespace` | `str` | 命名空间 |
| `messages` | `List[MemoryMessage]` | 消息列表 |
| `memories` | `List[MemoryRecord]` | 记忆记录 |
| `data` | `Dict` | 结构化数据 |
| `context` | `str` | 上下文摘要 |
| `tokens` | `int` | 当前 token 数量 |
| `new_session` | `bool` | 是否为新建会话 |
| `last_accessed` | `datetime` | 最后访问时间 |

## 长时记忆（Long-term Memory）

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

### 创建记忆

```python
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"
)
```

### 语义搜索

```python
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
)
```

### 搜索模式说明

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `semantic` | 向量相似度搜索 | 语义理解、概念匹配 |
| `keyword` | 关键词匹配搜索 | 精确术语查找 |
| `hybrid` | 语义+关键词混合 | 平衡精确性与相关性 |

### 时效性感知搜索

```python
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
)
```

### 编辑和删除记忆

```python
# 编辑记忆
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

```python
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}")
```

### 统一工具调用解析

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

## LangChain 集成

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

### 基础集成

```python
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 状态管理集成

```python
from langgraph.checkpoint.memory import MemorySaver

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

## 错误处理

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

```python
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}")
```

### 异常类型说明

| 异常类型 | 说明 |
|----------|------|
| `MemoryClientError` | 基础客户端异常 |
| `MemoryValidationError` | 参数验证失败 |
| `MemoryServerError` | 服务端返回错误 |

## 上下文管理器用法

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

```python
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="查询内容")
# 自动关闭连接
```

## 完整使用示例

```python
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 密钥：

```python
# 方式一：环境变量
# 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` 优化时效性搜索性能

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: redis/agent-memory-server; human_manual_source: deepwiki_human_wiki -->