Mem0 插件 context-loader 技能详解：在任务开始前预加载相关记忆

本文围绕 Mem0 插件中的 context-loader 技能（SKILL.md）展开，讲解它如何在新会话、切换上下文或开始复杂任务时，从 Mem0 平台并行检索相关记忆并注入当前上下文。读完本文，你将理解该技能的触发时机、四路并行 search_memories 的过滤器设计、上下文块的输出格式，以及插件底层钩子脚本与身份解析机制是如何支撑这一流程的。

一、context-loader 的定位：任务开始前的"记忆预取"

context-loader 是 Mem0 插件内置的 17 个技能之一，对应斜杠命令 /mem0:context-loader，官方描述为"Pre-load relevant memories for current task"（见 README.md 中的 Available Skills 表）。它的核心职责只有一句话：在动手干活之前，先把与当前任务相关的历史记忆（架构决策、编码约定、已知坑点）提前载入上下文，让 Agent 不必从零开始"回忆"项目背景。

从技能的 frontmatter 定义看，它的触发场景有两类：

• 会话开始：手动调用，或由技能描述匹配自动触发；
• 用户开始处理某个具体功能或一组文件、复杂多步任务启动时，或者用户直接说"we know what about X / context for X"。

这与插件整体设计一致：Mem0 插件通过 MCP 服务器（mcp_config.json 中配置了 https://mcp.mem0.ai/mcp/ 远程端点）提供 add_memory、search_memories、get_memories 等 9 个工具，而 context-loader 正是对其中 search_memories 工具的"编排式"使用方式——它不是单个查询，而是一套检索策略。

二、使用时机（When to use）

原技能文档列出了四类典型触发场景，完整继承如下：

• 会话启动时：手动调用，或由技能描述匹配自动触发（invoke manually or auto-triggered by skill description matching）；
• 用户开始处理某个具体功能或文件集时；
• 复杂多步任务开始时；
• 用户明确询问时：例如说 "what do we know about X" 或 "context for X"。

值得注意的是最后一条：该技能同时承担"被动注入"和"主动查询"两个角色。当用户直接问"关于 X 我们知道什么"时，它就退化为一次带记忆的问答；而在无感场景下，它由钩子或技能描述匹配驱动，静默完成预取。

三、五步执行流程

3.1 第一步：从当前消息/任务中提取主题

技能要求先从当前消息中提取检索线索，具体包括四类：文件路径、模块名、功能领域、错误模式。这四类线索分别对应下一节四种查询角度的构造依据——文件路径对应"编码约定"查询，模块名对应"架构决策"查询，错误关键字对应"已知坑点"查询。

3.2 第二步：发起 2–4 路并行 search_memories 调用

这是该技能的核心策略：不做单次检索，而是从不同角度并行查询，再合并。原技能文档给出了完整的过滤器矩阵：

查询角度	过滤器	目的
功能/模块名	{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "decision"}}]}	架构决策
提到的文件路径	{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "convention"}}]}	编码模式
错误关键字（如有）	{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}, {"metadata": {"type": "anti_pattern"}}]}	已知坑点
宽泛的项目上下文	{"AND": [{"user_id": "<id>"}, {"app_id": "<pid>"}]}	兜底查询

其中 <id> 与 <pid> 分别对应当前的 user ID 和 project scope（app_id）。这些 ID 并非凭空而来，插件脚本 scripts/_identity.py 中实现了明确的解析规则：

• user_id：优先取 MEM0_USER_ID 环境变量（显式覆盖），否则取 $USER，都没有则回退为 default；
• app_id（project scope）：从源码结构看，scripts/_project.py 负责项目 ID 解析，_identity.py 中的降级实现直接取当前工作目录的 basename 作为项目标识，配合 git 分支信息（resolve_branch）进一步细化作用域。

过滤器格式本身与插件底层检索实现完全一致。共享检索模块 scripts/_search.py 的 search_memories() 函数在构造非全局搜索的请求体时，正是按如下方式拼装 AND 子句：

base_clauses: list[dict] = [{"user_id": user_id}, {"app_id": project_id}]
if metadata_type:
    base_clauses.append({"metadata": {"type": metadata_type}})
...
filters = {"AND": base_clauses}

可以看到，技能文档中 {"metadata": {"type": "decision"}} 这类过滤器的写法，与底层实现对 metadata_type 参数的映射逐字对应——decision、convention、anti_pattern 就是打在记忆 metadata.type 上的标签，用于区分"决策 / 约定 / 反模式"三类知识。

另外两个值得注意的底层细节（均来自 _search.py）：

• 请求默认参数：检索请求携带 top_k（函数默认 3，技能要求合并后总量不超过 10）和 threshold（默认 0.3）；
• rerank 开关：REST 检索端点在省略 rerank 参数时不会做重排序，此时结果按原始向量相似度排序，最相关的一条记忆可能落在 top_k 窗口之外。因此钩子驱动的自动注入路径默认开启 rerank（额外约 150–200ms，在钩子预算内），并允许通过 MEM0_RERANK 环境变量以 0/false/no/off 关闭。

3.3 第三步：按记忆 ID 去重

四路查询返回的结果集大量重叠（一条记忆可能同时命中"模块名"和"宽泛上下文"两种查询），技能明确要求跨所有搜索响应按 memory ID 去重。这一步保证最终上下文块不会因重复条目而浪费 token。

3.4 第四步：输出紧凑上下文块（最多 10 条）

去重后，技能要求输出一个紧凑的上下文块，格式固定为：

context-loader: loaded <N> memories for "<task summary>"
  - [decision] <content> [mem0:<short_id>]
  - [convention] <content> [mem0:<short_id>]
  - [anti_pattern] <content> [mem0:<short_id>]

这个格式并非随意约定，它在插件的格式化模块中有同源实现。_search.py 中的 format_results_for_context() 对每条记忆的输出正是 - [{cat}] {text} [mem0:{mid}] 结构，其中：

• cat 取自 metadata.type（即 decision / convention / anti_pattern 等标签）；
• mid 取记忆 ID 的前 8 位作为 short_id，供后续 /mem0:peek、get_memory 等工具精确定位；
• text 截断到前 200 字符，控制上下文占用。

3.5 第五步：零结果时保持沉默

如果所有查询都没有返回结果，技能的规则是：什么都不输出，不要宣布"上下文为空"。这一设计与插件的整体哲学一致——自动注入路径（如 hooks.json 中 UserPromptSubmit 钩子调用的 scripts/on_user_prompt.sh）在检索无果时同样静默，避免在每次提交空提示词时污染对话。

四、四条硬约束（Constraints）

原技能文档给出了四条不可协商的约束，它们共同把 context-loader 锁定为"纯读取器"：

1. 只读——绝不修改或删除任何记忆（never modify or delete memories）；
2. 最多 10 条记忆——只保留最相关的；
3. 空结果静默——只有存在相关上下文时才输出发现；
4. 跳过当前会话上下文中已经可见的记忆——避免把会话里已有的信息再注入一遍。

第 4 条在实践中尤其关键：会话进行中，早期检索到的记忆已经存在于对话历史里，context-loader 再次触发时应将其过滤掉，只补充增量信息。

五、与插件钩子体系的关系

context-loader 是技能层（skills）的能力，而插件的自动化记忆注入主要由生命周期钩子承担，两者互补。从 hooks.json 可以看到与"上下文加载"直接相关的两条链路：

• UserPromptSubmit：每次用户提交提示词时运行 scripts/on_user_prompt.sh（8 秒超时），负责在提示词中注入相关记忆；
• PreToolUse（matcher 为 Read）：Agent 读取文件时运行 scripts/on_file_read.sh（5 秒超时），扫描被读文件并检索相关记忆上下文。

可以推断，context-loader 技能是这套自动注入机制的"手动版本"：钩子按固定节奏小批量注入（底层 search_memories() 的 top_k 默认为 3），而技能在任务节点上做 2–4 路并行、最多 10 条的集中预取。两者的检索底座（_search.py 的 AND 过滤器构造、rerank 开关、格式化函数）完全共享，因此过滤器写法与记忆标签体系是一致的。

六、如何运行：安装与调用路径

要在自己的会话中用上该技能，前提条件是完成 Mem0 插件安装，路径见 README.md：

1. 设置 API key（必须先于安装）：通过 CLI 写入 MEM0_API_KEY（以 m0- 开头），或用 mem0 init --agent --json 为 Agent 免浏览器签发评测 key；
2. 安装插件：以 Claude Code 为例，执行 /plugin marketplace add mem0ai/mem0 后 /plugin install mem0@mem0-plugins，Codex / Cursor / OpenCode / Antigravity 各有对应安装方式；
3. 完成引导：新会话中运行 /mem0:onboard，验证连接、导入项目文件（CLAUDE.md、AGENTS.md、.cursorrules）并安装面向编码的记忆分类；
4. 调用技能：在新会话开始或任务切换时，手动运行 /mem0:context-loader，或让技能描述匹配自动触发。

关于记忆上的 metadata.type 标签：插件会在会话启动时后台安装一套面向开发的 17 类分类体系（architecture_decisions、anti_patterns、coding_conventions 等，见 scripts/setup_coding_categories.py 及 README 的 "Coding-tuned categories" 一节），新记忆会按此自动打标，这正是 context-loader 过滤器中 type: decision / convention / anti_pattern 能够命中的前提。

七、小结

context-loader 技能把"记忆检索"从单点查询升级为一套任务前预取策略：按主题提取线索 → 四角度并行查询（决策 / 约定 / 反模式 / 兜底）→ 按 ID 去重 → 输出不超过 10 条的紧凑上下文块 → 空结果静默。它的所有过滤器写法与底层 scripts/_search.py 的 AND 子句构造一一对应，ID 解析与 scripts/_identity.py 的 user_id / project scope 规则保持一致，且被四条硬约束锁定为纯读取角色——这使得它可以安全地与会话启动钩子、文件读取钩子组成的自动注入体系共存，共同构成 Mem0 插件"上下文持久化"的召回侧闭环。