LycheeMemory
为 LLM 代理提供可检索、可整合的轻量长期记忆服务。
按维度查看评分与理由
证据显示：项目使用JWT和bcrypt进行认证，但未明确说明权限最小化原则；用户确认机制仅在部分操作中提及，如consolidate需手动调用，但自动镜像和自动合并可能未经用户明确同意；数据流透明度较好，README详细描述了数据存储和检索流程，但未提供数据流图；敏感数据处理方面，API密钥通过.env管理，但未说明加密存储；依赖安全方面，依赖列表未提供版本锁定或安全审计；外部影响方面，插件和MCP服务可能影响外部系统，但未说明权限控制；回滚方面，未提及数据回滚机制；来源归属方面，未提供贡献者指南或维护者信息。扣分原因：缺乏明确的权限最小化、用户确认、敏感数据加密、依赖安全审计、外部影响控制、回滚机制和来源归属。
证据显示：README和代码描述一致，但未提供完整的架构图；依赖可用性方面，依赖列表未提供版本锁定，且未说明离线安装；失败消息方面，README提到rerank失败时降级，但未提供详细的错误处理文档。扣分原因：依赖版本未锁定，失败处理文档不完整。
证据显示：README明确目标用户为LLM agent开发者，并提供了多种集成方式（OpenClaw、Claude Code、Hermes、MCP、PyPI）；能力边界清晰，描述了记忆类型和检索模式；触发精度方面，提供了详细的API参数和示例；环境适配方面，支持Python 3.9+和多种LLM提供商。扣分原因：未提供详细的配置选项说明，如JWT设置。
证据显示：README结构清晰，包含快速开始、架构、API参考等；安装说明详细，包括pip和源码安装；命名稳定性方面，项目从LycheeMem更名为LycheeMemory，但未提供迁移指南；示例和FAQ方面，提供了多个示例，但未提供FAQ；已知限制方面，仅在rerank文档中提及限制；许可证为Apache-2.0，但未提供版权信息；版本和变更日志方面，README有新闻，但未提供正式变更日志；维护责任方面，未提供贡献指南或维护者信息。扣分原因：命名变更未提供迁移指南，缺少FAQ、正式变更日志和贡献指南。
证据显示：输出可用性方面，提供了API和MCP工具，输出格式清晰；边际价值方面，提供了记忆管理功能，但未与其他方案对比；成本效益方面，README声称减少token消耗，但未提供详细数据。扣分原因：缺少与其他方案的对比和详细成本数据。
证据显示：README中的声明（如性能提升）未提供具体测试数据或引用；跨来源验证方面，未提供第三方验证；事实与推断分离方面，README将事实和推断混合，如声称ACL 2026论文但未提供链接。扣分原因：声明缺乏可追溯性，未提供第三方验证，事实与推断未分离。
- 项目使用JWT和bcrypt，但未明确权限最小化原则，建议审查认证和授权实现。
- 自动镜像和自动合并可能未经用户明确同意，建议增加用户确认机制。
- 依赖未锁定版本，建议使用锁文件或固定版本以确保可复现性。
- README中的性能声明缺乏具体数据，建议验证后再依赖。
- 项目从LycheeMem更名为LycheeMemory，但未提供迁移指南，可能影响现有用户。
这个 Agent 能做什么，适合哪些场景？
LycheeMemory 是面向 LLM 代理的自托管长期记忆框架，覆盖工作记忆、语义记忆、技能型程序记忆和视觉记忆。它以 SQLite、FTS5 与 LanceDB 存储及检索记忆，并通过 LangGraph 管线在响应后异步完成记忆整合。服务提供 Python 包、HTTP MCP 端点、OpenAI Chat Completions 兼容接口，以及 OpenClaw、Claude Code 和 Hermes 的插件集成。其语义记忆使用带类型和行动元数据的 MemoryRecord、CompositeRecord 层级树及检索反馈日志，适合希望将跨会话上下文沉淀为可复用证据的代理系统。部署边界是本地运行的 Python 服务；调用 LLM 和嵌入模型需要配置兼容提供方的凭据。
请求进入固定管线后，WMManager 写入会话轮次、检查双阈值 token 预算，并输出压缩历史和近期原始轮次。SearchCoordinator 基于查询、近期上下文与 ActionState 生成 SearchPlan，检索 CompositeRecord 层级树、MemoryRecord、技能库和必要时的原始会话片段；SynthesizerAgent 对候选记忆按 0–1 相关性评分，生成 background_context、provenance 和 skill_reuse_plan；ReasoningAgent 生成最终回复。响应完成后，ConsolidatorAgent 以后台任务调用 CompactSemanticEngine.ingest_conversation()，提取、去上下文化并标注 MemoryRecord，再用嵌入相似度进行 Record Fusion 和层级整合。外部宿主可通过 /memory/append-turn 镜像轮次、通过 /memory/consolidate 触发整合，或经 /mcp 调用 lychee_memory_smart_search、lychee_memory_search、lychee_memory_append_turn 与 lychee_memory_consolidate。
- 为使用 OpenClaw 的团队在多个会话之间保留用户偏好、约束和既往工具使用经验。
- 为已有 Python 代理增加持久记忆，并通过 lycheemem-cli 运行本地后端服务。
- 为支持远程 HTTP MCP 的客户端提供 compact 模式的一次性背景召回。
- 为需要复用操作步骤的支持或运维代理，将成功的工具使用模式沉淀到技能库并以 HyDE 检索。
- 为包含截图、图表或文档图片的代理会话保存视觉记忆，并进行文本到图片或图片相似检索。
这个 Agent 有哪些优点和局限？
- 同时提供 Python 包、HTTP MCP、OpenAI Chat Completions 兼容 API 与多个运行时插件，集成入口较多。
- 语义记忆不只是向量文本：MemoryRecord 支持七种类型、行动标签、使用统计和冲突感知的层级 Record Fusion。
- 检索先在 CompositeRecord 上进行 ANN 预筛和单次 LLM 相关性判断，再按需展开原子记录，并能补充 FTS、向量和原始轮次召回。
- 工作记忆采用 70% 预压缩与 90% 阻塞压缩的双阈值，后台 ConsolidatorAgent 不阻塞当次回复。
- 必须自行运行本地 Python 服务，并配置 LLM、嵌入模型及相应 API 凭据；没有文档化的托管服务流程。
- 默认 Transformer reranker 依赖可选的 PyTorch/Transformers 运行时，并会在首次使用时从 Hugging Face 加载检查点；不可用时会退回基础检索。
- 记忆数据使用 SQLite、LanceDB 和本地文件系统，采用前需要规划本地数据路径、持久化和访问控制。
- 视觉记忆需要 VLM 与 CLIP 风格嵌入模型；文档未提供其成本、硬件需求或生产容量基准。
如何安装或部署这个 Agent？
前提：Python 3.9+，以及 OpenAI、Gemini 或其他 litellm 兼容提供方的 LLM API 密钥。
安装核心包：
pip install lycheemem如需默认 Transformer reranker：
pip install "lycheemem[rerank]"在工作目录创建 .env，至少设置：
LLM_MODEL=openai/gpt-4o-miniLLM_API_KEY=sk-...
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIM=1536启动服务：
lycheemem-cli服务默认地址为 http://localhost:8000，交互文档位于 /docs。
如何使用这个 Agent？
启动服务后，可将兼容 OpenAI SDK 的 base_url 设为 http://localhost:8000/v1，并调用 POST /v1/chat/completions；请求体包含 model、messages 和稳定的 session_id。若只需召回上下文，向 POST /memory/smart-search 发送 {"query":"...","top_k":5,"synthesize":true,"mode":"compact"}，读取返回的 background_context。MCP 客户端可配置 http://localhost:8000/mcp，并在 initialize 后复用返回的 Mcp-Session-Id；推荐使用 lychee_memory_smart_search 的 compact 模式。外部对话宿主先用 /memory/append-turn 写入 user 或 assistant 轮次，再以同一 session_id 调用 /memory/consolidate。
这个 Agent 与同类方案有什么区别？
在 OpenClaw 场景中，LycheeMemory 提供原生插件：自动镜像用户与助手轮次，并在 /new、/reset、/stop 或 session_end 时触发边界整合。仓库还报告，在使用该插件的 PinchBench 评测中，相比 OpenClaw 原生记忆约提升 6% 分数、减少约 71% token 消耗和约 55% 成本；该结果是仓库披露的评测结论。