LycheeMem 是一个面向 LLM Agent 的轻量级长期记忆框架，通过 Claude Code 插件与 Hermes 插件，可以为 Agent 提供自动召回、会话镜像与记忆固化（consolidation）的完整工作流，让 AI 助手真正"记住"你的偏好、项目决策与历史对话，而无需你手动粘贴上下文。本文带你从零完成安装，并深入解析这两条插件链路的召回与固化机制。

一、为什么 Agent 需要长期记忆插件？

大语言模型本身是无状态的：会话一结束，上下文就全部丢失。你在上一周告诉 Agent"我喜欢简洁的回答风格"，它在新会话里会一无所知。LycheeMem 把记忆拆分为三类互补存储：

而插件要解决的核心问题只有三个：什么时候自动召回、什么时候自动写入、什么时候把临时对话固化为长期记忆。

二、准备工作：启动 LycheeMem 记忆服务

两条插件链路都依赖同一个后端服务，先把它跑起来。

git clone https://gitcode.com/gh_mirrors/ly/LycheeMem cd LycheeMem pip install lycheemem python main.py

服务默认监听8000端口。也可以直接用官方 CLI 一键启动：lycheemem-cli。

确认服务健康：

curl http://127.0.0.1:8000/health

💡 若.env中使用了其他端口（如API_PORT=8100），后续所有LYCHEEMEM_BASE_URL都要保持一致。

三、Claude Code 插件实战：三步接入

1. 校验并加载插件

Claude Code 插件通过MCP + hooks两种机制接入，完整安装指南见 INSTALL_CLAUDE.md。

export LYCHEEMEM_REPO="/path/to/LycheeMem" export LYCHEEMEM_BASE_URL="http://127.0.0.1:8000" claude plugin validate "$LYCHEEMEM_REPO/claude-plugin/lycheemem" claude --plugin-dir "$LYCHEEMEM_REPO/claude-plugin/lycheemem"

2. 在会话内验证

进入 Claude Code 后运行/plugin和/mcp确认插件与 MCP server 已加载，然后做端到端测试：

Please remember that my favorite fruit is lychee. What is my favorite fruit? Use LycheeMem to recall my favorite fruit.

如果自动召回生效，Claude 会基于 LycheeMem 返回的background_context作答，而不是凭空猜测。

3. 插件内部：三个 Hook 串起完整工作流

Claude Code 插件的自动化逻辑全部由 hook 驱动，配置在 hooks.json 中：

除了 hook，插件还注册了一个 memory skill，教会 Claude 在哪些场景下应主动调用lychee_memory_smart_search（例如询问历史对话、偏好、项目规范时），并规定了"召回优先、证据不足时明确说明而非编造"的回答原则。

四、Hermes 插件实战：运行时级自动记忆

Hermes 插件以 Python runtime 的形式接入，插件清单见 plugin.yaml，完整指南见 INSTALL_HERMES.md。

1. 安装并启用插件

mkdir -p ~/.hermes/plugins ln -sfn "$LYCHEEMEM_REPO/hermes-plugin/lycheemem" ~/.hermes/plugins/lycheemem hermes plugins enable lycheemem hermes plugins list

2. 配置连接环境变量

export LYCHEEMEM_BASE_URL="http://127.0.0.1:8000" export LYCHEEMEM_TRANSPORT="http" export LYCHEEMEM_ENABLE_PRE_LLM_CONTEXT=true export LYCHEEMEM_ENABLE_AUTO_APPEND=true export LYCHEEMEM_ENABLE_AUTO_CONSOLIDATE=true export LYCHEEMEM_SMART_SEARCH_TOP_K=5 export LYCHEEMEM_RESPONSE_LEVEL=minimal

3. 启动 Hermes 并做端到端验证

hermes

在 Hermes 内依次执行：

/plugins /lycheemem status /lycheemem health Please remember that my favorite fruit is lychee. What is my favorite fruit? /lycheemem recall favorite fruit

如果链路正常，/lycheemem recall会返回包含lychee的background_context。

4. 核心机制：pre_llm_call 到 on_session_end 的生命周期

Hermes 插件的工作流实现在 runtime.py 中，按会话生命周期划分为四个阶段：

1. pre_llm_call（自动召回）：每次模型调用前，插件用用户消息调用smart_search，把召回结果以Relevant memory from LycheeMem:前缀注入为background_context。由于发生在模型调用之前，通常不会显示为可见的工具调用——这是"无感召回"的关键。
2. post_llm_call（会话镜像）：每轮结束后，把 user / assistant 两条消息镜像写入 LycheeMem。内部用 SHA1 指纹去重，同一轮次不会重复写入。
3. on_session_end/on_session_finalize（记忆固化）：会话收尾时触发 consolidation，由 LLM 从对话中提取事实、偏好等类型化记忆写入语义记忆，支持后台异步执行并带 60 秒冷却（LYCHEEMEM_AUTO_CONSOLIDATE_COOLDOWN_SECONDS），避免频繁打扰。
4. 手动调试通道：/lycheemem recall <query>用于检查检索质量；lycheemem_smart_search工具留给显式召回场景。

HTTP/MCP 双通道的客户端封装见 client.py，所有开关与默认值集中定义在 config.py。

五、调参速查：让召回与固化符合你的场景

⚙️ 调试记忆流水线时推荐组合：LYCHEEMEM_AUTO_CONSOLIDATE_BACKGROUND=false+LYCHEEMEM_AUTO_CONSOLIDATE_COOLDOWN_SECONDS=0，让固化同步执行、立即生效，再观察服务端日志中的/memory/append-turn、/memory/consolidate、/memory/smart-search调用。

六、常见问题排查

• /plugins中看不到lycheemem：确认软链接存在（ls -la ~/.hermes/plugins/lycheemem），重新执行hermes plugins enable lycheemem后重启 Hermes。
• /lycheemem health失败：先用curl "$LYCHEEMEM_BASE_URL/health"验证服务，通常是端口或LYCHEEMEM_BASE_URL不一致。
• recall返回空：回忆需要先固化。改用同步固化参数重跑测试，并检查.env中的EMBEDDING_API_BASE；历史数据较多时首次启动会回填向量，属于正常现象。
• 修改 Claude Code 插件或 MCP 配置后不生效：必须重启 Claude Code。

七、总结

LycheeMem 的 Claude Code 与 Hermes 插件展示了一套通用的"记忆接入"范式：用生命周期 hook 实现无感自动召回与会话镜像，用异步 consolidation 完成记忆固化，再用 slash 命令 / MCP 工具保留手动调试通道。接入后，Agent 无需依赖模型"想起来调用工具"，记忆召回变成确定性的基础设施行为。

如果你正在构建跨会话的 AI 助手，这套工作流值得直接复用：先pip install lycheemem跑起服务，再按本文第三节或第四节接入你的 Agent 运行时，十分钟即可验证完整的"记住 → 召回 → 固化"闭环。