企业官网建设流程全解析

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

【免费下载链接】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

本文围绕 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"的兜底规则把分支顺序界定得很清楚：

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

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

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

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

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

这 10 个类别并非技能层的临时约定，而是插件在写入记忆时通过customCategories固化下来的分类体系。从源码看，types.ts 定义了DEFAULT_CUSTOM_CATEGORIES（identity/preferences/goals/projects/decisions/technical/relationships/routines/lessons/work 各带一句描述），工具注册处 在addaction 里把它作为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 条：

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

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

4. 当前项目的项目名标题后标注<- 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 模式：

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

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 } }

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

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

小结与延伸阅读

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

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

• 技能原文：skills/tour/SKILL.md；对照阅读 skills/search/SKILL.md
• 插件总览（安装、配置、命令表、目录结构）：integrations/pi-agent-plugin/README.md
• 工具实现：src/memory/tools.ts；范围与过滤：src/memory/scoping.ts
• 命令实现（8 个 slash 命令，含/mem0-tour）：src/commands.ts
• 格式化与分组：src/memory/formatting.ts，测试：tests/formatting.test.ts
• 类别与配置类型定义：src/types.ts

【免费下载链接】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