sense-setup

sense のセットアップとツリー設計

このスキルを使って、sense の設定を作成または変更します。既存のツリーへのクエリは sense スキルの対象です。一般的なツリー構造の設定例は EXAMPLES.md にあります。

ツリーをセットアップする

CLI をインストールし、Markdown のルートで初期化します。

npm install -g sensemaking
cd path/to/notes
sense init
sense status

sense init は sense.config.json を書き込みます。設定ファイルの検出では、現在のディレクトリから上位へたどります。--config <path> で別のファイルを選択できます。

デフォルトでは、設定ファイルが置かれたディレクトリを設定でインデックス化します。トップレベルの root で別の Markdown ツリーを指定できます。相対パスのルートは設定ファイルのディレクトリを基準に解決され、.sense/ は設定ファイルと同じ場所に残ります。1 つのツリーに対して、利用者ごとに異なるプリセット、保存済みクエリ、またはキャッシュが必要な場合に使います。

グロブとインデックス化されるパスは、選択したルートからの相対パスです。設定を変更した後は sense status と sense map を実行し、プリセットの対象範囲と選択されたストアを確認します。インデックス化されるコンテンツに影響する変更があると、関連するキャッシュが再構築され、その理由が報告されます。ビルドが有効なコマンドは、互換性のない派生キャッシュ形式を置き換え、不完全な機能の状態を修復します。設定の "build": false または --no-build を指定すると、Sense インデックスを再構築または修復せずに、必要なビルドが報告されます。

ストアを選ぶ

キャッシュの用途に応じて選択します。周辺のワークフローで別のエンジンが有利でなければ、まず sqlite を選び、相互運用性、SQL、接続動作、および代表的な Sense の測定結果を考慮します。現在の速度測定結果だけで、エンジンの長期的な適性が決まるわけではありません。

ストア	選択する場面	主なトレードオフ
sqlite	ツリーに最小限のセットアップ、高度な FTS5 検索構文、または Sense コマンドの同時実行が必要な場合	Node に同梱されています。生の SQL は SQLite です
duckdb	大規模なデータセットを対象とする DuckDB の分析作業や、ローカル／クラウドのワークフローにキャッシュを含める場合、または DuckDB の型と SQL が必要な場合	実験的な Sense アダプター、大規模なネイティブインストール、一度に開ける接続は 1 つ
turso	ツリーで組み込み Rust エンジンまたは Tantivy インデックスが役立つ場合、あるいはアダプターの進化に伴ってエンジンを評価する場合	実験的な Sense アダプター、制限された検索構文、一度に開ける接続は 1 つ

デフォルト以外のストアを推奨または設定する前に、該当する選択ガイドをお読みください。

• SQLite 選択ガイド
• DuckDB 選択ガイド
• Turso 選択ガイド

レイテンシや検索品質によって選択が変わる可能性がある場合にのみ、パフォーマンスのトレードオフをお読みください。この簡潔な比較は、採用されたリリースレポートから生成されています。詳細な測定結果は Git に保存されています。

各ストアは個別のキャッシュファイルを使用します。store を変更すると、古いキャッシュを移行するのではなく、インデックスが再構築されます。コマンドと公開テーブルは共通ですが、生の SQL と高度な単語検索構文は選択したエンジンに従います。

プリセットを設計する

プリセットは、名前が付いた自己完結型の範囲です。必須の default プリセットは、名前を指定しないコマンドで使用されます。その他のプリセットは名前で選択します。

フィールド	意味	デフォルト
include と exclude	プリセットの対象となるファイル	include は必須です
k	検索結果の件数	10
signals	有効にする検索シグナルと、その逆順位の重み	利用可能なすべてのシグナルを重み 1 で使用
where	常時適用されるフロントマターのフィルター	なし

いずれかのプリセットに含まれるファイルはインデックス化されます。プリセットの範囲は重複してもかまいません。どのプリセットにも含まれないファイルはインデックスに入りません。

raw/、notes/、archive/ など、安定したレイヤーにはパスを使います。status、project、日付など、変化する状態にはフロントマターのフィルターを使います。プリセットはインデックス化を制御するため、フロントマターのクエリを実行する前に、パスから対象範囲を計算できる必要があります。

ツリーの一部で異なる検索シグナルや結果件数が必要な場合は、プリセットを分けてください。単一用途のツリーに、追加のプリセット用語は必要ありません。

ベクトルを設定する

ベクトルには2つの選択が必要です。トップレベルの embed ブロックでモデルとプロバイダーを指定します。各プリセットの signals で、そのスコープにベクトルを使用するかどうかを決定します。

{
  "embed": {
    "model": "minishlab/potion-retrieval-32M",
    "provider": "static"
  },
  "presets": {
    "default": {
      "include": ["notes/**/*.md"],
      "signals": { "words": 1, "links": 1, "vectors": 1 }
    },
    "raw": {
      "include": ["raw/**/*.md"],
      "signals": { "words": 1, "links": 1 }
    }
  }
}

設定の "build": true というデフォルトにより、CLI クエリで必要な機能を準備できます。手動ビルドまたは監視のワークフローでは "build": false に設定してください。ビルドが有効な状態で初めてベクトル検索を行うと、指定された静的モデルがダウンロードされ、対象となるスコープが埋め込み処理されます。sense build と sense watch はこの設定にかかわらず、設定済みの機能をすべて準備します。CI、オフライン作業、またはタイミングの都合で事前取得が役立つ場合は、sense download でモデルを先に取得できます。プロバイダー、モデル、有効なエンドポイント、ベクトルの対象範囲、またはチャンク分割を変更する設定変更によって、ベクトルが無効になったり、再構築されたりすることがあります。設定の "build": false または --no-build を指定した場合、要求されたベクトルスコープの準備が完了している必要があり、新しいライブファイルは読み込まれません。

プロバイダーやモデルの選択、英語以外のツリーへの対応、チャンクサイズの変更、またはシグナルの重みの調整については、埋め込みの設定をお読みください。

クエリ可能なノートを設計する

Sense はさまざまな形式の Markdown を受け入れます。次の選択によって、どのクエリが信頼できる結果を返すかが決まります。

• 一貫したフロントマターのフィールドがあれば、厳密なフィルターや保存済みレポートを利用できます。実際の適用範囲と型は sense map で確認してください。
• ISO 8601 の日付は、選択したストアの日付関数で比較できます。日付形式が混在していても保存はできますが、信頼できる期間指定にはなりません。
• 1行の summary は結果に表示され、本文よりも高い語彙的な重みが付与されます。その代わり、常に最新の状態に保つ必要があります。
• プリセットの適用範囲にはフォルダーが自然な単位です。ステータスや所有者にはフロントマターが自然な単位です。
• 小さなノートは正確なヒットが得られ、ファイル全体の読み込みコストも低くなります。大きなノートも、peek、sections、検索結果の lines が範囲を示し、ベクトルのチャンク分割では長いセクションが分割されるため、問題なく使用できます。
• 繰り返し使う質問は queries に保存してください。決定的なフィルターやレポートには { "sql": "..." } を、順位付けされた検索には { "search": "..." } を使用します。

例に記載されているフィールド名は説明用です。スキーマはツリーごとに定義されます。予約済みのフロントマターキーは path、_mtime、_ctime、_size、_rank、_parse_error、content、links、sections です。Sense はこれらを警告とともに除外します。

結果を検証する

sense status を実行し、ストア、キャッシュ、ドキュメント数、埋め込みの状態、ウォッチャーの状態、プリセットの適用範囲を確認してください。sense map を実行し、検出されたフィールドと観測された型を確認してください。

編集後は、保存済みのクエリをすべて実行してください。パラメーター化された SQL クエリでは、パラメーターが結果を変える前に文の準備で列と構文が検証されるため、任意の値を使用できます。

セットアップのやり取りが終わった後も残すべき選択は、ツリーで管理しているエージェント向けガイダンス、または作成したノートに記録してください。Sense の設定には実行可能な設定と再利用可能なクエリを記述し、方針の説明は含めないでください。