ローカルナレッジベース

ローカルナレッジベースは、VelaTerm で作成・整理する Markdown ファイルを収めた通常のフォルダーです。ノートと添付ファイルはそのフォルダーに保存されるため、ほかのエディターでも引き続き編集できます。一部のメニュー項目ではローカルナレッジベースを「保管庫」と呼んでいますが、どちらも同じフォルダーを指します。

ローカルナレッジベースと並んで、組み込みの「セッションナレッジベース」があります。セッションナレッジベースには、エージェントがセッションから整理したナレッジが保存され、独自の項目、出典、変更履歴が管理されます。セッションナレッジベースを参照してください。

ナレッジベースを開く

右パネルのナレッジのアイコン（ツールチップは「ナレッジベース」）をクリックします。中央に「ナレッジベース」タブが開き、次の項目を含むホームページが表示されます。

検索ボックス（「セッションのナレッジとローカルノートを検索…」。後述の「検索」の節を参照してください）
「セッションナレッジベース」
「ローカルナレッジベース」
「ナレッジベースを開く」ボタンと「ナレッジベースを作成」ボタン

右パネルには、「セッションナレッジベース」「アーカイブ済みセッション」「ローカルナレッジベース」の3つを最上位とするツリーが表示されます。矢印をクリックすると、その場でフォルダーが展開されます。複数のナレッジベースを同時に展開することもできます。フォルダー名をクリックするとその内容が表示され、ノートをクリックするとノートが開きます。ツリーの上部にある「ナレッジベース」リンクでホームページに戻り、ページのヘッダーにある「1つ上の階層へ」ボタンで、ナレッジベースを離れずに親ページに移動します。

ノートは通常のドキュメントタブで開き、ほかの Markdown ファイルと同じように編集、保存、検索、PDF エクスポートができます（ドキュメントとブラウザタブを参照）。「ナレッジベース」タブはタブバーに残るため、元の場所に戻れます。

ローカルナレッジベースを開く・作成する

開く：「ナレッジベースを開く」をクリックし、フォルダーを選びます。デスクトップアプリではシステムのフォルダー選択画面が表示され、ブラウザのクライアントでは接続先のコンピューターのフォルダーを参照する画面が表示されます。既存の Obsidian の保管庫（vault）も、そのまま開けます。ファイルは元の場所に置かれたままで、.obsidian などの隠しフォルダーはインデックスの対象にならず、変更もされません。
作成：「ナレッジベースを作成」をクリックし、「名前」を入力して「フォルダー」を選び（「参照」も使えます。提案される場所は ~/Notes です）、確定します。VelaTerm がフォルダーを作成して開きます。親フォルダーはあらかじめ存在している必要があり、同じ名前のフォルダーがあってはなりません。条件を満たさない場合は、「移動先または同名のファイルが既に存在します。別の名前かフォルダーを選んでください。」と表示されます。既存のフォルダーを使うには、代わりに「ナレッジベースを開く」を選んでください。
名前の変更：ツリーでナレッジベースを右クリックし、「名前を変更」を選びます。ディスク上のフォルダーの名前が変更されます。
閉じる：ナレッジベースのツールバーで「保管庫を閉じる」をクリックするか、ツリーでナレッジベースを右クリックして同じ項目を選びます。閉じると一覧からフォルダーが外れますが、ファイルはディスクに残ります。同じフォルダーをもう一度開くと、ごみ箱とインポート履歴も元のまま残っています。

ここでいう「ローカル」とは、接続先の VelaTerm バックエンドが動作しているコンピューターのことです。ブラウザのクライアントでは、「ナレッジベースを開く」でそのコンピューターのフォルダーを参照し、インポートではブラウザで選んだファイルがそのコンピューターにアップロードされます。

ファイルとフォルダーのインポート

インポート先のナレッジベースを開き、ツールバーの「読み込む」をクリックします。
インポート先の「フォルダー」を選び、「ファイルを選択」または「フォルダーを選択」をクリックするか、ファイルやフォルダーをインポート領域にドラッグします。
一覧を確認して確定します。

インポートはバックグラウンドで実行されるため、コピー中もページを切り替えたり、ノートを開いたりできます。進捗はナレッジベースのツールバーとホームページに表示され、インポートのダイアログまたは「インポート履歴」からキャンセルできます。完了すると、インポートされたファイルとスキップされたファイルの数がバナーに表示されます。ウィンドウにフォーカスがない場合は、システム通知（「インポートが完了しました」または「インポートに失敗しました」）が表示されます。1つのナレッジベースで同時に実行できるインポートは1つだけです。

インポートでは、ASCII 以外の文字を含むファイル名、フォルダーの相対的な構成、添付ファイルも含めて、ファイルがそのままコピーされます。元のファイルが変更されることはありません。フォルダーをインポートすると、そのフォルダー自体も含まれます。既存のファイルを上書きするファイルが1つでもある場合は、一括インポート全体が拒否されます。隠しファイルと、設定用の隠しフォルダーはスキップされます。ブラウザのファイル選択画面では空のフォルダーを受け渡せないため、空のフォルダーはインポートされません。

1回のインポートに含められるのは、最大 5,000 個のファイル（スキップされる隠しファイルも数に含まれます）、合計 1 GiB まで、1ファイルあたり 100 MiB までです。ファイルはいったん一時領域に置かれ、すべてが届いてからインポート先に表示されます。そのため、アップロードが中断されても、書きかけのノートが表示されることはありません。

「インポート履歴」には、すべてのインポートが、日時、インポート先（最上位のフォルダーは「ナレッジベースのルート」）、状態（「インポート中」「完了」「失敗」「キャンセル済み」「中断」）、インポートされたファイルとスキップされたファイルの数、サイズ、所要時間とともに一覧表示されます。「ファイル（N）」をクリックすると、各ファイルとスキップされた理由を確認できます。「記録を削除」は履歴から記録を削除しますが、インポートされたファイルは削除されません。アプリが予期せず終了した場合など、進捗が2分以上止まったインポートは「中断」になります。その記録を削除すると、そのインポートのために一時領域に置かれていたファイルも削除されます。

ノートの作成と整理

ナレッジベースのページには、「最近のノート」「ごみ箱」「インポート履歴」の各ビュー、「新規ノート」ボタン、ツールバーの「新規フォルダー」「読み込む」「保管庫を閉じる」ボタンがあります。ノートの一覧は、タグで絞り込んだり（「すべてのタグ」）、「更新日時順」または「タイトル順」で並べ替えたりできます。

ナレッジベースのページを表示している間は、⌘N / Ctrl+N で「新規ノート」を作成し、⌘O / Ctrl+O で「クイックオープン」（パスでノートを探す機能）を開き、⌘⇧F / Ctrl+Shift+F で「ノートを検索…」ボックスに移動します。
ノートの名前を変更するには、ツリーでノートを右クリックして「名前を変更」を選びます。ノートを移動するには、同じナレッジベース内の別のフォルダーにドラッグします。「削除」を選ぶと、ノートはそのナレッジベースのごみ箱に移ります。
フォルダーを開いているときに「名前の変更・移動」を使うと、ナレッジベースのルートからの相対パスで指定した場所にフォルダーを移動できます。移動先の親フォルダーはあらかじめ存在している必要があります。ノートやフォルダーを移動すると、同じナレッジベース内のほかのノートにあるリンクが更新されます。その際、リンクの表示テキストは保たれ、コードの部分は変更されません。
削除した項目は、ナレッジベース内の .vkb-trash フォルダーに移ります。項目を元に戻すには、「ごみ箱」を開いて「復元」をクリックします。同じ名前の既存のファイルが上書きされることはありません。
タグは、本文中の #tag と、YAML の tags のリストまたは配列から取得されます。
ノートに貼り付けた画像は、ノートと同じ場所にある assets フォルダーに保存されます。

ページが表示されている間、ツリーと一覧は約5秒ごと、およびウィンドウにフォーカスが戻ったときに更新されます。開いているドキュメントタブは、ほかのプログラムによる変更を検出すると、再読み込みを提案します。

ナレッジベースのページ、ダイアログ、インポート履歴、検索、検索範囲、タグ、並べ替え、クイックオープンにはそれぞれ固有の URL があるため、ページを再読み込みしたり、ブラウザの「戻る」「進む」ボタンを使ったりできます。保存していないテキストやフォームの入力内容は、URL に含まれません。

検索

ホームページ：セッションナレッジベースとすべてのローカルナレッジベースをまとめて検索し、結果を取得元ごとにまとめて表示します。アーカイブ済みセッションは含まれません。
右パネル：ツリーの上にある「ノートを検索…」で、すべてのローカルナレッジベースを検索します。
ナレッジベースのページ：「ノートを検索…」で、ノートの名前、パス、本文を検索します。「検索範囲」で「このナレッジベース」と「すべてのナレッジベース」を切り替えます。

複数の語を入力した場合は、すべての語に一致する必要があります。各結果には、ナレッジベースまたはセッションのグループ、抜粋、行番号、一致した数、そのノートがリンクしている「関連ノート」が表示され、いずれもクリックすると開きます。↑ キーと ↓ キーで結果を選び、Enter キーで開き、Esc キーで検索をクリアします。結果は、名前またはパスに一致するもの、一致した数の多いもの、更新日時の新しいものの順に並びます。表示される結果は最大 100 件で、それを超える場合は、一覧の末尾に「先頭の結果のみ表示しています。キーワードを絞り込むと残りを確認できます。」と表示されます。

VelaTerm はまず完全一致を探し、見つからない場合にだけ近似一致に切り替えて、「完全一致はありません。近似の結果を表示しています。」と表示します。近似一致は、ラテン文字と数字からなる語に適用されます。対象は、文字が同じ順序で含まれるもの（knwl で knowledge が見つかります）、頭文字（kb で knowledge base が見つかります）、軽い入力ミス（4文字以上の語では1文字、8文字以上の語では2文字まで。knoledge で knowledge が見つかります）です。中国語などラテン文字以外のテキストは、完全一致で照合されます。

リンクと既存ファイルとの互換性

VelaTerm は、一般的な [[note]]、[[folder/note|label]]、[[note#heading]] の形式、標準的な Markdown の相対リンク、![[image.png]] を認識します。これらは、ノートの移動時のリンクの更新、検索結果の「関連ノート」の表示、後述の vkb コマンドに使われます。エディターでは、[[…]] のリンクはプレーンテキストとして表示されます。同じ名前のファイルが複数ある場合、短いリンクはリンク先が一意に決まるときだけ解決されます。一意に決まらない場合は、フォルダーのパスを含めて書いてください。

ファイルは通常の Markdown のままで、YAML のフロントマターもファイル内に残ります。エディターのソースモードでは、フロントマターがそのまま表示されます。UTF-8 以外の Markdown ファイルと 5 MiB を超える Markdown ファイルはノートとして一覧に表示されず、「スキップ済み」として数えられます。1つのナレッジベースに含められるファイルとフォルダーは最大 50,000 個です。これを超えるフォルダーは開けず、「ファイルまたは選択した内容が保管庫の上限を超えています。」と表示されます。シンボリックリンクはたどりません。

これらの機能は、ローカルのファイル、フォルダー、Markdown、リンク、検索を使った日常的な作業に対応しています。Obsidian のプラグイン、テーマ、Canvas、ブロック参照、ノートの埋め込み、YAML のエイリアスには対応していません。これらに関係するファイルは変更されずにそのまま残ります。ファイルの構成とリンクの構文については、Obsidian のドキュメントの保管庫、内部リンク、添付ファイルを参照してください。

セッションナレッジベースからのコピーとエージェントからの照会

セッションナレッジベースで項目を開き、「ローカル保管庫にコピー」を選んで、コピー先のナレッジベースとファイル名を指定します。コピーは独立した Markdown のノートになり、元の項目、その出典スナップショット、変更履歴はそのまま残ります。

VelaTerm のセッションでは、ユーザーまたはエージェントが vkb を使って、登録済みのローカルナレッジベースを読み取れます。

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes は、現在のバックエンドに登録されているすべてのローカルナレッジベースを検索します。各結果には、vaultId、vaultName、path、absolutePath、line、matches、score、matched（実際に一致したテキスト）、related（このノートがリンクしているノート）、summary（一致箇所の前後のテキスト）が含まれます。応答には、total、hasMore、unavailable（読み取れなかったナレッジベース）、fuzzy（結果が近似一致かどうか）も含まれます。返される結果は最大 100 件です。
note は、ノートの本文、見出しの構成、リンク、バックリンク、タグを返します。
search は、セッションナレッジベース、ローカルのノート、およびコードのインデックスがある場合はコードグラフから、一致した結果を返します（コードグラフとナレッジベースを参照）。

これらのコマンドは読み取り専用で、ノートを変更することはありません。また、VelaTerm がナレッジベースの内容をセッションに自動的に追加することもありません。

データの保存とログ

ノートと添付ファイルの正本は、ディスク上のファイルです。アプリケーションのデータベース（kb_* テーブル）には、登録済みのナレッジベースの一覧、ごみ箱の記録、インポート履歴、再構築できる検索キャッシュだけが保存されます。セッションナレッジベースは、専用の memory_* テーブルを使います。

開く、書き込み、移動、削除、復元、インポートの各操作は、操作 ID、件数、所要時間とともに実行時ログに記録されます。ノートの内容が記録されることはありません。これらの行には knowledge イベントが使われます。VLX_LOG_DIR が設定されていない場合は、VLX_KNOWLEDGE_LOG_DIR でその出力先ディレクトリを指定します。インポート履歴はデータベースに保存され、「インポート履歴」ページに表示されます。ナレッジベースを完全にバックアップするには、そのフォルダーと、ごみ箱とインポートの記録を保持しているアプリケーションデータの両方を保存してください。