Chronicle

chronicle demo 加载的合成示例工作日全历史知识图谱。未显示任何真实屏幕数据。

Chronicle

Chronicle 会记录你的屏幕和系统事件，将它们转换为知识图谱，并通过 MCP 向大模型 Agent 提供该图谱。

Agent 通常在开始每项任务时，对你的电脑一无所知。它们不知道你正在处理哪个工单、打开了哪个文件，也不知道你十分钟前查找过什么。因此，你最终只能手动粘贴上下文。Chronicle 会在本地保存这些记忆，让 Agent 可以查询：

• 从上次停下的地方继续。 “完成 Acme 导出”之所以可行，是因为 Agent 能看到你正在编辑 export.ts、PR 882 正等待审核，以及 Notion 中的导出规范内容。
• 通过演示来教会它。 录下你做某项任务的过程，Agent 就能按顺序获取所用的应用、页面和步骤，从而重复执行。
• 将上下文交给不支持 MCP 的工具。 将录制内容导出为 Markdown 上下文文件、JSON、GraphML 或 Cypher，供 ChatGPT 或 Claude Projects、NotebookLM、Neo4j 或 RAG 工作流使用。

所有内容都存储在一个本地文件夹（~/.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 使用界面。

权限和平台工具

• 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 和卡号会在写入任何内容之前被脱敏。

构建图谱。 每个会话都有自己的图谱分片。记录期间会持续扩展该分片，并在会话结束时重建一次；会话之外捕获的帧则写入每小时一个的分片。全历史图谱是对这些分片进行的 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。

每个节点和边都会记录其对应的耗时及来源帧，因此 Agent 可以引用证据。如果有可用的 OpenAI 密钥，模型还会在每次记录结束时对内容进行优化（参见 LLM 优化）。

提供服务。 get_context(task) 会返回一个包含以下部分的上下文包：

• 当前屏幕；
• 最近的活动区块和系统事件；
• 常见的应用切换；
• 与任务相关的子图；
• 引用的帧。

然后，Agent 会通过 query_graph、get_entity、search_history 和 get_frame 进一步查询；这些工具可以返回屏幕截图本身。

连接 Agent

打包安装

这些安装方式需要将 uv 添加到 PATH。每种方式都会运行 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 Agent 模式）	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 进程进行捕获：持有 ~/.chronicle/capture.lock 的进程会负责捕获。因此，Agent 无需运行 chronicle serve，即可调用 start_recording。传入 --no-record 可关闭此功能。

托管 Agent 和模型 API（Streamable HTTP）

chronicle serve 会在 POST /mcp 上提供 MCP，并支持协议版本 2025-06-18、2025-03-26 和 2024-11-05。托管 Agent 需要公共 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（Settings › Connectors › Developer mode › Create）：粘贴 /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	让 Agent 在指定时长内录制演示
rebuild_graph / activity_summary / list_meetings	维护和摘要
tune_graph	对某个范围运行大模型优化步骤
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)，后者会将录制的演示转换为 Agent 可以重复执行的步骤：

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

然后向 Agent 提问：“对 session 1 使用 learn_from_recording 提示词，并为这张收据再做一次。”

Web UI 和 REST API

chronicle serve 会在 http://127.0.0.1:3030 启动 UI：

• **主页：**最近的录制内容及其主要应用、任务和主题，以及过去一周各应用的使用时长。
• **录制：**开始定时录制，并查看这台机器可以捕获哪些内容。
• **上下文：**每段录制、全部历史记录，或根据任务、时间范围或录制内容生成的新上下文。上下文会显示八类工作的上下文文件（通用、数据分析、求职申请、编码、研究、写作、会议跟进、客户工作）、会议、知识图谱、帧和事件时间线，以及搜索。
• **工作流：**在多段录制中发现的重复循环，以及计划任务管道。
• **集成：**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 音频处理管道

命令行

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 编辑。两个设置项与环境变量对应：graph_half_life_hours 会覆盖 CHRONICLE_HALF_LIFE_HOURS，而 CHRONICLE_LLM 的优先级高于 llm_provider。

大模型优化

启发式图知道应用、页面、工单、文件和标识符，但无法判断“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 设置中的 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 进行验证。遭拒的操作会在下一轮返回给模型。一次运行最多执行 --rounds 轮（默认值为 2），若没有提出新内容则提前停止。
• 接受的操作会存储在 kg_llm_patches 中，并在每次重建后重放，因此运行 graph build 后优化结果仍会保留。--reset 会移除这些操作。
• 模型创建的节点和边带有 source: "llm"，关系则带有 confidence 和一条证据引文。get_context 会先列出活动，再列出诸如 Crusoe —is_a→ company 这样的关系。

上下文文件。 对于八种预设中的每一种，模型都会编写一份文档，包含该类工作所需的章节和“待跟进事项”列表，并引用帧。提供给模型的证据会附加在“录制证据”下方。

缓存和故障。

• 响应按提示词和模型的哈希值缓存。如果某个范围内的图未发生变化，则会跳过处理，除非你传入 --force。
• 遇到速率限制、超时和 API 错误时，最多会重试三次。账户没有额度时，首次调用就会失败。
• 错误会记录在 last_llm_error 中，且不会中断录制。上下文文件生成失败时，会回退到离线版本。

可以通过 chronicle.llm.register(name, factory) 添加其他提供方。提供方需实现 call_tools(system, user, tools) -> [{"name", "arguments"}] 和 complete(system, user) -> str。

隐私

录制内容、屏幕截图和图数据都保存在 CHRONICLE_HOME 中。以下三种情况下，数据会离开本机：

• MCP 客户端： 你连接的 Agent 会接收它所请求的工具结果。
• 大模型优化： 启用后，窗口标题、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	大模型补丁处理流程和提供方
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