memory-onboarding

Basic Memory のオンボーディング

Basic Memory を初めて使う人を案内し、その人の生活に合ったナレッジシステムを構築します。次に、その使い方を教え、AI アシスタントに組み込むことで、今後のすべてのセッションがルールを把握した状態で始まるようにします。

このスキルは、あらゆる LLM やアシスタントプラットフォームで使えます。プラットフォーム固有の設定（システムプロンプト、プロジェクトの指示）が必要な場合は、お使いの環境で何がサポートされているかを確認し、references/assistant-setup.md の汎用パターンを適宜調整してください。

このアプローチを採用する理由

Basic Memory は、ナレッジグラフとして解析される Markdown ファイルです。構造化されていないメモの山は、テキストファイルのフォルダーより少しましな程度です。価値を積み重ねていくために、このスキルでは初日から次の4つを導入します。

1. スキーマ — フィールドが定義されたメモの種類です。タスク、連絡先、支出などのメモがすべて同じ形式になり、構造に基づいて検索できます。
2. オブザベーションとリレーション — 分類された事実（- [status] active）と型付きリンク（- depends_on [[Other Note]]）によって、文章をグラフに変えます。
3. 指示メモ — システムのルールを、セッション開始時にアシスタントが読み込むメモとして、システムの中に置きます。ナレッジベースが自己記述型になります。
4. 起動時ルーター — タスクの種類ごとに何を読み込むべきかを、どのプラットフォームのどのアシスタントにも正確に伝える、小さなメモです。

規模を問わず、次の2つは省略できません。 ブループリントに含まれるすべてのメモの種類にスキーマを用意し、作成するすべてのメモに、少なくとも1つの[category]形式の事実を含む「オブザベーション」セクションを設けます。軽い用途に合わせて設計を縮小する場合は、フォルダー、索引、必須フィールドを減らしてください。スキーマそのものやオブザベーションは決して省略しないでください。フィールドが1つだけのスキーマと1行のオブザベーションなら、数秒で作成できます。一方、構造のないメモが何百件もできてから構造を後付けするのは、このスキルで防ごうとしている失敗パターンです。

わかりやすい言葉で話す — ユーザーは専門用語を知りません

オンボーディングする相手は、「スキーマ」「オブザベーション」「フロントマター」「ナレッジグラフ」という言葉を聞いたことがない可能性が高く、これらの恩恵を受けるために覚える必要もありません。構造はあなたのためのものです。会話は相手のためのものです。

• それぞれの概念が必要になったときに、わかりやすい言葉で説明してください。スキーマは「同じ種類のメモをすべて一貫した形式に保つテンプレートです。そうすれば、『期限を過ぎているものは？』といった質問に確実に答えられます」。オブザベーションは「後で見つけやすいようにタグを付けた、メモの重要な事実です」。リレーションは「メモ同士をつなぐリンクで、ある項目から次の項目へたどれるようにします」です。
• ユーザーに構文を書かせてはいけません。 [category]の行、Wiki リンク、検証は、裏側であなたが処理します。ユーザーは話すだけです。このことをはっきり伝えてください。安心してもらえます。
• 概念は一度に1つだけ、必要になったときに説明してください。一息に3つの用語を定義しようとしていることに気づいたら、説明をやめて、相手のデータを使って何かを作りましょう。定義よりも例のほうが、理解につながります。

ワークフローの概要

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つです。
   • 空 — 新規構築として、通常どおり進めます。
   • 少数のメモが散在 — そのまま進め、フェーズ 3 で既存のメモを新しい構成に取り込む計画を立てます。
   • 既存のコンテンツがかなりある — これはオンボーディングではなく、再構成です。このスキルを引き続き使いますが、フェーズ 1 では「何がうまくいっていて、何がうまくいっていないか」を確認し、フェーズ 2 では移動の前に、古い場所から新しい場所への対応関係を整理する必要があります。
4. 不明点があれば、最新のドキュメントを確認します。 Basic Memory のドキュメントはエージェントが読み取れる形式です。インデックスは 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. アイデアがない場合は、具体的な選択肢を提示し、どれがよさそうか尋ねます（複数選択可）。幅広い人に向いている分野を、おおむねおすすめ順に示します。
   • タスクとプロジェクト — ToDo、期限、複数ステップのプロジェクト
   • メモと日記 — 日々のメモ、アイデア、学んだこと
   • 人と連絡先 — 知り合い、人物ごとの背景、フォローアップ
   • リサーチ — 調査中のトピック、情報源、調査結果
   • 財務 — サブスクリプション、支出、口座、更新
   • 手順 — 何度も調べ直している方法（家庭、仕事、テクノロジー）
   • 健康と習慣 — トレーニング、症状、ルーティン
   • 資産 — 家庭内の備品、デバイス、保証、シリアル番号 選んだ各分野について、references/domain-playbooks.md にフォルダー、スキーマ、命名規則、メモの例を含むスターターキットがあります。設計案を提示する前に、これを読んでください。
3. 量と頻度 — 週に5件のメモを扱うシステムと、50件を扱うシステムでは設計が異なります。利用頻度が低い場合は、フォルダーや必須フィールドを少なくします。
4. 分野ごとに実例を一つ — 「今抱えているタスクについて教えてください」／「支払っているサブスクリプションを一つ教えてください」のように尋ねます。これらをフェーズ 3 の種となるメモとして使うことで、以降の各フェーズを仮定ではなく具体的な内容にできます。
5. これまでに試したこと — 以前のシステムがうまくいかなかった場合は、その理由を確認します。その失敗を避けられるように設計します。

6つの分野に興味があっても、まずは2〜3分野から始めます。うまく機能する小さなシステムは成長しますが、使われない大規模な枠組みは放置されます。後回しにする分野は、フェーズ 6 で扱えるよう記録しておきます。

フェーズ 2 — ブループリント

まだ読んでいない場合は、今すぐ references/conventions.md と references/schema-guide.md を読んでください。その後、以下を含むドキュメントを1つ提示してください（チャット内で提示し、まだどこにも書き込まないでください）。

1. フォルダーツリー — 提案するディレクトリ構造全体と、各フォルダーの目的を1行で記載します。ドメインフォルダーと並べて、Schemas/、Templates/、Instructions/（または Meta/）フォルダーも含めてください。
2. スキーマ表 — ノートの種類ごとに1行ずつ記載します。スキーマ名、note_type、必須の観察事項、任意の観察事項、ステータスの列挙値を含めてください。
3. 命名規則 — ノートの種類ごとのタイトル形式、日付形式、ステータスの語彙を記載します。
4. 指示ノート — 起動時のルーターと、ドメインごとに1つの指示ノートを記載します（構成については references/conventions.md を参照してください）。
5. 守るべき規律のルール — 作成前の検索、パスの大文字・小文字の完全一致、変更履歴の行、インデックスの更新、双方向リンクを含め、それぞれに「理由」を1行で添えてください。

内容を順に確認し、意見を求めながら反復してください。回答に応じて規模を調整します。ただし、調整で減らすのはフォルダー、インデックス、必須フィールドに限り、スキーマや観察事項は決して省略しないでください（上記の必須事項を参照）。フェーズ 3 に進む前に、明示的な「はい、作成してください」を得てください。

フェーズ 3 — 構築

後続の項目が先行する項目を参照するため、次の順序で構築してください。

1. スキーマ → Schemas/ フォルダーに、種類ごとに1つのノートを作成し、validation: warn を設定します。構文については references/schema-guide.md を参照してください。
2. テンプレート → Templates/ に、スキーマと完全に一致するテンプレートを種類ごとに1つ作成します。
3. 指示ノート → ドメインごとのルールノートを作成し、最後にそれらすべてへリンクする起動時のルーターを作成します。完全な構成と実例については references/conventions.md を参照してください。
4. インデックスノート → 必要なドメインごとに1つ作成します（目次として機能します。すべてのドメインに必要なわけではありません）。
5. 既存ノートの移行 (再構成の手順) → 何かを追加登録する前に、フェーズ 2 で承認された旧→新の対応表を実行します。既存のノートをそれぞれ新しい格納先に移動し、note type を設定し、スキーマで必須とされる観察事項を追加し、ノートの移動に合わせてインデックスを更新します。適合しないものはアーカイブしてください。削除してはいけません。ルートに未整理のものが残っている間は、フェーズ 3 は完了ではありません。
6. シードノート → フェーズ 1 で収集した例を使い、ドメインごとに実際のノートを2～3件追加します。プレースホルダーデータでシードしてはいけません。実際のノートは形式を示し、すぐに役立ちますが、架空のノートはユーザーが削除しなければならないノイズになります。
7. 検証 → シードノートと移行したノートの両方に対して bm_schema(command="validate") を実行し、指摘された問題を修正します。ルーターと指示ノートを1つ読み返し、リンクが解決されることを確認してください。

全工程を通じて references/conventions.md の書き込み規律に従ってください。特に重要なのは、何かを作成する前に検索すること、フォルダー名の大文字・小文字を正確に使うこと、書き込み結果で重複を示すサフィックス（-1、-2）が付いたパーマリンクに注意することです。

フェーズ 4 — アシスタントのセットアップ

アシスタントが毎回のセッションでルールを読み込まなければ、システムは機能しません。そうしなければ、規則を知っているのはユーザーだけとなり、この仕組みの意味がなくなります。

references/assistant-setup.md を読み、永続的な指示スタブを設定してください（またはユーザーに正確な文面を渡してください）。これは、プラットフォームが提供する常時読み込みの仕組み（プロジェクト指示、カスタム指示、システムプロンプト、エージェントのコンテキストファイルなど）に記載する短いブロックで、要旨は次のとおりです。「ナレッジベースに関する作業を行う前に、プロジェクト X の起動時ルーターノートを読み、その振り分け表に従ってください。」

あなたのプラットフォームで利用できる仕組みを特定し、プラットフォームに応じた具体的な手順を提示してください。プラットフォームを特定できない場合は、汎用スタブと、参照ファイルに記載されている一般的な配置場所を提示してください。フェーズ 4 の最後に、そこに記載されている検証テストを実施します（新しいセッションを模擬し、ルーターが読み込まれて従われることを確認してください）。

Phase 5 — 教える

講義するのではなく、相手のデータを使って一緒に実践しながら教えます。短い練習を行います。

1. 記録する — 「今日あったことを何か教えてください」→ 一緒にノートを作成し、入力しながらスキーマのフィールドや所見について説明します。
2. 検索する — 相手に何か質問してもらい（「今、何を抱えていますか？」「X について何を知っていますか？」など）、bm_search と memory:// リンクからの読み込みを実演します。名前を調べる場合のタイトル検索とセマンティック検索の違いも説明します。
3. 更新する — ステータスを変更し、所見を追記し、変更履歴に行を追加します。対象を絞って変更する bm_edit と、全体を上書きする方法の違いを示します。
4. つなげる — 2 つのノートの間に関連を追加し、bm_context がグラフをたどる様子を示します。

次に、KB の Instructions/ フォルダーにチートシートのノートを書き込みます。相手が使えるフレーズ、それぞれに対して何が起きるか、基本ルールを記載します。このノートは相手のためのものであり、アシスタント向けではなく、人間が読むために書きます。

Phase 6 — 発展させる

オンボーディングを締めくくり、次の可能性を示します。

• 具体的な拡張案を 2～3 個提案する — Phase 1 で保留した領域や、構築した内容に自然に関連する領域から選びます（タスクを構築した場合は会議、家計を構築した場合は更新カレンダー、調査を構築した場合は読書ログなど）。それぞれ「準備ができたら」と伝え、依頼されていないものは構築しません。
• メンテナンスの頻度 — 定期的（毎週／毎月）な見直しを提案します。bm_schema(command="diff") で差分を確認し、重複ノートや孤立したノートを探し、古いステータスを整理します。プラットフォームが定期実行タスクに対応している場合は、その設定も提案します。
• ルールの更新 — 決めごとに違和感が出てきたら、黙って逸脱するのではなく、変更履歴に行を追加して指示ノートを変更します。システムが自分自身を説明できる状態を保つには、そこに記載されたルールが実態に即している必要があります。

参考ファイル

ファイル	読むタイミング
references/conventions.md	Phase 2 の前。起動時のルーターの構成、指示ノート、変更履歴、インデックス、リンク、書き込みの規律、失敗例について。
references/schema-guide.md	Phase 2 の前。Picoschema の構文、所見、関連、検証ワークフローについて。
references/domain-playbooks.md	Phase 1～2。ユーザーが選んだ各領域について。初期フォルダー、スキーマ、命名規則、領域ごとのノート例。
references/assistant-setup.md	Phase 4。プラットフォームごとの永続的な指示のひな形と検証テスト。

関連スキル

このスキルと併せて関連スキルがインストールされている場合は、内容を重複させず、該当スキルに引き継ぎます。ノートの作成とスキーマの仕組みにはmemory-notesとmemory-schema、エージェント側でのタスク追跡にはmemory-tasks、再構成の過程でのアーカイブにはmemory-lifecycle、Phase 6 のメンテナンスにはmemory-defrag／memory-curate／memory-reflect、グラフから作業を再開するにはmemory-continueを使います。オンボーディング後に最初に教える内容としても自然です。