人工智能AI AgentAgent 记忆RAG【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址https://gitcode.com/gh_mirrors/ev/EverOS点击查看免费下载EverOS 项目的use-cases/claude-code-plugin目录提供了一套让 Claude Code 拥有跨会话持久记忆的插件EverMem Plugin本文聚焦其中最直接、最常用的手动检索入口——/evermem:search命令对应文档 commands/search.md。文章会从命令声明与运行方式出发逐层拆解其背后的 Node.js 脚本、EverMem Cloud API 客户端与配置体系并对比插件在用户提交提示词时自动执行的记忆召回逻辑帮助你完整掌握如何在 Claude Code 中精准检索过去会话沉淀的记忆并让结果真正服务于当前工作。命令文档一条命令的完整契约/evermem:search由插件命令定义文件 commands/search.md 声明文件通过 YAML frontmatter 定义了命令的元信息--- description: Search EverMem for relevant memories from past sessions arguments: - name: query description: The search query to find relevant memories required: true ---description向 Claude Code 说明命令用途——在过往会话中检索相关记忆arguments声明命令必须携带一个query参数required: true表示缺省时命令无法执行有效检索。正文部分给出了命令的实际运行方式node ${CLAUDE_PLUGIN_ROOT}/commands/scripts/search-memories.js $ARGUMENTS其中${CLAUDE_PLUGIN_ROOT}是 Claude Code 注入的插件目录环境变量$ARGUMENTS则是用户在/evermem:search后输入的完整查询串。这与 hooks/hooks.json 中 hook 脚本的调用方式同样使用${CLAUDE_PLUGIN_ROOT}前缀保持一致是插件脚本的标准路径约定。文档最后还规定了命令的输出行为搜索完成后需要把关键发现总结给用户标出最相关的记忆并说明它们对当前工作可能有哪些帮助。这一要求意味着/evermem:search不是简单的终端打印工具而是检索 归纳的一体化工作流脚本负责把原始记忆捞出来Claude 负责把记忆转化为可用的上下文判断。脚本剖析search-memories.js 的六步执行流命令真正执行的脚本是 commands/scripts/search-memories.js其执行流程可以概括为以下六步1. 读取查询参数并校验const query process.argv[2] || ; if (!query) { console.log(Usage: /evermem:search query); console.log(Example: /evermem:search how do we handle authentication); process.exit(0); }查询串取自命令行第二个参数$ARGUMENTS展开后的结果。若为空脚本会打印用法提示并以 0 退出码结束而不是抛出异常。2. 校验 API Key 配置if (!isConfigured()) { console.log(Error: EVERMEM_API_KEY not configured); console.log(Set it with: export EVERMEM_API_KEYyour-key); process.exit(1); }isConfigured()来自 hooks/scripts/utils/config.js其实现为!!getApiKey()即只要环境变量EVERMEM_API_KEY存在即视为已配置。配置缺失时退出码为 1便于脚本化的上层调用感知失败。3. 打印请求上下文const config getConfig(); console.log(Searching EverMem Cloud...\n); console.log(Query: ${query}); console.log(User: ${config.userId}); console.log(Group: ${config.groupId});getConfig()返回统一的配置对象apiKey、userId、groupId、apiBaseUrl、isConfigured。这里直接暴露了检索的范围边界——记忆按userId个人或groupId项目组隔离搜索永远发生在当前用户/当前项目的命名空间内。4. 调用搜索 APIconst apiResponse await searchMemories(query, { topK: 10, retrieveMethod: hybrid });这是命令的核心调用向 EverMem Cloud 发起一次混合检索hybrid最多返回 10 条候选记忆。searchMemories由 hooks/scripts/utils/evermem-api.js 提供。5. 展示原始响应调试友好console.log(--- RAW API RESPONSE ---); console.log(JSON.stringify(apiResponse, null, 2)); console.log(--- END RAW RESPONSE ---\n);与自动注入链路inject-memories.js会静默吞掉错误不同手动搜索命令刻意把 API 原始响应完整打印出来方便用户在排查检索质量时直接观察返回结构。6. 转换结果并格式化输出const memories transformSearchResults(apiResponse);转换后的记忆列表按score降序排列随后以如下格式输出含 70 字符自动换行兼容中英文混排Searching EverMem Cloud... Query: how do we handle authentication User: claude-code-user Group: authsrv9f2a1 --- RAW API RESPONSE --- { ... } Found 3 memories: 1. [Score: 85.0%] 2026-02-09 10:30:00 ---------------------------------------------------------------------- Discussion about JWT token implementation and middleware order请求细节searchMemories 的请求体与数据模型searchMemories的完整实现在 hooks/scripts/utils/evermem-api.js它是理解整个检索机制的关键。请求构造如下const url ${config.apiBaseUrl}/api/v1/memories/search; const filters config.groupId ? { group_id: config.groupId } : { user_id: config.userId }; const requestBody { query, method: retrieveMethod, // keyword | vector | hybrid | agentic top_k: topK, // 默认 10 memory_types: memoryTypes, // 默认 [episodic_memory] filters // group_id 优先否则 user_id };要点端点POST {apiBaseUrl}/api/v1/memories/search默认 base URL 为https://api.evermind.ai可用EVERMEM_API_URL覆盖鉴权请求头携带Authorization: Bearer ${config.apiKey}检索方法method支持keyword、vector、hybrid、agentic四种search-memories.js固定使用hybrid混合检索记忆类型默认只检索episodic_memory情景记忆/会话片段这是插件保存会话时使用的记忆类型超时控制使用AbortController实现 30 秒超时TIMEOUT_MS 30000超时抛出API timeout after 30000ms容错设计非 2xx 响应或非 JSON 响应不会抛异常而是把{ status, rawBody, error }等信息封装进_debug信封随响应返回配合上面提到的 RAW 输出便于定位问题。响应转换函数transformSearchResultsevermem-api.js从apiResponse.data.episodes中提取每条记忆映射为统一结构{ text: ep.summary || , // 记忆正文取 summary 字段 subject: ep.subject || , // 主题标题 timestamp: ep.timestamp, // 时间戳 memoryType: ep.memory_type, // 记忆类型 score: ep.score || 0, // 相关度分数 metadata: { groupId, type, participants } }转换结果按score降序排序保证了终端里最相关的记忆排在最前面。终端输出的百分比分数即score * 100。配置体系四个环境变量与 groupId 生成规则/evermem:search能正确工作的前提是插件配置到位。完整的配置加载逻辑在 hooks/scripts/utils/config.js共涉及四个环境变量变量作用默认值EVERMEM_API_KEYEverMem API 密钥必需无未配置时命令报错退出EVERMEM_USER_ID个人记忆的归属标识claude-code-userEVERMEM_GROUP_ID显式指定项目组 ID按规则自动生成EVERMEM_API_URLAPI 基础地址https://api.evermind.ai其中groupId的自动生成规则值得一提config.js取当前工作目录的项目名前 4 个字符小写、仅保留字母数字加上完整路径 SHA-256 哈希的前 5 个字符拼成最多 9 字符的稳定 ID。这样同一台机器上即使两个项目同名也会因路径不同而得到不同的组 ID避免记忆串组。另外插件还支持在插件根目录放置.env文件config.js启动时会读取.env并写入process.env但不会覆盖已存在的环境变量——环境变量的优先级高于.env文件。手动搜索场景下最简配置就是export EVERMEM_API_KEYyour-api-key-here手动搜索 vs 自动召回两种检索路径的分工值得对比的是插件中还有一条自动驾驶的检索链路UserPromptSubmithook 会在用户每次提交提示词时自动检索记忆脚本为 hooks/scripts/inject-memories.js。两条链路共享同一套searchMemoriestransformSearchResults基础设施但参数与行为差异明显维度/evermem:search手动inject-memories.js自动触发时机用户显式输入命令每次提交提示词时topK1015检索方法hybridhybrid最少词数限制无空查询会提示用法MIN_WORDS 3过短静默跳过最低分数阈值无原样展示MIN_SCORE 0.1低于阈值不注入最多展示条数全部最多 topK 条MAX_MEMORIES 5失败行为打印错误并退出码 1全部静默退出process.exit(0)绝不阻塞用户工作流输出去向终端systemMessage展示给用户 additionalContext注入 Claude 上下文自动链路还有两个细节值得注意其词数统计countWords对 CJK中日韩字符按每个字算一个 token处理中文提示词同样能触发检索注入给 Claude 的上下文包装在relevant-memories标签内并明确提示记忆按时间从新到旧排列冲突时以更新信息为准——这是避免陈旧记忆误导模型的关键设计。手动搜索命令则更适合主动回顾比如开始新任务前想查上次关于 N1 查询问题的结论。/evermem:ask命令commands/ask.md则把手动检索进一步升级它要求 Claude 先用 MCP 工具evermem_search检索建议 10 条结果必要时换关键词重试最多 3 次再结合当前会话上下文与通用知识作答并在回答中明确标注信息来源Based on our discussion on [date]...。这是手动检索与对话式问答的衔接示例。调试与排障开启调试日志设置EVERMEM_DEBUG1后debug.js工具会在/tmp/evermem-debug.log中记录详细过程。手动搜索命令本身已内置 RAW 响应打印配合[EverMemAPI]前缀的调试输出见evermem-api.js中的setDebugPrefix(EverMemAPI)可以完整还原一次搜索的请求体与响应体。常见问题EVERMEM_API_KEY not configured先echo $EVERMEM_API_KEY确认环境变量存在若为空按 README.md 的指引写入 shell profile 并source重载No memories found matching your query.可能性包括——本组/本用户还没有足够的历史会话记忆需先经Stophook 保存查询词过短或过于宽泛没有超过阈值的相关记忆。可先运行插件自带的自测脚本 scripts/test-retrieve-memories.js 检查基础检索是否正常该脚本内置了多组典型查询并模拟与inject-memories.js完全一致的调用方式HTTP 错误403 Forbidden通常是 API Key 无效或过期502 Bad Gateway是服务端暂时不可用可稍后重试超时API timeout after 30000ms表示 30 秒内未收到响应可检查网络与EVERMEM_API_URL指向。兼容性说明云 API 与本地 EverOS 的关系需要特别指出的是use-cases/claude-code-plugin/README.md开头的兼容性说明明确写道该插件目录记录的是遗留的 EverMem Cloud 插件仍在使用旧版云端/api/v1/memories/*路由不应视为 EverOS 1.0.0 开源 API 的权威实现。新建集成应参照 docs/migration-to-1.0.0.md 的迁移说明与 docs/api.md 的 API 参考。也就是说本文描述的searchMemories请求体query/method/top_k/memory_types/filters是 EverMem Cloud 时代的协议EverOS 本地优先架构下的检索入口与协议细节以迁移文档与 OpenAPI 规范docs/openapi.json为准。理解二者的差异是你在自建 EverOS 记忆层时正确选型的关键。小结/evermem:search是 EverMem Plugin 中最小却最完整的一条检索链路命令声明frontmatter→ 脚本执行参数校验、配置读取→ API 调用hybrid 混合检索、Bearer 鉴权、30 秒超时→ 结果转换score 降序→ 终端格式化展示 → Claude 归纳总结。它与UserPromptSubmit自动召回形成主动回顾 被动注入的双通道共同构成 Claude Code 的跨会话记忆体验。无论你是在排查为什么搜不到记忆还是想为其他工具复刻一套类似的记忆检索命令这条链路从命令定义到 API 客户端的每一层都值得直接借鉴。赞分享人工智能AI AgentAgent 记忆RAG【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址https://gitcode.com/gh_mirrors/ev/EverOS点击查看免费下载相关推荐DeepFace 年龄与性别识别完整指南5分钟跑通单图推理到批量打标DeepFace 年龄与性别识别完整指南5分钟跑通单图推理到批量打标 给图库或会员系统加这个人大概多大、什么性别的标签是人脸分析里最常见的起步需求。De人工智能AI AgentAgent 记忆RAGEverOS 记忆层实战EverMem Claude Code 插件 help 命令、快速配置与记忆自动化指南EverOS 记忆层实战EverMem Claude Code 插件 help 命令、快速配置与记忆自动化指南 EverMem 是为 Claude Code人工智能AI AgentAgent 记忆RAGEverOS 记忆可视化实战EverMem Memory Hub 命令与本地代理架构深度解析EverOS 记忆可视化实战EverMem Memory Hub 命令与本地代理架构深度解析 导读 本文以 EverOS 仓库中 Claude Code 插人工智能AI AgentAgent 记忆RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
