Chronicle

chronicle demo が読み込む、合成サンプル勤務日の全履歴ナレッジグラフです。実際の画面データは表示されません。

Chronicle

Chronicle は画面とシステムのイベントを記録し、ナレッジグラフに変換して、そのグラフを MCP 経由で LLM エージェントに提供します。

エージェントは通常、コンピューターについて何も知らない状態で各タスクを開始します。どのチケットに取り組んでいたか、どのファイルを開いていたか、10 分前に何を調べたかはわかりません。そのため、手作業でコンテキストを貼り付けることになります。Chronicle はその記憶をローカルに保持し、エージェントが取得できるようにします。

• 中断したところから再開できます。 エージェントは、export.ts を編集していたこと、PR 882 がレビュー待ちであること、Notion に記載されていたエクスポート仕様を確認できるため、「Acme のエクスポートを完了して」という指示に対応できます。
• 実演して教えられます。 タスクを一度自分で行う様子を記録すれば、エージェントはアプリ、ページ、手順を順番に把握し、同じ作業を繰り返せるようになります。
• MCP に対応していないツールにもコンテキストを渡せます。 記録を Markdown コンテキストファイル、JSON、GraphML、または Cypher としてエクスポートし、ChatGPT や Claude Projects、NotebookLM、Neo4j、RAG パイプラインで利用できます。

すべてのデータはアカウントやテレメトリなしで、1 つのローカルフォルダー（~/.chronicle）に保存されます。マシンの外に送信されるデータは、キーを指定したモデルプロバイダーに送られるものだけです（プライバシーを参照）。

クイックスタート

Python 3.10 以降が必要です。主な対応プラットフォームは macOS です。Linux（X11）と Windows はベストエフォートでサポートしています。

uv tool install "chronicle-context[graph]"   # or: pipx install "chronicle-context[graph]"
chronicle demo                               # load a synthetic workday, so you can try it without recording
chronicle context "finish the Acme export"   # print what an agent would receive
chronicle mcp install cursor                 # or claude-desktop, claude-code, codex, vscode, gemini-cli, ...

chronicle context は、get_context MCP ツールが返すものと同じ Markdown を出力します。サンプルの勤務日では、次のように始まります（抜粋）。

# Computer context (Chronicle)
Task: finish the Acme export

## What you were doing
- 15:34-15:56 writing Acme Export spec · amount_usd (22m) [topic 1]
- 16:28-16:48 coding export.ts · amount_usd (20m) [topic 2]
- 16:50-17:02 coding Checks passed · Merge (12m) [topic 3]

## On screen now
- Chrome · Checks · PR 882 at Sun 16:50 (frame 18)
- URL: https://github.com/northwind/billing/actions
- Visible text: ... Merge is waiting on Priya's second review. Acme export is still due Friday.

## Knowledge graph (all)
- [topic] Acme export (`topic:acme-export`, 1h58m, frames 18, 16, 13)
- [pr] PR 882 (`pr:882`, 2h42m, frames 18, 17, 16)
- [file] export.ts (`file:export.ts`, 1h48m, frames 17, 11, 6)
- [person] Maya Chen (`person:maya-chen`, 2h28m, frames 16, 14, 12)

自分の作業を記録するには、chronicle doctor を実行して権限を確認してから、chronicle record 30m または chronicle serve を実行し、http://127.0.0.1:3030 の UI を使用してください。

権限とプラットフォームツール

• macOS：「システム設定」›「プライバシーとセキュリティ」で、Chronicle を実行するもの（ターミナル、または Claude Desktop や Cursor などの MCP ホストアプリ）に「画面収録」と「アクセシビリティ」を許可してください。ブラウザーの URL には、ブラウザーごとに初回のみ「オートメーション」の確認が必要です。対応ブラウザーは Safari、Chrome、Arc、Brave、Edge、Vivaldi、Opera です。
• Linux： xdotool と xprop が必要です。スクリーンショットを撮るには、grim、gnome-screenshot、scrot、ImageMagick の import のいずれかをインストールしてください。クリップボードには xclip または wl-paste、アイドル時間には xprintidle を追加してください。
• Windows： user32 と PowerShell を通じて、ウィンドウ、アイドル時間、スクリーンショット、クリップボードを読み取ります。
• OCR（任意）： brew install tesseract または apt install tesseract-ocr を実行してください。

必須の依存関係は FastAPI と uvicorn のみです。graph エクストラは重複のマージを改善する scikit-learn と scipy を追加し、llm は OpenAI SDK と python-dotenv を追加します。

動作の仕組み

記録。 セッションは、設定した時間（90s、30m、2h）が経過するか、停止されるまで実行されます。デフォルトでは5秒ごとに、レコーダーが前面のアプリとウィンドウ、ブラウザーのURLとタブタイトル、スクリーンショットを取得します。また、システムイベント app_switch、window_focus、url_change、clipboard、idle_start／idle_end、session_start／session_stop も記録します。画面上のテキストはmacOSのアクセシビリティツリーから取得し、アプリがテキストを公開していない場合は、スクリーンショットに対して tesseract のOCRを実行します。キー入力が記録されることはありません。パスワードマネージャー、「システム設定」、プライベートブラウジングのウィンドウは対象外となり、メールアドレス、APIキー、JWT、カード番号は書き込まれる前に秘匿化されます。

グラフを構築する。 各セッションには専用のグラフシャードが割り当てられます。シャードは記録中に拡張され、セッション終了時に一度再構築されます。セッション外で取得されたフレームは、1時間ごとのシャードに保存されます。全履歴グラフはシャードをSQLで集計したもので、古いシャードほど重みが小さくなります（デフォルトの半減期は72時間です）。これにより現在の作業に焦点を当てられ、セッションを削除すると、そのシャードだけが削除されます。

• ノード： アプリ、ウィンドウ、サイト、ページ、検索クエリ、トピック、ファイル、チケット（BILL-142）、PR、コード識別子、人、プロジェクト、顧客、会議、セッション、タスク。トピックは「Acme export」のようなキーフレーズで、頻度、分散、大文字・小文字、位置、滞在時間に基づいてスコア付けされます。タスクはトピックごとに区分されたアクティビティです。
• エッジ： has_window、visited、on_site、shows、searched、about、co_occurs、switched_to、then（ワークフローの遷移）、spoke_in、discussed、copied、typed（POST /add 経由で送信されたテキスト）、captured。

各ノードとエッジには、そこに費やした時間と、その元となったフレームが記録されるため、エージェントは根拠を引用できます。OpenAIキーが利用可能な場合は、セッション終了時にモデルが各記録をさらに精緻化します（LLMによる精緻化を参照）。

提供。 get_context(task) は、次の要素を含むコンテキストパックを返します。

• 現在の画面；
• 最近のアクティビティブロックとシステムイベント；
• よくあるアプリ間の遷移；
• タスクに関連するサブグラフ；
• 引用されたフレーム。

エージェントはその後、query_graph、get_entity、search_history、get_frame を使って詳細を調べます。get_frame はスクリーンショットそのものを返すこともできます。

エージェントを接続する

パッケージ済みのインストール

これらを使用するには、PATH 上に uv が必要です。いずれも uvx chronicle-context mcp を実行し、操作の前に get_context を呼び出すようモデルに指示します。

• Claude Code、Claude Desktop、Cowork： claude plugin marketplace add aniketxdey/chronicle を実行し、続けて claude plugin install chronicle@chronicle を実行します。
• Gemini CLI： gemini extensions install https://github.com/aniketxdey/chronicle を実行します。
• MCP Registryクライアント： io.github.aniketxdey/chronicle を検索します。

ローカルクライアント（stdio）

chronicle mcp install <client> はサーバー設定をクライアントの設定に統合し、古いファイルのコピーを .chronicle-backup として保持します。代わりに chronicle mcp config <client> を実行すると設定スニペットを出力し、chronicle mcp clients を実行するとすべてのクライアントを一覧表示します。

クライアント	コマンド	書き込まれる設定
Claude Desktop	chronicle mcp install claude-desktop	claude_desktop_config.json → mcpServers
Claude Code	chronicle mcp install claude-code	claude mcp add --scope user chronicle -- … を実行
Cursor	chronicle mcp install cursor	~/.cursor/mcp.json
VS Code（Copilot エージェントモード）	chronicle mcp install vscode	ユーザーの mcp.json → servers
Windsurf	chronicle mcp install windsurf	~/.codeium/windsurf/mcp_config.json
OpenAI Codex CLI	chronicle mcp install codex	~/.codex/config.toml → [mcp_servers.chronicle]
Gemini CLI	chronicle mcp install gemini-cli	~/.gemini/settings.json
Cline、LM Studio	chronicle mcp install cline / lm-studio	各クライアントの mcpServers JSON
Zed、Continue、Goose	chronicle mcp config zed / continue / goose	スニペットを貼り付け

その他のクライアントの場合：

{ "mcpServers": { "chronicle": { "command": "chronicle", "args": ["mcp"] } } }

stdio サーバーは単独で記録できます。一度にキャプチャできる Chronicle プロセスは 1 つだけです。~/.chronicle/capture.lock を保持しているプロセスがキャプチャします。そのため、chronicle serve を実行していなくても、エージェントは start_recording を呼び出せます。記録を無効にするには --no-record を渡します。

ホステッドエージェントとモデル API（Streamable HTTP）

chronicle serve は POST /mcp で MCP を公開し、プロトコルバージョン 2025-06-18、2025-03-26、2024-11-05 をサポートします。ホステッドエージェントにはパブリック HTTPS URL が必要なため、トンネルの背後に配置してトークンを設定します。

export CHRONICLE_TOKEN=$(openssl rand -hex 16)
export CHRONICLE_PUBLIC_URL=https://<your-tunnel-host>
chronicle serve &
cloudflared tunnel --url http://127.0.0.1:3030    # or ngrok, tailscale funnel
# MCP URL: $CHRONICLE_PUBLIC_URL/mcp/$CHRONICLE_TOKEN, or /mcp with "Authorization: Bearer $CHRONICLE_TOKEN"

トークンを設定すると、UI シェルと /health を除くすべてのルートでトークンが必要になります。?token=… を付けて UI を一度開くと、トークンが記憶されます。Origin ヘッダーがローカル以外のリクエストは拒否されます。

• ChatGPT（設定 › コネクター › 開発者モード › 作成）：認証なしで /mcp/<token> URL を貼り付けます。search ツールと fetch ツールは、コネクターとディープリサーチが期待する形式のデータを返します。
• OpenAI Responses API： tools=[{"type": "mcp", "server_label": "chronicle", "server_url": URL, "require_approval": "never"}]。詳細は examples/openai_responses.py を参照してください。
• Anthropic Messages API（MCP コネクターのベータ版 mcp-client-2025-04-04）：コンピューター操作ツールと併せて、mcp_servers=[{"type": "url", "url": URL, "name": "chronicle"}] を指定します。詳細は examples/anthropic_computer_use.py を参照してください。
• Gemini API（google-genai）：chronicle mcp に接続した MCP ClientSession をツールとして渡します。chronicle mcp config gemini-api を実行すると設定スニペットが出力されます。
• その他： chronicle mcp config http を実行すると curl 呼び出しが出力されます。

プロバイダーのモデル名やベータ版のフラグは頻繁に変更されるため、これらのスニペットは出発点として扱い、プロバイダーの MCP ドキュメントを確認してください。

MCP ツール

ツール	機能
get_context	タスク用のコンテキストパック：現在の画面、最近のアクティビティとイベント、遷移、関連するサブグラフ、引用されたフレーム
search_history	画面上のテキスト、イベント、文字起こし、記憶を全文検索します
query_graph / get_entity / graph_summary	エンティティを検索し、根拠となるフレームを使って隣接ノードをたどり、件数と主な遷移を取得します
list_tasks	アクティビティから区分し、トピックごとにグループ化したタスクのタイムライン
get_frame	周辺のイベントと音声を含む単一フレーム。include_image=true を指定するとスクリーンショットを添付します
start_recording / stop_recording / list_sessions	エージェントが指定した時間のデモを記録できるようにします
rebuild_graph / activity_summary / list_meetings	メンテナンスと要約
tune_graph	指定範囲で LLM による調整処理を実行します
search / fetch	ChatGPT コネクターとディープリサーチインターフェース

リソース：chronicle://context/current、chronicle://graph/summary、chronicle://sessions、およびテンプレート chronicle://context/session/{id} と chronicle://frame/{id}。

プロンプト：use_my_computer_context(task) と learn_from_recording(session_id)。後者は、記録したデモをエージェントが繰り返し実行できる手順に変換します：

chronicle record 5m --label "file an expense report"   # do the task once
chronicle context --session 1                          # check what the agent will see

次に、エージェントにこう尋ねます："learn_from_recording プロンプトを使ってセッション 1 を実行し、この領収書についてもう一度行ってください。"

Web UI と REST API

chronicle serve を実行すると、http://127.0.0.1:3030 で UI が起動します：

• ホーム： 最近の記録と、記録で使われた主なアプリ、タスク、トピック、および過去 1 週間のアプリごとの使用時間を表示します。
• 記録： 時間を指定して記録を開始し、このマシンで何をキャプチャできるかを確認します。
• コンテキスト： 各記録、すべての履歴、またはタスク、時間範囲、記録から生成した新しいコンテキストを表示します。コンテキストには、8 種類の作業（一般、データ分析、求人応募、コーディング、調査、執筆、会議後のフォローアップ、顧客対応）向けのコンテキストファイル、会議、ナレッジグラフ、フレームとイベントのタイムライン、検索が含まれます。
• ワークフロー： 記録から見つかった反復的なループと、スケジュールされたパイプを表示します。
• インテグレーション： MCP クライアントのセットアップとファイルのエクスポートを行います。

REST API のドキュメントは http://127.0.0.1:3030/docs にあります。特に便利なルート：

ルート	用途
POST /sessions {duration, label}	記録を開始します
GET /context?task=&format=markdown	get_context パック
GET /graph、GET /graph/node?id=	グラフと単一ノードの検索
GET /contexts/file?preset=…	コンテキストファイルと、それを書き込んだモデル
GET /contexts/export?format=md|json|graphml|cypher	エクスポート
POST /add	Whisper 音声パイプラインなど、独自のキャプチャからフレーム、イベント、文字起こしを送信します

CLI

chronicle serve [--host --port]                       web UI, REST API, and HTTP MCP
chronicle record <duration> [--label --interval --detach]
chronicle stop [id] · chronicle sessions
chronicle graph build|show|find|node|export [--session N]   (build --full re-extracts every shard)
chronicle graph tasks [--session N --since "2h ago" --json]
chronicle graph merges [--session N --threshold --json]     (near-duplicate nodes the build merges)
chronicle graph tune [--session N --rounds 2 --force --reset]
chronicle context [task] [--minutes N --session N --json]
chronicle mcp [stdio|clients|config <client>|install <client> [--path --dry-run]]
chronicle search <q> · chronicle ask <question> · chronicle status · chronicle doctor · chronicle demo

設定

変数	デフォルト	意味
CHRONICLE_HOME	~/.chronicle	データベース、スクリーンショット、パイプ、ロックファイル
CHRONICLE_TOKEN	未設定	HTTP API と MCP でこのトークンを必須にします
CHRONICLE_PUBLIC_URL	http://127.0.0.1:3030	リンクとリモートクライアントのスニペットのベース URL
CHRONICLE_DEMO=1	オフ	起動時に空のデータベースへサンプルの勤務日データを読み込みます
CHRONICLE_DISABLE_CAPTURE=1	オフ	このプロセスからは記録しません
CHRONICLE_HALF_LIFE_HOURS	72	全履歴グラフの減衰半減期。0 または off で無効になります
CHRONICLE_LLM	未設定（自動）	openai または off。未設定の場合、OpenAI キーが利用可能であれば有効になります
CHRONICLE_LLM_MODEL	gpt-4.1-mini	グラフの調整とコンテキストファイルに使用するモデル
OPENAI_API_KEY / OPENAI_BASE_URL	未設定 / OpenAI	openai プロバイダーの認証情報とエンドポイント

キャプチャ間隔、アイドル状態のしきい値、スクリーンショット、OCR、クリップボード、編集、保持期間は設定項目で、UI または POST /settings から編集できます。2 つの設定は環境変数に対応しています。graph_half_life_hours は CHRONICLE_HALF_LIFE_HOURS を上書きし、CHRONICLE_LLM は llm_provider より優先されます。

LLM による精緻化

ヒューリスティックなグラフは、アプリ、ページ、チケット、ファイル、識別子を把握できますが、「Crusoe」が企業であることや、あるページが求人情報であることまでは判断できません。OpenAI キーが利用可能な場合、モデルがグラフを精緻化し、コンテキストファイルを書き込みます。キーがない場合、Chronicle は完全にオフラインで動作します。グラフはヒューリスティックなままで、コンテキストファイルは録画から直接作成されます。

uv tool install "chronicle-context[graph,llm]"
echo "OPENAI_API_KEY=sk-..." >> ~/.chronicle/.env
chronicle graph tune --session 1    # runs automatically when a recording ends
chronicle graph show --session 1    # activities and typed relations are listed first

キーは環境変数、現在のディレクトリにある .env、または Ask 用に Settings に保存した OpenAI キーからも取得できます。.env が、すでに設定されている変数を上書きすることはありません。Settings › LLM refinement または CHRONICLE_LLM=off で、精緻化を無効にできます。GET /llm/status は、使用中のプロバイダーとモデル、および最後に発生したエラーを報告します。

グラフのパッチ。 モデルは、最も重要なノードとその証拠（ウィンドウタイトル、URL と検索クエリ、墨消し済みの画面テキスト、滞在時間）を読み取ります。モデルは厳密な関数呼び出しを通じて応答します。関数は add_entity、retype_node、rename_node、merge_nodes、add_relation、add_trait、set_activity、drop_node です。add_relation は is_a、part_of、works_on、competes_with、located_in、researching、mentions、listed_in、uses、related_to をサポートします。

• 各操作は、スキーマと、その時点で存在するノード ID に照らして検証されます。却下された操作は、次のラウンドでモデルに返されます。1 回の実行では --rounds の回数（デフォルトは 2）まで処理を行い、新しい提案がなくなると早期に終了します。
• 受理された操作は kg_llm_patches に保存され、再構築のたびに再適用されるため、graph build の後も精緻化内容が保持されます。--reset を指定すると削除されます。
• モデルが作成したノードとエッジには source: "llm" が付与され、関係には confidence と証拠の引用が付与されます。get_context はアクティビティを最初に、その後に Crusoe —is_a→ company のような関係を一覧表示します。

コンテキストファイル。 8 つのプリセットそれぞれについて、モデルはその作業に必要なセクションと「未解決の事項」リストを含むドキュメントを作成し、フレームを引用します。モデルに提供された証拠は、「記録された証拠」の下に追加されます。

キャッシュとエラー。

• 応答はプロンプトとモデルのハッシュをキーにキャッシュされ、グラフに変更がないスコープは --force を指定しない限りスキップされます。
• レート制限、タイムアウト、API エラーが発生した場合、最大 3 回まで再試行されます。クレジットがないアカウントでは、最初の呼び出しで失敗します。
• エラーは last_llm_error に記録され、録画が停止することはありません。コンテキストファイルの作成に失敗した場合は、オフライン版にフォールバックします。

他のプロバイダーは chronicle.llm.register(name, factory) で追加できます。プロバイダーは call_tools(system, user, tools) -> [{"name", "arguments"}] と complete(system, user) -> str を実装します。

プライバシー

録画、スクリーンショット、グラフは CHRONICLE_HOME に保持されます。データがマシンの外部に送信されるのは、次の 3 つの場合です。

• MCP クライアント： 接続先のエージェントは、要求したツールの結果を受け取ります。
• LLM による精緻化： 有効にすると、ウィンドウタイトル、URL、墨消し済みの画面テキストが OpenAI に送信されます。
• Ask： chronicle ask と Ask ボックスは、一致した履歴を Settings で設定したプロバイダーに送信します。

詳細は PRIVACY.md をご覧ください。

開発

git clone https://github.com/aniketxdey/chronicle && cd chronicle
uv pip install -e ".[dev,graph,llm]"
pytest
python examples/stdio_client.py "finish the Acme export"
npx @modelcontextprotocol/inspector --cli chronicle mcp --method tools/list

モジュール	役割
chronicle/probe.py	マシンからウィンドウ、URL、スクリーンショット、アクセシビリティテキスト、OCR を読み取ります
capture.py、sessions.py	レコーダーと時間指定セッション
graph.py	シャードの構築、集約、減衰
tuner.py、llm.py	LLM によるパッチ処理とプロバイダー
context.py、contexts.py	コンテキストパックとコンテキストファイル
mcp_server.py、clients.py	JSON-RPC コア、stdio トランスポート、クライアントごとの設定
main.py、web/	HTTP サーバーと UI

リリースについては docs/PUBLISHING.md に記載されています。OSWorld ベンチマークのハーネスは bench/ にあり、評価については bench/PROTOCOL.md に記載されています。まだ実行されていないため、結果はありません。

License

MIT