obs-memory

Obsidian エージェントメモリ

セッションをまたいで保持される、グラフ構造のメモリである Obsidian ナレッジボルトを利用できます。状況を把握したり、アーキテクチャやコンポーネントの知識を参照したり、新たな発見を書き戻したりするために活用してください。

ボルトの検出

次の順にパスを解決します（最初に一致したものを使用します）。

1. 環境変数：$OBSIDIAN_VAULT_PATH
2. エージェントの設定参照：エージェントのプロジェクト設定またはグローバル設定からボルトのパスを解析します（~/Documents/SomeName/のようなパスを含む「Obsidian Knowledge Vault」セクションを探します）
3. デフォルト：~/Documents/AgentMemory

解決したパスを以降のすべての操作で$VAULTとして保存します。CLI 呼び出し用に、basename "$VAULT"から$VAULT_NAMEを導出します。

$VAULT/Home.mdを確認して、ボルトが存在することを検証します。ボルトが存在しない場合はユーザーに伝え、同梱のテンプレートから新しいボルトを作成するためにinitコマンドを実行するよう提案します。

セッション開始時 — 状況把握

各セッションの開始時に、最大2回の操作で状況を把握します。

手順1：TODOを読む

CLIを優先：

obsidian vault=$VAULT_NAME tasks path="todos" todo verbose

代替手段：$VAULT/todos/Active TODOs.mdのファイルを読みます。

保留中、進行中、および最近完了した作業を把握します。

手順2：現在のプロジェクトを検出して概要を読む

現在の作業ディレクトリからプロジェクトを自動検出します。

basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $(pwd)

次に、$VAULT/projects/*/内のファイルを一覧表示し、一致するプロジェクトがあるか確認します。Git リポジトリ名（またはディレクトリ名）とプロジェクトフォルダー名を照合します。一致するものが見つかった場合は、$VAULT/projects/{matched-name}/{matched-name}.mdにあるプロジェクト概要を読みます。

このプロジェクト概要には、すべてのコンポーネント、パターン、アーキテクチャ上の決定事項、ドメインへのウィキリンクが含まれています。リンク先のノートはまだ読まないでください。現在のタスクでその情報が必要になったときに参照します。

セッション開始時に読まないもの

• Home.md（状況を把握できず、プロジェクトも見つからない場合に限ります）
• sessions/（ユーザーが過去の作業について言及した場合に限ります）
• ドメインインデックス（プロジェクト横断の知識が必要な場合に限ります）
• コンポーネントノート（そのコンポーネントを作業するときに限ります）

自動動作

このスキルを使用するすべてのエージェントに、次の動作が適用されます。明示的なコマンドは必要ありません。

セッション開始時

上記のセッション開始手順に従い、依頼されなくてもTODOとプロジェクト概要を読み、状況を自動的に把握します。解決したパスにボルトが存在しない場合は、ユーザーに伝え、initを実行するよう提案します。

セッション終了の合図があったとき

ユーザーが「done」「wrapping up」「that's it」「let's stop」など、セッションの終了を示す言葉を使った場合は、セッションの要約を書き込むかどうかを尋ねます。自動実行はせず、まず「セッションを終了する前に、ボルトにセッションの要約を書き込みますか？」と確認します。

コンポーネントを発見したとき

ボルトノートのないコンポーネントを詳しく分析し、プロジェクトにアクティブなボルトがある場合は、インポートと依存関係から関係性を推測してコンポーネントノートを作成するか、ユーザーに確認します。例：「AuthMiddleware コンポーネントのボルトノートがないことに気づきました。作成して依存関係を整理しますか？」

初回実行時

解決したどのパスにもボルトが存在しない場合は、ユーザーにinitの実行方法を案内し、Git リポジトリ内であれば現在のプロジェクトのひな形も自動作成します。

作業中 — グラフ内の移動

原則：まずCLIクエリを使い、次にファイルを読みます。 Obsidian CLIを使うと、プロパティ、リンク、バックリンク、タグ、検索に構造化された方法でアクセスできます。ファイル全体を読むより、こちらを優先してください。

CLIを優先する参照方法（推奨）

ファイル読み込みトークンを消費せずに対象を絞って検索するには、次のCLIコマンドを使用します。

# Query a component's dependencies
obsidian vault=$VAULT_NAME property:read file="Component Name" name="depends-on"

# Find what depends on a component
obsidian vault=$VAULT_NAME property:read file="Component Name" name="depended-on-by"
obsidian vault=$VAULT_NAME backlinks file="Component Name"

# Find all outgoing links from a note
obsidian vault=$VAULT_NAME links file="Component Name"

# Find all notes of a type
obsidian vault=$VAULT_NAME tag verbose name="component"

# Search vault content
obsidian vault=$VAULT_NAME search format=json query="search term" matches limit=10

# Get note structure without full read
obsidian vault=$VAULT_NAME outline file="Component Name"

# Read a specific property
obsidian vault=$VAULT_NAME property:read file="Component Name" name="key-files"

$VAULT_NAMEはボルトフォルダーの名前（$VAULTのベース名）です。

CLI が利用できない場合のファイル読み取りによる代替

Obsidian CLI が利用できない場合は、ファイルを読み取ってください。

• コンポーネントを理解する必要がありますか？ プロジェクト概要から該当するノートにリンクされています。そのノートを読みます。
• アーキテクチャ上の決定を確認する必要がありますか？ コンポーネントのノートまたはプロジェクト概要からリンクされています。リンクをたどります。
• プロジェクト横断の知識が必要ですか？ コンポーネント／パターンのノートからドメインノートにリンクされています。リンクをたどります。
• セッション履歴が必要ですか？ 行き詰まった場合、またはユーザーが以前の作業について言及した場合にのみ読みます。

フロントマターを先に確認する

適切なノートを見つけるために複数のノートを確認する場合は、各ファイルの最初の約10行だけを読みます。フロントマターの tags、project、type、status フィールドを確認すれば、本文全体を読む前にノートが関連するかどうか判断できます。

読み取り前にディレクトリを一覧表示する

ファイルを読む前にディレクトリの内容を一覧表示し、トークンを消費せずに何があるか把握します。

• $VAULT/projects/{name}/**/*.md — プロジェクトのすべてのノート
• $VAULT/domains/{tech}/*.md — ドメイン知識ファイル

Vault への書き込み

簡潔に書きます。ノートは人間向けのドキュメントではなく、将来の自分が参照するためのものです。次の点を優先します。

• 散文より箇条書き
• 説明の繰り返しよりウィキリンク（説明を繰り返さず、リンクします）
• 冗長な説明より、見つけやすさを高めるフロントマターのタグ

書き込むタイミング

• 新しいコンポーネントを発見した場合：コードベースの一部を十分に理解したら、コンポーネントノートを作成します
• アーキテクチャ上の決定をした場合：重要な設計上の選択をしたら、ADR を記録します
• パターンを特定した場合：今後のセッションで従うべき、繰り返し使われるパターンを記録します
• ドメイン知識を得た場合：プロジェクト横断の知識を発見したら、ドメインノートに記録します

スコープのルール

知識の種類	場所	例
1つのプロジェクトのみ	projects/{name}/	この API での認証処理
複数のプロジェクトで共有	domains/{tech}/	Go のインターフェースの仕組み
技術に依存しない普遍的な知識	patterns/	SOLID の原則
セッションの要約	sessions/	実施した作業と発見したこと
TODO	todos/Active TODOs.md	プロジェクトごとにグループ化

フロントマターの規約

新しいノートには必ず次を含めます。

---
tags: [category, project/short-name]
type: <component|adr|session|project>
project: "[[projects/{name}/{name}]]"
created: YYYY-MM-DD
---

ウィキリンクの規約

• 関連ノートへのリンク：[[projects/{name}/components/Component Name|Component Name]]
• ドメインへのリンク：[[domains/{tech}/{Tech Name}|Tech Name]]
• プロジェクトへのリンク：[[projects/{name}/{name}|project-name]]

ノートのテンプレート

コンポーネントノート：

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/{name}/{name}]]"
created: {date}
status: active
layer: ""
depends-on: []
depended-on-by: []
key-files: []
---

セクション：目的、注意点

アーキテクチャ上の決定：

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/{name}/{name}]]"
status: proposed | accepted | superseded
created: {date}
---

セクション：背景、決定、検討した代替案、結果

セッションノート：

---
tags: [sessions]
type: session
projects:
  - "[[projects/{name}/{name}]]"
created: {date}
branch: {branch-name}
---

セクション：背景、実施した作業、発見したこと、決定事項、次のステップ

コマンド

init — Vault を初期化する

同梱のテンプレートから新しい Obsidian Agent Memory Vault をセットアップします。

使用方法：init [path]

手順：

1. Vault のパスを決定する：引数が指定されている場合はその値を使用し、指定されていない場合は Vault の解決チェーンを使用します（デフォルト：~/Documents/AgentMemory）。

2. Vault がすでに存在するか確認する：$VAULT/Home.md を確認します。存在する場合は、そのパスに Vault がすでに存在することをユーザーに伝え、開くかどうかを尋ねます。

3. 同梱テンプレートを見つける：テンプレートは、スキルパッケージのルートを基準とした vault-template/ にあります。スキルパッケージのインストールディレクトリを検索します。エージェントのプラグイン／スキルキャッシュ内、またはローカルチェックアウト内にある場合があります。正しいパスを確認するため、vault-template/Home.md を探します。

4. Vault を作成する：

   mkdir -p "$VAULT"
   cp -r "$TEMPLATE_DIR/vault-template/"* "$VAULT/"
   

5. Obsidian の設定ディレクトリを作成する：

   mkdir -p "$VAULT/.obsidian"
   

   以下を $VAULT/.obsidian/app.json に書き込みます：

   {
     "alwaysUpdateLinks": true,
     "newFileLocation": "folder",
     "newFileFolderPath": "inbox",
     "attachmentFolderPath": "attachments"
   }
   

6. 空のディレクトリを作成する：

   mkdir -p "$VAULT/inbox"
   mkdir -p "$VAULT/attachments"
   

   各空ディレクトリに .gitkeep ファイルを作成します。

7. 作成した Vault を報告し、次の手順を案内する：

   • Obsidian で開く：Vault Switcher → フォルダーを Vault として開く → $VAULT
   • OBSIDIAN_VAULT_PATH 環境変数またはエージェント設定で Vault のパスを設定する
   • 作業を開始する。エージェントが作業を進めながらナレッジグラフを構築します

8. エージェント設定のスニペットを生成する：ユーザーのエージェントに適した Vault パスのスニペットを出力します。Claude Code の場合は、CLAUDE.md のスニペットを出力します：

   ## Obsidian Knowledge Vault
   Persistent knowledge vault at `$VAULT`.
   

   その他のエージェントの場合は、汎用的な指示「環境変数またはエージェント設定に OBSIDIAN_VAULT_PATH=$VAULT を追加してください。」を出力します。

9. 現在のプロジェクトを自動で足場作成する：Git リポジトリ内にいる場合は、project コマンドを自動で実行し、現在のプロジェクトの足場を Vault 内に作成します。

10. 簡潔に出力する：最終出力は最大 5～8 行に収めます。作成した Vault のパス、プロジェクトの足場作成（該当する場合）、Obsidian での開き方、Vault パスの設定方法を記載します。

analyze — プロジェクトを分析して Vault に情報を取り込む

現在のコードベースを分析し、相互に関連した、内容が充実したノートを Vault に作成します。

使い方：analyze（引数なし。現在のリポジトリを使用します）

フェーズ 1：情報の発見 — ナレッジソースをスキャンする

既存のナレッジを含むファイルをリポジトリ内でスキャンします：

カテゴリ	スキャンするファイル
エージェント設定	CLAUDE.md、.claude/CLAUDE.md、.cursorrules、.windsurfrules、.clinerules、AGENTS.md、Agents.md
ドキュメント	README.md、CONTRIBUTING.md、ARCHITECTURE.md、docs/architecture.md、docs/ARCHITECTURE.md
既存の ADR	docs/adr/ADR-*.md、architecture/ADR-*.md、adr/*.md、docs/decisions/*.md
プロジェクトメタデータ	package.json、go.mod、Cargo.toml、pyproject.toml、setup.py、Gemfile、pom.xml、build.gradle、*.csproj
ビルド／CI	Makefile、Dockerfile、docker-compose.yml、.github/workflows/*.yml、.gitlab-ci.yml
設定	tsconfig.json、.eslintrc.*、jest.config.*、.goreleaser.yml

見つかった各ファイルを読み込みます。大きなファイル（README、エージェント設定）はすべて読み込みます。メタデータファイルからは主要な項目（名前、バージョン、依存関係）を抽出します。

以下の情報も収集します：

• git remote get-url origin からリポジトリの URL
• git rev-parse --show-toplevel からリポジトリのルートパス
• git branch --show-current から現在のブランチ
• ディレクトリツリー（ソースディレクトリの上位 2 階層。隠しディレクトリ、vendor、node_modules は除外）
• 言語判定用のファイル拡張子の出現頻度

フェーズ 2：分析 — 抽出と統合

発見した内容を使用して、以下を統合します。

1. プロジェクトのメタデータ：名前、言語、フレームワーク、リポジトリ URL、ローカルパス
2. アーキテクチャの概要：エントリーポイント、レイヤー構成（例：internal/ → Go のサービスレイヤー、src/components/ → React アプリ）、ビルドシステム
3. コンポーネント一覧：主要な機能モジュール — 独立した単位を表す最上位のソースディレクトリ、または論理的なグループ。それぞれについて、目的（README／エージェント設定のコンテキストに基づく）、主要ファイル、関連性を記載します。
4. パターン一覧：コーディング規約、エラー処理戦略、テスト方法 — エージェント設定ファイル（「Coding Guidelines」「Testing」などのセクションを含む CLAUDE.md）から抽出します。
5. ドメインのマッピング：検出したテクノロジー → vault のドメインノート（例：Go、TypeScript、Terraform、React）
6. 既存の決定事項：リポジトリで見つかった ADR ファイル → vault の ADR ノートとしてインポートします。
7. 依存関係の概要：パッケージマニフェストから主要な依存関係を抽出します（別のノートではなく、プロジェクト概要に記載します）。

フェーズ 3：ハイドレーション — Vault ノートの作成

冪等性のルール：

• プロジェクトディレクトリが存在しない場合 → すべてを作成します（ひな形の作成と内容の追加）
• プロジェクトディレクトリが存在するが、概要がひな形の場合 → 概要を内容が入力されたものに置き換えます
• 個別のコンポーネント／パターン／ADR ノートがすでに存在する場合 → スキップして報告します（手動での作業を上書きしません）
• ドメインノート：存在しない場合は作成し、すでに存在する場合はプロジェクトへのリンクを追記します

作成するノート：

1. プロジェクト概要（$VAULT/projects/{name}/{name}.md）— 内容をすべて入力します：

   ---
   aliases: []
   tags: [project/{short-name}]
   type: project
   repo: {git remote url}
   path: {repo root path}
   language: {detected language(s)}
   framework: {detected framework(s)}
   created: {YYYY-MM-DD}
   status: active
   ---
   

   セクション：

   • アーキテクチャ：分析に基づく実際の説明
   • コンポーネント：コンポーネントノートへの Wikilink を含む表
   • プロジェクトのパターン：パターンノートへの Wikilink を含む表
   • アーキテクチャ上の決定事項：ADR ノートへの Wikilink を含むリスト
   • 主要な依存関係：パッケージマニフェストから抽出
   • ドメイン：ドメインノートへの Wikilink

2. コンポーネントノート（$VAULT/projects/{name}/components/{Component}.md）— 主要モジュールごとに 1 つ：

   ---
   tags: [components, project/{short-name}]
   type: component
   project: "[[projects/{name}/{name}]]"
   created: {YYYY-MM-DD}
   status: active
   layer: {detected layer}
   depends-on: []
   depended-on-by: []
   key-files: [{key files list}]
   ---
   

   セクション：目的、注意点

3. パターンノート（$VAULT/projects/{name}/patterns/{Pattern}.md）— エージェント設定の規約に基づいて作成：

   ---
   tags: [patterns, project/{short-name}]
   type: pattern
   project: "[[projects/{name}/{name}]]"
   created: {YYYY-MM-DD}
   ---
   

   セクション：パターン、使用する場面、実装

4. ADR のインポート（$VAULT/projects/{name}/architecture/ADR-{NNNN} {title}.md）— 既存のリポジトリ ADR から作成：

   ---
   tags: [architecture, decision, project/{short-name}]
   type: adr
   project: "[[projects/{name}/{name}]]"
   status: accepted
   created: {YYYY-MM-DD}
   ---
   

   元の内容を保持し、vault のフロントマターを追加します。

5. ドメインノート（$VAULT/domains/{tech}/{Tech}.md）：

   • 新規の場合：プロジェクトへのリンクを含めて作成します
   • 既存の場合：「Projects Using This Domain」セクションにこのプロジェクトを追加します

6. インデックスの更新：

   • $VAULT/projects/Projects.md — 行を追加／更新します
   • $VAULT/domains/Domains.md — 新しいドメインの行を追加／更新します

フェーズ 4：レポート

概要を出力します：

Analyzed: {project-name}
  Sources read: {N} knowledge files
  Created: project overview (populated)
  Created: {N} component notes
  Created: {N} pattern notes
  Imported: {N} architecture decisions
  Linked: {N} domain notes
  Skipped: {N} existing notes (preserved)

recap — セッションの概要を記録

セッションの概要ノートを作成し、TODO を更新します。

使用法：recap

手順：

1. 以下を実行してセッションのコンテキストを収集します：

   git log --oneline -20
   git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat
   git branch --show-current
   

2. 現在の TODO を読み込みます — CLI を優先：

   obsidian vault=$VAULT_NAME tasks path="todos" todo verbose
   

   代替手段：$VAULT/todos/Active TODOs.md を読み込みます。

3. $VAULT/projects/$PROJECT/$PROJECT.md からプロジェクトの概要（Wiki リンクとコンテキスト）を読み込みます。

4. セッションノートを作成します — CLI を優先：

   obsidian vault=$VAULT_NAME create path="sessions/{YYYY-MM-DD} - {title}" template="Session Note" silent
   obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="type" value="session" type="text"
   obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="branch" value="{current-branch}" type="text"
   obsidian vault=$VAULT_NAME property:set path="sessions/{YYYY-MM-DD} - {title}" name="projects" value="[[projects/$PROJECT/$PROJECT]]" type="list"
   

   次に、本文の内容を追記します：

   obsidian vault=$VAULT_NAME append path="sessions/{YYYY-MM-DD} - {title}" content="..."
   

   代替手段：ファイルを $VAULT/sessions/{YYYY-MM-DD} - {title}.md に直接書き込みます：

   ---
   tags: [sessions]
   type: session
   projects:
     - "[[projects/$PROJECT/$PROJECT]]"
   created: {YYYY-MM-DD}
   branch: {current-branch}
   ---
   

   記入するセクション：

   • Context：作業していた内容（git log のコンテキストから）
   • Work Done：達成した内容の番号付きリスト（コミットと差分から）
   • Discoveries：記録しておく価値のある技術的な発見
   • Decisions：このセッションで行った設計上の選択
   • Next Steps：次に行うこと（チェックボックス）

5. TODO を更新します：$VAULT/todos/Active TODOs.md を編集します。

   • Active TODOs から完了した [x] 項目を削除し、日付付きの ## $PROJECT (YYYY-MM-DD) 見出しの下に $VAULT/todos/Completed TODOs Archive.md へ追記します（ファイルが存在しない場合は作成します）。
   • セッション中に見つかった新しい項目を追加します。
   • 項目はプロジェクトごとにグループ化します。
   • Active TODOs に [x] 項目を残さないでください — 項目は時間とともに蓄積し、各セッション開始時のコンテキストウィンドウを無駄に消費します。

6. Session Log を更新します：日付、プロジェクト、ブランチ、および1行の概要を $VAULT/sessions/Session Log.md に追加します。

7. 書き込んだ内容を報告します。

project — 新規プロジェクトのひな形を作成

Vault に新しいプロジェクトのひな形を作成します。最初の引数をプロジェクト名として使用し、引数がない場合は $PROJECT を使用します。

使い方：project [name]

手順：

1. プロジェクト名を決定します：引数が指定されている場合はそれを使用し、指定されていない場合は $PROJECT を使用します。

2. プロジェクトの存在を確認します：$VAULT/projects/{name}/{name}.md を確認します。存在する場合はユーザーに伝え、代わりにそのファイルを開くか確認します。

3. ディレクトリ構造を作成します：

   • $VAULT/projects/{name}/
   • $VAULT/projects/{name}/architecture/
   • $VAULT/projects/{name}/components/
   • $VAULT/projects/{name}/patterns/

4. $VAULT/projects/{name}/{name}.md にプロジェクトの概要を作成します：

   ---
   aliases: []
   tags: [project/{short-name}]
   type: project
   repo: {git remote url if available}
   path: {working directory}
   language: {detected from files}
   framework:
   created: {YYYY-MM-DD}
   status: active
   ---
   

   セクション：Architecture、Components、Project Patterns、Architecture Decisions、Domains

   以下を自動検出して記入します：

   • リポジトリ内のファイル拡張子から言語を判定
   • git remote get-url origin からリポジトリの URL を取得
   • $VAULT/domains/ に存在する関連ドメインへのリンク

5. Projects.md を更新します：$VAULT/projects/Projects.md のプロジェクトテーブルに行を追加します。

6. 作成したひな形の構造を報告します。

note — テンプレートからノートを作成

テンプレートを使用してノートを作成します。最初の引数で種類（component、adr、pattern）を指定します。

使い方：note <component|adr|pattern> [name]

note component [name]

$VAULT/projects/$PROJECT/components/{name}.md に作成します：

---
tags: [components, project/{short-name}]
type: component
project: "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
status: active
layer: ""
depends-on: []
depended-on-by: []
key-files: []
---

セクション：Purpose、Gotchas

名前の引数が指定されている場合は、コンポーネント名として使用します。指定されていない場合は、ユーザーに確認します。

note adr [title]

$VAULT/projects/$PROJECT/architecture/ADR-*.md にある既存の ADR を一覧表示し、次の ADR 番号を決定します。

$VAULT/projects/$PROJECT/architecture/ADR-{NNNN} {title}.md に作成します：

---
tags: [architecture, decision, project/{short-name}]
type: adr
project: "[[projects/$PROJECT/$PROJECT]]"
status: proposed
created: {YYYY-MM-DD}
---

セクション：Context、Decision、Alternatives Considered、Consequences

note pattern [name]

$VAULT/projects/$PROJECT/patterns/{name}.md に作成します：

---
tags: [patterns, project/{short-name}]
project: "[[projects/$PROJECT/$PROJECT]]"
created: {YYYY-MM-DD}
---

セクション：Pattern、When to Use、Implementation、Examples

ノートを作成した後、プロジェクトの概要からそのノートへの Wiki リンクを追加します。

todo — TODO を管理

現在のプロジェクトの Active TODOs を表示、更新します。

使い方：todo [action]

手順：

1. $VAULT/todos/Active TODOs.md から現在の TODO を読み込みます。

2. 追加の引数がない場合：$PROJECT の現在の TODO を表示し、更新内容を尋ねます。

3. 引数が指定されている場合：TODO アクションとして解析します。

   • プレーンテキスト → $PROJECT の下に新しい未完了項目として追加
   • done: <text> → 項目を完了済みにします。Active TODOs から削除し、$VAULT/todos/Completed TODOs Archive.md の日付付き ## $PROJECT (YYYY-MM-DD) 見出しの下に追記します（ファイルが存在しない場合は作成します）
   • remove: <text> → 一致する項目を削除

4. Active TODOs（および項目を完了した場合はアーカイブファイル）を書き戻します。

lookup — Vault を検索する

ナレッジを検索します。対象を絞ったサブコマンドとフリーテキスト検索に対応しています。

使い方：lookup <subcommand|freetext>

lookup deps <name>

コンポーネントが依存する対象を照会します。

obsidian vault=$VAULT_NAME property:read file="<name>" name="depends-on"

フォールバック：コンポーネントのノートを読み込み、depends-on のフロントマターリストを解析します。

lookup consumers <name>

コンポーネントに依存する対象（逆方向の依存関係）を照会します。

obsidian vault=$VAULT_NAME property:read file="<name>" name="depended-on-by"
obsidian vault=$VAULT_NAME backlinks file="<name>"

結果を組み合わせます。depended-on-by は明示的な関係を示し、backlinks は暗黙的な参照を見つけます。フォールバック：コンポーネントのノートを読み込み、Grep でバックリンクを検索します。

lookup related <name>

指定したノートに関連するすべてのノート（両方向）を照会します。

obsidian vault=$VAULT_NAME links file="<name>"
obsidian vault=$VAULT_NAME backlinks file="<name>"

フォールバック：ノートを読み込んでウィキリンクを抽出し、Vault 全体から [[<name> を Grep で検索します。

lookup type <type> [project]

指定したタイプ（component、adr、session、project）のノートをすべて検索します。

obsidian vault=$VAULT_NAME tag verbose name="<type>"

[project] が指定されている場合は、project/<short-name> のタグも付いているノートに結果を絞り込みます。

obsidian vault=$VAULT_NAME search query="type: <type>" path="projects/<project>"

フォールバック：$VAULT 全体から type: <type> を Grep で検索します。

lookup layer <layer> [project]

特定のレイヤーにあるコンポーネントをすべて検索します。

obsidian vault=$VAULT_NAME search query="layer: <layer>" path="projects/<project>"

プロジェクトが指定されていない場合は、すべてのプロジェクトを対象に検索します。

obsidian vault=$VAULT_NAME search query="layer: <layer>" path="projects"

フォールバック：$VAULT/projects/ 全体から layer: <layer> を Grep で検索します。

lookup files <component>

コンポーネントの主要ファイルを照会します。

obsidian vault=$VAULT_NAME property:read file="<component>" name="key-files"

フォールバック：コンポーネントのノートを読み込み、key-files のフロントマターリストを解析します。

lookup <freetext>

Vault 全体を対象に一般検索します。

obsidian vault=$VAULT_NAME search format=json query="<freetext>" matches limit=10

フォールバック：$VAULT 内のすべての .md ファイルを対象に、ファイルの内容からクエリを検索します。

クエリがタグのように見える場合（# または project/ で始まる場合）：

obsidian vault=$VAULT_NAME tags name="<query>"

クエリがノート名と一致する場合：

obsidian vault=$VAULT_NAME backlinks file="<query>"

検索結果の表示：ユーザーが全文を読むノートを選べるよう、一致したノートのフロントマター（最初の約 10 行）とともに表示します。

relate — 関係を管理する

フロントマターのプロパティを使って、ノート間の双方向の関係を作成し、照会します。

使い方：relate <subcommand> [args]

対応する関係タイプ

順方向のプロパティ	逆方向のプロパティ
depends-on	depended-on-by
extends	extended-by
implements	implemented-by
consumes	consumed-by

relate <source> <target> [type]

2 つのノート間に双方向の関係を作成します。デフォルトのタイプは depends-on/depended-on-by です。

手順：

1. ノート名を解決します：ノートの表示名には file= パラメーターを使用します。同じ名前のノートが異なるフォルダーにあり、曖昧さが生じる可能性がある場合は、Vault からの相対パス全体を path= で指定します。

2. source の現在のプロパティを読み込みます（順方向）：

   obsidian vault=$VAULT_NAME property:read file="<source>" name="<forward-property>"
   

   フォールバック：source ノートのフロントマターを読み込みます。

3. 関係がすでに存在するか確認します：<target>（ウィキリンクとして）がすでにリストに含まれている場合は、処理をスキップして「すでに関連付けられています」と報告します。

4. source に追加します（順方向）： 現在の値に [[<target>]] を追加して新しいリストをローカルに作成し、次のように設定します。

   obsidian vault=$VAULT_NAME property:set file="<source>" name="<forward-property>" value="<full-list>" type="list"
   

   フォールバック：source ノートのフロントマターを直接編集します。

5. target の現在のプロパティを読み込みます（逆方向）：

   obsidian vault=$VAULT_NAME property:read file="<target>" name="<inverse-property>"
   

6. target に追加します（逆方向）：

   obsidian vault=$VAULT_NAME property:set file="<target>" name="<inverse-property>" value="<full-list>" type="list"
   

7. 報告します：作成した関係を報告します。

安全性：必ず読み込んでから設定します。確認せずに追記してはいけません。リスト全体をローカルで構築し、アトミックに設定します。

relate show <name>

ノートのすべての関係を表示します。

手順：

1. 8 つすべての関係プロパティをクエリします：

   obsidian vault=$VAULT_NAME property:read file="<name>" name="depends-on"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="depended-on-by"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="extends"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="extended-by"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="implements"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="implemented-by"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="consumes"
   obsidian vault=$VAULT_NAME property:read file="<name>" name="consumed-by"
   

   フォールバック：ノートのフロントマターを読み取り、すべての関係プロパティを解析します。

2. 構造的なリンクをクエリします：

   obsidian vault=$VAULT_NAME links file="<name>"
   obsidian vault=$VAULT_NAME backlinks file="<name>"
   

3. 結果を関係タイプごとにグループ化して提示します。明示的な（プロパティによる）関係を先に示し、次にまだ含まれていない構造的な（ウィキリンクによる）関係を示します。

relate tree <name> [depth]

BFS で依存関係ツリーをたどります。デフォルトの深さは 2 です。

手順：

1. BFS を初期化します：<name> を深さ 0 として開始します。訪問済みセットとキューを維持します。

2. キュー内の各ノードについて：

   obsidian vault=$VAULT_NAME property:read file="<current>" name="depends-on"
   

   フォールバック：ノートを読み取り、フロントマターから depends-on を解析します。

3. 未訪問の依存関係を current_depth + 1 の深さでキューに追加します。depth の上限に達したら停止します。

4. ツリーを依存関係の連鎖を示すインデント付きリストとして提示します。

トークン予算のルール

1. 読み取りより CLI を優先：プロパティの読み取り、バックリンク、リンク、タグ、検索には obsidian CLI を使用します。これらはファイル全体を読み取らずに、対象を絞ったデータを返します。
2. セッション開始時：操作は最大 2 回（TODO とプロジェクト概要）
3. 作業中：ノート全体を読み取る前に、lookup サブコマンドと relate show を使用します。
4. まずフロントマター：スキャン時は、ノート全体を読むと決める前に約 10 行を読み取ります。
5. 読み取り前に一覧表示：ファイルを読む前にディレクトリの内容を一覧表示します。
6. 簡潔に書く：箇条書き、リンク、タグを使い、箇条書きで十分な場合は文章を使いません。

エラー処理

• ボルトが存在しない場合 → 初期化するために /obs init の実行を提案します
• プロジェクトがボルト内に存在しない場合 → プロジェクトのひな型を作成するために /obs project の実行を提案します
• ノートがすでに存在する場合 → 上書きせずに内容を表示し、編集を提案します
• git リポジトリが検出されない場合 → 現在のディレクトリ名をプロジェクト名として使用します
• CLI コマンドが失敗した場合 → 同じデータを取得するためにファイルの読み取りに切り替えます

ボルト構造のリファレンス

$VAULT/
├── Home.md                           # Dashboard (read only if lost)
├── projects/{name}/
│   ├── {name}.md                     # Project overview — START HERE
│   ├── architecture/                 # ADRs and design decisions
│   ├── components/                   # Per-component notes
│   └── patterns/                     # Project-specific patterns
├── domains/{tech}/                   # Cross-project knowledge
├── patterns/                         # Universal patterns
├── sessions/                         # Session logs (read only when needed)
├── todos/Active TODOs.md             # Pending work (read at session start)
├── templates/                        # Note templates
└── inbox/                            # Unsorted