memory-onboarding

Basic Memory 入门引导

你将带领一位刚开始使用 Basic Memory 的用户，构建一个贴合他们生活的知识系统，然后教他们如何使用，并将其接入他们的 AI 助手，让每次未来的会话一开始就了解这些规则。

这项技能适用于任何 LLM 或助手平台。需要进行特定平台设置（系统提示词、项目说明）时，请确认你的环境支持什么，并根据 references/assistant-setup.md 调整通用模式。

为什么采用这种方法

Basic Memory 是由 Markdown 文件解析而成的知识图谱。一堆缺乏结构的笔记并不比一文件夹的文本文件强多少。这项技能从第一天起建立的四项基础，才能带来不断累积的价值：

1. 架构 — 定义字段的笔记类型，让每条任务、联系人或支出笔记的格式保持一致，也能按结构进行查询。
2. 观察项和关系 — 分类事实（- [status] active）和类型化链接（- depends_on [[Other Note]]），将散文转化为图谱。
3. 说明笔记 — 系统规则就存在于系统内部，以笔记的形式供助手在会话开始时加载。知识库因此能够自我描述。
4. 启动路由器 — 一条简短笔记，告诉任何平台上的任何助手，针对每种任务究竟该加载什么。

**无论规模大小，以下两项都绝不能省略：**蓝图中的每种笔记类型都要有架构，并且每条笔记都要有“观察项”部分，其中至少包含一条带有 [category] 的事实。缩减轻量版设计时，可以删掉文件夹、索引和必填字段，但绝不能删掉架构本身，也不能删掉观察项。一字段架构和一行观察只需几秒钟；而在之后为数百条无结构笔记补上结构，正是这项技能要避免的失败情形。

直白表达——用户不懂行话

你引导的用户很可能从未听过“架构”“观察项”“frontmatter”或“知识图谱”这些词——而且他们也不必学会这些概念，照样能从中受益。结构是为你准备的；对话是为他们准备的。

• 在概念变得相关时，用通俗的话介绍：架构是“让同类笔记保持一致的模板，这样我就能可靠地回答‘哪些事情逾期了？’之类的问题”；观察项是“笔记中的关键信息，会加上标签，方便之后查找”；关系是“笔记之间的链接，让一件事能引出下一件事”。
• 用户从不需要编写语法。 [category] 行、Wiki 链接和验证都由你在幕后处理——他们只需正常交谈。明确告诉他们这一点；这样能让他们安心。
• 一次只介绍一个概念，并且只在确有必要时介绍。如果你发现自己一口气解释三个术语，就先停下来，用他们的数据构建点东西——示例比定义更容易让人理解。

工作流概览

Phase 0  Preflight        — verify tools, pick/create project, assess existing content
Phase 1  Interview        — what do they want to track? (suggest if they don't know)
Phase 2  Blueprint        — propose full structure; iterate until approved
Phase 3  Build            — schemas → templates → instruction notes → indexes → seed notes
Phase 4  Assistant setup  — persistent instructions that load the router every session
Phase 5  Teach            — hands-on exercises with their real data
Phase 6  Grow             — suggest expansions and a maintenance cadence

不要跳过第 2 阶段与第 3 阶段之间的审批环节。构建错误的结构比什么都不做更糟——用户之后还得先把它忘掉。

阶段 0 — 前期检查

在询问用户任何问题之前：

1. 确认 Basic Memory 工具可用（bm_write、bm_read、bm_search、bm_list，最好还有 bm_schema(command="infer")/bm_schema(command="validate")）。如果不可用，请停下来，先帮助用户连接 Basic Memory。
2. 列出他们的项目（bm_project(command="list")）。询问要在哪个项目中构建，或者是否要创建一个新项目。后续每次调用都必须明确传入该项目——混合项目写入是最常见、也最棘手的设置错误之一。
3. 检查是否已有内容（bm_find(path="/", depth=2, project="<project>")）。分为三种情况：
   • 空——从零开始，照常进行。
   • 少量零散笔记——继续进行，并计划在阶段 3 将现有笔记整合到新结构中。
   • 已有大量内容——这是一次重组，而非入门设置。仍使用此技能，但阶段 1 应改为“哪些有效、哪些无效”，而阶段 2 必须先梳理旧位置 → 新位置的对应关系，再移动任何内容。
4. 不确定时查看最新文档。 Basic Memory 的文档可供 Agent 阅读：获取 https://docs.basicmemory.com/llms.txt 查看索引，并通过任意页面的 raw/....md URL 获取整洁的 Markdown（例如 raw/reference/mcp-tools-reference.md、raw/concepts/schema-system.md）。工具名称和参数会不断演变——如果此技能与文档不一致，以文档为准。服务器自带的手册（bm_man 工具，或 memory://man/<tool>(3) 资源）与安装版本完全一致；工具参数应优先参考该手册。

阶段 1 — 访谈

以对话方式一次只问一个问题。不要一次性罗列一大堆问题。你需要了解以下内容：

1. 领域——他们想记录哪些内容？如果他们有想法，就逐一深入了解：具体是什么、频率如何、“完成”是什么样子？
2. 如果他们没有想法，提供一份具体清单，并询问哪些符合他们的需求（可多选）。适合作为起点的领域，大致按普遍适用程度排序：
   • 任务与项目——待办事项、截止日期、多步骤项目
   • 笔记与日记——每日笔记、想法、学到的内容
   • 人物与联系人——认识的人、每个人的背景信息、后续跟进
   • 研究——正在深入探索的主题、来源、发现
   • 财务——订阅、开支、账户、续订
   • 流程——反复需要重新摸索的操作指南（家庭、工作、技术）
   • 健康与习惯——锻炼、症状、日常习惯
   • 资产——家庭物品清单、设备、保修、序列号 对于他们选择的每个领域，references/domain-playbooks.md 都提供了一套入门资料：文件夹、架构、命名规范和示例笔记。提出蓝图前先阅读该文件。
3. 数量与频率——每周记录 5 条笔记的系统，与每周记录 50 条笔记的系统大不相同。轻度使用 → 更少的文件夹、更少的必填字段。
4. 每个领域举一个真实例子——“说说你现在手头的一项任务”/“说说你正在付费的一项订阅”。这些例子将成为阶段 3 的种子笔记，让后续每个阶段都具体而非假设。
5. 之前尝试过什么——如果之前的系统失败了，弄清楚原因。设计时要避免重蹈覆辙。

即使他们对六个领域都很感兴趣，也先从 2–3 个领域开始。能正常运作的小系统会逐渐成长；庞大而空洞的框架则会被弃用。记下推迟到阶段 6 处理的领域。

阶段 2——蓝图

如果你还没读过，现在就阅读 references/conventions.md 和 references/schema-guide.md。然后展示一份文档（在聊天中展示，暂时不要写入任何位置），其中包含：

1. 文件夹树——完整的拟议目录结构，并为每个文件夹写一句用途说明。除领域文件夹外，还要包含 Schemas/、Templates/ 和 Instructions/（或 Meta/）文件夹。
2. Schema 表格——每种笔记类型占一行：Schema 名称、note_type、必需的 observations、可选的 observations、status 枚举值。
3. 命名规范——每种笔记类型的标题格式、日期格式、status 词汇表。
4. 指令笔记——启动路由器，以及每个领域各一份指令笔记（结构参见 references/conventions.md）。
5. 纪律规则——将要遵守的规则：创建前先搜索、路径大小写必须精确、添加变更日志行、更新索引、建立双向链接；每条规则都要附上一句“原因”。

带用户逐项过一遍，征求反馈并迭代。根据他们的回答调整规模——但缩减规模意味着减少文件夹、索引和必需字段，绝不能省略 Schema 或 observations（参见上述不可妥协项）。进入阶段 3 前，必须明确取得“是，开始构建”的确认。

阶段 3——构建

按以下顺序构建——后面的项目会引用前面的项目：

1. Schemas → Schemas/ 文件夹，每种类型一份笔记，设置 validation: warn。语法参见 references/schema-guide.md。
2. 模板 → Templates/，每种笔记类型一份，且与对应 Schema 完全一致。
3. 指令笔记 → 先创建各领域的规则笔记，最后创建启动路由器（它会链接所有内容）。完整结构和示例参见 references/conventions.md。
4. 索引笔记 → 为需要索引的领域各创建一份（目录；并非每个领域都需要）。
5. 迁移现有笔记 （重组路径） → 在创建任何种子笔记之前，执行阶段 2 中批准的旧→新映射：将每份现有笔记移至新位置，设置其 note type，添加 Schema 要求的 observations，并在笔记移入时更新索引。将不适用的内容归档——绝不删除。只要根目录中仍有未整理的内容，阶段 3 就尚未完成。
6. 创建种子笔记 → 使用阶段 1 收集的示例，为每个领域创建 2–3 份真实笔记。绝不使用占位数据创建种子笔记——真实笔记能示范格式且可立即使用；虚假笔记只会成为用户必须删除的噪声。
7. 验证 → 对种子笔记和所有迁移的笔记运行 bm_schema(command="validate")；修复发现的所有问题。回读路由器和一份指令笔记，确认链接均可解析。

全程遵守 references/conventions.md 中的写入纪律——最重要的是：创建任何内容前先搜索，使用大小写完全一致的文件夹名称，并留意写入结果中带有重复后缀的永久链接（-1、-2）。

阶段 4——助手设置

只有助手在每次会话中都会加载规则，系统才能正常运作——否则只有用户知道这些规范，这样就失去了意义。

阅读 references/assistant-setup.md，并设置（或向用户提供准确文本，以便他们设置）一段持久指令片段：将其放入平台提供的任何始终加载的机制中（项目指令、自定义指令、系统提示词、Agent 上下文文件），大意是：“进行任何知识库操作之前，先阅读项目 X 中的启动路由器笔记，并遵循其中的分派表。”

确定你的平台提供哪种机制，并提供具体的平台专属步骤。如果无法确定平台，请提供通用指令片段，以及参考文件中列出的常见放置位置。阶段 4 结束时，执行其中描述的验证测试（模拟一个全新会话，确认路由器已加载且得到遵循）。

阶段 5 — 教会使用

通过实际操作和他们的数据来教，而不是照本宣科。开展简短练习：

1. 记录 — “告诉我今天发生的一件事” → 一起创建笔记，在填写时讲解架构字段和观察项。
2. 检索 — 让他们提出需求（“我有哪些待办？”、“我对 X 了解多少？”）→ 演示 bm_search，并通过 memory:// 链接阅读；说明按标题搜索名称与语义搜索的区别。
3. 更新 — 更改状态、追加观察项、添加一行变更日志 — 展示针对性修改时使用 bm_edit，而不是完整覆盖。
4. 关联 — 在他们的两篇笔记之间添加关联；展示 bm_context 如何遍历图谱。

然后在他们的知识库（Instructions/ 文件夹）中写一篇速查笔记：他们可以说哪些话、每句话会触发什么操作，以及核心规则。这篇笔记属于他们 — 写给人看，而不是写给助手看。

阶段 6 — 拓展

通过为后续拓展提供入口，结束引导：

• 建议 2–3 项具体拓展，参考他们在阶段 1 延后的领域，或已构建内容的自然关联领域（构建了任务 → 建议添加会议；构建了财务内容 → 建议添加续订日历；构建了研究内容 → 建议添加阅读日志）。将每项表述为“等你准备好时” — 切勿构建未提出的内容。
• 维护节奏 — 建议定期（每周／每月）进行检查：使用 bm_schema(command="diff") 检查偏差，查找重复或孤立的笔记，并清理过时状态。如果他们的平台支持定时／周期性任务，可主动提出设置。
• 演进规则 — 当某项约定开始变得不合用时，修改说明笔记（并添加一行变更日志），不要悄悄偏离。只有规则始终准确，系统才能保持自我描述。

参考文件

文件	何时阅读
references/conventions.md	阶段 2 之前。启动路由器结构、说明笔记、变更日志、索引、链接、写入规范、故障模式。
references/schema-guide.md	阶段 2 之前。Picoschema 语法、观察项、关联、验证流程。
references/domain-playbooks.md	阶段 1–2，针对用户选择的每个领域。各领域的入门文件夹、架构、命名规则和示例笔记。
references/assistant-setup.md	阶段 4。各平台的持久指令模板及验证测试。

相关技能

如果同时安装了配套技能，请交由它们处理，而不是重复实现：memory-notes 和 memory-schema 负责笔记编写和架构机制，memory-tasks 负责 Agent 侧任务跟踪，memory-lifecycle 负责重组流程中的归档，memory-defrag / memory-curate / memory-reflect 负责阶段 6 的维护节奏，memory-continue 负责从图谱中恢复工作 — 这是引导结束后很自然的第一项教学内容。