mem0 pi-agent-plugin Tour 技能详解：按类别浏览记忆库的完整流程与源码实现

2026-09-04 13:05:23作者：仰钰奇

本文围绕 tour/SKILL.md 展开，讲解 mem0 pi-agent-plugin 中 "Memory Tour" 技能如何把 Mem0 中存储的全部记忆按类别分组、逐条完整呈现给用户：包括单项目全量 Tour、--all-projects 跨项目 Tour、带查询词的 Search 模式三种运行方式的执行步骤与输出格式，并结合工具注册实现、范围隔离实现和格式化实现的源码，说明这些步骤在插件内部的真实调用链与边界保护机制。读完本文，你可以复现 Tour 技能的完整流程、理解其背后 mem0_memory 工具（get_all / search 等 action）的参数与过滤逻辑，并知道如何把 Tour 与搜索、置顶、整合等技能组合成一套记忆管理工作流。

什么是 Memory Tour

tour 技能的 frontmatter 将其定位为：

Browses all stored memories grouped by category with full content display. Use when reviewing all memories, exploring stored knowledge, onboarding to a new session, or getting an overview of what the agent remembers.

即它不是快速检索，而是一次"记忆库导览"：向用户展示 Mem0 里到底存了什么，并按类别（category）分组、展示完整内容。技能文档给出了三个典型触发场景：

审查全部记忆（reviewing all memories）——检查记忆质量、发现过期或重复条目，为 /mem0-dream 整合做铺垫；
探索已存知识（exploring stored knowledge）——了解 agent 记住了哪些偏好、目标、决策；
新会话上手（onboarding to a new session）——在一个新的 agent 会话中快速获得"agent 记得什么"的全景概览。

tour 是 pi-agent-plugin README 所列 8 个技能之一，与 context-loader、remember、search、forget、dream、pin、status 配套，分别对应会话预取、存、查、删、整合、保护、诊断。其中 tour 的定位是"完整导览"，明确比 search 技能更重：search 输出紧凑单行结果，tour 则展示完整记忆文本。

三种运行模式：一条命令的三条分支

tour 技能的核心是一条 /mem0-tour 命令在不同参数形态下进入三种模式，文档用两段"If ... NOT present"的兜底规则把分支顺序界定得很清楚：

参数形态	模式	底层动作	输出特征
`/mem0-tour <query>`	Search 模式	`mem0_memory` 的 `action="search"`、`query=<query>`	紧凑单行结果（同 search 技能）
`/mem0-tour --all-projects`	Cross-project 模式	`mem0_memory` 的 `action="get_all"`、`scope="global"`，不加项目过滤	先按项目分组、再按类别分组
`/mem0-tour`	单项目全量 Tour	`mem0_memory` 的 `action="get_all"`	按类别分组、完整文本

分支优先级：先看是否有查询词，再看是否有 --all-projects 标志，两者都没有才走单项目全量 Tour。下面逐条展开文档中的原始规则。

单项目全量 Tour（默认流程）

文档给出 5 个步骤，此处完整继承并逐条讲解。

Step 1: Fetch ALL memories —— 使用 mem0_memory 工具，action="get_all"。不带 query，也不限制条数，把当前范围内的全部记忆拉回来。

Step 2: Group by category —— 用每条记忆的 categories 字段分组，并映射为展示名。文档给出的映射表如下（未命中任何已知类别时一律显示为 Other）：

Category	Display name
`identity`	Identity & Background
`preferences`	Preferences
`goals`	Goals & Aspirations
`projects`	Projects & Initiatives
`decisions`	Decisions
`technical`	Technical Knowledge
`relationships`	People & Relationships
`routines`	Routines & Workflows
`lessons`	Lessons Learned
`work`	Work & Professional
anything else	Other

这 10 个类别并非技能层的临时约定，而是插件在写入记忆时通过 customCategories 固化下来的分类体系。从源码看，types.ts 定义了 DEFAULT_CUSTOM_CATEGORIES（identity/preferences/goals/projects/decisions/technical/relationships/routines/lessons/work 各带一句描述），工具注册处在 add action 里把它作为 customCategories 传给 mem0.add(...)，因此 Mem0 服务端分类时就按这套体系打标，tour 技能的分组表与之天然对齐。

Step 3: Display results —— 分组按记忆数量降序排列，每个分组按如下格式输出：

## <display_name> (<count> memories)
- <full_memory_content> (<date>)
- ...

文档对展示深度有两条硬性要求：每条记忆展示完整文本，不得截断；单个分组超过 10 条时只展示按时间倒序的前 10 条，并标注 ... and <N> more。

Step 4: Print totals —— 结尾输出总量统计：

<N> memories across <M> categories

Step 5: Empty state —— 若一条记忆都没有，输出固定文案：

No memories stored yet. Start a conversation — Mem0 captures learnings automatically, or use /mem0-remember to store something manually.

空态文案同时点出了两条写入路径：自动捕获（对话中自动学习）和手动 /mem0-remember，这与插件 README 中 "Automatic memory capture — learns from every conversation" 的特性一致。

Cross-project 模式（`--all-projects`）

文档对跨项目模式的规定如下，共 4 条：

使用 mem0_memory 工具，action="get_all"、scope="global" —— 不加项目过滤；
结果先按项目分组，再在每个项目内按类别分组；
输出格式：

## <project_1> (<N> memories) <- current
**Goals** — <memory content>
...

## <project_2> (<N> memories)
...

<N> memories across <M> projects

当前项目的项目名标题后标注 <- current。

这里的 scope="global" 有明确的底层语义。从 scoping.ts 看，三种 scope 对应的过滤条件为：

project（默认）：{ user_id, app_id } —— 当前项目池；
session：{ user_id, app_id, run_id } —— 仅当前会话；
global：{ user_id, app_id: "*" } —— 该用户下所有项目的记忆，app_id 用通配符匹配。

所以跨项目 Tour 之所以能"按项目分组"，正是 global 过滤把用户所有 app_id 下的记忆都取回来，再由 agent 依据每条记忆的归属项目做二次分组。而 app_id 的来源同样在源码中：detectAppId() 通过 git rev-parse --show-toplevel 取仓库根目录名（失败时退回当前目录名），这使 monorepo 内所有子目录共享同一记忆池——这也是"项目"这一分组维度的定义依据。

Search 模式（带查询词）

当 /mem0-tour 收到查询参数（例如 /mem0-tour cooking recipes）时，进入 Search 模式：

使用 mem0_memory 工具，action="search"、query=<query>；
输出紧凑单行结果，"same format as the search skill"——即 search/SKILL.md 定义的单行格式 <number>. [<category>] <content> (<date>) [mem0:<short_id>]，带 mem0:<id> 短引用；
无结果时输出：No memories matching "<query>".

也就是说，tour 带查询词时退化为一次检索而不是导览，这让 /mem0-tour 一条命令覆盖了"查一条"到"看全部"的谱系。检索侧在插件里还有相关性阈值保护：README 说明 searchThreshold（默认 0.3，可在配置文件中调整）是 /mem0-search、/mem0-forget、/mem0-pin 的最低相似度分（0–1），相似度不够的记忆不算命中，避免返回无关的"最接近"条目；命令层搜索同时启用了 rerank: true 与 topK: 10（见 commands.ts 的 searchMemories）。

底层机制：`mem0_memory` 工具与范围隔离

tour 技能全部步骤建立在 mem0_memory 工具之上。该工具在 tools.ts 中注册，支持 6 个 action，参数为 action、query?、content?、memory_id?、scope?：

action	参数要求	作用	在 tour 相关流程中的位置
`get_all`	无 query	列出当前 scope 内全部记忆	Tour 的 Step 1（单项目与跨项目）
`search`	`query` 必填	语义检索	tour 的 Search 模式
`add`	`content` 必填	存新记忆，自动套用 10 个 `customCategories`	与 tour 配套的手动写入路径
`update`	`memory_id` + `content`	按 ID 替换文本，保留原 ID	`/mem0-pin` 的实现（前置 `[PINNED]` 标记）
`delete`	`memory_id` 必填	删除单条	与 `/mem0-forget` 配套
`delete_all`	无	清空当前 scope（破坏性，仅明确请求）	不在 tour 流程内

get_all 的返回经 formatMemoryList 格式化后输出，details 中附带 totalCount；search 则附带 matchCount，并会记录一条含延迟与结果数的遥测事件（captureToolEvent）。

几个与 tour 直接相关的工程细节：

输出保护：工具输出统一经过 truncateOutput（tools.ts），上限 200 行 / 50 KB，超限截断并附 [Output truncated: showing X of Y lines] 提示。对记忆量大的用户，全量 Tour 时 agent 拿到的记忆列表会在此处被限制，这正是技能层要求"分组超过 10 条只展示 top 10"的合理性所在——两边共同防止输出爆炸。
scope 缺省即项目级：工具描述明确要求"正常查询不要传 scope"，省略时自动落到插件配置的 defaultScope（默认为 project），只有用户明确要求跨项目时才用 global。tour 的跨项目模式则显式传 scope="global"，与该约定一致。
格式化函数：formatting.ts 提供了 formatAge（<1 小时显示 Xm ago，<24 小时显示 Xh ago，否则 Xd ago）、formatMemoryCompact（[<cat>] <text> (<age>) [mem0:<id>] 单行格式）、formatMemoryList（编号列表）与 groupByCategory（按 categories[0] 或 uncategorized 分组）。tour 的 (<date>) 与 compact 引用都出自这里，且 tests/formatting.test.ts 对分钟/小时/天三档时间格式与单行结构做了单元测试覆盖。

实战使用方式

tour 技能面向 Pi Agent 会话内的自然交互，而命令层 /mem0-tour [scope] 提供等价的命令行入口（commands.ts 中注册，支持 project/session/global 三种 scope 参数）。插件安装与配置方式（README 原文）：

pi install npm:@mem0/pi-agent-plugin

export MEM0_API_KEY="m0-your-key-here"

或写入 ~/.pi/agent/mem0-config.json（环境变量 MEM0_API_KEY、MEM0_USER_ID 优先于配置文件）：

{
  "apiKey": "m0-your-key-here",
  "userId": "your-username",
  "autoCapture": true,
  "defaultScope": "project",
  "searchThreshold": 0.2,
  "dream": { "enabled": true, "auto": true, "minHours": 24, "minSessions": 5, "minMemories": 20 }
}

基于文档规则与源码事实，一套典型工作流是：

新会话上手：会话开始时先跑一次无参 tour，确认 agent 的项目记忆全景（此时若为空，会看到提示你用对话或 /mem0-remember 开始积累）；
定位细节：对某条感兴趣的记忆，改用 /mem0-tour <关键词> 或直接按 mem0:<id> 引用去 search 技能做精确回看——search 技能支持 UUID 形态的直接 ID 查询；
跨项目盘点：定期用 /mem0-tour --all-projects 检查同一用户在多个项目间的记忆分布，注意标题上的 <- current 标记区分当前项目；
整理闭环：tour 发现的重复/过期条目交给 /mem0-dream 整合，关键条目先 /mem0-pin 保护（其底层即 update action 加 [PINNED] 前缀，tour 里可直接辨认）。

小结与延伸阅读

tour 技能的价值在于把"记忆存在与否"的模糊感变成可审查的清单：5 步单项目流程、4 条跨项目规则、3 条检索规则共同定义了 /mem0-tour 的完整行为，而其每一步都可追溯到插件源码——get_all/search 的 action 实现、project/session/global 三级过滤、customCategories 固化的 10 类分类体系、200 行/50KB 的输出保护，构成了技能文档与实现之间的一致闭环。

延伸阅读（均为仓库内相对路径）：