LycheeMemory
为 LLM 代理提供可检索、可整合的轻量长期记忆服务。
这个 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-mini
LLM_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% 成本；该结果是仓库披露的评测结论。