Chronicle MCP

Chronicle MCP：ローカル AI チャット履歴の検索と記憶

AI コーディングエージェント向けのプライベートなオフラインメモリです。 Chronicle MCP（chronicle-mcp-server）は、ローカルで動作する stdio MCP サーバーです。お使いのマシン上にある Cursor、Claude、ChatGPT、Cline のチャット記録をインデックス化し、BM25 検索を提供することで、エージェントが過去の会話を貼り直すことなく参照できるようにします。これにより、コンテキストトークンを最大 40% 削減できます。アーカイブとインデックスはディスク上に保存されるため、クラウドサービス、アカウント、API キーは不要です。

‎ ‎ ‎ ‎ ‎

特長 · CLI の仕組み · セットアップウィザード · ツール一覧 · インストール · 自動保存 · テスト · 比較 · よくある質問 · ライセンス

Chronicle は、AI チャットの記録を完全にお使いのマシン上で同期、整理、フォーマット、インデックス化する Model Context Protocol（MCP）サーバーです。ローカルエディターの履歴と LLM のコンテキストをつなぐことで、エージェントは過去の会話ログを検索、比較、取得、参照できます。コードブロックを圧縮し、メッセージの長さを制限する、トークン節約に最適化されたヒューリスティクスを備えており、コンテキストウィンドウの使用量を最大 40% 削減します。

掲載先

1.6.2 の新機能

• 新規インストール時の問題を修正しました。 以前のリリースでは、サーバーが動作しない mcp 2.x を pip がインストールしていました。依存関係を mcp>=1.22,<2 に変更しました。
• ツール定義を書き直しました。 すべてのツールに、タイトル、動作と使用するタイミングの説明、副作用、戻り値、アノテーション（readOnlyHint、destructiveHint、...）が付いています。すべてのパラメーターが文書化され、すべての操作セレクターが列挙型になりました。
• エラーを正しく返すようになりました。 失敗時には isError: true が返されます。また、不明な操作名は、別の操作を暗黙に実行することなく拒否されます。
• 新しい実行方法： uvx chronicle-mcp-server、chronicle serve、chronicle --version、およびDockerfile。
• サーバーの説明、recall_past_work プロンプト、2 つのリソース： chronicle://capabilities と chronicle://chats。

1.6.1 の新機能

• Python 3.10～3.13 での CI に加え、すべてのプッシュとプルリクエストでビルドと twine check を実行します。
• 正確なツールカタログ：8 つのツールに加え、maintain_storage(op_type="capabilities") でも報告されるようになった start_session プロンプト。
• PyPI メタデータ（プロジェクトリンク、キーワード、分類子）を充実させ、コミット済みのビルド成果物がない、よりクリーンなリポジトリを実現しました。

以前のリリースについては、CHANGELOG をご覧ください。

主なアーキテクチャ機能

フォーマット正規化エンジン

AI プロバイダーやエディタークライアントは、さまざまな形式で会話ログを保存します。Chronicle はこれらの構造を、標準的なロールとコンテンツによるメッセージ形式に正規化します。

• ChatGPT のエクスポート：ChatGPT は、会話履歴を再帰的なマッピングノード構造でエクスポートします。Chronicle はこれらのマップをたどってフラット化し、作成タイムスタンプに基づいてメッセージを時系列順に並べ替え、プレーンテキストのメッセージスレッドを抽出します。
• Claude のエクスポート：Claude は、chat_messages フィールド内にネストされたフラットなリストとしてメッセージを構造化します。Chronicle はこれらのリストを解析し、カスタムの送信者ロール（human や assistant など）を標準ロールに対応付け、テキスト文字列をクリーンアップします。
• 汎用および Markdown 形式：Chronicle には、フラットな JSON メッセージリスト（Cline や Continue など）や、User や Assistant などのヘッダーをメッセージの境界に対応付ける構造化 Markdown ログ用のパーサーが含まれています。

コンテキストトークンの最適化

大規模なチャットログは、すぐにコンテキストウィンドウを使い切り、API コストを増加させる可能性があります。Chronicle は、事前にトークンを節約する仕組みを実装しています。

• コードブロックの要約：冗長なコードブロックを、プログラミング言語と行数を示すメタデータの要約に自動的に置き換えます。必要に応じてこの動作を無効にし、コードスニペット全体を確認できます。
• 長さの制限：極端に長い個々のメッセージを、設定可能な文字数の上限で切り詰めます。必要であれば、上限を拡大してツールを再実行できることを知らせるメッセージを追加します。

コンテキストウィンドウのトークン節約グラフ

この節約効果を検証するため、複数ターンの会話ベンチマークを実行しました。以下のグラフは、メッセージターンの推移に伴うトークン使用量の合計を示しています。

繰り返しの構文や大きな生のコードスニペットを簡潔にまとめることで、Chronicle は最大 40 パーセントのトークンを節約し、API 使用コストを直接削減するとともに、コンテキストウィンドウの枯渇を防ぎます。

ハイブリッド分割と BM25 スコアリング検索エンジン

ワークスペース検索の精度を高め、コンテキストを考慮した回答を取得するため、Chronicle は最先端の検索パイプラインを組み込んでいます。

• ハイブリッドドキュメント分割：インデックス作成時に、長い会話を論理的な部分に分割します。連続するメッセージ間の時間が 1800 秒（30 分）を超えた場合は時間に基づいて分割し、4 メッセージのスライディンググループにおける語彙の Jaccard 類似度が 0.12 を下回った場合は語彙に基づいて分割します。各分割は仮想ドキュメント（filename__chunk_idx）として保存され、検索されます。
• Okapi BM25 スコアラー：単純なキーワードマッチングや生の TF-IDF を、Okapi BM25 スコアリング（k1 = 1.5、b = 0.85）に置き換えます。パラメーター b = 0.85 は強い長さペナルティを適用し、長く冗長なチャットログが、短く的確なバグ修正を検索結果で上回らないようにします。
• ハンドオフレシートの優先表示：変更したパス、確定事項、スキップしたテスト、次のアクションを記録した、簡潔なエージェント状態ファイルを保存する専用ツールを統合しています。有効なハンドオフレシートは自動的に優先され、検索結果の最上位に表示されます。

コマンドラインインターフェースの仕組み

cli.py ファイルはシステムのエントリーポイントとして機能し、pyproject.toml の設定（chronicle = "cli:main"）を通じて、システムパス上に統一された chronicle コマンドを登録します。

1. インタラクティブなセットアップウィザード

Chronicle には、依存関係なしで使えるインタラクティブな TTY セットアップウィザードが備わっています。chronicle setup を実行するか、インタラクティブターミナルで引数なしで chronicle を実行すると、セットアップフローが開始されます。

ヒント

セットアップウィザードは上質な紫色のテーマでデザインされており、矢印キーによるナビゲーション、スペースバーでの切り替え、入力欄での編集、パスのリアルタイム検証に対応しています！

キーボードナビゲーションと操作

選択メニューを操作する際は、次のキーを使用します。

ウィザードのフェーズと操作

ウィザードでは、次のフェーズが順に案内されます。

重要

ウィザードの使い方 — ステップごとのガイド

1. プロセスを開始する：ターミナルで chronicle setup を実行し、ウィザードを起動します。
2. モノリシックファイルを分割する：エクスポートした conversations.json（ChatGPT または Claude のもの）のパスを貼り付けます。ファイルは分割され、チャットフォルダー内に個別のスレッドとして保存されます。
3. チャットディレクトリを指定する：デフォルトの ~/universal-chats フォルダーをそのまま使うか、カスタムパスを入力します。
4. 対象の IDE を選択する：
   • Down Arrow を押して VS Code、Trae などまで下にスクロールします。
   • Space を押して選択を切り替えます。
   • Antigravity を選択すると、チェック時にサブ選択肢（Antigravity IDE、Antigravity 2.0、Antigravity CLI）がすぐ下に自動的に展開されます！
   • Other (Enter custom entry) までスクロールし、任意のシステム固有のフォルダー名を入力して、新しいエディターを追加します。
   • パスのリアルタイム検証：カスタム設定パスの親ディレクトリが存在しない場合、画面下部に警告が表示されます：⚠ App/IDE "<name>" was not found on your system.。Backspace で削除するか、有効なパスを入力すると続行できます。
5. 完了して起動する：Enter を押して、選択したすべてのアプリの JSON 設定ファイルを書き込みます。ライブ環境ダッシュボードに、ワークスペース設定の概要がすべて表示されます。

chronicle setup

── Chronicle Archive Setup ─────────────────────────────────────
Do you want to split a single conversations.json file?
Enter path to export file (or press ENTER to skip): 

Enter path to folder containing your conversations [Default: ~/universal-chats]: 
✓ Using existing storage directory: /Users/username/universal-chats
Successfully set chats directory to: /Users/username/universal-chats

Please select the applications/IDEs where you want to install Chronicle MCP:
  (Use arrow keys to navigate, Space to toggle, Enter to confirm)
    [✓] Cursor
    [ ] VS Code (Cline / Roo Code)
    [ ] Trae IDE
    [ ] Claude Code
    [ ] Windsurf
    [ ] Claude Desktop
    [ ] ChatGPT Desktop
❯   [✓] Antigravity
        [✓] Antigravity IDE
        [ ] Antigravity 2.0
        [ ] Antigravity CLI
    Other (Enter custom entry): 

── Chronicle Environment Live ──────────────────────────────────
 ✓ Storage Folder : /Users/username/universal-chats
 ✓ Auto-Saved Configs for: [Cursor, Antigravity IDE]

  How to run the server manually:
  $ uvx --from chronicle-mcp-server chronicle

  recalled in <1ms · 100% local · zero cloud
────────────────────────────────────────────────────────────────

2. Chronicle の統合グローバルコマンド

サブコマンドなしで実行すると、chronicle コマンドは状況に応じて動作します：

• インタラクティブな TTY ターミナル：インタラクティブなセットアップウィザードを起動します。
• 非 TTY／サブプロセス：MCP クライアント向けの stdio トランスポートサーバーを起動します。

カスタム保存ディレクトリを設定する --chats-folder などのオプションを受け付け、add と split のサブコマンドを公開します。

3. クロスプラットフォームのパス解決ルール

CLI は Python の sys.platform と pathlib.Path を使用したパス解決ロジックを実装し、ユーザーディレクトリに関する各 OS の標準的な規則に従います：

4. IDE のネイティブ統合とフォールバックエンジン

CLI ラッパーは、主要な AI 支援開発ツールやエディターを標準でサポートします：

5. shutil.which による ENOENT エラーの防止

ホストクライアント（Claude Desktop や Cline など）は、ユーザーのログインシェル環境変数（.bashrc や .zshrc で定義されたカスタムパスなど）を引き継がないことが多い、分離されたサブプロセス内で MCP サーバーを起動します。

chronicle split /path/to/conversations.json --out /path/to/output_directory

7. グローバルチャットフォルダーの設定

デフォルトでは、Chronicle は処理済みのアーカイブを ~/.chronicle/chats に保存します。--chats-folder パラメーターを使用して、カスタムのグローバル保存フォルダーを設定できます。

chronicle --chats-folder /path/to/custom/chats

指定したパスはローカル設定ファイル（~/.chronicle_settings.json）に保存されるため、複数の開発環境でアーカイブを一元管理できます。

ツールリファレンスカタログ

Chronicle は、その機能を8つのパラメーター化されたツール（6つのコアツールと2つの引き継ぎツール）、2つのプロンプト、2つのリソースに集約しています。この設計により、サーバーのすべての機能を維持しながら、クライアント AI モデルの認知負荷を抑えています。すべてローカルで実行され、ネットワークに接続するツールはありません（openWorldHint: false）。

検証とエラー。 操作セレクター（method、view_type、source_type、insight_type、op_type、action）は列挙型であり、limit、top_k、page、per_page などの件数は1以上である必要があります。無効な値はツールの実行前に拒否されます。チャットファイルが見つからない、日付が無効、選択した操作に必須の引数が不足しているなど、実行時に失敗した場合は、修正方法を説明するメッセージとともに isError: true を含む MCP の結果が返されます。

1. search_history

• 説明：ローカルのチャット記録を統合的に検索・絞り込むインターフェースです。キーワード、Okapi BM25 によるセマンティック検索、日付範囲、関連するチャットの検索に対応しています。
• パラメーター：
  • query (str, default: "")：検索クエリ文字列またはキーワードのリストです。
  • method (str, default: "semantic")：検索方式です。次のオプションに対応しています。
    • semantic：時間経過に伴う指数減衰を適用した Okapi BM25 スコアリングによる標準的なセマンティック検索です。
    • keyword：ファイル内の語句を完全一致で検索します。
    • date_range：日付範囲内に更新されたファイルを絞り込みます（start_date と end_date が必要です）。
    • related：参照ファイルと意味的に近いアーカイブを検索します。
  • keywords (list of strings, optional)：キーワード検索に使用する任意のキーワードリストです。
  • start_date (str, optional)：日付範囲による絞り込みの開始日（YYYY-MM-DD）です。
  • end_date (str, optional)：日付範囲による絞り込みの終了日（YYYY-MM-DD）です。
  • limit (int ≥ 1, default: 50)：キーワード検索または日付範囲検索の最大結果数です。
  • top_k (int ≥ 1, default: 10)：セマンティック検索または関連チャット検索の最大一致数です。
  • client (str, default: "default")：サブフォルダーのクライアント識別子です。
  • file_name (str, optional)：関連検索の参照チャットファイル名です。

2. get_chat_logs

• 説明：保存された記録を統合的に読み取るインターフェースです。トークン節約オプションを使って、ページ分割されたファイル一覧、要約、ファイルメタデータ、またはメッセージ範囲を取得します。
• パラメーター：
  • chat_id (str, optional)：対象チャットのファイル名です。省略すると、利用可能なすべてのファイルが一覧表示されます。
  • view_type (str, default: "content")：取得する情報の種類です。次のオプションに対応しています。
    • content：指定したインデックス範囲内のメッセージテキストを取得します。
    • metadata：メッセージ数や更新日などのファイル統計情報です。
    • summary：冒頭と末尾のコンテキストを示す構造的な要約です。
  • start_msg (int ≥ 1, default: 1)：メッセージ範囲の開始インデックス（1 始まり）です。
  • end_msg (int ≥ 1, default: 20)：メッセージ範囲の終了インデックスです。
  • max_msg_len (int, default: 1000)：トークン数の増加を抑えるためのメッセージの文字数上限です。上限なしにするには 0 を設定します。
  • summarize_code (bool, default: True)：Markdown のコードブロックをメタデータヘッダーに要約します。
  • page (int ≥ 1, default: 1)：フォルダー一覧のページインデックスです（chat_id を省略した場合に使用します）。
  • per_page (int ≥ 1, default: 50)：フォルダー一覧のページあたりの結果数です。
  • client (str, default: "default")：サブフォルダーのクライアント識別子です。

3. sync_workspace_data

• 説明：さまざまなツールや形式の外部会話記録またはワークスペースログを取り込み、インポートし、同期します。
• パラメーター：
  • source_type (str)：ソース種別の識別子です。次のオプションに対応しています。
    • raw_content：テキストバッファーまたはクリップボードから直接 JSON をインポートします。
    • local_path：ディスク上のローカルパスから JSON ファイルをコピーします。
    • agent_transcripts：設定済みのサードパーティ製クライアントフォルダーから記録（JSON、JSONL、MD）を同期します。
    • cursor_agent_transcripts：非推奨です。Cursor ワークスペースのプロジェクト記録フォルダーをスキャンします。
  • payload (str, dict, or list, optional)：入力データペイロードです（未加工の JSON テキスト、ディスク上のファイルパス、またはフォルダーパス）。
  • title (str, optional)：インポート時の対象ファイル名またはタイトルです。
  • source_dir (str, optional)：記録のスキャンに使用するフォルダーディレクトリを上書きします。
  • limit (int ≥ 1, default: 50)：同期するファイルの最大数です。
  • client (str, default: "default")：サブフォルダーのクライアント識別子です。

4. compile_project_insights

• 説明: アクションアイテムの抽出、インデックスの作成、チャットの比較、ブリーフの生成など、チャットログからインサイトを集約してまとめます。
• パラメーター:
  • insight_type (str): まとめる形式です。次のオプションを指定できます。
    • action_items: ToDo、チェックボックス、タスクリストを抽出します。
    • knowledge_index: トピック別に分類されたファイルのインデックスを再構築または一覧表示します。
    • compare_chats: 2つのファイルに共通する用語と固有の用語を分析し、詳しく説明します。
    • project_brief: 複数のチャットの要約とアクションアイテムを1つのMarkdownドキュメントにまとめます。
  • target_chats (list of strings, optional): ブリーフまたは比較の対象となるチャットファイル名のリストです。
  • file_name (str, optional): アクションアイテム抽出の対象となるチャットファイル名です。
  • file_name_a (str, optional): 比較する最初のチャットファイル名です。
  • file_name_b (str, optional): 比較する2つ目のチャットファイル名です。
  • brief_title (str, default: "Project Brief"): まとめたブリーフのタイトル見出しです。
  • rebuild (bool, default: False): すべてのファイルを再スキャンしてナレッジインデックスを更新します。
  • summary_only (bool, default: False): インデックス検索でファイル一覧全体の代わりに、トピックごとのファイル数を返します。
  • client (str, default: "default"): サブフォルダーのクライアント識別子です。

5. maintain_storage

• 説明: サーバー操作、ストレージのクリーンアップ、設定、機能の照会を行います。
• パラメーター:
  • op_type (str): メンテナンス操作の名前です。次のオプションを指定できます。
    • compress: 指定した期間より古いアーカイブをGzipで圧縮します。
    • deduplicate: コンテンツハッシュに基づいて重複ログを検索し、削除します。
    • configure: 自動保存するメッセージ数の上限、パス、トランスクリプトを更新します。
    • capabilities: サーバーのメタ機能とクライアント設定を返します。
  • settings (dict, optional): 設定のペイロード辞書です（configure用）。
  • days_old (int ≥ 1, optional): 圧縮対象とする日数のしきい値です（デフォルトは30）。
  • dry_run (bool, default: True): 削除を実行せずに重複を一覧表示します。
  • client (str, default: "default"): サブフォルダーのクライアント識別子です。

6. manage_session_state

• 説明: アクティブなセッションのキャッシュ、フォルダーの監視、ファイルのマージ、Markdownへのエクスポート、ファイルの削除を管理します。
• パラメーター:
  • action (str): 実行する操作です。次のオプションを指定できます。
    • save: アクティブなメッセージリストをストレージに保存します。
    • register_auto_save: 接続終了時にセッションを自動保存するよう登録します。
    • trigger_auto_save: 保留中のセッションを直ちにディスクに書き込みます。
    • watch_folder: 前回の実行以降のファイル変更を報告します。
    • merge: 既存のチャットアーカイブに新しいメッセージを追加します。
    • export_markdown: JSONトランスクリプトをMarkdownドキュメントに変換します。
    • delete: アーカイブファイルを完全に削除します（confirm=Trueが必要です）。
  • conversation_name (str, optional): アクティブな会話名です。
  • messages (list of dicts, optional): メッセージリストのペイロードです。
  • force_save (bool, default: False): メッセージ数がしきい値に満たない場合でもチャットセッションを保存します。
  • file_name (str, optional): 対象のファイル名です。
  • confirm (bool, default: False): 削除を確認します。
  • new_messages (list of dicts, optional): マージするメッセージリストです。
  • client (str, default: "default"): サブフォルダーのクライアント識別子です。

7. save_handoff_receipt

• 説明：現在の実行状態（未履行の約束、作業状態、証拠、および無効になる条件）を記録した構造化された引き継ぎレシートを保存し、次のエージェントが安全に作業を続けられるようにします。レシートは supersedes を介して連鎖を形成し、インデックス化されます。また、有効なレシートは検索結果の先頭に表示されます。
• パラメーター：
  • obligations（dict）：次のエージェントに残す、未完了の約束や取り決めです。
  • work_state（dict）：変更したファイルや進捗など、作業の現在の状態です。
  • evidence（dict）：実行した、またはスキップしたチェックなどの裏付けとなる証拠です。
  • invalidation（dict）：レシートが古くなる条件（監視対象のファイルなど）と、実行すべき next_safe_action です。
  • status（str、デフォルト："open"）：レシートのステータスです。
  • supersedes（str、任意）：このレシートが置き換える、以前のレシートの ID です。
  • closure（dict、任意）：レシートをクローズする際の詳細（closed_by、closed_at、closure_basis、closure_evidence）です。
  • receipt_id（str、任意）：明示的に指定するレシート ID です。省略すると自動生成されます。
• 戻り値：保存したファイル名とその receipt_id。後続のレシートで supersedes として渡します。
  • client（str、デフォルト："default"）：サブフォルダーのクライアント識別子です。

8. get_handoff_status

• 説明：現在のワークスペースの引き継ぎ状態を返します。有効なレシートの連鎖、ワークスペースがブロックされているかどうか（たとえば、レシートの作成後にファイルが変更された場合）、および次に実行すべき安全なアクションが含まれます。
• パラメーター：
  • client（str、デフォルト："default"）：サブフォルダーのクライアント識別子です。

プロンプト：start_session

• タイトル：Chronicle セッションを開始
• 説明：チャットの開始時に manage_session_state（action="register_auto_save"）で会話を登録し、セッションが自動的に保存されるようエージェントに指示するシステム指示を返します。

プロンプト：recall_past_work

• タイトル：過去の作業を呼び出す
• 引数：topic（str）：検索する内容。「認証のリファクタリング」などです。
• 説明：エージェントが get_handoff_status を確認し、search_history で検索してから、少量ずつメッセージ範囲を指定して get_chat_logs で最適な検索結果を読む手順を案内します。

リソース

• chronicle://capabilities（JSON）：maintain_storage(op_type="capabilities") と同じサーバー機能レポートです。
• chronicle://chats（テキスト）：get_chat_logs で一覧表示される、アーカイブ済みチャットファイルの最初のページです。

インストールと設定

クイックセットアップ（推奨）

パッケージを PyPI から直接インストールし、対話型セットアップウィザードを実行すると、ストレージパスとエディター連携が自動的に設定されます。

pip install chronicle-mcp-server
chronicle setup

システムの前提条件

• Python 3.10 以降。
• Python パッケージ mcp 1.22 以降、2.0 未満（Model Context Protocol SDK。自動的にインストールされます）。
• Python setuptools（パッケージとしてインストールする場合）。

サーバーを直接起動する

MCP クライアントは stdio 経由で Chronicle を起動します。クライアント設定では、以下のいずれのコマンドもサーバーコマンドとして使用できます。

uvx chronicle-mcp-server          # no install needed
chronicle-mcp-server              # after pip install chronicle-mcp-server
chronicle serve                   # same server, through the main CLI
chronicle --version

環境変数（すべて任意）：

Docker

このイメージは、アーカイブを/dataボリュームに配置して、同じstdioサーバーを実行します。

docker build -t chronicle-mcp .
docker run -i --rm -v "$HOME/.chronicle:/data" chronicle-mcp

MCPの通信はstdinとstdoutを介して行われるため、必ず-iを指定してください。クライアント設定では、コマンドにdockerを、引数に["run", "-i", "--rm", "-v", "/path/to/archive:/data", "chronicle-mcp"]を使用します。コンテナ内でChronicleが認識できるのは、マウントしたフォルダーだけです。そのため、エディターのトランスクリプトをインポートするには、それらのフォルダーもマウントし、TRANSCRIPTS_DIRをそのフォルダーに設定する必要があります。

MCP Bundle（Claude Desktop、Smithery）

mcpb/には、.mcpbファイルに対応したクライアントでのワンクリックインストールと、Smitheryレジストリー向けのMCP Bundleマニフェストが含まれています。このバンドルは薄いラッパーです。固定されたPyPIリリースをuvxで実行するため、uvをインストールする必要があります。次のコマンドでビルドします。

npx @anthropic-ai/mcpb pack mcpb chronicle-mcp.mcpb

CIではマニフェストを検証し、実行のたびにパッケージ化したバンドルをchronicle-mcp-mcpbアーティファクトとしてアップロードします。

手動インストール

1. リポジトリーをクローンします。

   git clone https://github.com/Leviathan0x0/Chronicle-MCP.git
   cd Chronicle-MCP
   

2. Python仮想環境をセットアップします。

   python3 -m venv venv
   source venv/bin/activate
   

3. 依存関係とパッケージを編集可能モードでインストールします。

   pip install -e .
   

CursorとVS Codeでのセッションの自動保存

CursorやVS Codeなどのエディターは、チャットウィンドウやタブが閉じられたときにMCPサーバーへ通知しません。そのためChronicleは、会話履歴が自動的に保存されるよう、複数の手順からなる仕組みを実装しています。

1. プロセス終了ハンドラー（自動フラッシュ）

Chronicleサーバーには、Pythonのatexitモジュールで登録された終了ハンドラーが含まれています。チャットタブを閉じるかエディターを終了すると、エディターがstdio接続を終了し、Chronicleプロセスも終了します。この終了トリガーを受け取ると、サーバーは登録済みの保留中セッションをローカルのチャットフォルダーに自動的にフラッシュします。

2. ワークスペースルールの生成（オプトイン）

このフラッシュを正常に行うには、会話中にアクティブなチャットセッションを登録する必要があります。エージェントに登録を指示する方法は2つあります。

• start_sessionプロンプトを使うか、MCPクライアントがモデルに渡すサーバー指示を利用します。
• サーバー環境でCHRONICLE_AUTO_CONFIGURE_RULES=1を設定して、ルールファイルの使用をオプトインします。すると起動時にChronicleが、アクティブなワークスペースのルールファイル（.cursorrules、.clinerules、.windsurfrules、.clauderulesなど）にルールを作成または追記します。これはデフォルトでは無効なため、明示的に指定しない限り、サーバーがプロジェクト内に書き込むことはありません。

ルールの内容は次のとおりです。

At the beginning of the chat session, you must call the "manage_session_state" tool with action="register_auto_save" to register this conversation. Provide a descriptive title based on the user's initial prompt. As the conversation progresses, periodically update the registration payload to keep it current.

これにより、チャット履歴が動的に登録され、エディターが接続を終了するとすぐに、Chronicleが履歴全体を保存フォルダーに書き込みます。

検証とテストの実行

Chronicleには、プラットフォームのパス解決、解析ロジック、ツールの互換性を検証するユニットテストと統合テストが含まれています。

1. ユニットテストの実行

コアビジネスロジックを検証するユニットテスト一式を実行します。

python3 -m unittest discover -p "test_*.py"

2. 統合テストの実行

8つのツールすべてをエンドツーエンドで実行します（実際のアーカイブに影響しないよう、CHRONICLE_BASE_DIRを一時フォルダーに設定してください）。

CHRONICLE_BASE_DIR="$(mktemp -d)" python3 test_all_tools.py

3. MCPのイントロスペクションとライブスモークテスト

test_mcp_introspection.pyはユニットテストの一部として実行されます。stdio経由でサーバーを起動し、ツール、パラメーター、プロンプト、リソースの説明、タイトル、注釈のいずれかが失われた場合、エラー時にisErrorの設定が停止した場合、またはバージョン番号に不一致が生じた場合に失敗します。smoke_test_live.pyは、実際のアーカイブ、または任意のサーバーコマンドに対して読み取り専用のチェックを実行します。

python3 smoke_test_live.py
python3 smoke_test_live.py --command docker run -i --rm -v "$HOME/.chronicle:/data" chronicle-mcp

これらはすべて、Python 3.10～3.13でCIにより実行されます。また、サポート対象の最小バージョンのmcp（1.22）での実行、python -m buildとtwine checkによるパッケージングジョブ、Dockerジョブも実行されます。Dockerジョブではイメージをビルドし、stdio経由でinitializeとtools/listを確認します。

市場比較マトリクス

コントリビューション

コミュニティからのコントリビューションを歓迎します。始めるには、以下を行ってください。

1. リポジトリをフォークし、新しいブランチを作成します。
2. 新しい動作に対するユニットテストをtest_chat_connector.py内に記述します。
3. テストスイートをローカルで実行し、すべてのコード変更を検証します。

   python3 -m unittest discover -p "test_*.py"
   CHRONICLE_BASE_DIR="$(mktemp -d)" python3 test_all_tools.py
   

4. コードが適切にフォーマットされ、すべてのインポートが正しく並べ替えられていることを確認します。
5. 変更内容とテストカバレッジを詳しく説明したプルリクエストを送信します。

リリース

pyproject.toml、server.json、mcpb/manifest.json（versionと固定されたmcp_config.args）、およびmcpb/server/main.pyのバージョンを更新し、CHANGELOG.mdに項目を追加してから、v<version>というタグを付けてGitHubリリースを公開します。公開ワークフローではパッケージをビルドし、信頼された公開を通じてPyPIにアップロードします。

公開ロードマップ

Chronicleで今後予定されている機能と拡張：

• ローカル埋め込み：軽量なONNXモデルを使用した、オプションのローカルベクトル検索を追加します。
• データベース監査：過去のログに対するキャッシュの自動クリーンアップとデータ整合性監査を追加します。
• 動的な調整：さまざまなLLMホストアーキテクチャ（Claude、GPT、Gemini）に最適化した、専用のプロンプト形式を提供します。
• IDEサポートの拡張：新たに登場する開発環境向けの設定注入スクリプトを、すぐに使える形で提供します。

よくある質問（FAQ）

一般的な質問とセットアップに関する質問

Q：新しいインタラクティブセットアップウィザードを使うメリットは何ですか？

A： 設定プロセスを完全に自動化できます。10秒もかからずに、ストレージディレクトリの設定、モノリシックな会話ログの分割、システム環境の確認、カスタムパスの検証、すべての対象アプリケーションへの設定の注入を行います。

Q：セットアップウィザードで紫色のテーマが使われているのはなぜですか？

A： Chronicleは、高級感があり最先端だと感じられるように設計されています。セットアップウィザードでは、視認性の高い鮮やかな紫／マゼンタのテーマ（\033[1;35m）に、カスタムカーソルポインター（❯）とステータスチェック（[✓]）を組み合わせ、ターミナルでの操作性を最適化しています。

Q：カスタムアプリディレクトリがシステム上に見つからない場合、どうなりますか？

A： インタラクティブセレクターによって、無効な設定を防止できます。「Other」に入力したカスタム名の設定ディレクトリを特定できない場合、画面下部に次の警告がインラインで表示されます：⚠ App/IDE "<name>" was not found on your system.。ほかの選択項目を失わずに、バックスペースで入力を簡単に修正できます。

Q：セッションの自動保存はどのように機能しますか？

A： Chronicleはワークスペースルールファイル（例：.cursorrules、.clinerules）を生成し、起動時にセッションを登録するようAI エージェントに指示します。タブまたはエディターを閉じると、サーバープロセスの終了フックが自動フラッシュを実行し、トランスクリプトをストレージフォルダーに書き込みます。

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。