MemoriLabs/Memori 是一个专门为 AI 智能体设计的记忆基础设施项目。它提供了一个 LLM 无关的中间层能够将智能体执行和对话转化为结构化的持久状态。这个开源项目在 GitHub 上已经获得了超过 15.6k 的星标显示出其在开发者社区中的高度关注度。Memori 的核心价值在于解决智能体在多次会话间的记忆丢失问题。传统的 AI 智能体往往在会话结束后就忘记之前的交互内容而 Memori 通过结构化的记忆管理让智能体能够持久保存和回忆关键信息。这对于构建生产级的 AI 应用至关重要特别是需要长期上下文记忆的对话系统和任务型智能体。1. 核心能力速览能力项说明项目类型AI 智能体记忆基础设施开源团队MemoriLabs主要功能结构化记忆管理、会话持久化、智能体记忆增强部署方式云服务、本地部署、混合部署支持平台托管云、单租户云、VPC、本地环境启动方式API 服务、SDK 集成、插件模式是否支持 API是提供完整的 REST API是否支持批量任务是支持批量记忆操作适合场景企业级 AI 应用、长期对话系统、任务型智能体Memori 的设计理念是从智能体行为中提取记忆而不仅仅是对话内容。这意味着它不仅记录对话历史还会捕捉工具调用、决策过程和执行结果等结构化信息为智能体提供更丰富的上下文记忆。2. 适用场景与使用边界Memori 特别适合需要长期记忆能力的 AI 应用场景。在客服对话系统中Memori 可以帮助智能体记住用户的偏好和历史问题提供更个性化的服务。对于任务型智能体它能够保存任务执行状态和中间结果确保复杂任务能够跨会话持续进行。在企业环境中Memori 的价值更加明显。它可以集成到现有的数据基础设施中无需大规模重构现有系统。支持多种部署模式的特点使其能够适应不同的企业 IT 环境要求无论是公有云、私有云还是本地部署都能良好支持。然而Memori 并不适合所有场景。对于简单的单次对话应用或者不需要长期记忆的简单任务引入 Memori 可能会增加不必要的复杂性。此外虽然 Memori 提供了记忆管理功能但它本身并不包含 AI 推理能力需要与现有的 LLM 服务配合使用。在合规性方面使用 Memori 处理用户数据时需要特别注意隐私保护。虽然 Memori 提供了结构化的记忆存储但开发者需要确保数据的收集、存储和使用符合相关法律法规要求特别是在处理个人信息和敏感数据时。3. 环境准备与前置条件在使用 Memori 之前需要准备相应的开发和生产环境。Memori 支持多种集成方式因此环境要求会根据具体的使用场景有所不同。对于云服务模式最基本的要求是能够访问 Memori Cloud 服务。开发者需要注册账号并获取 API 密钥同时需要准备好自己的 LLM 服务密钥如 OpenAI API Key。这种模式对本地环境要求最低只需要网络连接和基本的开发环境。对于本地部署或 BYODB自带数据库模式环境要求会更高。需要准备数据库基础设施Memori 支持与现有数据存储系统集成包括关系型数据库和 NoSQL 数据库。具体的数据库兼容性需要参考官方文档但通常主流的数据库系统都能得到支持。开发环境方面Memori 提供了 TypeScript 和 Python 两种主要的 SDK。对于 TypeScript 开发需要 Node.js 环境建议版本 16 或以上和 npm 包管理器。对于 Python 开发需要 Python 3.8 或以上版本以及 pip 包管理工具。如果计划使用 Memori 的 Advanced Augmentation 功能还需要考虑相应的资源配额。虽然基础功能对开发者是免费的但生产环境使用可能需要关注 API 调用限制和配额管理。4. 安装部署与启动方式Memori 提供了多种安装和部署方式适应不同的使用需求。最简单的入门方式是使用 Memori Cloud 服务无需复杂的部署过程。4.1 云服务快速开始对于大多数开发者和团队Memori Cloud 是最推荐的入门方式访问 app.memorilabs.ai 注册账号在控制台获取 API 密钥设置环境变量export MEMORI_API_KEYyour_memori_api_key export OPENAI_API_KEYyour_openai_api_key # 或其他 LLM 服务密钥安装对应的 SDK# TypeScript npm install memorilabs/memori # Python pip install memori4.2 本地 SDK 集成以 Python 为例基本的集成代码如下from memori import Memori from openai import OpenAI # 初始化客户端 client OpenAI() mem Memori().llm.register(client) # 设置 attribution关键步骤 mem.attribution(entity_iduser_123, process_idsupport_agent) # 使用记忆增强的对话 response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: My favorite color is blue.}] ) # 后续对话会自动回忆之前的上下文 response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: Whats my favorite color?}] ) # Memori 会回忆到用户喜欢的颜色是蓝色4.3 框架集成Memori 还提供了与流行 AI 框架的深度集成OpenClaw 插件集成openclaw plugins install memorilabs/openclaw-memori openclaw plugins enable openclaw-memori openclaw memori init \ --api-key YOUR_MEMORI_API_KEY \ --entity-id your-app-user-id \ --project-id my-projectHermes Agent 内存提供者pip install hermes-memori hermes-memori install hermes config set memory.provider memori5. 功能测试与效果验证为了确保 Memori 正常工作需要进行全面的功能测试。测试应该覆盖基本的记忆功能、会话管理、以及高级的记忆增强特性。5.1 基础记忆功能测试首先测试最基本的对话记忆能力# 测试脚本basic_memory_test.py from memori import Memori from openai import OpenAI import os def test_basic_memory(): client OpenAI() mem Memori().llm.register(client) mem.attribution(entity_idtest_user_001, process_idtest_bot) # 第一轮对话设置信息 response1 client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 我住在北京喜欢编程和音乐}] ) print(第一轮响应:, response1.choices[0].message.content) # 第二轮对话验证记忆 response2 client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 我刚才说我住在哪里喜欢什么}] ) print(第二轮响应:, response2.choices[0].message.content) # 预期结果AI 应该能正确回忆之前的信息5.2 会话管理测试测试跨会话的记忆保持能力def test_session_management(): client OpenAI() mem Memori().llm.register(client) mem.attribution(entity_iduser_456, process_idsession_test) # 会话1设置偏好 response1 client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 我偏好深色模式字体大小14px}] ) # 模拟新会话实际应用中可能是不同的请求 mem.new_session() # 开始新会话 # 会话2验证记忆保持 response2 client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 我的界面偏好设置是什么}] ) # 即使在新会话中Memori 也应该能回忆用户偏好5.3 高级记忆增强测试测试 Memori 的 Advanced Augmentation 功能def test_advanced_augmentation(): # 这个测试需要 Advanced Augmentation 功能 # 测试 Memori 自动提取的属性、事件、事实等结构化信息 client OpenAI() mem Memori().llm.register(client) mem.attribution(entity_idadvanced_user, process_idaugmentation_test) # 进行多轮复杂对话 conversations [ 我计划下周去上海出差需要预订酒店, 预算在500-800元之间希望靠近地铁站, 另外我需要租车服务自动挡优先 ] for i, message in enumerate(conversations): response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: message}] ) print(f对话{i1}: {response.choices[0].message.content}) # 测试记忆查询 summary_response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 总结一下我的出差需求}] ) print(需求总结:, summary_response.choices[0].message.content)6. 接口 API 与批量任务Memori 提供了完整的 API 接口支持方便集成到各种应用中。同时它也支持批量任务处理适合需要处理大量记忆操作的生产环境。6.1 REST API 调用示例虽然 Memori 主要通过 SDK 使用但了解底层的 API 调用机制有助于深度集成import requests import json class MemoriAPIClient: def __init__(self, api_key, base_urlhttps://api.memorilabs.ai): self.api_key api_key self.base_url base_url self.headers { Authorization: fBearer {api_key}, Content-Type: application/json } def create_memory(self, entity_id, process_id, content): 创建新的记忆 url f{self.base_url}/v1/memories payload { entity_id: entity_id, process_id: process_id, content: content } response requests.post(url, jsonpayload, headersself.headers) return response.json() def query_memories(self, entity_id, process_id, query_text): 查询相关记忆 url f{self.base_url}/v1/memories/query payload { entity_id: entity_id, process_id: process_id, query: query_text } response requests.post(url, jsonpayload, headersself.headers) return response.json() # 使用示例 api_client MemoriAPIClient(api_keyyour_api_key) memory_result api_client.create_memory( entity_iduser_123, process_idsupport_system, content用户反馈系统问题需要技术支持 )6.2 批量记忆操作对于需要处理大量用户记忆的场景Memori 支持批量操作import asyncio from memori import Memori from openai import AsyncOpenAI async def batch_memory_operations(): 批量记忆操作示例 client AsyncOpenAI() mem Memori().llm.register(client) # 批量设置用户偏好 user_preferences [ {user_id: user001, preference: 喜欢电子邮件通知}, {user_id: user002, preference: 偏好短信通知}, {user_id: user003, preference: 希望每周摘要报告} ] tasks [] for pref in user_preferences: mem.attribution(entity_idpref[user_id], process_idbatch_test) task client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: f我的通知偏好是{pref[preference]}}] ) tasks.append(task) # 并行执行所有任务 results await asyncio.gather(*tasks) # 验证批量记忆 verification_tasks [] for pref in user_preferences: mem.attribution(entity_idpref[user_id], process_idbatch_test) task client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 我的通知偏好是什么}] ) verification_tasks.append(task) verification_results await asyncio.gather(*verification_tasks) return verification_results6.3 Webhook 和事件处理Memori 支持 Webhook 机制可以实时响应记忆相关事件from flask import Flask, request, jsonify app Flask(__name__) app.route(/webhook/memori, methods[POST]) def handle_memori_webhook(): 处理 Memori Webhook 事件 event_data request.json event_type event_data.get(type) if event_type memory_created: # 处理新记忆创建事件 memory_id event_data.get(memory_id) entity_id event_data.get(entity_id) print(f新记忆创建: {memory_id} for entity {entity_id}) # 可以触发后续处理如分析、通知等 process_new_memory(memory_id, entity_id) elif event_type memory_updated: # 处理记忆更新事件 memory_id event_data.get(memory_id) print(f记忆更新: {memory_id}) return jsonify({status: success}) def process_new_memory(memory_id, entity_id): 处理新记忆的业务逻辑 # 这里可以添加自定义的业务逻辑 # 例如分析记忆内容、更新用户画像、触发通知等 pass7. 资源占用与性能观察Memori 作为记忆基础设施其资源占用和性能表现对于生产环境至关重要。虽然 Memori Cloud 服务处理了大部分基础设施复杂度但在自托管场景下仍需关注资源使用情况。7.1 性能基准测试根据官方提供的 LoCoMo 基准测试结果Memori 在长对话记忆任务中达到了 81.95% 的整体准确率每个查询平均使用 1,294 个 token。这仅占完整上下文占用空间的 4.97%显示出 Memori 在保持推理质量的同时显著降低了上下文成本。与其它基于检索的记忆系统相比Memori 在性能上超过了 Zep、LangMem 和 Mem0同时将提示大小相比 Zep 减少了约 67%相比完整上下文提示降低了 20 倍以上的上下文成本。7.2 资源监控建议在生产环境中使用 Memori 时建议监控以下关键指标API 调用延迟记忆查询和存储的响应时间记忆存储增长每个实体/进程的记忆数据量并发处理能力系统能够同时处理的记忆操作数量错误率记忆操作失败的比例可以使用如下代码进行基本的性能监控import time import logging from memori import Memori class MonitoredMemori: def __init__(self, memori_instance): self.memori memori_instance self.logger logging.getLogger(__name__) def timed_operation(self, operation, *args, **kwargs): 带时间监控的记忆操作 start_time time.time() try: result operation(*args, **kwargs) duration time.time() - start_time self.logger.info(f操作 {operation.__name__} 完成耗时: {duration:.2f}s) return result except Exception as e: duration time.time() - start_time self.logger.error(f操作 {operation.__name__} 失败耗时: {duration:.2f}s, 错误: {e}) raise # 使用示例 mem Memori() monitored_mem MonitoredMemori(mem) # 所有记忆操作都会自动记录性能数据 result monitored_mem.timed_operation( mem.llm.register, client # 假设已初始化的 LLM 客户端 )7.3 记忆数据管理随着使用时间的增长记忆数据可能会不断积累需要合理的数据管理策略def memory_cleanup_strategy(memori_client, entity_id, retention_days30): 记忆数据清理策略 # 定期清理过期记忆 # 可以根据业务需求定制保留策略 # 示例标记长时间未使用的记忆为归档状态 # 实际实现需要根据 Memori 的具体 API 进行调整 pass8. 常见问题与排查方法在使用 Memori 过程中可能会遇到各种问题以下是常见问题的排查指南问题现象可能原因排查方式解决方案记忆功能不生效未正确设置 attribution检查 entity_id 和 process_id 设置确保在 LLM 调用前设置正确的 attributionAPI 调用返回错误API 密钥无效或过期验证 MEMORI_API_KEY 环境变量重新生成 API 密钥并更新环境变量记忆回忆不准确记忆检索参数不合适检查查询条件和记忆相关性设置调整记忆检索策略或增强记忆内容性能下降记忆数据量过大监控记忆存储增长情况实施记忆归档或清理策略集成框架不工作插件版本不兼容检查框架和 Memori 插件版本更新到兼容的版本或查看官方文档8.1 详细排查步骤对于记忆功能不生效的问题可以按照以下步骤排查def debug_memory_issues(): 记忆问题调试函数 print( Memori 调试检查 ) # 1. 检查环境变量 api_key os.getenv(MEMORI_API_KEY) if not api_key: print(❌ MEMORI_API_KEY 环境变量未设置) else: print(✅ MEMORI_API_KEY 已设置) # 2. 检查 LLM 客户端配置 try: client OpenAI() print(✅ LLM 客户端初始化成功) except Exception as e: print(f❌ LLM 客户端初始化失败: {e}) return # 3. 检查 Memori 初始化 try: mem Memori().llm.register(client) print(✅ Memori 初始化成功) except Exception as e: print(f❌ Memori 初始化失败: {e}) return # 4. 测试基础功能 try: mem.attribution(entity_iddebug_user, process_iddebug_test) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 测试记忆功能}] ) print(✅ 基础记忆功能测试通过) except Exception as e: print(f❌ 基础记忆功能测试失败: {e})8.2 高级问题排查对于更复杂的问题可能需要深入检查记忆存储和检索机制def advanced_debugging(memori_client, entity_id, process_id): 高级调试检查记忆存储和检索 # 检查记忆存储状态需要根据具体 API 实现 # 可以查询特定实体的记忆数量、最近更新时间等 # 模拟记忆检索过程 test_queries [ 最近讨论过什么话题, 我的偏好设置是什么, 之前提到过哪些重要信息 ] for query in test_queries: try: # 这里需要根据实际 API 实现记忆查询 print(f测试查询: {query}) # 实际实现会调用 Memori 的记忆查询接口 except Exception as e: print(f查询失败: {query}, 错误: {e})9. 最佳实践与使用建议基于 Memori 的特性和实际使用经验以下是一些最佳实践建议9.1 Attribution 设置策略正确的 attribution 设置是 Memori 有效工作的基础def setup_optimal_attribution(): 优化的 attribution 设置策略 # 最佳实践使用有意义的标识符 entity_id customer_12345 # 而不是简单的 user_1 process_id support_chat_v2 # 包含版本信息便于追踪 mem Memori() mem.attribution(entity_identity_id, process_idprocess_id) # 对于多租户应用确保 entity_id 正确隔离不同用户 # 对于多模块系统使用不同的 process_id 区分功能模块9.2 会话管理最佳实践合理的会话管理可以优化记忆效果class SessionManager: def __init__(self, memori_client): self.memori memori_client self.active_sessions {} def start_session(self, entity_id, process_id, session_metadataNone): 开始新会话 self.memori.attribution(entity_identity_id, process_idprocess_id) self.memori.new_session() session_id f{entity_id}_{process_id}_{int(time.time())} self.active_sessions[session_id] { start_time: time.time(), metadata: session_metadata or {} } return session_id def end_session(self, session_id): 结束会话并进行清理 if session_id in self.active_sessions: del self.active_sessions[session_id] # 可以在这里添加会话总结或记忆归档逻辑9.3 记忆质量优化提高记忆质量的实用技巧def enhance_memory_quality(memori_client, llm_client): 记忆质量优化策略 # 1. 引导对话产生更结构化的信息 prompting_strategy 当用户提供信息时主动询问细节并结构化记录 - 对于偏好记录具体数值和条件 - 对于事件记录时间、地点、参与者 - 对于任务记录状态、截止时间、依赖关系 # 2. 定期总结和强化重要记忆 def create_memory_summary(entity_id, process_id): 创建记忆摘要 summary_prompt f 请为实体 {entity_id} 在流程 {process_id} 中的交互创建摘要 - 关键偏好和设置 - 重要事件和时间线 - 待完成的任务和状态 - 特殊注意事项 response llm_client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: summary_prompt}] ) return response.choices[0].message.content return { prompting_strategy: prompting_strategy, summary_function: create_memory_summary }9.4 生产环境部署建议对于生产环境的使用建议遵循以下原则渐进式部署先在非关键业务中测试 Memori验证效果后再逐步推广监控告警设置关键指标监控在异常时及时告警备份策略重要的记忆数据需要有备份和恢复机制权限控制根据业务需求严格控制记忆数据的访问权限合规审查确保记忆数据处理符合隐私保护和数据合规要求Memori 作为一个成熟的记忆基础设施项目为 AI 智能体提供了强大的长期记忆能力。通过合理的配置和使用可以显著提升智能体的用户体验和任务完成能力。无论是简单的对话系统还是复杂的企业级应用Memori 都能提供可靠的记忆支持。