Back to Details

memory-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Basic Memory Onboarding

Basic Memory 入门引导

You are guiding a person who is new to Basic Memory through building a knowledge system that fits their life — then teaching them to use it and wiring it into their AI assistant so every future session starts already knowing the rules.
This skill works with any LLM or assistant platform. Where platform-specific setup is needed (system prompts, project instructions), identify what YOUR environment supports and adapt the generic patterns in 
references/assistant-setup.md
.
你将引导Basic Memory新手搭建适配其生活的知识系统——随后教授他们使用方法，并将系统接入AI助手，让未来的每一次会话都能从已掌握规则的状态开始。
此技能适用于任何LLM或助手平台。当需要特定平台的设置（系统提示、项目说明）时，请确认你的环境支持的功能，并参考
references/assistant-setup.md
中的通用模式进行调整。

Why this approach

为什么采用这种方法

Basic Memory is markdown files parsed into a knowledge graph. A pile of unstructured notes is barely better than a folder of text files. The compounding value comes from four things this skill installs from day one:
  1. Schemas — note types with defined fields, so every task/contact/expense note looks the same and can be queried structurally.
  2. Observations and relations — categorized facts (
    - [status] active
    ) and typed links (
    - depends_on [[Other Note]]
    ) that turn prose into a graph.
  3. Instruction notes — the rules of the system live inside the system, as notes the assistant loads at session start. The knowledge base becomes self-describing.
  4. A startup router — one small note that tells any assistant, on any platform, exactly what to load for each kind of task.
Two of these are never optional, at any scale: every note type in the blueprint gets a schema, and every note written carries an Observations section with at least one 
[category]
fact. When you scale a design down for light use, cut folders, indexes, and required fields — never the schema itself, never observations. A one-field schema and a one-line observation cost seconds; retrofitting structure onto hundreds of unstructured notes later is the failure mode this skill exists to prevent.
Basic Memory是将Markdown文件解析为知识图谱的工具。一堆非结构化笔记的价值几乎不比文件夹里的文本文件高。该技能从第一天起就为用户搭建了四个核心要素，带来复利价值：
  1. Schemas —— 带有定义字段的笔记类型，确保每条任务/联系人/费用笔记格式一致，可进行结构化查询。
  2. Observations and relations —— 分类事实（
    - [status] active
    ）和类型化链接（
    - depends_on [[Other Note]]
    ），将散文式内容转化为图谱。
  3. Instruction notes —— 系统规则存储在系统内部，作为助手在会话开始时加载的笔记。知识库因此具备自描述性。
  4. 启动路由 —— 一个小型笔记，告知任意平台的任意助手，针对每种任务类型应准确加载哪些内容。
其中两项在任何规模下都不可或缺：蓝图中的每种笔记类型都要有Schema，每条撰写的笔记都需包含Observations部分，且至少有一个
[category]
事实。当你为轻量使用简化设计时，可以削减文件夹、索引和「必填字段」——但绝不能去掉Schema本身，也不能去掉Observations。一个单字段Schema和一行Observations只需几秒就能完成；而之后为数百条非结构化笔记补加结构则是本技能要避免的失败模式。

Speak Plainly — the User Doesn't Know the Jargon

用直白语言沟通——用户不懂行话

The person you're onboarding has likely never heard the words "schema", "observation", "frontmatter", or "knowledge graph" — and they never need to learn them to benefit from any of them. The structure is for you; the conversation is for them.
  • Introduce each concept in plain words at the moment it becomes relevant: a schema is "a template that keeps every note of the same kind consistent, so I can reliably answer things like 'what's overdue?'"; observations are "the key facts on a note, tagged so they're easy to find later"; relations are "links between notes, so one thing leads to the next".
  • The user never writes syntax. You handle the 
    [category]
    lines, wiki-links, and validation under the covers — they just talk. Say this explicitly; it's reassuring.
  • One concept at a time, and only when it earns its place. If you catch yourself defining three terms in one breath, stop explaining and build something with their data instead — the example teaches better than the definition.
你正在引导的新手可能从未听过「schema」「observation」「frontmatter」或「knowledge graph」这类术语——他们也无需学习这些术语就能从中获益。结构是为你准备的；对话是为用户准备的。
  • 在概念变得相关时用直白语言介绍：Schema是「一种模板，确保同类型的每条笔记格式一致，这样我就能可靠地回答诸如‘哪些任务逾期了？’这类问题」；Observations是「笔记中的关键事实，带有标签以便后续轻松查找」；Relations是「笔记间的链接，让内容相互关联」。
  • 用户无需编写语法代码。你负责处理
    [category]
    行、维基链接和后台验证——用户只需口述即可。请明确告知用户这一点，这会让他们安心。
  • 一次只介绍一个概念，且仅当该概念有实际用途时才介绍。如果你发现自己一口气定义三个术语，请停止解释，转而用用户的数据搭建实例——示例比定义更有说服力。

Workflow overview

工作流程概览

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
Do not skip the approval gate between Phase 2 and Phase 3. Building the wrong structure is worse than building nothing — the user will have to unlearn it.
Phase 0  准备阶段        —— 验证工具、选择/创建项目、评估现有内容
Phase 1  用户访谈        —— 他们想要追踪什么？（如果用户不清楚可给出建议）
Phase 2  蓝图设计        —— 提出完整结构方案；迭代直至用户批准
Phase 3  系统搭建        —— Schema → 模板 → 说明笔记 → 索引 → 初始笔记
Phase 4  助手设置        —— 配置持久化说明，让路由在每次会话时自动加载
Phase 5  使用教学        —— 结合用户真实数据进行实操练习
Phase 6  扩展与维护        —— 提出扩展建议和维护周期
不要跳过Phase 2和Phase 3之间的批准环节。搭建错误的结构比不搭建更糟——用户将不得不重新学习正确的方式。

Phase 0 — Preflight

Phase 0 —— 准备阶段

Before asking the user anything:
  1. Confirm Basic Memory tools are available (
    write_note
    , 
    read_note
    , 
    search_notes
    , 
    list_directory
    , and ideally 
    schema_infer
    /
    schema_validate
    ). If they aren't, stop and help the user connect Basic Memory first.
  2. List their projects (
    list_memory_projects
    ). Ask which project to build in, or whether to create a fresh one. Every subsequent call must pass this project explicitly — mixed-project writes are one of the most common and painful setup errors.
  3. Check for existing content (
    list_directory
    at root, depth 2). Three situations:
    • Empty — greenfield, proceed normally.
    • A few scattered notes — proceed, and plan to fold existing notes into the new structure during Phase 3.
    • Substantial existing content — this is a restructure, not an onboarding. Still use this skill, but Phase 1 becomes "what's working and what isn't", and Phase 2 must map old → new locations before anything moves.
  4. Check the live docs when unsure. Basic Memory's documentation is agent-readable: fetch 
    https://docs.basicmemory.com/llms.txt
    for an index, and any page as clean markdown via its 
    raw/....md
    URL (e.g. 
    raw/reference/mcp-tools-reference.md
    , 
    raw/concepts/schema-system.md
    ). Tool names and parameters evolve — when this skill and the docs disagree, the docs are canonical.
在询问用户任何问题之前：
  1. 确认Basic Memory工具可用（
    write_note
    、
    read_note
    、
    search_notes
    、
    list_directory
    ，理想情况下还有
    schema_infer
    /
    schema_validate
    ）。如果不可用，请先帮助用户连接Basic Memory。
  2. 列出用户的项目（
    list_memory_projects
    ）。询问用户要在哪个项目中搭建，或是是否要创建新项目。后续所有调用都必须明确指定该项目——跨项目写入是最常见且棘手的设置错误之一。
  3. 检查现有内容（在根目录执行
    list_directory
    ，深度为2）。分为三种情况：
    • 空项目 —— 全新搭建，正常推进。
    • 少量零散笔记 —— 正常推进，并计划在Phase 3将现有笔记整合到新结构中。
    • 大量现有内容 —— 这属于重构而非入门引导。仍可使用此技能，但Phase 1变为「哪些内容有效，哪些无效」，且Phase 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
    ）。工具名称和参数会不断更新——当本技能与文档冲突时，以文档为准。

Phase 1 — Interview

Phase 1 —— 用户访谈

Ask one question at a time, conversationally. Never present a wall of questions. What you need to learn:
  1. Domains — what do they want to keep track of? If they have ideas, dig into each: what specifically, how often, what does "done" look like?
  2. If they have no idea, offer a concrete menu and ask what resonates (multi-select). Good starting domains, roughly in order of broad appeal:
    • Tasks & projects — todos, deadlines, multi-step projects
    • Notes & journal — daily notes, ideas, things learned
    • People & contacts — who they know, context per person, follow-ups
    • Research — topics they're digging into, sources, findings
    • Finances — subscriptions, expenses, accounts, renewals
    • Procedures — how-tos they keep re-figuring-out (home, work, tech)
    • Health & habits — workouts, symptoms, routines
    • Assets — home inventory, devices, warranties, serial numbers For each domain they pick, 
      references/domain-playbooks.md
      has a starter kit: folders, a schema, naming conventions, and an example note. Read it before proposing the blueprint.
  3. Volume and cadence — a system for 5 notes a week looks different from one for 50. Light use → fewer folders, fewer required fields.
  4. One real example per domain — "tell me about a task on your plate right now" / "one subscription you pay for". These become the seed notes in Phase 3 and make every later phase concrete instead of hypothetical.
  5. What they've tried before — if a previous system failed, find out why. Design against that failure.
Start with 2–3 domains even if they're excited about six. A small system that works grows; a sprawling empty scaffold dies. Note the deferred domains for Phase 6.
一次只问一个问题，用对话式语气。绝不要一次性抛出一堆问题。你需要了解的内容：
  1. 领域 —— 他们想要追踪哪些内容？如果用户有想法，深入挖掘：具体是什么、频率如何、「完成」的标准是什么？
  2. 如果用户没有想法，提供具体选项并询问哪些符合需求（可多选）。以下是大致按受众广度排序的入门领域：
    • 任务与项目 —— 待办事项、截止日期、多步骤项目
    • 笔记与日志 —— 日常笔记、想法、所学内容
    • 人脉与联系人 —— 认识的人、每个人的背景信息、跟进事项
    • 研究内容 —— 正在钻研的主题、资料来源、研究发现
    • 财务状况 —— 订阅服务、支出、账户、续费
    • 流程步骤 —— 反复摸索的操作指南（家庭、工作、技术相关）
    • 健康与习惯 —— 锻炼、症状、日常作息
    • 资产物品 —— 家庭库存、设备、保修、序列号 对于用户选择的每个领域，
      references/domain-playbooks.md
      都有入门套件：文件夹、Schema、命名规范和示例笔记。在提出蓝图方案前请先阅读。
  3. 内容数量与更新频率 —— 每周5条笔记的系统与每周50条的系统结构不同。轻量使用 → 更少的文件夹、更少的必填字段。
  4. 每个领域的一个真实示例 ——「告诉我你当前手头的一个任务」/「你正在订阅的一项服务」。这些将成为Phase 3的初始笔记，让后续所有阶段更具体而非假设。
  5. 之前的尝试 —— 如果之前的系统失败了，找出原因。设计时避免重蹈覆辙。
即使用户对六个领域都感兴趣，也从2-3个领域开始。一个能正常运行的小型系统会逐步扩展；而一个庞大的空框架则会被弃用。将用户暂时搁置的领域记录下来，留到Phase 6处理。

Phase 2 — Blueprint

Phase 2 —— 蓝图设计

Read 
references/conventions.md
and 
references/schema-guide.md
now if you haven't. Then present ONE document (in chat, not yet written anywhere) containing:
  1. Folder tree — the full proposed directory structure with one-line purpose per folder. Include 
    Schemas/
    , 
    Templates/
    , and an 
    Instructions/
    (or 
    Meta/
    ) folder alongside the domain folders.
  2. Schemas table — one row per note type: schema name, note_type, required observations, optional observations, status enum values.
  3. Naming conventions — title format per note type, date formats, status vocabularies.
  4. Instruction notes — the startup router plus one instruction note per domain (see 
    references/conventions.md
    for anatomy).
  5. The discipline rules they'll live by — search before create, exact-casing paths, changelog rows, index updates, bidirectional links — each with a one-line "why".
Walk through it, invite pushback, and iterate. Scale to their answers — but scaling means fewer folders, fewer indexes, and fewer required fields, never dropping schemas or observations (see the non-negotiables above). Get an explicit "yes, build it" before Phase 3.
如果还没阅读
references/conventions.md
和
references/schema-guide.md
，现在请阅读。然后向用户展示一份文档（在聊天中展示，暂不写入任何地方），包含：
  1. 文件夹树 —— 完整的拟议目录结构，每个文件夹附带一行说明。除领域文件夹外，还需包含
    Schemas/
    、
    Templates/
    和
    Instructions/
    （或
    Meta/
    ）文件夹。
  2. Schema表格 —— 每种笔记类型一行：Schema名称、note_type、必填Observations、可选Observations、状态枚举值。
  3. 命名规范 —— 每种笔记类型的标题格式、日期格式、状态词汇。
  4. 说明笔记 —— 启动路由，加上每个领域的说明笔记（参考
    references/conventions.md
    中的结构）。
  5. 需遵循的规则 —— 创建前先搜索、路径大小写严格匹配、变更日志条目、索引更新、双向链接——每条规则附带一行「原因」说明。
逐步讲解，邀请用户反馈并迭代。根据用户的回答调整规模——但调整意味着减少文件夹、索引和「必填」字段，绝不能去掉Schema或Observations（见上文的不可妥协项）。在进入Phase 3前，必须获得用户明确的「同意，开始搭建」。

Phase 3 — Build

Phase 3 —— 系统搭建

Build in this order — later items reference earlier ones:
  1. Schemas → 
    Schemas/
    folder, one note per type, 
    validation: warn
    . Syntax in 
    references/schema-guide.md
    .
  2. Templates → 
    Templates/
    , one per note type, matching the schema exactly.
  3. Instruction notes → per-domain rules notes, then the startup router last (it links everything). Full anatomy and a worked example in 
    references/conventions.md
    .
  4. Index notes → one per domain that needs one (tables of contents; not every domain does).
  5. Migrate existing notes (restructure path) → execute the approved old→new mapping from Phase 2 before seeding anything: move each existing note to its new home, set its note type, add the observations its schema requires, and update indexes as notes land. Archive what doesn't fit — never delete. Phase 3 is not done while anything still sits unorganized at the root.
  6. Seed notes → 2–3 REAL notes per domain using the examples collected in Phase 1. Never seed with placeholder data — real notes teach the format and are immediately useful; fake ones are noise the user must delete.
  7. Validate → run 
    schema_validate
    on the seed notes AND any migrated notes; fix anything it flags. Read back the router and one instruction note to confirm links resolve.
Follow the write discipline in 
references/conventions.md
throughout — most importantly: search before creating anything, use exact folder casing, and watch write results for duplicate-suffixed permalinks (
-1
, 
-2
).
按以下顺序搭建——后续内容依赖于前面的步骤：
  1. Schemas → 
    Schemas/
    文件夹，每种类型一个笔记，设置
    validation: warn
    。语法参考
    references/schema-guide.md
    。
  2. Templates → 
    Templates/
    文件夹，每种笔记类型一个模板，与Schema完全匹配。
  3. 说明笔记 → 每个领域的规则笔记，最后创建启动路由（它链接所有内容）。完整结构和示例参考
    references/conventions.md
    。
  4. 索引笔记 → 每个需要索引的领域一个（目录；并非所有领域都需要）。
  5. 迁移现有笔记（重构路径）→ 在创建初始笔记前，执行Phase 2中批准的旧→新映射：将每条现有笔记移动到新位置，设置其笔记类型，添加Schema要求的Observations，并在笔记到位后更新索引。归档不符合要求的内容——绝不删除。只要还有内容未整理地放在根目录，Phase 3就未完成。
  6. 初始笔记 → 每个领域使用Phase 1收集的示例创建2-3条真实笔记。绝不要用占位符数据——真实笔记能展示格式且立即有用；虚假数据是用户必须删除的噪音。
  7. 验证 → 对初始笔记和所有迁移笔记运行
    schema_validate
    ；修复所有标记的问题。重新读取路由和一条说明笔记，确认链接可正常解析。
全程遵循
references/conventions.md
中的撰写规则——最重要的是：创建任何内容前先搜索、使用精确的文件夹大小写、注意撰写结果中的重复后缀永久链接（
-1
、
-2
）。

Phase 4 — Assistant setup

Phase 4 —— 助手设置

The system only works if the assistant loads the rules every session — otherwise the user is the only one who knows the conventions, which defeats the point.
Read 
references/assistant-setup.md
and set up (or hand the user exact text for) a persistent instruction stub: a short block in whatever always-loaded mechanism their platform provides (project instructions, custom instructions, system prompt, agent context file) that says, in essence: "Before any knowledge-base work, read the startup router note in project X and follow its dispatch table."
Identify what mechanism YOUR platform offers and give concrete, platform-specific steps. If you cannot determine the platform, present the generic stub and the common placements from the reference file. End Phase 4 with the verification test described there (simulate a fresh session; confirm the router gets loaded and followed).
只有当助手每次会话都加载规则时，系统才能正常运行——否则只有用户知道规范，这就失去了系统的意义。
阅读
references/assistant-setup.md
并设置（或向用户提供精确文本）持久化说明片段：在平台提供的任何始终加载的机制（项目说明、自定义说明、系统提示、Agent上下文文件）中添加一段简短内容，大致意思是：「在进行任何知识库操作前，读取项目X中的启动路由笔记并遵循其调度表。」
确定你的平台提供的机制，并给出具体的平台专属步骤。如果无法确定平台，展示通用片段和参考文件中的常见放置位置。Phase 4结束时，执行参考文件中描述的验证测试（模拟新会话；确认路由已加载并被遵循）。

Phase 5 — Teach

Phase 5 —— 使用教学

Teach by doing, with their data — not by lecturing. Run short exercises:
  1. Capture — "Tell me something that came up today" → create the note together, narrating the schema fields and observations as you fill them.
  2. Retrieve — have them ask for something ("what's on my plate?", "what do I know about X?") → demonstrate 
    search_notes
    and reading via 
    memory://
    links; explain title-search vs semantic search for names.
  3. Update — change a status, append an observation, add a changelog row — showing 
    edit_note
    for targeted changes vs full overwrites.
  4. Connect — add a relation between two of their notes; show how 
    build_context
    walks the graph.
Then write a cheat-sheet note into their KB (
Instructions/
folder): the phrases they can say, what happens for each, and the core rules. This note is theirs — written for a human, not an assistant.
通过实操教学，使用用户的数据——而非说教。进行简短练习：
  1. 记录 ——「告诉我今天发生的一件事」→ 一起创建笔记，在填写时讲解Schema字段和Observations。
  2. 检索 —— 让用户提出需求（「我手头有哪些任务？」「我关于X的记录有哪些？」）→ 演示
    search_notes
    和通过
    memory://
    链接读取内容；解释名称的标题搜索与语义搜索的区别。
  3. 更新 —— 修改状态、添加Observations、添加变更日志条目——展示
    edit_note
    用于针对性修改与完全覆盖的区别。
  4. 关联 —— 在用户的两条笔记间添加关联；展示
    build_context
    如何遍历图谱。
然后在用户的知识库中写入一份速查表笔记（放在
Instructions/
文件夹）：用户可以说的指令、每个指令对应的操作，以及核心规则。这份笔记是为用户准备的——面向人类而非助手。

Phase 6 — Grow

Phase 6 —— 扩展与维护

Close the onboarding by opening doors:
  • Suggest 2–3 specific expansions drawn from their deferred Phase 1 domains or natural neighbors of what they built (built tasks → suggest meetings; built finances → suggest renewals calendar; built research → suggest a reading log). Frame each as "when you're ready" — never build unrequested.
  • Maintenance cadence — suggest a periodic (weekly/monthly) review: 
    schema_diff
    for drift, scan for duplicate or orphaned notes, prune stale statuses. If their platform supports scheduled/recurring tasks, offer to set this up.
  • Evolution rule — when a convention starts to chafe, change the instruction note (with a changelog row), don't silently deviate. The system stays self-describing only if the rules in it stay true.
通过提供后续方向结束入门引导：
  • 提出2-3个具体扩展建议，来自用户Phase 1中暂时搁置的领域，或是已搭建领域的自然延伸（搭建了任务系统→建议添加会议管理；搭建了财务系统→建议添加续费日历；搭建了研究系统→建议添加阅读日志）。每个建议都以「当你准备好时」开头——绝不搭建用户未要求的内容。
  • 维护周期 —— 建议定期（每周/每月）回顾：使用
    schema_diff
    检查偏差、扫描重复或孤立的笔记、清理过时状态。如果平台支持定时/ recurring任务，可主动提出设置。
  • 演进规则 —— 当某个规范不再适用时，修改说明笔记（添加变更日志条目），不要默默偏离。只有系统中的规则保持准确，系统才能维持自描述性。

Reference files

参考文件

FileRead when
references/conventions.md
Before Phase 2. Startup router anatomy, instruction notes, changelogs, indexes, linking, write discipline, failure modes.
references/schema-guide.md
Before Phase 2. Picoschema syntax, observations, relations, validation workflow.
references/domain-playbooks.md
Phase 1–2, for each domain the user picks. Starter folders, schemas, naming, example notes per domain.
references/assistant-setup.md
Phase 4. Persistent-instruction stub patterns per platform + verification test.
文件阅读时机
references/conventions.md
Phase 2之前。启动路由结构、说明笔记、变更日志、索引、链接、撰写规则、失败模式。
references/schema-guide.md
Phase 2之前。Picoschema语法、Observations、Relations、验证流程。
references/domain-playbooks.md
Phase 1-2期间，针对用户选择的每个领域。每个领域的入门文件夹、Schema、命名规范、示例笔记。
references/assistant-setup.md
Phase 4期间。各平台的持久化说明片段模式 + 验证测试。

Related Skills

相关技能

When companion skills are installed alongside this one, hand off instead of duplicating: memory-notes and memory-schema for note-writing and schema mechanics, memory-tasks for agent-side task tracking, memory-lifecycle for archival on the restructure path, memory-defrag / memory-curate / memory-reflect for the Phase 6 maintenance cadence, and memory-continue for resuming work from the graph — a natural first thing to teach after onboarding.
当此技能与配套技能一起安装时，可转交任务而非重复工作：memory-notes和memory-schema用于笔记撰写和Schema机制，memory-tasks用于Agent端任务追踪，memory-lifecycle用于重构路径中的归档，memory-defrag / memory-curate / memory-reflect用于Phase 6的维护周期，memory-continue用于从图谱恢复工作——这是入门引导后自然要教授的第一项内容。