sense

sense

ファイルを読む前に、sense を使って Markdown ツリー内の根拠を特定します。設定のデフォルトが "build": true の場合、CLI クエリは必要な機能を利用するために、設定されたツリーを段階的にスキャンします。ベクトルの準備対象は、利用可能な範囲に限定されます。設定が "build": false の場合、または単一クエリで --no-build を指定した場合は、最後に完了したインデックス世代を読み込み、要求された準備状況を確認しますが、ライブファイルはスキャンしません。明示的な build と watch は、デフォルト設定にかかわらず準備を行います。結果にはパス、メタデータ、スニペット、行範囲が含まれます。タスクで本文の確認が必要な場合は、返されたファイルまたは範囲を読みます。

セットアップ、ストアの選択、プリセット、ノートの設計については sense-setup スキルを参照してください。Obsidian Bases ファイルの翻訳については sense-bases を参照してください。

結果や出力制御について説明する際は、共通のSense 用語集を使用してください。スニペット、セクション、セクションの説明、アウトライン、チャンク、リンクの種類を区別する際は、この用語集を確認してください。これらの名称は相互に置き換えられません。

まずツリーを確認する

ツリーまたはその設定に不慣れな場合は、次を実行します。

sense status     # config, store, cache, document count, preset coverage
sense map        # fields, hubs, recent notes
sense --list     # saved queries

コマンドで設定が見つからないと報告された場合は、ユーザーがツリーの設定を希望しているときに限り sense init を実行します。単発のクエリは、ツリーを変更する許可にはなりません。

コマンドを選ぶ

必要なこと	コマンド
正確な件数、フィルター、グループ化、または既知のフィールドに関するレポート	sense sql または保存済みの SQL クエリ
あるテーマに関するノート	sense search
1 つのノートのフロントマター、アウトライン、リンク、バックリンク	sense peek
2 つのノート間の最短リンク経路	sense path
あるノートからリンクされていない類似ノート	sense related
ツリーの構造と利用可能なフィールド	sense map

まず結果の範囲を絞って実行します。最初の結果で答えが得られない場合に限り、--k の値を増やす、プリセットの範囲を広げる、または検索語を増やします。

sense search "pricing" --k 10
sense search "sourcing quotes" --preset raw
sense peek notes/pricing-model.md
sense path onboarding.md pricing-model.md
sense related notes/pricing-model.md --k 10
sense sql "SELECT path FROM frontmatter WHERE status = ? LIMIT 50" active

構文を組み立てる前にストアガイドを読む

設定の store キーで、SQL 方言とテキスト検索の文法が選択されます。キーを省略した場合は sqlite になります。sense search では、すべてのストアで単独の単語と引用符で囲んだフレーズを使用できます。高度な演算子と、生のテキストインデックス SQL の仕様はストアによって異なります。

エンジン関数、日付、JSON、テキストマッチング、ネイティブ型を使用する生の SQL を記述する前に、該当するガイドを読んでください。高度な検索演算子を使用する前にも、ガイドを確認してください。

• SQLite クエリガイド
• DuckDB クエリガイド
• Turso クエリガイド

テーブル、? プレースホルダー、引用符で囲んだ識別子、has()、basename()、プリセットの scope バインディングは共通です。移植可能な SQL には、スキーマと、特定のエンジンに依存せずに使えるクエリが記載されています。

検索と根拠

search は、選択したプリセットで有効になっているシグナルを組み合わせます。

シグナル	根拠
match	ノートに検索語が含まれています。snippets に一致した箇所が表示されます。
link	検索に一致したノートから、このノートへのリンクがあります。
vector	埋め込みモデルが、このノートをクエリの近くに配置しました。検索語が含まれていない場合もあります。

match+link のような組み合わせは、複数のシグナルによってその行が返されたことを意味します。score は、その検索結果内でのみ行を順位付けします。検索間で比較しないでください。similarity は、現在の結果とモデル内でベクトル根拠を順位付けします。ツリーをまたいで固定の類似度しきい値を適用しないでください。

lines の値は、インデックス化されたノート内の行範囲を示します。単語の一致箇所や埋め込みチャンクを含むセクションを特定できます。値がある場合は、その範囲を読んでください。範囲が null の場合、ノート全体が参照先です。ベクトルのみの行には語彙的なスニペットがなく、ノートにクエリ語が含まれている証拠ではなく、手がかりとして扱ってください。

検索結果を事実に関する主張の根拠として使う場合、不在が重要な場合、結果にノイズが多い場合、またはシグナルの重みを調整する場合は、検索の根拠とトラブルシューティングをお読みください。

sense search --explain --format json は、返されたノートについて、実際の順位付けへの寄与を追加します。順位付けは変更せず、返されなかった結果すべてについて説明するものでもありません。寄与と via の根拠ラベルの違いについては、検索ガイドで説明しています。

スコープと出力

引数なしのコマンドでは default プリセットが使われます。--preset <name> で別のプリセットを選択します。search、map、peek、path、related では、--include、--exclude、--no-exclude によって、1 回の呼び出しに限りクエリのスコープを変更できます。ただし、どのプリセットでもインデックス化されていないファイルにはアクセスできません。実際の対象範囲は sense status で確認できます。スコープは結果を選択するものであり、プリセットはセキュリティ境界ではありません。

peek は、ベース名を試す前に、スコープ外の完全一致パスを拒否します。ベース名はスコープ内で解決し、解決されたリンクとバックリンクのうちスコープ内のものだけを表示します。未解決の対象は記述されたまま残ります。path は、インデックス化されたツリー全体から両端のノートを解決し、中間のノートにはスコープを適用します。related は、インデックス化されたツリー全体からシードを解決し、結果候補にはスコープを適用します。

peek --section-count-limit n はセクションの説明数を制限します。--link-count-limit n は、外部リンク、バックリンク、未解決リンクの各グループを個別に制限します。どちらも既定値は 20 で、正の安全な整数を指定する必要があります。必要なアウトラインやリンクが切り詰められている場合は数を増やし、トリアージの場合は減らしてください。合計数は引き続き、選択されたグループ全体を示します。制限によってスコープが広がることはありません。セクションの説明は、どこを読めばよいかを示すものであり、セクションの文章を返すものではありません。

--where は、フロントマターのエイリアス f を使って、検索コマンドとグラフコマンドを絞り込みます。

sense search "pricing" --where "f.status = 'active' AND has(f.tags, 'sales')"

sense sql は既定でインデックス全体を対象にします。--preset を指定すると、コマンドは一時的な scope(path) テーブルをバインドします。SQL ではこのテーブルを結合する必要があります。

sense sql "SELECT f.path FROM frontmatter f JOIN scope ON scope.path = f.path" --preset default

テーブル出力は人が読むためのものです。コードやエージェントが行を解析する場合は --format json を使ってください。大量の行をファイルにリダイレクトする場合は --format csv を使ってください。sql、search、related、保存済みクエリは、3 種類すべての形式に対応しています。map、peek、status、path はテーブルと JSON に対応しています。

保存済みクエリ

再利用する場合に限り、クエリを sense.config.json に保存します。

{
  "queries": {
    "by-tag": { "sql": "SELECT path, title FROM frontmatter WHERE has(tags, ?) ORDER BY path" },
    "hot": { "search": "pricing", "preset": "raw", "k": 20 }
  }
}

これらは sense by-tag urgent および sense hot として実行します。呼び出し時のフラグは、保存済み検索の preset、k、または where の値を上書きします。

保存済みエントリを実行すると、そのエントリが検証されます。終了コード 0 は実行されたことを示し、6 は呼び出しに別の引数が必要であることを示します。4 は、クエリ、ストア、CLI のブートストラップの失敗など、運用上のエラーを示します。空の結果も有効なデータの場合があるため、クエリの目的に照らして解釈してください。

テーブル

テーブル	内容
frontmatter	検出された各フロントマターキーの列に加え、path、_mtime、_ctime、_size、_rank、_parse_error
content	path、title、summary、作成者が記述したテキスト、およびストアが管理する検索列
links	src、記述された target、解決済みの dst、embed
tags	フロントマターとインラインタグを統合し、重複を除去したもの
sections	見出し、レベル、行範囲、トークン推定値
preset_files	各プリセットの対象となるパス

機能によってテーブルが追加されることがあります。sense map と sense status で有効な機能を確認できます。

_parse_error が null 以外の場合、そのファイルのフロントマター値は復元されていません。フィールドの欠落と無効なフロントマターを区別するには、フィルターに _parse_error IS NULL を含めてください。照合が最初に実行されるため、修正は次のコマンドで反映されます。

読み取りの基本方針

回答に必要な列だけを選択してください。行を返す探索には LIMIT を使用してください。content.text よりも、path、title、summary、範囲を限定したスニペットを優先してください。COUNT や GROUP BY などの集計は、結果の形によってすでに範囲が限定されています。

結果から大きなノートが見つかった場合は、peek を使ってから、該当する行範囲を読み取ってください。小さなファイルは全体を読むほうが効率的な場合があります。

コマンドの実行例は EXAMPLES.md にあります。

メンテナンス

• CLI がインストールされていない場合は、npm install -g sensemaking でインストールします。
• sense status はキャッシュのパスとウォッチャーの状態を表示します。
• 状態に疑いのある派生インデックスを再作成するには、sense build --force を使用します。ソースファイル、設定、ウォッチャーの所有権の申告はそのまま保持されます。
• 頻繁な編集の間、別のプロセスに設定済みのすべての機能を準備した状態に保たせるには、sense watch を使用します。デフォルトのクエリは、必要な機能のために設定済みのツリーをスキャンし、ベクトルの準備を対象条件を満たすパスに限定します。--no-build は完了済みの世代のみを読み取ります。