Sample Amazon Bedrock Agentcore Memory MCP Server

使用Amazon Bedrock AgentCore内存扩展Kiro CLI中的会话内存

代理核心内存MCP服务器

一种模型上下文协议（MCP）服务器，它将Amazon Bedrock AgentCore Memory作为MCP服务器公开，可以与Kiro等任何其他MCP客户端集成，提供自动对话存储和检索。

它做什么

AgentCore内存MCP服务器将您的kiro-cli对话存储在Amazon Bedrock AgentCore内存中，提供跨会话的持久上下文。

先决条件

• 待更新
• Python 3.13或更高版本
• 具有Amazon Bedrock访问权限的AWS帐户
• 已配置有效的AWS凭据
• 已安装kiro-cli

快速启动

步骤1：安装依赖项

运行以下命令以创建虚拟环境并安装依赖项：

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip3 install -r requirements.txt

步骤2：创建AgentCore内存资源

运行安装脚本以创建内存资源：

MCP服务器支持灵活的参与者识别：

选项1：用户ID（默认）

• 集 ACTOR_ID_TYPE=userid 在代理/kiro_memory.json中
• 使用您的系统用户名 USER 环境变量
• 最适合个人使用

选项2：项目ID

• 集 ACTOR_ID_TYPE=projectid 在代理/kiro_memory.json中
• 集 PROJECT_ID=your-project-id 特工/kiro_memory.json
• 最适合基于团队/项目的内存隔离

使用的命名空间策略是： /strategy/semanticMemoryStrategy/actor/{actorId}/session/{sessionId}

python3 setup_bedrock_agentcore_memory.py

此交互式脚本将：

• 检查AWS凭据和权限
• 使用语义记忆策略创建AgentCore内存资源
• 配置参与者ID类型（用户ID或项目ID）
• 生成内存资源ID
• 测试连接
• 创建kiro代理配置

步骤3：配置kiro-cli

mkdir -p ~/.kiro/agents/
mkdir -p ~/.kiro/hooks/
cp -p agent/kiro_memory.json ~/.kiro/agents/
cp -p hooks/cache-prompt.sh ~/.kiro/hooks/
cp -p hooks/load-preferences.sh ~/.kiro/hooks/
cp -p hooks/store-conversation.sh ~/.kiro/hooks/
chmod 755 ~/.kiro/hooks/*

步骤4：将kiro_memory代理配置为默认代理

将以下内容添加到 cli.json 归档 ~/.kiro/settings/ 要使用的目录 kiro_memory 默认代理：

{"chat.defaultAgent": "kiro_memory"}

第五步：打开kiro cli

如果已经登录kiro-cli，请先注销并重新登录。

kiro-cli login --use-device-flow
kiro-cli --classic
/tools

配置示例

示例1：用户ID配置（个人使用）

{
  "mcpServers": {
    "agentcore-memory-mcp-server": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/bedrock_agentcore_memory_mcp_server.py"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AGENTCORE_MEMORY_ID": "your-memory-id",
        "ACTOR_ID_TYPE": "userid",
        "PROJECT_ID": "",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

示例2：项目ID配置（团队/项目使用）

{
  "mcpServers": {
    "agentcore-memory-mcp-server": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/bedrock_agentcore_memory_mcp_server.py"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AGENTCORE_MEMORY_ID": "your-memory-id",
       
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

可用工具

核心工具

• search_conversation_history - 主要工具 用于按主题或时间段搜索对话历史记录

- 直接搜索存储的会话事件 - 快速可靠-在存储后立即查找对话 - 返回完整上下文的完整对话回合 - 包含 context_summary 易于与kiro上下文整合的字段 - 多词搜索支持：搜索内容中存在的所有单词，无论顺序如何

• search_memories -通过处理后的长期记忆进行语义搜索

- 通过AWS retrieve_memory_records API使用语义/向量搜索进行概念匹配 - 通过语义策略处理的记忆进行搜索 - 包含 context_summary 具有相关性得分的字段 - 备注：存储对话和它们出现在语义搜索中之间可能存在延迟

• store_conversation -使用一致的会话ID存储对话

- 用途 MemoryClient.create_event() 触发语义记忆策略 - 自动生成每小时会话ID以保持一致性

• get_direct_conversation_history -访问特定会话的完整对话内容

• list_sessions -列出以前存储的会话

注： 所有工具支持可选 actor_id 参数。如果没有提供，actor_id将根据您的 ACTOR_ID_TYPE 配置。

诊断工具

• get_server_config -获取完整的MCP服务器配置，包括memory_id、region、actor_id和命名空间模式
• get_session_details -获取特定会话的详细信息，包括事件和提取的记忆

管理工具

• delete_session -删除特定会话及其所有事件

- 需要session_id参数 - 删除会话中的所有事件 - 无法撤消

• get_memory_stats -查看全面的内存使用统计数据

- 显示总会话、事件和长期记忆 - 显示最近会话的详细信息和事件计数 - 提供每个会话的平均事件数 - 用途 list_memory_records API可准确计数所有提取的内存 - 跨多个命名空间模式搜索以确保完全覆盖

• clear_all_data -清除演员的所有对话数据

- 破坏性操作 -要求 confirm=True 参数 - 删除参与者的所有会话和事件 - 无法撤消 - 注：语义策略提取的长期记忆保留在内存资源中

使用示例

搜索对话历史记录（主要工具）

这 search_conversation_history 该工具提供可靠的对话检索。结果包括a context_summary kiro可以用来理解之前讨论的字段：

搜索功能：

• 单字查询：搜索精确的子字符串匹配（例如，“lambda”）
• 多词查询：搜索内容中存在的所有单词，无论顺序如何（例如，“lambda python runtime”将匹配包含“lambda for python支持的运行时”的内容）
• 上下文集成：退货 context_summary 根据kiro的上下文提供完整的对话内容

# Find conversations about Lambda Python runtime
"search my conversation history about lambda python runtime"

# Find conversations about EMR
"search my conversation history about EMR"

# Get all recent conversations
"show me my recent conversation history"

# Search with custom timeframe
"search my conversations about serverless from the last 7 days"

搜索语义记忆

这 search_memories 工具通过语义处理的长期记忆进行搜索。结果包括a context_summary 相关性得分：

# Search for memories about Python
"search my long-term memory about Python functions"

# Search for memories about AWS services
"search my memory about AWS Lambda"

存储对话

可以通过指示kiro-cli手动存储对话：

"store this conversation in memory"

检查服务器配置

"show me the memory server configuration"

这将返回完整的配置，包括memory_id、region、actor_id和命名空间模式。

删除特定会话

"delete session cli_session_20260122_14 from memory"

这将删除指定会话中的所有事件。该操作无法撤消。

查看内存统计信息

"show me my memory usage statistics"

这将返回：

• 会话总数
• 事件总数（按每个会话中实际列出的事件计数）
• 长期记忆数量（使用 list_memory_records 跨多个名称空间模式的API）
• 每个会话的平均事件数
• 最近会议的详细信息及其事件计数

该工具现在通过以下方式提供准确的计数：

• 实际上列出每个会话中的事件，而不是信任缓存的计数
• 使用 list_memory_records API枚举所有提取的内存
• 在多个命名空间模式（参与者级别、会话级别）中搜索，以确保完全覆盖

检查特定会话

"get details for session cli_session_20260122_15"

这将返回：

• 会话中的事件数
• 每个事件的详细信息（消息、时间戳）
• 从本次会话中提取的长期记忆数量
• 实际内存内容
• 正在使用的确切命名空间

清除所有数据（小心使用！）

"clear all my conversation data from memory with confirmation"

警告：这是一次破坏性的行动：

• 删除actor_id的所有会话和事件
• 无法撤消
• 需要 confirm=True 要执行的参数
• 语义策略提取的长期记忆将保留，但会失去其源事件

主要特点

上下文集成

两者 search_conversation_history 和 search_memories 返回a context_summary 字段提供：

• 查看对话历史记录：完整的用户/助理消息交换
• 用于语义记忆：提取具有相关性得分的见解

这使得kiro能够理解之前的讨论，并自动根据历史背景采取行动。

多词搜索

搜索工具支持灵活的多词查询：

• 搜索内容中存在的所有单词，无论顺序如何
• 示例：“lambda python运行时”匹配包含“lambda for python支持的运行时”的内容

演员ID灵活性

所有工具支持可选 actor_id 参数：

• 如果未提供，则使用配置 ACTOR_ID_TYPE （用户ID或项目ID）
• 允许对特定用例进行覆盖
• 确保正确的命名空间隔离

许可证

此库根据MIT-0许可证获得许可。请参阅LICENSE文件。

故障排除

为什么不是 search_memories 找到我的对话？

语义记忆策略异步处理对话：

1. 存储: store_conversation 用途 MemoryClient.create_event() 存储并触发策略处理
2. 处理：语义策略提取对长期记忆的见解（可能需要几分钟）
3. 搜索: search_memories 使用AWS retrieve_memory_records 带有通配符命名空间匹配的API

如果记忆没有出现：

• 存储后等待几分钟，以便处理策略
• 使用 search_conversation_history 用于立即访问存储的对话
• 检查CloudWatch日志中的内存资源，以验证是否正在进行提取
• 验证命名空间模式是否匹配： /strategy/semanticMemoryStrategy/actor/{actorId}/*

内存隔离：

• search_memories 仅从配置的memory_id返回内存
• 结果的作用域为actor_id命名空间
• 通配符命名空间模式确保搜索所有会话

配置问题

如果找不到对话：

1. 使用检查您的actor_id配置 get_server_config
2. 验证 ACTOR_ID_TYPE 匹配您的设置（用户ID或项目ID）
3. 如果使用projectid，请确保 PROJECT_ID 设置正确
4. 重新启动kiro-cli以使用更新的环境变量重新加载MCP服务器

技术细节

存储方法

• 用途 MemoryClient.create_event() 而不是 session.add_turns()
• 更好地触发语义记忆策略以进行自动处理
• 为一致分组生成每小时会话ID

搜索实施

• 对话历史：通过AgentCore SDK直接搜索会话事件
• 语义记忆：AWS retrieve_memory_records 带有命名空间通配符的API
• 命名空间模式: /strategy/semanticMemoryStrategy/actor/{actorId}/*
• 上下文集成：两个工具都返回 context_summary 用于kiro的上下文窗口

演员ID解析

这 get_actor_id(actor_id_type) 函数确定actor_id：

• userid：用途 USER 环境变量（系统用户名）
• projectid：用途 PROJECT_ID 环境变量
• 所有工具均接受可选 actor_id 要覆盖的参数

安全

看 贡献 了解更多信息。

许可证

此库根据MIT-0许可证获得许可。请参阅LICENSE文件。