bm-setup

Basic Memory のセットアップ

短時間で状況に応じたインタビュー（約 2〜3 分）を実施してから、設定を書き込みます。 会話形式で進め、コンテキストから答えがすでに明らかな質問は省略してください（例：list_memory_projects にローカルプロジェクトが 1 つだけ表示され、クラウドワークスペースがない場合は、クラウドやチームについて尋ねず、そのまま確認します）。すべての質問に妥当なデフォルトを提案し、ユーザーが一言で承認できるようにします。インタビューが終わり、計画を確認するまでは、書き込みを行わないでください。

前提条件の確認

最初に、Basic Memory MCP サーバーが接続されていることを確認します — list_memory_projects を呼び出します。このツールが利用できないか、エラーが発生する場合、Basic Memory はまだ Claude Code に接続されていません。そこで停止し、まずユーザーの接続を案内してください（以下の手順はすべて接続が前提です）。

1. インストールします：uv tool install basic-memory --prerelease=allow（またはpip install basic-memory）、バージョンは >= 0.19.0 です。uv では --prerelease=allow を付けたままにしてください。公開済みリリースは FastMCP のプレリリース版に依存しており、このフラグがないと uv は古い Basic Memory リリースを警告なくインストールします。
2. 接続します：claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp を実行し、MCP サーバーが読み込まれるようにセッションを再起動します。

続行する前に list_memory_projects をもう一度確認してください。成功するまではインタビューを始めないでください。

インタビュー

推測できないことだけを尋ねます。以下を確認してください。

1. 用途／どのように使うか。 「このプロジェクトの主な用途は何ですか？ コード開発、調査、執筆、知識の記録、計画、それとも複数の組み合わせですか？」この回答に基づいて、提案するフォルダー構成（ステップ 4）を決め、SessionStart の概要に表示できるよう記録します。質問せずに推測した場合は、想定した用途と、それに対応する構成を伝え、ユーザーが一言で修正できるようにします。

   コード開発という回答の場合、コーディング用セットアップ（sessionProfile: "coding"）にします。ディレクトリが Git リポジトリ内にあることを確認し、origin リモートまたは GitHub CLI から owner/name のような安定した repository 識別子を特定してユーザーに提示し、確認を求めます。リモートがない、または曖昧な場合は推測しないでください。また、現在のディレクトリが Git チェックアウトであるというだけで coding と推測しないでください。用途が複数ある場合は、このリポジトリで Git とプルリクエストのコンテキストを記録するか確認します。コーディングプロファイルは Coding Session スキーマを設定し、明示的なチェックポイントに、検索可能な必須の Git 識別情報（リポジトリ、ブランチ、SHA、作業ディレクトリ）に加えて、プルリクエストが存在する場合は型付きのプルリクエストフィールドを記録します。

2. プロジェクトの対応付け。 「この用途に使う Basic Memory プロジェクトはすでにありますか？ それとも新しく作成しますか？」

   • 既存の場合 → list_memory_projects() の結果を表示し、ユーザーに選んでもらいます。その名前を primaryProject に設定します。
   • 新規の場合 → 名前を提案します（デフォルト：このリポジトリのディレクトリ名）。create_memory_project で作成します。
     • ローカルプロジェクト（デフォルト）：パスのデフォルトは ~/basic-memory/<name>/ です。接続されている Basic Memory サーバーならどれでも作成できます。
     • クラウドプロジェクト（クラウドワークスペースに記録したい場合）：list_workspaces のスラッグを workspace セレクターに渡し、/<name> のようなクラウド形式のパスを指定して、クラウドに接続された MCP サーバーで作成します。ローカル専用サーバー（uvx --prerelease=allow basic-memory mcp）はこのパスをローカルディレクトリとして扱い、作成に失敗します（例：読み取り専用の /）。ローカルサーバーとクラウドサーバーの両方が接続されている場合は、作成とスキーマの設定の両方をクラウドサーバー経由で行い、primaryProject には新しいプロジェクトの external_id UUID を設定します（ワークスペース間での衝突を防止できます）。

3. クラウド／チーム（追加のワークスペースがない場合はスキップ）。
   list_workspaces を実行します。ユーザーが複数のワークスペースに所属している場合は、個人用／デフォルトのワークスペースとは別に、チームワークスペースを利用している可能性があります。list_memory_projects を使って、それぞれにあるプロジェクトを確認します（注意：ワークスペース間でプロジェクト名が重複するため、必ず my-team-2/notes のようなワークスペース名付きの名前、または external_id の UUID を使用してください。名前だけを使ってはいけません）。

   • チームから読み取る（推奨）：セッションブリーフに読み込んで想起に使うチームプロジェクトを尋ねます。名前付きのプロジェクトを secondaryProjects に保存します。これらは読み取り専用です。想起時に読み取られますが、書き込みは行われません。
     上限：セッションごとに、SessionStart ブリーフが読み取る共有プロジェクトは、一覧の先頭から6 件のみです（レイテンシー／出力の上限）。6 件を超えるプロジェクトを希望する場合は、関連性の高い順に並べ、残りは設定済みでも毎回のセッションでは読み取られないことを伝えます。
   • 共有先（任意）：ユーザーが /basic-memory:bm-share を介してチームにメモを公開する場所を希望する場合は、"<qualified-name>": { "promoteFolder": "shared" } として teamProjects に追加します。共有は常に手動で行います。自動キャプチャがチームプロジェクトに書き込むことはありません。

   primaryProject には、ユーザーが自身のキャプチャに使用する、ユーザー所有のプロジェクトを設定します。チームプロジェクトは、読み取りと意図的な共有にのみ使用します。

4. 配置 — 学習または提案（プロジェクトの状態によって異なります）。目標は、新しいメモをどこに配置するかを伝える、短い placementConventions 文字列（3〜6 行）です。プロジェクトに既にメモがあるかどうかによって、取得方法が異なります。

   • メモがある既存のプロジェクト → 学習します。内容を確認します。list_directory でフォルダー構成を調べ、各フォルダーからいくつかメモをサンプルとして確認します（繰り返し登場する型付きメモを含むフォルダーでは、必要に応じて schema_infer を実行して構造を確認できます）。実際の慣習をまとめます。たとえば、トピック別のフォルダー構成、命名スタイル、よく使われる観察カテゴリなどです。実際のメモから推測し、慣習を押し付けないでください。
   • 新規または空のプロジェクト → 提案します（まだ学習できるものがありません）。手順 1 で確認した重点に合った、簡素な構成を提案します。任意のトップレベルフォルダーを 3〜5 個にとどめ、深い分類体系は作りません。これは開始点であり、ひな型ではないことを明確に伝えます。構成がなくてもメモは問題なく使え、構成は後から自然に形成されていきます。空のフォルダーは作成しないでください。フォルダーはメモが追加されると作成されます。ユーザーが一言で編集または却下できるようにします。 いずれの場合も、短くまとめて結果を placementConventions として保存します。SessionStart ブリーフにはこの内容が captureFolder とともに表示されるため、これにより、ユーザーの期待する場所にキャプチャが保存されます。設定しない場合、配置は当て推量になります。

5. スキーマ。「このプロファイル用のセッションスキーマに加えて、後で正確に見つけられるよう、決定とタスクのスキーマも追加します。よろしいですか？」（以下の「スキーマをシードする」を参照してください。）

6. ライフサイクルイベントのキャプチャ。「このプラグインでは、診断のために SessionStart イベントと PreCompact イベントのローカル記録をデフォルトで保持します。この設定を有効にしておきますか？」デフォルトはオンにします。通常のセッションブリーフと PreCompact チェックポイントは、どちらの設定でも機能します。キャプチャを有効にすると、ライフサイクルのメタデータが上限付きでローカルの受信トレイに追加され、bm hook flush でローカルにアーカイブされます。ナレッジグラフのメモは作成されません。ユーザーがオプトアウトした場合にのみ、JSON の真偽値 false を保存します。

   • キャプチャはローカルかつ個人用に保持されます。チームプロジェクトに直接書き込むことはありません。

7. どのくらい積極的に動作させますか？（出力スタイル）「積極的にキャプチャしますか？想起前にグラフを検索し、重要な決定を型付きメモとして書き込み、パーマリンクを引用しますか？それとも、セッションブリーフ、PreCompact チェックポイント、必要に応じた /basic-memory:bm-remember の実行だけにとどめますか？」有効にすると、outputStyle: "basic-memory" が設定されます。デフォルトでは有効にします。想起専用でノイズを抑えた設定にする場合は、無効のままにします（アシスタントがどの程度積極的に動作するかを決める唯一の設定項目です。フックはどちらの場合も常に実行されます）。

8. 共有スキル（任意、デフォルトは有効）。「Basic Memory のツールキット全体、つまり共有の memory-* スキル（memory-notes、memory-tasks、memory-research、 memory-schema、memory-defrag、……）も必要ですか？ このプラグインと一緒にインストールできます。」 これらは正規の、フレームワークに依存しないスキルです（OpenClaw にバンドルされているものと同じセットです）。 このプラグインには Claude-Code 固有の接続部分のみが含まれており、必要に応じて共有セットを取得します。独自のコピーは同梱していません。（「共有スキルのインストール」を参照してください。）

適用（計画を確認した後）

1. スキーマを登録する

プラグインには <plugin>/schemas/ にシード用スキーマが用意されています。これは このスキルのディレクトリから2階層上のディレクトリにある schemas/ です（このスキルは <plugin>/skills/bm-setup/ にあります）。コーディング用プロファイルの場合は coding-session.md を、一般用プロファイルの場合は session.md を読み、続けて decision.md と task.md を読みます。

これらのスキーマは、Claude 統合が直接書き込むノートを対象としています。ライフサイクルエンベロープはノートではありません。bm hook flush はその運用トレースをローカルにアーカイブするため、投影されたセッションスキーマやツール台帳スキーマを登録する必要はありません。

各スキーマについて：

• 選択したプロジェクトに、その種類のスキーマがすでにあるか確認します（metadata_filters={"type": "schema"} を指定して search_notes を使うか、read_note("schemas/<name>") を試します）。存在する場合はスキップしてください。ユーザーがカスタマイズした可能性のあるスキーマを上書きしてはいけません。
• 存在しない場合は、primaryProject を指定して write_note で書き込みます（project として渡すか、external_id が UUID の場合は project_id として渡します）。
  • directory="schemas"、note_type="schema"、title = スキーマのタイトル（Session / Decision / Task）。
  • content = Markdown の 本文のみ。--- のフロントマターブロックの後（# Session 見出しと本文）をすべて含めます。
  • metadata = スキーマの構造化フロントマターを ネストした辞書 として指定します。entity、version、schema マップ全体、settings を含めます（ネストされた frontmatter はそのまま保持し、列挙値は ["open","resumed","closed"] のような JSON 配列として渡します）。
  • スキーマの --- フロントマターを content に含めてはいけません。クラウドへの書き込みでは、このネストされた YAML が暗黙のうちに文字列 '[object Object]' に変換され、schema / settings が破損します（basic-memory-cloud#1000）。metadata パラメーターはローカルとクラウドの両方で正しく往復します。登録後、read_note(..., output_format="json", include_frontmatter=true) でノートを1つ確認します。schema / settings が文字列ではなく、ネストされたオブジェクトとして返される必要があります。
• コーディング用セットアップ： 選択した coding-session.md スキーマでは、Git 識別フィールド（repository、repo_root、cwd、branch、git_sha）は設計上必須です。必須かつ実証されたフィールドがあることでコーディングチェックポイントを検索できるため、一般用 Session スキーマも追加で登録せず、スキーマを変更せずに登録してください。

2. 共有スキルをインストールする（ユーザーが選択した場合）

まず、ソースチェックアウトを上書きしないよう確認してください。 ./skills がすでに存在し、git で追跡されていて、memory-* ディレクトリを含む場合は、スキル自体のソースリポジトリ（例：basic-memory 自体）の中にいます。インストールすると、作業コピーが公開済みのバージョンで上書きされます。その場合はインストールをスキップし、スキルがソースとしてすでに存在するとユーザーに伝えてください。コマンドを実行してはいけません。簡易チェック：

git ls-files skills/ | grep -q memory- && echo "source repo - skip install"

それ以外の場合は、次を実行します。

npx skills add basicmachines-co/basic-memory/skills -g

-g は正規の memory-* スキルをユーザーレベル（~/.claude/skills/）にインストールするため、すべてのプロジェクトで利用できます。これは OpenClaw と共有される単一の信頼できる情報源です。このプラグインはコピーを同梱せず、この共有セットに依存します。 npx / skills CLI を利用できない場合は、トップレベルの skills/README.md にある手動インストールを案内してください。

3. 設定を書き込む

聞き取り内容をもとに basicMemory ブロックを作成します。

{
  "basicMemory": {
    "primaryProject": "<chosen>",
    "secondaryProjects": [],
    "captureFolder": "sessions",
    "rememberFolder": "bm-remember",
    "recallTimeframe": "3d",
    "preCompactCapture": "extractive",
    "sessionProfile": "coding",
    "repository": "owner/name",
    "captureEvents": true,
    "placementConventions": "<learned or suggested summary, or null>",
    "teamProjects": {}
  },
  "outputStyle": "basic-memory"
}

sessionProfile は明示的に保存します。repository は、ユーザーが確認した後、coding プロファイルの場合にのみ保存します。coding_session スキーマでは照会可能な Git の識別フィールドが必須のため、リポジトリ識別子がないとコーディングのセットアップは完了しません。general のセットアップでは、両方のキーの例の値を省略します（"sessionProfile": "general"、repository なし）。

ユーザーがオプトインした場合にのみ outputStyle を含めます。これは チームのデフォルト（.claude/settings.json に書き込み／マージし、コミットを提案する）か、個人用（.claude/settings.local.json）かを確認します。既存のファイルがある場合は、マージします。ファイルを読み込み、上記のキーのみを追加／置換し、それ以外はすべて保持します。コンパクトで有効な JSON を使用します。captureEvents は必ず JSON のブール値として保存します。

basicMemory ブロックを書き込むと、SessionStart フックの初回実行時の案内も停止します。設定が存在することが、セットアップ完了のシグナルになるためです。

4. 配線をスモークテストする

終了前に、記憶の検索が実際に解決されることを確認します。これにより、プロジェクト名の誤り、クラウド認証情報の不足、ルーティングされない参照などを、ユーザーがその場で修正できるうちに検出できます。SessionStart フックと同じ構造化クエリを、フックが使う CLI（basic-memory／bm／uvx --prerelease=allow basic-memory）で実行します。

• プライマリ： primaryProject に対して … tool search-notes --type schema --page-size 10 を実行します。UUID の場合は --project-id <uuid>、それ以外の場合は --project <ref> を使用します。直前にシードしたスキーマが返るはずです。コーディングのセットアップでは、Coding Session スキーマがあることを確認します。
• 共有プロジェクトを1つ（secondaryProjects が空でない場合のみ）：最初の参照先に対して --type decision --status open クエリを実行します。問題なく実行できれば十分です。0 results は問題ありませんが、エラーになる場合は参照先がルーティングされていません。
• フックの状態： 最初に利用可能な basic-memory、bm、または uvx --prerelease=allow basic-memory ランチャーを使い、basic-memory hook status --harness claude --project-dir <project-root> を実行します。対象の設定を検出し、選択されたプロジェクトと記録状態を報告する必要があります。共有受信トレイの件数と最終フラッシュ状態をセットアップの概要に記録します。件数には、サポートされているすべてのハーネスのエンベロープが含まれます。

クエリでエラーが発生した場合、またはプライマリから何も返されない場合は、終了前にそのことを伝えてプロジェクト参照を修正します。次のセッションの概要が空にならないようにしてください。

終了

実施した内容を数行で確認します。プロジェクトの対応付け、セッションプロファイル（コーディングのセットアップの場合は確認済みのリポジトリ）、シードしたスキーマとすでに存在していたスキーマ、配置情報を学習したのか提案したのか、スモークテストの結果、ライフサイクルイベントの記録が有効かどうか、共有フックの受信トレイ／フラッシュの状態、出力スタイルが有効かどうかを含めます。

次に、出力スタイルの設定に応じて有効化を案内します。

• 出力スタイルが有効 → セッション開始時に固定されるため、完全な記録動作が有効になるのは次のセッションからです。ユーザーにセッションを再起動（新しい Claude Code セッションを開始）して有効化するよう促します。「まだ何も動作しない」と誤解されないよう、正確に説明してください。記憶の検索はこのセッションですでに有効です（SessionStart フックのプロンプトは実行済み）。PreCompact チェックポイントも今すぐ機能します。再起動を待つのは、能動的な記録動作のみです。
• 出力スタイルがオフ → 再起動は不要です。フックはすでに実行されています。

最後に、次のように伝えます。「完了です。次のメッセージからこれを使用します。いつでも /basic-memory:bm-status を実行すると、追跡中の内容を確認できます。」