Mem0 Plugin Peek 技能解析：/mem0:peek 快速记忆检索、短 ID 直查与紧凑引文输出

Mem0 Plugin Peek 技能解析：/mem0:peek 快速记忆检索、短 ID 直查与紧凑引文输出

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain

Mem0 Plugin 为 Claude Code、Cursor、Codex、OpenCode、Antigravity 等 AI 编码环境提供持久化语义记忆，其中peek技能（/mem0:peek）是面向「快速查证」场景的轻量检索命令：既支持按关键词做双通道语义搜索，也支持通过短 ID 或[mem0:id]引文直查单条记忆，并以每行一条的紧凑格式返回结果。读完本文，你能完整掌握 peek 的三步执行流程（解析 → 并行搜索 → 去重展示）、其背后的身份与项目作用域解析机制（user_id/app_id从何而来），以及 rerank 参数在平台 REST 接口上的真实行为，从而在 Agent 工作流中可靠地用它来核对「某个决策是否被记录下来」或解析记忆引文。

1. peek 在插件技能体系中的定位

peek 技能定义在 skills/peek/SKILL.md，其元信息声明的用途是：

Searches memories and displays compact one-liner results, or looks up a specific memory by ID. Use for quick memory lookups, checking if a decision was recorded, resolving[mem0:id]citations, or browsing memories without full category detail.

也就是说，它解决的是四个具体场景：快速记忆检索、确认某个决策是否已被记录、解析[mem0:<id>]形式的记忆引文、以及不想展开完整分类详情的轻量浏览。原文档明确将它与/mem0:tour做了区分——「Quick search with compact output. Lighter than/mem0:tour」。两者对比可以理解为：

值得注意的是，tour 技能文档中本身就内置了一段「Peek mode」流程：当/mem0:tour带搜索词且不带--all-projects时，会退化为与 peek 完全相同的紧凑搜索流程。这说明 peek 实质上是插件记忆检索的「紧凑显示协议」，两个入口共用同一套双路搜索策略。

2. Step 1：解析查询与 Memory ID 检测

用户提供搜索查询，例如/mem0:peek auth middleware。若未提供查询词，技能要求 Agent 反问 "What should I search for?"，而不是凭空搜索。

关键的工程细节是Memory ID 检测。如果查询词命中以下任一模式，技能会把它当作「直接按 ID 查单条记忆」而不是搜索：

• 裸十六进制短 ID：^[a-f0-9]{8}$（8 位 hex 短 ID）
• 完整 UUID：^[a-f0-9]{8}-[a-f0-9-]+$
• 引文引用：[mem0:<hex>]—— 提取其中的 hex 部分

检测到 ID 后的处理策略是三层降级：

1. 直接调用 MCP 工具get_memory(<id>)（如果是短 ID，则作为完整 UUID 的前缀尝试匹配）；
2. 命中则跳过 Step 2 的搜索，直接进入 Step 3 展示这一条结果；
3. 未命中则回落到正常搜索——把这个 ID 当作文本 query 去检索。

这个设计对应了 README 中提到的「17 个/mem0:命令」体系：peek 输出的[mem0:<short_id>]标记是全局记忆引用协议的一部分，后续/mem0:forget（按 ID 删除）、/mem0:pin（保护）等命令都以同一 ID 体系为操作对象，而 peek 是其中最常用来「验证引文指向哪条记忆」的入口。

3. Step 2：双通道并行搜索（Broad + Targeted）

未命中 ID 检测时，peek 要求发起2 个并行的search_memories调用：

1. Broad（宽召回）: query=<用户查询词> filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]} top_k=10 rerank=true 2. Targeted（定向召回）: query=<用户查询词> filters={"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "decision"}}]} top_k=5 rerank=true

设计意图很清晰：

• Broad 通道在user_id+app_id双约束下取 top 10，保证召回面——任何类别的记忆（决策、约定、反模式、工具链配置）都可能命中；
• Targeted 通道额外叠加metadata.type == "decision"过滤，专门捞「架构决策」类记忆——因为 peek 的典型用例之一就是「确认某个决策是否被记录过」；
• 两路都显式设置rerank=true，让平台侧用 reranker 重排而不是只按原始向量相似度截断。

3.1 作用域参数从哪里来：user_id与app_id的解析链

filters 里的<id>和<pid>并非手填，而是插件共享脚本在会话期自动解析的身份与项目作用域：

• user_id：见 scripts/_identity.py 的resolve_user_id()——优先读MEM0_USER_ID环境变量，否则取$USER，再兜底"default"；
• app_id：见 scripts/_project.py 的resolve_project_id()，解析优先级为：
  1. MEM0_PROJECT_ID环境变量（显式覆盖，对应/mem0:switch-project的能力）；
  2. ~/.mem0/project_map.json按当前工作目录查找；
  3. 按 git remote URL 的 SHA-256 哈希键查找（目录被移动/重命名后的自愈回退，并会回填新的 cwd 键）；
  4. git remote slug（如git@github.com:mem0ai/mem0.git→mem0ai-mem0）；
  5. 兜底：当前目录 basename。

这解释了为什么 peek 的每次搜索都被严格限定在「某用户 × 某项目」的格子内——同一台机器上多个仓库的记忆互不串扰，这也是空结果提示里出现for project <project_id>的原因。

3.2rerank参数在平台接口上的真实语义

peek 两次搜索都要求rerank=true，这个要求在插件的共享搜索助手 scripts/_search.py 中有明确的源码级解释：

The REST search endpoint does not rerank whenrerankis omitted, so auto-injected context is ordered by raw vector similarity and the single most relevant memory can fall outside the injected top_k window.

也就是说，Mem0 的 REST 搜索端点（POST /v3/memories/search/，见 scripts/_search.py 的SEARCH_URL）在省略rerank字段时不重排，结果只按原始向量相似度排序，唯一最相关的记忆可能掉出top_k窗口。为此插件提供了should_rerank()：默认开启 rerank（额外约 150–200ms 延迟在 hook 的 curl 预算内），并允许用户通过MEM0_RERANK环境变量关闭——取值0、false、no、off（大小写不敏感）禁用，未设置或其他值均启用。

这些行为不是口说无凭，仓库中有成体系的回归测试（tests/test_search.py）：

• test_search_memories_omits_rerank_by_default（#L138-L155）：不传rerank时请求体中不得出现rerank字段（回归 issue #5684，避免「默认重排」造成意外的额外延迟/配额消耗）；
• test_search_memories_forwards_rerank_true（#L158-L176）：rerank=True必须真实到达请求体，否则端点不会重排；
• test_should_rerank_defaults_true/test_should_rerank_opt_out_values（#L179-L196）：锁定MEM0_RERANK的默认开启与全部关闭取值。

此外，search_memories()的健壮性也有测试覆盖：API key 为空直接返回空列表而不发请求（test_search_memories_no_api_key_returns_empty）；网络异常时向 stderr 输出错误并返回[]，而 429 限流必须留下可区分的错误日志（test_search_memories_logs_rate_limit_error，注释标注 "Bug bash #22: a 429 must not look identical to a genuine empty result"）——这对 peek 使用者是个实用提示：当 peek 返回「无结果」而会话恰好遇到限流时，应先检查是否刚被 429。

从源码结构看，hook 自动注入路径走的是这个 Python 助手（带 5 秒超时的urllib直连），而/mem0:peek命令本身由 Agent 通过 MCP 工具search_memories发起；两者最终打到同一个平台搜索端点，参数语义（filters的AND子句、top_k、threshold、rerank）是一致的。

4. Step 3：去重与紧凑一行式展示

两路结果合并后，先按记忆 ID 去重（Broad 的 top 10 与 Targeted 的 top 5 必然重叠），再按固定模板输出：

## mem0 peek: "<query>" (<N> results) 1. [decision] Auth module uses JWT with RS256 keys (2025-05-15) [mem0:a3f8b2c1] 2. [anti_pattern] Don't use symmetric HS256 — leaked in env (2025-05-10) [mem0:7e2d9f4a] 3. [convention] All middleware in src/middleware/ (2025-05-08) [mem0:c4d5e6f7]

每行的格式契约是：

<number>. [<type>] <content, 80 chars> (<date>) [mem0:<short_id>]

• <type>：记忆类别，来自metadata.type（如decision、anti_pattern、convention）；
• <content>：记忆正文，截断到 80 字符——这是「紧凑」的关键，保证 Agent 上下文里一条记忆只占一行；
• <date>：记忆日期；
• [mem0:<short_id>]：8 位 hex 短 ID 引文，即 Step 1 中可被再次用于直查的引用标记。

无结果时的空状态输出是确定性的：

No memories matching "<query>" for project <project_id>.

这套一行式引文格式并非 peek 独有，插件的自动注入路径也使用同一族格式：scripts/_search.py 中的format_results_for_context()把搜索结果渲染为- [<category>] <text[:200]> [mem0:<id 前 8 位>]注入 prompt。可以推断，[mem0:xxxxxxxx]短 ID 引文是插件「记忆 → Agent 上下文 → 后续按 ID 操作」闭环的通用货币：peek 打印它、hook 注入它、Agent 用get_memory/forget/pin消费它。

5. 运行前提与相关组件

peek 不是独立程序，它依赖插件整体的三层组件（见 integrations/mem0-plugin/README.md 与 plugin.json 的声明）：

1. MCP Server：插件通过 mcp_config.json 接入 Mem0 远程 MCP 端点（https://mcp.mem0.ai/mcp/，Authorization: Token ${MEM0_API_KEY}在会话启动时做环境变量插值）。search_memories与get_memory正是 MCP 工具表中的两个工具；
2. API Key：MEM0_API_KEY（以m0-开头）必须已在 shell 环境或客户端本地环境中设置——scripts/_identity.py 的resolve_api_key()会按「环境变量 → Claude Code userConfig 注入 → shell profile 文件提取」的顺序兜底解析；
3. 生命周期 Hooks（可选但推荐）：hooks.json 将SessionStart、UserPromptSubmit、PreToolUse、Stop、PostToolUse等事件接到scripts/下的脚本，自动捕获记忆并强制user_id/app_id元数据——UserPromptSubmit钩子（on_user_prompt.sh，超时 8 秒）内部就调用 §3 所述的search_memories()助手做相关记忆注入。peek 之所以「有东西可查」，很大程度依赖这些钩子在会话过程中持续写入记忆。

典型验证链路也写在 README 中：/mem0:health（连通性）→/mem0:stats（计数）→/mem0:remember "we use TypeScript"→/mem0:tour或/mem0:peek查看。

6. 小结：何时用 peek，何时用 tour

从这份技能文档可以提炼出一条清晰的决策准则：

• 用/mem0:peek <query>：你只需要答案本身——「JWT 的决策记过没有？」「a3f8b2c1这条记忆写的什么？」——需要的是带引文的一行式结果，可以直接粘进对话或 commit message；
• 用/mem0:tour：你要审视图景——按类别浏览全部记忆、查看完整正文、在新项目 onboarding 时建立整体认知；
• 两者共享同一套双路搜索协议（Broadtop_k=10+ Targeted decisiontop_k=5，均rerank=true），因此检索质量一致，差异只在展示密度。

配合MEM0_RERANK调优重排开销、MEM0_PROJECT_ID固定项目作用域，peek 就成为 Agent 编码工作流中「记忆可查证性」的最小可用单元：每条输出都带[mem0:<id>]引文，任何一条结果都可以被后续命令精确追踪、引用、更新或删除。

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain