memory-comark

Memory Comark

Basic Memory のノートには、Comark ブロックディレクティブ（::bm-bars{...} … ::）で記述した、小さく安全なコンポーネントを含められます。Basic Memory Cloud は、ノート、Wiki、共有ページでこれらを描画します。それ以外の場所（ローカルエディター、GitHub、エージェントによる生の読み取りなど）でも、同じ Markdown は通常のリスト、表、段落として読めるため、コンポーネントによってコンテンツが隠れることはありません。

形にすることで文章やリスト以上の情報を伝えられる場合に、コンポーネントを使ってください。文章を主役にし、アイデアごとに図は1つ、セクションあたり最大2つにします。それぞれの間には、図が示す内容を説明する文を入れてください。

用語、すべてのプロパティ、データ形式の一覧は、references/components.md にあります。初めて使うコンポーネントについては、使用前にこちらを読んでください。

コンポーネントを選ぶ

ほとんどのノートでは、次のコンポーネントだけで十分です。残りはリファレンスに記載されています（全39種類）。

表示したい内容	使用するもの
1つまたは少数の主要な数値	bm-stat
いくつかの値の比較	bm-bars
短い順位付きリスト	bm-rank
小さなデータ表	bm-table
全体に対する進捗	bm-meter
軸のない傾向	bm-spark
段階ごとに減少する流れ	bm-funnel
タスクリスト	bm-check
レーンごとの作業（現在、次、後で）	bm-kanban
順番に並ぶイベント	bm-timeline
枠で囲んだ主張や要約	bm-frame
短い経路（a → b → c）	bm-flow
実際のグラフ、シーケンス、状態機械	フェンス付きの ```mermaid ブロック（コンポーネントではありません）

該当するものがなければ、文章か通常の Markdown 表を使ってください。コンポーネントを独自に作ってはいけません。::bm-pie のような未知の名前は描画されず、生のテキストとして表示されます。

コンポーネントを書く

各コンポーネントは、独立した行に ::bm-name{attributes} を書いて開始し、独立した行の :: で閉じます。

The queue rewrite more than doubled steady-state throughput.

::bm-bars{title="Throughput" caption="Before and after the queue rewrite"}
- Before: 42/s
- **After: 96/s**
::

重要なルール：

• データは属性ではなく、本文に Markdown として記述します。- label: value の行や、グリッドの場合は表を使います。太字は現在の行または選択した行を示し、斜体は目立たなくする表示を示します。 — note を付けると補足を追加できます。
• 属性値は二重引用符で囲み、" を含めることはできません。 エスケープ方法はありません。query 内では、フレーズを一重引用符で囲みます。 query="search 'queue rewrite'"。
• タスクの状態は Markdown で管理します。 bm-check と bm-kanban の中では - [ ] と - [x] を使います。レンダリングされたノート上でチェックボックスを操作できます。
• ノート内に HTML、スクリプト、スタイル、クラスを記述してはいけません。 また、コンポーネントをコードフェンスで囲んではいけません（フェンス付きブロックはコードのまま表示されます）。
• 登録済みのプロパティのみを使用してください。 未知の属性を指定すると、元のソースと登録済みのプロパティを含む警告フレームに prop-unknown が表示され、黙って破棄されることはありません。

チェックリストとボードの例：

::bm-check{title="Launch"}
- [x] Freeze the schema
- [ ] Write the migration note — due Friday
::

::bm-kanban{title="Roadmap"}
### Now
- **Billing page**
- [ ] Usage emails

### Next
- *Partner portal*
::

ナレッジベースのライブビュー

query 属性を持つコンポーネントには、そのコンポーネントが属するプロジェクトの最新データが表示されます。ノートがそのナレッジベース自体について説明している場合は、手作業でコピーした数値よりもライブビューを優先してください。コピーした件数は古くなるためです。

::bm-stat{label="Open decisions" query="notes | where type == decision and status == open | count"}
::

::bm-bars{title="Open decisions by owner" query="notes | where type == decision and status != done | group owner | sort count desc"}
::

::bm-table{title="Due soon" query="notes | where tags contains infra and due < 2026-10-15 | fields title, owner, due | sort due"}
::

::bm-timeline{title="Recent edits" query="activity 7d"}
::

::bm-rank{title="Related notes" query="search 'checksum conflict' | limit 5"}
::

パイプラインは左から右に読みます。ソース（notes、search 'phrase'、activity 7d|30d）の後に、必要に応じてステージを順番に続けます：where、group、count または sum field、fields、sort、limit（1～50）。リファレンスには、すべての演算子と、各コンポーネントが受け付ける形式が記載されています。

使用できる形式：

• チャート、順位、棒グラフには、各行に数値が必要です：group field、count、sum field を追加するか、search ソースを使います。
• スパークライン、KPI、プロットには複数の行が必要です（group、daily、または search）。単一の count では使えません。
• bm-table は fields を受け付けます。bm-timeline は daily を付けない activity を受け付けます。bm-activity は activity 30d | daily を受け付けます。

周囲の文章では、次の意味を正確に説明してください。

• notes ビューは、インデックス化された frontmatter の正確な件数を示します。Search ビューは順位付けされ、対象範囲も限定されているため、「すべて」とは表現せず、「一致」と呼んでください。
• != を使うと、フィールドがないノートも含まれます。group を使うと、フィールドがないノートは none グループに入ります。
• Frontmatter の数値はテキストとして保存されます。比較と合計では、小数を表すテキストは数値として扱われ、それ以外は無視されます。

引用する前に、レンダリング結果を確認する

Basic Memory Cloud では、read_note(view="text") は、読者が目にする形でノートを返します。つまり、すべてのコンポーネントがプレーンな Markdown として表示され、ライブクエリはその時点で実行されます。ライブビューを書き込んだら、読み戻して行があることを確認してから、本文中に数値を記載してください。どのノートにも存在しないフィールドを対象にしたクエリは、空のビューとしてレンダリングされます。

それ以外の環境では、クエリを実行するのはブラウザーのみです。そのため、相当する読み取りを自分で実行してください（たとえば、メタデータフィルターを使った search_notes など。詳しくは memory-metadata-search スキルを参照してください）。

ライブチャートの本文はスナップショットであり、ライブデータを読み込めないときに読者が目にする行です。新しいライブビューでは、本文が空のままになることがあります。編集画面で Freeze snapshot を使うと、行を入力できます。スナップショットの行を自分で追加する場合は、本文中でスナップショットであることを明記し、チャートの行の形式に従ってください。

コンポーネントを含む既存のノートを編集する

• edit_note を使って、1つのコンポーネントだけを変更してください（ディレクティブ行または行に対して find_replace を使います）。1つの値を変更するために、ノート全体を書き直さないでください。
• 人がノートを編集すると、リッチエディターによって書式が正規化されます。属性の順序が変わり、YAML ブロックは JSON に戻ります。値は保持されるため、書式を元に戻そうとしないでください。
• 閉じる :: 行は残してください。本文があるブロックに閉じる記号がないと directive-unclosed が発生し、警告には開始記号と YAML のプロパティが表示される一方、その後の Markdown は表示されたままになります。ソース内の意図した境界に閉じる記号を追加してください。エディターが位置を推測することはありません。本文のない単独のリーフは引き続き有効ですが、新しいコンポーネントには明示的な閉じ記号を使用してください。

コンポーネントにエラーが表示された場合

壊れたコンポーネントには、コード化された問題と修正方法が専用の枠内に表示されます。ノートの残りの部分は引き続きレンダリングされます。Basic Memory Cloud では、write_note と edit_note の実行結果に、これらの問題が Component problems として一覧表示されます（書き込みが妨げられることはありません）。そのため、すぐに edit_note で修正してください。マニュアル（memory://man/comark(7)）の comark(7) は、構文とコードをすぐに確認できるリファレンスです。特によく見られるコードは次のとおりです。

コード	意味	修正方法
prop-unknown	コンポーネントが受け付けないプロパティ	削除するか、警告またはリファレンスに記載された登録済みプロパティを使用します
directive-unclosed	本文のあるブロックに閉じる記号がありません	Markdown ソース内の意図した境界に :: を追加します
query-measure	チャートに行ごとの数値がありません	group、count、sum を追加するか、search を使います
query-series	1つの値からトレンドを作成しようとしています	group、daily、または limit が 2 以上の search を使います
query-escaped-quote	クエリ内に \" があります	クエリ内ではシングルクォートを使います
query-field / query-operator	フィールド名または演算子が無効です	フィールド名にはドット付きパスを使い、文字は [A-Za-z0-9_-] にします。演算子は == != < <= > >= contains です
query-stage-order	ステージの順序が正しくありません	where、group、count/sum、fields、sort、limit の順にします
chart-body-empty	本文に行がありません	- label: value の行を追加します
chart-body-number	数値のない行があります	すべての行に数値が必要です

不明なプロパティがある場合、近くのリッチ編集を行っても、元のディレクティブとデータは保持されます。閉じ記号があり形式が不正なコンポーネントは、レビュー済みのエージェントによる置き換えと取り消しを利用できます。閉じ記号が欠けている場合は、ソースを編集して修正する必要があります。正規の検証と厳密なエクスポートでは、ソースを修正するまで、形式が不正な状態は拒否されます。bm-problem などの内部復旧ノードを作成しないでください。コンポーネント名とプロパティは、リファレンスで確認してください。

チェックリスト

1. ここでは、文章より図表のほうが効果的ですか？そうでなければ、文章を書いてください。
2. コンポーネント名とすべてのプロパティは、リファレンスに記載されていますか？
3. データは本文に Markdown の行またはテーブルとして記載されていますか？また、値に " は含まれていませんか？
4. ライブビューの場合、パイプラインはこのコンポーネントに必要な形式を出力していますか？また、自分で読み取りを行って数値を確認しましたか？
5. 図表の周囲に、何を示しているか、また数値が正確な件数なのか順位なのかを説明する文章がありますか？