inkvault

InkVault

以本地为先、由用户掌控的持久记忆，适用于 AI 对话、浏览和工作。

留住工作背后的上下文：你问了什么、学到了什么，以及打开过哪些页面。 InkVault 会将受支持的 AI 会话和你选择的浏览器历史记录保存在本地 SQLite 保险库中， 这样即使原有工具清除了历史记录，你也能再次找到它们。

你可以在 Memory Atlas 中自行搜索保险库，也可以通过 MCP 连接 AI 工具，让它在你提出请求时检索 过往上下文。可选的 Windows 屏幕捕获功能还能记录你使用过的应用时间线，以及你选择的应用中的文本。 来源、保险库文件夹和备份都由你掌控。

InkVault 免费且采用 MIT 许可证。无需账户，也不收集遥测数据。InkVault 本身不会上传你的档案。 如果你连接了 AI 客户端，返回给该客户端的记忆可能会根据该客户端的设置发送给其模型提供商。

开始使用保险库

你需要 uv 和一个终端。 将受支持的本地会话和选定的浏览器历史记录复制到保险库中：

uvx --from git+https://github.com/sandoreclegane/inkvault inkvault sync

在终端中，InkVault 会向你问好，先询问哪些浏览器配置文件属于你，再读取其历史记录；构建搜索索引时会显示进度，最后提供简短摘要。首次使用时，它会下载搜索模型（约 130 MB）。保存完成后，Memory Atlas 会自动打开。添加 --no-open 可跳过此步骤。以后访问时，运行 inkvault dashboard 即可再次打开 Atlas：

uvx --from git+https://github.com/sandoreclegane/inkvault inkvault dashboard

搜索你记得的内容，选择一个结果，并结合上下文阅读。添加 inkvault schedule，即可每晚刷新并备份保险库；也可以 连接你的 AI 工具，在对话中搜索保险库。

要保存 Pieces 档案？ 请参阅从 Pieces 恢复。

InkVault 保存的内容

设置每晚计划任务后，InkVault 会读取 Claude Code 和 Codex 已保存在磁盘上的会话文件，以及 你所选浏览器配置文件的历史记录，并复制新增内容：你问了什么、助手回答了什么、每个会话的名称，以及你打开过哪些页面。这样，你的 AI 工具就能搜索上个月或去年它们帮你处理过的内容，以及你当时阅读的内容，即使原始文件早已不存在。

• Claude Code：来自 ~/.claude/projects 的所有项目。即使源文件被清理，同步过的消息仍会保留在保险库中。
• Codex：来自 ~/.codex/sessions 的所有已保存会话。
• Claude 桌面应用（Agent 模式，Windows）：包括其审计日志中才保留的提示词。
• 你的浏览器：Chrome、Edge、Comet、Brave、Arc、Vivaldi、Opera 和 Firefox，仅限你指定为自己的配置文件 （了解方式）。清理浏览器自身历史记录后，内容仍会保留。

只会添加自上次同步以来的新增内容。不会保存工具输出和附件，并会从网址中清除登录验证码和令牌（参见隐私）。

你将获得什么

• 属于你的 Vault：保留的会话、选定的浏览器历史记录、可选的屏幕活动，以及任何找回的 Pieces 记录，都存储在一个本地 SQLite 文件 vault.db 中。你可以独立保管它，不受生成这些数据的工具影响。
• 为 AI 工具提供搜索：一个 MCP 服务，提供 search_memories（合并关键词与语义搜索）、timeline（“我 3 月在做什么？”）、get_memory 和 memory_stats。
• Memory Atlas：运行 inkvault dashboard 打开它（在 Windows 上，也可通过 inkvault dashboard --shortcut 创建的 InkVault Atlas 图标打开）。它展示你这一年的活动：每天的活跃时段（将鼠标悬停在某一天上，可查看当天内容）、工作时间、项目之间的关联、项目与主题的时间线，以及热门应用和网站。每张图表都有表格视图。Search 视图可跨 Vault 查找内容，并在阅读器中打开原文。它只在这台电脑上运行（127.0.0.1，使用私密链接，空闲时会停止），无需联网。
• Daily Light（v0.3.2）：每天从 32 篇精选公有领域文本中选取一段引文，依据你的本地日期选择，不会使用你的历史记录。你可以在当前 Atlas 会话中将其隐藏。如果往年今天有已编入索引的活动，On this day 会在 Search 中打开这些内容。你也可以设置 From 和 To，不输入关键词即可浏览任意日期范围。这些日期浏览功能仅适用于 Atlas；MCP 工具保持不变。
• 你的 Claude Code、Codex 和 Claude 桌面会话：你的提示词和回复会与其他保留的历史记录并列显示，可作为聊天搜索（名称格式如 Claude Code · project: title），也会纳入时间线、摘要和仪表板。
• 你的浏览器历史记录：来自你指定为自己的浏览器配置文件中，你在 Chrome、Edge、Comet、Brave、Arc、Vivaldi、Opera 或 Firefox 中打开的页面。即使浏览器删除了已访问记录，已复制的访问记录仍会保留在 Vault 中。可通过 web 搜索，也会显示在时间线、摘要和仪表板中。
• 屏幕捕获（可选，仅限 Windows）：显示你使用过的窗口的时间线，以及你选择的应用中窗口的文本。不保存图像。请参阅屏幕捕获。
• 每日摘要（可选）：由 Ollama 通过本地模型为每天撰写 2-3 句摘要。在不向托管模型发送数据的情况下，总结你保留的活动。

连接你的 AI 工具

Claude Code

claude mcp add inkvault --scope user -- uvx --from git+https://github.com/sandoreclegane/inkvault inkvault serve

Codex（~/.codex/config.toml）

[mcp_servers.inkvault]
command = "uvx"
args = ["--from", "git+https://github.com/sandoreclegane/inkvault", "inkvault", "serve"]

Hermes、Claude Desktop 和其他 MCP 客户端：通过 stdio 运行 uvx --from git+https://github.com/sandoreclegane/inkvault inkvault serve。

然后提问：“3 月 10 日那周我在做什么？”、“找到我保存的那个重试助手”、“我上次查看 Stripe 仪表板是什么时候？”

您的浏览历史

浏览器配置文件可能属于其他人，因此除非您选择，否则 InkVault 不会读取任何配置文件：

inkvault browsers

它会列出找到的每个配置文件（浏览器、名称、已登录的邮箱），并询问哪些属于您。sync 和 rescue 发现新的配置文件时也会询问；夜间运行不会询问，并会跳过您尚未选择的配置文件。如果其他人开始在这台电脑上使用浏览器，请再次运行 inkvault browsers：在 Windows 和 macOS 上，InkVault 会注意到被替换的配置文件，以及配置文件的已登录账户发生变化的情况，但它不一定总能识别出来。

• inkvault browsers --no "chrome/Profile 2" --forget 会停止复制某个配置文件，并移除已复制的内容，即使浏览器已卸载也不例外。
• inkvault browsers --skip-site mybank.com 永远不会保留该网站或其子域名，并会移除已有内容。

移除操作会重建搜索索引和控制面板，并删除每条已移除访问记录日期（UTC）当天及前后一天的摘要。如果操作中断，下次运行 inkvault sync、inkvault index 或夜间任务时会完成操作，在此之前搜索功能会保持关闭。它无法撤回您的 AI 工具已经收到的答案，也无法关闭已经打开的控制面板标签页。夜间备份仍会保留已移除的访问记录，直到备份轮换清除它们（7 个夜晚）。

**保留的内容：**每个页面的地址和标题，以及打开时间。存储任何内容前，InkVault 都会移除地址中包含的登录码、令牌、签名链接、密码重置令牌，以及您的邮箱或用户名。搜索内容（?q=…）会保留。这能识别常见形式，但无法涵盖所有可能的机密信息。复制操作会在浏览器运行时进行，因此最新的几条访问记录可能要等到下次同步才会复制。

目前尚不支持 Safari（macOS 会阻止读取，除非授予“完全磁盘访问权限”）。

屏幕采集（Windows）

使用 inkvault watch，你可以添加本地前台窗口时间线，并读取所选应用中的文本。 安装监视器之前，屏幕采集会保持关闭。目前仅支持 Windows；在 macOS 和 Linux 上， inkvault watch 会说明这一点并退出。

记录内容

• 无处不在的时间线。 每个前台窗口都会成为一段时间记录：包括应用、清理后的标题，以及开始和结束时间。只是快速切换浏览的窗口不会被保留；离开期间（5 分钟无输入或屏幕已锁定）也不计时。
• 所选应用中的文本。 在某个窗口停留 30 秒后，InkVault 会读取其中的文本（使用 Windows 自带的 OCR，在你的设备上运行），并在文本发生变化时保存。同一窗口最多每 2 分钟读取一次。
• 绝不保存图像。 窗口图像只会暂存在内存中以便读取，绝不会写入磁盘。
• 保存任何内容之前，标题和文本中的机密信息（API 密钥、令牌、JWT、password: ... 值）都会被遮盖，URL 也会被清理。这能识别常见格式，但无法涵盖所有可能的机密信息。

哪些应用会读取文本。 默认包括：Comet 和 Edge；Claude、ChatGPT、Perplexity 和 Codex；Windows Terminal、VS Code 和 Cursor；Notion、Obsidian 和 Notepad；以及 Microsoft 365 应用（Word、Excel、PowerPoint、Outlook、新版 Outlook、OneNote）。其他所有应用都只记录时间线。有两类应用默认关闭，只有你明确同意后才会启用；运行 --install 时会询问：

• 消息应用（Discord、WhatsApp、Telegram、Teams、LinkedIn）。读取这些应用会保存其他人的消息和姓名，而 Discord 的标题会显示你正在交谈的对象姓名。除非你回答“是”，否则保持关闭。
• Chrome。 其窗口标题只显示页面名称和“Google Chrome”，不包含个人资料名称，因此 InkVault 无法区分你的 Chrome 个人资料和其他人的。除非你回答“是”，否则保持关闭。

如果没有终端（例如通过脚本安装），这两类应用都会保持关闭。你可以自行添加或移除任何应用。

Windows 账户的所有使用者都会被记录。 监视器会在安装它的账户中运行，并从登录时开始工作。如果其他人也使用该账户，他们的操作同样会被记录。对于不应被记录的人，请使用单独的 Windows 账户。

绝不采集的内容。 密码管理器和 Windows 登录及权限提示（1Password、Bitwarden、KeePass、 KeePassXC、锁屏、UAC）会被完全跳过：不记录时间段，也不读取文本。标题包含 InPrivate、Incognito 或 Private Browsing 的窗口，以及通过 --never-app 或 --never-title 添加的任何内容，也会被跳过。

安装

uv tool install "inkvault[screen]"
inkvault watch --apps       # preview: shows the settings, records nothing
inkvault watch --install    # asks about messaging apps and Chrome, then starts at every sign-in

--apps 是预览模式：它会显示哪些应用会读取文本、哪些应用绝不会被采集，但不会启动任何内容。--install 会注册一项任务计划程序任务，在登录时启动监视器、在监视器停止时重新启动，并在确认监视器确实正在运行后才提示“屏幕采集已开启”。它还会添加两个桌面快捷方式：暂停屏幕采集（1 小时） 和 恢复屏幕采集。如果未安装 screen extra（或 Windows 中未安装 OCR 语言），监视器仍会记录时间线，而 inkvault status 会说明为何没有文本。

控制

命令	功能
inkvault watch --apps	显示哪些应用会读取文本，哪些应用永远不会被捕获。不做任何更改
inkvault watch --install	立即开始屏幕捕获，并在每次登录时启动
inkvault watch --stop	停止正在运行的监视器（下次登录时会重新启动）
inkvault watch --pause 30m, 1h 或 until-tomorrow	暂停记录一段时间。即使在夜间运行期间也有效
inkvault watch --resume	结束暂停
inkvault watch --add-app EXE / --remove-app EXE	读取此应用中的文本 / 恢复为仅记录时间线
inkvault watch --never-app EXE	永远不记录此应用
inkvault watch --never-title TEXT	跳过标题包含此文本的所有窗口
inkvault watch --reset-settings	恢复默认设置
inkvault watch --uninstall	停止监视器并移除登录任务

设置保存在 InkVault 文件夹中的 screen.json 里，监视器会在几秒内应用更改。如果文件无法读取或无效，则在修复前不会记录任何内容。可执行文件名不区分大小写。

搜索记录

• timeline 会实时显示屏幕活动：单独的 屏幕 部分会按时间倒序列出时间范围内的窗口，包括当前打开的窗口。
• search_memories 会在夜间索引完成后（或运行 inkvault index 后）搜索屏幕文本和窗口标题；结果会说明索引覆盖到什么时间。使用 source="screen" 可仅搜索屏幕活动。
• 对屏幕搜索结果使用 get_memory，可查看窗口的应用、标题和时间，以及最近的文本。
• inkvault status 会显示监视器状态（运行中、已暂停、前台应用、上次错误）、登录任务，以及已存储的时间段和文本读取次数。
• 信息面板包含 屏幕使用时间 卡片和 按应用划分的屏幕使用时间 图表；每日摘要也会包含按应用划分的屏幕使用时间和最长窗口。摘要永远不会包含屏幕文本。

忘记记录

inkvault forget --screen --app Discord.exe
inkvault forget --screen --since "2026-10-12 09:00" --until "2026-10-12 11:30"

时间均为你的本地时间：--since 日期表示本地午夜；--until 日期包含整天。添加 Z 或时区偏移量可指定精确时刻。--until 只能与 --since 一起使用；--app 会移除某个应用的所有记录。记录会按整个窗口删除：凡是与时间范围重叠的时间段都会被删除，其所有文本也会一并删除；命令会先显示实际删除的时间范围，再要求确认。搜索结果、信息面板和摘要都会重新生成，不再包含这些记录。此前生成的夜间备份仍会保留这些记录，直到轮换删除（7 个夜晚）；AI 工具已经收到的回答则无法撤回。忘记记录只会删除过去的记录；若要停止记录某个应用，请使用 --never-app。

限制

• 银行及其他敏感网站。 浏览器历史记录的 skip_sites 列表保存的是域名，但窗口标题很少包含域名，因此无法在此处应用。请将银行页面标题中的文本添加到 --never-title（例如 --never-title "Example Bank"）。
• 隐私窗口。 标记（InPrivate、Incognito、Private Browsing）都是英文。浏览器本地化后可能使用其他词语，也可能没有标记；请使用 --never-title 添加相应文本。
• 最后一瞬间。 InkVault 会在读取窗口前后各检查一次，如果窗口发生变化，就会丢弃读取到的文本。如果窗口在最后一次检查与屏幕绘制之间的瞬间发生变化，则无法捕获。
• 搜索按夜间索引，timeline 实时更新。 新的屏幕活动会立即显示在 timeline 中，并在下一次索引后出现在搜索结果中。
• Store 应用仅显示在时间线中。 Windows Store（UWP）应用在不包含文本的框架窗口中运行，因此会显示在时间线中，但不会读取其文本。
• 仅支持 Windows。 不支持 macOS 和 Linux。

保持最新

保持受支持的会话和所选浏览器历史记录为最新，重建搜索索引和 Atlas，并每晚备份你的保险库：

uvx --from git+https://github.com/sandoreclegane/inkvault inkvault schedule

这会将 InkVault 安装为永久的 inkvault 命令（使用 uv tool install，或更新较旧的版本），并通过系统自带的调度程序设置每晚 03:00 运行：Windows 上的任务计划程序、macOS 上的 launchd、Linux 上的 systemd 用户计时器（或 cron）。如果 uv 的工具目录不在 PATH 中，它会提示你运行 uv tool update-shell。

每次运行都会导出新的捕获内容（如果 PiecesOS 正在运行），复制新的 Claude Code 和 Codex 会话，以及你选择的配置文件中的新浏览器历史记录，并立即在 backups/ 中保存一份带日期的 vault.db 副本（保留最近 7 份）。然后重建搜索索引，写入新的摘要（如果 Ollama 正在运行），并重建仪表板。某个步骤失败不会阻止其他步骤继续运行。运行期间会保持电脑唤醒（Windows 和 macOS）。导出设有时间上限：如果积压太多，无法在时限内完成，运行会正常停止，备份已有内容，并在下一晚从停止处继续。

夜间运行期间不会启动 rescue；它会提示你重试。如果夜间运行开始时 rescue 正在运行，夜间运行会等待它（最长一小时）；rescue 完成后会自行备份。

inkvault status 会显示计划安排和上次运行情况。它会检查调度程序本身，并提示任务是否已禁用、运行的是其他保险库（每台电脑上的每个用户只能有一个夜间运行计划，因此为另一个保险库安排计划会替换当前计划），或指向已不存在的 InkVault 安装；如果运行已逾期（26 小时内未运行），也会发出提示。每次运行都会记录到 InkVault 文件夹中的 nightly.log（如果无法写入 nightly.log，则记录到同一位置的 nightly-fallback.log）。

计划与保险库文件夹绑定，因此如果你一开始使用了 --home，运行 schedule 时也要使用相同的 --home。

如果运行时电脑处于睡眠或关机状态：

• Windows 和 systemd 会在电脑下次开机时补运行。
• macOS 会在电脑从睡眠中唤醒后补运行，但关机后不会。
• cron 不会补运行。

Windows 任务仅在你登录时运行。你可以让电脑为运行而唤醒：

• Windows：schedule 会询问。你的电源计划必须允许唤醒计时器，某些笔记本电脑（Modern Standby）会忽略它们。
• macOS：schedule 会询问，然后打印一条供你运行的一次性 sudo pmset repeat ... 命令。它会替换你已有的任何 pmset repeat 计划。
• Linux：用户计时器无法唤醒电脑。systemd 会在你登录时运行计时器；loginctl enable-linger $USER 可使其始终运行。

inkvault schedule --at 02:30 可选择其他时间，--wake 或 --no-wake 可跳过询问，--off 可关闭计划，uv tool upgrade inkvault 可更新 InkVault。

命令

命令	作用
inkvault rescue	导出、建立索引、生成摘要（如果 Ollama 正在运行）、构建并打开仪表板
inkvault export	从 PiecesOS 复制所有内容。可以安全停止后重新运行：只会添加新内容
inkvault sync	将新的 Claude Code 和 Codex 会话及浏览器历史记录复制到知识库，然后重建搜索索引
inkvault browsers [--yes|--no KEY] [--forget] [--skip-site HOST]	选择哪些浏览器配置文件属于你，以及永不保留哪些网站的内容
inkvault index	重建搜索索引
inkvault digest [--model M] [--redo]	使用本地模型生成每日摘要（默认为 qwen3.5:4b）
inkvault dashboard	重建并打开 Memory Atlas
inkvault serve	运行 MCP 服务
inkvault status	查看知识库中有什么、存放在哪里，以及计划任务和上次夜间运行的时间
inkvault watch ...	屏幕捕获（Windows）：预览、安装、暂停、停止。参见屏幕捕获
inkvault forget --screen --app EXE / --since T --until T	从知识库中移除屏幕捕获内容
inkvault schedule [--at HH:MM] [--wake|--no-wake] [--off]	每晚刷新并备份知识库
inkvault nightly	立即刷新并备份一次（计划任务运行的内容）

隐私

这是你的屏幕历史记录、聊天记录、浏览记录和代码。InkVault 会在本地存储并搜索你的存档：

• 所有内容都存储在应用数据文件夹（%LOCALAPPDATA%\InkVault、~/Library/Application Support/InkVault， 或 ~/.local/share/inkvault）中，或存储在 INKVAULT_HOME 指向的位置。绝不会存放在代码文件夹内。
• 无遥测、无账户、无云服务。
• InkVault 本身不会上传你的存档。当你通过 MCP 连接 AI 客户端时，返回给该客户端的记忆可能会根据该客户端的设置发送给其模型提供商。请谨慎选择客户端及其设置。
• 只会下载一项内容：搜索模型（从 Hugging Face 下载约 130 MB，仅下载一次）。Atlas 不会发出网络请求； 其图表库（ECharts）已打包，因此可以离线使用。
• 摘要使用你自己机器上的 Ollama。使用 --no-digest 可跳过摘要。
• 对于 Claude Code 和 Codex 会话，InkVault 会保留你输入的内容、助手回复的内容以及会话标题。 Claude Code 的回复包含其工具调用，因此它写入的文件会按原样保留。工具输出（读取的文件、 命令输出）、粘贴的图片和附件不会保留：它们通常占文件的大部分，也是秘密最容易出现的地方。 这能降低风险，但无法完全排除风险，因为你输入或粘贴的任何文本都会保留。
• 浏览器历史记录只会从你选择的配置文件（inkvault browsers）的浏览器文件副本中读取。InkVault 会保留 每个页面的地址、标题和打开时间，并移除地址中包含登录码、令牌、签名链接、重置令牌或你的邮箱地址或用户名的部分。它无法保证捕获所有秘密。使用 inkvault browsers --skip-site 和 --no … --forget 可移除你不想保留的内容。
• 屏幕捕获（Windows，安装前默认关闭）会保留窗口标题，以及你选择的应用中的文本。 不会保存图像。秘密会在存储前从标题和文本中遮蔽。关于其无法捕获的内容，请参见 屏幕捕获。上述连接客户端边界同样适用于屏幕记忆。
• 捕获的文本和页面标题由其他人、应用和网站编写。MCP 服务会指示你的 AI 工具将其视为数据，而非指令。

备份你的知识库。 它只有一个文件：InkVault 文件夹中的 vault.db。其他所有内容都可以通过 inkvault index 从中重建。

从 Pieces 中抢救数据

InkVault 最初是为了保存 Pieces 记忆而创建的。抢救数据仍受支持；你也可以在没有 Pieces 的情况下创建并维护知识库。

请保持 PiecesOS 安装并运行，直到安全完成导出：

uvx --from git+https://github.com/sandoreclegane/inkvault inkvault rescue

导出会保留 PiecesOS 返回的原始记录：捕获内容、摘要及其文本、聊天、代码片段、标签、网站和人员。

这需要一些时间。 PiecesOS 每秒传输约 8 条记录，因此一年的捕获内容（约 100,000 条）需要 3-4 小时。请让它继续运行，或者随时按 Ctrl+C：InkVault 会保留目前已保存的所有内容，并打开一个仪表板，展示你已有的内容。稍后再次运行同一条命令，就会从上次中断的地方继续。

须知

• 仪表板上的项目是根据会话标题中反复出现的短语检测出来的。若要自行选择，请在 InkVault 文件夹中创建 themes.txt，写入类似 Website = website|landing page|stripe 的行，然后运行 inkvault dashboard。
• 主题来自 Pieces 为每个会话摘要添加的主题标签。持续主题会跨月反复出现；集中主题则集中在几周内。下次运行 inkvault index（rescue 和夜间运行都会执行）后，这些主题就会显示出来。感谢 Pieces 的 Anthony 提出这个想法。
• Claude Code 和 Codex 会话会从 ~/.claude/projects 和 ~/.codex/sessions 读取（如果你设置了 CLAUDE_CONFIG_DIR 和 CODEX_HOME，则从相应目录读取）。rescue 和夜间运行也会读取这些会话；inkvault sync 则会独立读取，无需 Pieces。只会读取自上次同步以来新增的内容。
• Claude 桌面应用会话（Agent 模式，Windows）会从应用自身的文件夹读取（%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\local-agent-mode-sessions），并命名为 Claude desktop · project: title。macOS 和 Linux 上暂不读取。
• PiecesOS 端口：InkVault 会先读取 PiecesOS 保存在自身配置中的端口（.port.txt），再尝试上次成功使用的端口，最后尝试 39300 和 1000。若要指定端口，请设置 INKVAULT_PIECES_PORTS 或传入 --pieces-ports（夜间运行时使用：inkvault --pieces-ports 39301 schedule）。
• Pieces 自带的导出工具：Pieces 表示会提供该工具。也请使用它；两份副本总比一份好。计划支持将其格式导入 InkVault。
• 已在 Windows 上使用 PiecesOS 12.6.2 和包含 120,000 条捕获内容的知识库进行测试。macOS 和 Linux 上应该也能正常运行；欢迎反馈。目前，inkvault schedule 已在 Windows 上完成端到端测试；在 macOS 和 Linux 上目前仅通过自动化测试，因此非常欢迎使用真实 Mac 或 Linux 设备进行测试并反馈。

与 Pieces 无关联

InkVault 是一个独立项目。“Pieces”是其所有者的商标。

采用 MIT 许可证。由 T. Matthew Chase / Logos 7 制作。