セッションナレッジベース

この章では、「セッションナレッジベース」「整理履歴」「アーカイブ済みセッション」について説明します。ローカルの Markdown ファイルの管理、編集、インポートについては、ローカルナレッジベースで説明しています。

セッションナレッジベースには、ナレッジ、判断、制約、教訓が、プロジェクト → セッション → 項目の階層で保存されます。生成された項目は独立して保存されるため、元のセッションが変わっても変更されず、手動で編集することもできます。セッションナレッジベースは接続先の VelaTerm バックエンドに属し、そのバックエンドのプロジェクトとセッションで共有されます。別のサーバーに接続すると、そのサーバーのナレッジベースが表示されます。

セッションナレッジベースは、セッション内容の検索とは別の機能です。セッションの検索では元の会話からテキストを探しますが、ナレッジベースでは保存済みの項目だけを検索します。VelaTerm は、ユーザーが指示したときに項目を整理、保存、表示します。新しいセッションに項目を自動的に追加することはありません。

セッションを整理する

サイドバーのセッションまたはそのタブを右クリックし、「セッションナレッジベースに整理」を選びます。アーカイブ済みセッションでも同じ操作ができます。
「エージェント」で、Claude、Codex、Grok Build、OpenCode、Pi、OMP のいずれかを選びます。VelaTerm は「設定」▸「エージェント」で指定された実行ファイルのパスを使い、指定がなければ PATH からプログラムを探します。見つからないエージェントは「未インストールまたは未設定」と表示され、選べません。
必要に応じて、「モデル（任意）」と「思考の深さ」を選びます。「既定のモデル」と「エージェントの既定値」を選ぶと、エージェント自身の設定に従います。モデルの一覧はセッションの作成時と同じもので、思考の深さの選択肢は、それに対応するモデルでのみ表示されます。VelaTerm は、最後に使ったエージェント、モデル、思考の深さを記憶します。エージェントはログイン済みで、選んだモデルを利用できる必要があります。
「整理して保存」をクリックします。選んだエージェントがセッションのテキストを受け取り、エージェント自身のモデル設定で処理します。
タスクの状況は「整理履歴」で確認できます。ダイアログを閉じても、タスクは停止しません。

VelaTerm は、エージェントの会話の記録があればそれを読み取ります。ない場合は、セッションのターミナルの録画（ターミナルの使い方を参照）から、ターミナルの制御コードを取り除いたものを使います。どちらも読み取れない場合は、「このセッションには読み取り可能な会話がありません。」と表示されます。ターミナルの録画には画面に表示されたテキストが含まれ、再描画された内容が含まれることもあるため、整理を行うエージェントは、その出力を検証済みの事実として扱わないようにする必要があります。

出典スナップショットには、整理のために読み取ったテキストが保存されます。プロジェクト名とセッション名はセッションが最初に追加されたときに保存され、その後にプロジェクトやセッションの名前の変更、移動、アーカイブ、削除が別の場所で行われても更新されません。

セッションをもう一度整理すると、セッションが再び読み取られ、以前にそのセッションから生成された項目が、手動で加えた編集も含めて置き換えられます。テキストとモデルの設定が変わっていなくても同様です。セッションにまだ完了していないタスクがある場合は、新しいタスクがそれに取って代わります。古いタスクがすでに実行中の場合は、古いプロセスが停止した後で新しいタスクが自動的に開始されます（「このセッションの前のタスクが停止すると、自動的に開始します。」）。古いタスクは履歴に残ります。

整理のしくみ

整理は3つの段階で行われ、タスクの進捗として表示されます。

テーマを抽出中：セッションを区切って読み取り、再利用できるナレッジを抽出します。テーマの統合はこのタスクの中でのみ行われ、ほかのセッションの項目や、以前の手動の編集は使われません。
知識を統合中：テーマごとに抽出された内容を、ナレッジ、制約、不確かな点を保ったまま統合します。エージェントには、後から行われた訂正や矛盾を考慮し、結論を作り出さないよう指示しています。
記事を保存中：VelaTerm がフィールド、出典、リンク、バージョンを確認し、1回のデータベーストランザクションで、そのセッションから生成された項目を置き換えます。同じタイトルの項目は同一の項目として扱われ、新しい版が追加されます。生成されなくなった項目は変更履歴とともに削除され、その項目へのリンクも削除されます。整理は成功したものの再利用できる内容が見つからなかった場合は、そのセッションから以前に生成された項目が消去されます（「再利用できる知識は抽出されませんでした。このセッションから生成済みの項目は削除されました。」）。確認での不合格、キャンセル、バージョンの競合が起きた場合は、以前の項目が変更されずに残り、途中までの結果は保存されません。

エージェントは構造化された内容を返し、データベースの変更はすべて VelaTerm が行います。項目は互いにリンクし、「この記事へのリンク」の一覧は自動的に算出されます。出典スナップショットと変更履歴は、元のセッションを削除しても引き続き利用できます。

整理されたナレッジの品質は、引き続きユーザー自身で判断する必要があります。誤りがある場合は、項目を編集するか、以前の版を復元してください。復元すると新しい版が作成され、置き換えられた版も保持されます。

整理履歴

「整理履歴」には、整理のタスクが1ページに40件ずつ表示されます。各タスクには、エージェント、モデル（選ばなかった場合は「既定のモデル」）、思考の深さ、日時が表示され、実行中のタスクには現在の段階（「テーマを抽出中」「知識を統合中」「記事を保存中」）も表示されます。タスクの状態は「開始待ち」「処理中」「キャンセル中」「完了」「失敗」「キャンセル済み」のいずれかで、一覧からタスクの「出典スナップショット」と、生成された項目を開けます。

「キャンセル」は、待機中または実行中のタスクを停止します。実行中のタスクには、エージェントのプロセスが停止するまで「キャンセル中」と表示されます。キャンセルしても、出典スナップショットは削除されません。
「再試行」は、失敗したタスクやキャンセルしたタスクを、同じ出典スナップショット、モデル、思考の深さでやり直します。履歴には、タスクを作成したときの設定が表示されます。既定値が表示されている場合、それはエージェントが判断したことを意味し、VelaTerm が特定のモデルに決めたわけではありません。

異なるセッションは並行して整理できます。1つのセッションで同時に実行されるタスクは1つだけで、同じセッションを再び送信すると、キューを作らずに最新の待機中のタスクだけが残ります。待機中のタスクはデータベースに保存され、アプリの再起動後も引き継がれます。実行中のタスクが2分間進捗を報告しない場合は、中断されたものとして扱われます（「整理処理が中断されました。保存済みの出典スナップショットから再試行できます。」）。待機している時間は、タスクの制限時間に含まれません。

整理の実行中も項目を編集できます。タスクの実行中に、そのセッションから生成された項目が編集または削除された場合、タスクはバージョンの競合を報告します。加えた変更は保持され、後で再試行できます。異なるセッションでは同じ項目のタイトルを使えますが、1つのセッション内ではタイトルが重複しないようにする必要があります。

項目の閲覧と管理

右パネルからナレッジベースを開き（ローカルナレッジベースを参照）、「セッションナレッジベース」をプロジェクト、セッション、項目の順に展開します。プロジェクトまたはセッションをクリックするとその項目が一覧表示され、項目をクリックすると内容を読めます。「1つ上の階層へ」ボタンで親ページに戻ります。

一覧ページでは、検索（「記事のタイトルと本文を検索…」）、タグによる絞り込み（「すべてのタグ」）、「更新日時順」または「タイトル順」での並べ替え、更新ができます。検索の対象はタイトル、要約、本文、タグで、複数の語を指定できます（すべての語に一致する必要があります）。タイトルに一致する結果が上位に並び、各結果には直接関連する項目も表示されます。完全一致がない場合は、ローカルナレッジベースの検索と同じように近似一致の結果が表示されます。
セッションの項目は、1ページに40件ずつ表示されます。プロジェクトとセッションの一覧はこの制限で切り詰められることはなく、ツリーの長い一覧には「さらに読み込む」が表示されます。
項目のページには、Markdown の本文、「関連記事」「この記事へのリンク」「出典」「変更履歴」が表示されます。本文はその場で編集して ⌘S / Ctrl+S で保存できます。また、「編集」でタイトル、要約、タグを変更したり、「Markdown をエクスポート」「ローカル保管庫にコピー」「削除」を実行したりできます。項目を削除すると変更履歴も削除されますが、元のセッションとそのスナップショットは残ります。
「記事を新規作成」で、項目を手動で作成できます。手動で作成した項目は「手動作成」グループに表示されます。

ツリーでは、次の管理操作もできます。

項目を右クリックすると、名前の変更や削除ができます。項目を別のセッションにドラッグすると、所属先を変更できます。
プロジェクトまたはセッションのグループを右クリックすると、名前の変更や、そのグループの項目の削除ができます。グループの名前を変更すると、実際のプロジェクトやセッションの名前も変更されます。グループを削除しても、削除されるのはそのナレッジ項目だけです（「このグループのナレッジ記事 N 件をすべて削除しますか？プロジェクトまたはセッション自体は残ります。」）。
セッションを別のプロジェクトにドラッグすると、実際のセッションがそのプロジェクトに移動します。
「手動作成」「過去に統合された項目」「元のプロジェクトが不明」の各グループは、名前を変更できません。

項目のページ、編集フォーム、出典スナップショット、版、整理のダイアログ、整理履歴にはそれぞれ固有の URL があり、選んだプロジェクト、セッション、検索、絞り込み、並べ替え、ページも URL に含まれます。

アーカイブ済みセッション

アーカイブ済みセッションは、ナレッジベースで管理します。ナレッジベースのツリーでは、「セッションナレッジベース」の隣に「アーカイブ済みセッション」があり、アーカイブ済みセッションが元のプロジェクトごとにまとめられています。サイドバーのヘッダーにある「アーカイブ済みセッション」ボタンでも、同じ場所が開きます。

メインの領域には、すべてのアーカイブ済みセッションがプロジェクトごとに一覧表示されます。開いたセッションには2つのタブがあります。「会話」には会話全体が、「ナレッジ記事」にはそのセッションから生成された項目が表示されます。
「アーカイブ内容を検索…」は、アーカイブ済みセッションの全文だけを検索し、一致した結果をセッションごとにまとめて表示します。
開いたアーカイブ済みセッションでは、「通常のセッションに戻す」「セッションナレッジベースに整理」「完全なコンテキストを Markdown でエクスポート」（Claude と Codex のセッション）、「完全に削除（録画も含む）」を実行できます。完全な削除は、確認の手順なしにすぐ実行されます。
項目と出典スナップショットは別に保存されているため、セッションをアーカイブ、復元、削除しても、既存のナレッジ項目は変わりません。復元したセッションでは、会話を続けられます。

以前のバージョンのデータ

VelaTerm が古いデータをアップグレードした際、元のセッションが1つだけの項目は、そのセッションに割り当てられました。すでに複数のセッションを統合していた項目は、「過去に統合された項目」グループにそのまま保持されています。これらの項目は分割されず、元のセッションのいずれかをもう一度整理しても置き換えられることはありません。出典のない項目は「手動作成」に移されました。まだ存在していたプロジェクトの情報は、アップグレード時に一度だけ補完されました。プロジェクトを特定できなかった出典は、元のセッション名とスナップショットとともに「元のプロジェクトが不明」に表示されます。

データと制限

セッションナレッジベースは、セッションの検索インデックスとは別に、アプリケーションの SQLite データベース（memory_* テーブル）に保存されます。インターフェースが保持するのは、表示中の内容と保存していないフォームの入力内容だけです。検証、バージョンの確認、重複の検出、すべての書き込みはバックエンドで行われます。

1つの出典は最大 2,000,000 文字、抽出の1区切りは最大 24,000 文字、モデルへの1回の入力は最大 350,000 文字、1つの項目の本文は最大 200,000 文字です。
エージェントの1回の呼び出しは最大10分間実行でき、その各出力ストリームは最大 8 MiB まで出力できます。
OpenCode、Pi、OMP では、1回の呼び出しで渡すテキストは 128 KiB までに制限されます。
エージェントが想定した構造に合わない出力を返した場合、VelaTerm は最大3回まで再度依頼します。

これらの制限を超えた場合は、明示的に失敗として扱われます（「出典、コンテキスト、または出力が対応サイズを超えています。内容の切り詰めや記事の保存は行われていません。」）。内容が切り詰められて保存されることはありません。

整理の処理は、アプリケーションのデータディレクトリにある logs/runtime-*.log に記録されます。VLX_LOG_DIR が設定されていない場合は、VLX_MEMORY_LOG_DIR で出力先ディレクトリを指定します。VLX_MEMORY_LOG_LEVEL=error を指定するとエラーだけが記録され、off を指定するとこのモジュールのログが無効になります。ログには、タスクと段階、入力と出力の件数、所要時間、文字数、SHA-256 ダイジェスト、トークンの使用量が記録されます。プロンプト全体、出典のテキスト、モデルの応答、認証情報、エラー出力が記録されることはありません。元の資料は出典スナップショットに保存されています。

コードグラフとの関連付け

ナレッジ項目はコードのシンボルに関連付けることができ、項目のページの「コードへの参照」からコードグラフに移動できます。関連付けたファイルが変更されると、その項目に確認が必要であることが表示されます。確認を済ませても、項目の本文は変わりません。セッション内のエージェントは、vkb でコードと項目を照会できます。コードグラフとナレッジベースを参照してください。