chatvault

chatvault

你过去的 AI 聊天记录已经保存在本地磁盘上。chatvault 让 MCP 客户端能够搜索、重新打开并盘点这些记录，而不会让任何历史记录离开 这台机器。无需账户，无需上传，也不会发起网络请求：服务会读取由你控制的文件夹中的 JSON 文件。

配置

• CHATVAULT_CORPUS_DIR（可选）— 语料库所在位置。 默认为 ~/.chatvault/corpus。
• CHATVAULT_READ_ONLY（可选）— 设置为 1 后，两个写入工具（save_conversation、save_memory） 会拒绝操作，并返回说明当前模式的错误。读取操作仍可正常进行。

语料库布局

每个对话对应一个 JSON 文件，另有 memories.json：

{
  "id": "abc",
  "platform": "claude",
  "title": "Planning a trip",
  "updatedAt": "2026-10-01T12:00:00.000Z",
  "messages": [
    { "role": "user", "text": "Where should we go?" },
    { "role": "assistant", "text": "Some ideas..." }
  ]
}

消息还可以包含 formattedText 和 images （{mime, dataBase64} 条目，用于保存保留的图像字节数据）。 对话可以包含 localTitle。语料库目录为空或不存在都没有问题：搜索和列表操作只会返回空结果。

每个对话都有一个内容指纹，以 fp2: 开头， 后接 SHA-256 十六进制摘要。摘要涵盖 标题、设置时的本地标题，以及按顺序排列的每条消息 ——消息的索引、角色、文本、存在时的格式化文本，以及 每张图像的 mime 类型和保留的字节数据。时间戳和派生字段不计入，因此，重新保存相同内容会保留相同的指纹，而重命名或编辑消息则会更改指纹。确切的序列化形式（键已排序的规范 JSON） 是带标签的重建结果。

工具

• search_conversations — 对标题和消息文本执行分词全文搜索。必需参数：query。可选参数：platform（精确匹配）、title（子串）、date_from 和 date_to（根据 updatedAt 匹配），以及 match_mode — any（默认）、all 或 phrase。结果按匹配数量排序，其次按最近时间排序，并附带摘要片段。
• get_conversation_image — 获取消息中存储的图像。 必需参数：conversation_id、message_index、image_index。 返回 mime 类型和 base64 字节数据；图像不存在时会如实报错。
• get_conversation — 获取 id 对应的完整对话记录，其中包含 contentFingerprint 字段。
• list_conversations — 按 updatedAt 排列对话。 可选参数 order（默认为 newest_first，也可设为 oldest_first）和 limit。
• list_recent — 获取最近更新的对话，包含标题、简短摘要（第一条用户 消息的摘录 — 属于重建结果）和平台。可选参数 limit。
• conversation_inventory — 以快照分页的方式列出紧凑的 {id, platform, title, fingerprint} 条目。调用时不传参数即可开始扫描，然后将每页的 nextCursor 作为 cursor 传回。每页最多包含 100 个 条目；limit 可以缩小每页条目数。最多保留八个快照，未知或已过期的游标会报错，并要求重新开始扫描。
• corpus_status — 返回语料库的 {lastReceivedAt, count}；语料库为空时，lastReceivedAt 为 null。
• save_conversation — 添加或更新对话。 必需参数：platform、title、messages。省略 id 时会自动分配 一个值（chatvault:<n>）。返回 {id, fingerprint}。
• save_memory — 将来自 text 的持久事实存储起来。记录会追加到 memories.json，初始状态为关闭 （enabled: false），直到你审核并启用它；随后返回已存储的记录。

搜索和列表结果也会附带一个 corpus 块 — {lastReceivedAt, count} — 方便调用方了解回答所依据语料库的新鲜程度和大小。

CLI

npx @reneturcios/chatvault corpus_status '{}'
npx @reneturcios/chatvault search_conversations '{"query":"trip"}'
npx @reneturcios/chatvault --version

输出为工具的结果文本。退出代码：成功时为 0， 结果出错时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/chatvault mcp

MCP 客户端配置：

{
  "mcpServers": {
    "chatvault": {
      "command": "npx",
      "args": ["-y", "@reneturcios/chatvault", "mcp"],
      "env": {
        "CHATVAULT_CORPUS_DIR": "/path/to/corpus"
      }
    }
  }
}

Docker

docker run -i -v /path/to/corpus:/corpus -e CHATVAULT_CORPUS_DIR=/corpus ghcr.io/cloudcorprecords/chatvault
docker run --rm ghcr.io/cloudcorprecords/chatvault --version

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (temp corpus dirs, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios