maestro/docs/tools/notes.md

SearchNotes / ReadNote / WriteNote

ユーザーの共有 knowledge notes（data/users/{userId}/notes/{folder}/{file}.md）を扱う 3 ツール。 ファイルは YAML frontmatter + Markdown 本文で構成され、DB の note_index (FTS5 対応) に mirror される。

SearchNotes

購読中（note_subscriptions に mode=search または mode=inject、enabled=1 の行がある）の note を FTS5 全文検索する。

引数

フィールド	型	必須	説明
query	string	必須	検索クエリ。ツール内部でフレーズ検索として扱われる
folder	string	省略可	特定フォルダーのみに絞り込む
limit	integer	省略可	最大取得件数（デフォルト 10、上限 100）

戻り値

マッチした note のリスト（owner_id/folder/file_name: title）。 続いて ReadNote で全文を取得できる。

FTS5 クエリの注意

クエリはフレーズ検索として自動エスケープされる。kubernetes pod → "kubernetes pod" に変換。 AND / OR 演算子を使いたい場合は複数回呼び出して結果を手動合算すること。

---

ReadNote

特定の note の全文（frontmatter + 本文）を取得。可視性チェックあり。

引数

フィールド	型	必須	説明
owner_id	string	必須	note の所有者 user ID
folder	string	必須	フォルダー名
file_name	string	必須	ファイル名（例: foo.md）

可視性ルール

• 自分の note（owner_id が自分）: 常に読める
• visibility: public の note: 全ユーザーが読める
• visibility: org の note: scope_org_id が自分の所属 org に含まれる場合のみ読める
• visibility: private の他人の note: 読めない（isError: true）

---

WriteNote

自分の notes/{folder}/{file}.md を作成または更新する。

引数

フィールド	型	必須	説明
folder	string	必須	フォルダー名（[a-zA-Z0-9._-] のみ）
file_name	string	必須	ファイル名（.md で終わる）
content	string	必須	YAML frontmatter を含む完全な Markdown 内容

Frontmatter フィールド

---
title: "Note のタイトル（省略可）"
visibility: public      # private | org | public
scope_org_id: "org-id" # visibility=org の場合に必須（自分の所属 org の ID）
mode_hint: search       # search | inject（省略可）
tags:
  - kubernetes
  - security
---

• visibility は必須。省略すると private として扱われる
• visibility: org の場合、scope_org_id は自分の所属 org の ID でなければならない
• mode_hint: inject にすると、購読者の system prompt に自動注入される
• フォルダーとファイル名は固定の 2 階層（notes/<folder>/<file>.md）

書き込み後の動作

• DB の note_index + FTS5 テーブルを即座に更新
• 同フォルダーへの self subscription がなければ自動作成（mode=search、enabled=1）
• エラー時は isError: true を返す（バリデーションエラーや権限エラー）

---

使い分け

場面	ツール
「CVE 対象?」「〜の設定は?」など知識検索	SearchNotes("CVE")
検索結果の 1 件の詳細を読む	ReadNote
スケジュールタスクで取得した情報をチームと共有	WriteNote（visibility: org）
自分用のメモ・ログを残す	WriteNote（visibility: private）