星匣 · StarVault

你的 AI 记忆，始终属于你。

项目介绍 / Project site

星匣把分散的 AI 对话、附件与 Skill 收进自己的长期档案，方便检索、回溯和换机迁移，也为更懂你的助手准备有出处的历史资料。

产品原名为 Chat History Vault（会话档案）。软件代码发布于 StarDreamTech/starvault，聊天备份使用用户自行配置的私有仓库。starvault 与 chat-history-vault 命令均可使用；Python 模块、MCP 服务标识、Skill 标识和数据目录保持兼容。

桌面主窗口右上角的 GitHub 图标打开软件的公开源码仓库，不是聊天备份仓库。「管理 → 关于与反馈」（或设置中的同名分类）提供仓库及问题反馈链接；反馈公开，请勿上传私人对话、附件或凭据。

Homebrew 安装

brew tap cpython666/tap
brew install starvault                # CLI、MCP、使用者 Skill；macOS / Linux
brew install --cask starvault         # 桌面应用；当前提供 Apple Silicon macOS
starvault --help
open -a StarVault

桌面 Cask 同时安装 CLI 和 Python 后端，应用自带工具代码与图标。首版 macOS 应用使用本机临时签名，尚未通过 Apple 开发者签名和公证；若系统阻止打开，可在“系统设置 → 隐私与安全性”核对来源后允许打开。Intel macOS、Windows、Linux 的桌面端目前使用源码构建；不要将它们称为已有可下载的原生安装包。

源码、版本与安装包见 GitHub Releases。公开软件仓库不存放聊天内容；备份同步会校验目标为私有仓库。

新版 Homebrew 若提示未信任此安装源，核对 Formula / Cask 后，可仅信任本产品：brew trust --formula cpython666/tap/starvault 和 brew trust --cask cpython666/tap/starvault，再继续安装。

把 Codex、Claude Code、Claude Desktop、WorkBuddy、OpenClaw、DeepSeek Harness 的本地会话及导入的 ChatGPT 对话备份为可阅读、可筛选的档案。Claude Desktop 包括已经保存在本地的云端聊天导入副本，以及 Code Projects 的本地缓存消息。GitHub 只上传对话正文与分类索引；原始消息记录、附件、命令和日志留在本地。

• 软件仓库的 main：工具代码；以下会话分支创建在独立配置的私有备份仓库中。
• <电脑名称>-codex：这台电脑的 Codex CLI 文字会话和索引。
• <电脑名称>-claude：这台电脑的 Claude Code 文字会话和索引。
• <电脑名称>-claude-desktop：Claude / Claude-3p 桌面目录中的本地会话、已有导入副本和 Code Projects 缓存消息，保留其原始来源与覆盖范围。
• <电脑名称>-workbuddy：这台电脑的 WorkBuddy 文字会话和索引。
• <电脑名称>-openclaw：这台电脑的 OpenClaw 文字会话和索引。
• <电脑名称>-dsh：这台电脑的 DeepSeek Harness 文字会话和索引。
• <电脑名称>-chatgpt：单独保存导入的 ChatGPT 对话。
• 本地 images/：按图片内容 SHA-256 去重的 PNG/JPEG/GIF/WebP 原始文件，不压缩、不上传。
• 本地 attachments/：可选复制的 GLB、Blend、文档、代码等，按内容去重并保留旧版本。
• 本地 skills/：Skill 完整目录的 ZIP 快照、来源和历史版本；仅保存在本地。
• 本地 records/<电脑-工具>/<会话>/：原始对话 JSONL、原始元数据、文件关联清单及可选的命令日志；Claude Desktop 本地 JSONL 会话 / OpenClaw / DeepSeek Harness 另存完整事件流 source.jsonl，Code Projects 保存提取并合并的消息快照，压缩 Codex 会话保留原始压缩副本 source.jsonl.zst。

依赖：Python 3.9+；备份需要 Git，私有仓库同步需要 GitHub 登录。无必装的第三方 Python 包，无需 Git LFS 或数据库服务。读取 Codex、DeepSeek Harness 或 OpenClaw 中的 zstd 压缩内容时，按顺序使用 Python 3.14+ 标准库、可选的 zstandard、系统或 Homebrew 的 libzstd、zstd 命令之一；都没有时该来源会报告无法读取，不会静默跳过。

MCP 查询已有档案只需要 Python 3.9+；不需要打开桌面应用、安装第三方运行时依赖或登录 GitHub。

统一命令行

chat-history-vault 统一提供备份、查询、附件与 Skill 迁移、MCP 服务。需要 Python 3.9+，运行时只使用标准库；备份流程还需要 Git，向私有仓库同步时需要 GitHub 登录。建议安装在独立虚拟环境中，避免与其他 Python 软件混装。

在项目根目录安装，macOS / Linux：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
chat-history-vault --help
chat-history-vault --version

Windows PowerShell 可直接运行虚拟环境中的程序，无需修改脚本执行策略：

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\chat-history-vault.exe --help
.\.venv\Scripts\chat-history-vault.exe --version

下文的 chat-history-vault 在未激活环境时，可替换为 .venv/bin/chat-history-vault（macOS/Linux）或 .\.venv\Scripts\chat-history-vault.exe（Windows）。同一解释器也支持 python -m chat_history_vault；在源码目录可直接用 python3 -m chat_history_vault，原有 vault.py、vault_mcp.py 入口继续保留。安装不会配置 MCP 客户端、创建定时任务或安装桌面应用；桌面后端定位仍按下文的 CHAT_HISTORY_VAULT_TOOL 设置。

# 备份与迁移沿用原参数；init 见“一台新电脑的设置”
chat-history-vault export                   # 仅本地备份
chat-history-vault sync --tool codex        # 会提交并推送到已配置的私有仓库
chat-history-vault attachment-policy --kinds none   # 后续只备份会话，不另行复制附件
chat-history-vault attachment-policy --kinds images # 后续同时复制图片
chat-history-vault attachment-policy --kinds images,documents,models
chat-history-vault migrate --kinds models,logs --plan
chat-history-vault skills --archive "/path/to/backup" --defaults --plan

# 查询已有档案，无需 init 或登录 GitHub
chat-history-vault call vault_status --archive "/path/to/backup"
chat-history-vault search "Windows 迁移" --archive "/path/to/backup" --limit 10
chat-history-vault read MyLaptop-codex SESSION_ID --archive "/path/to/backup" --format dialogue
chat-history-vault attachments MyLaptop-codex SESSION_ID --archive "/path/to/backup"
chat-history-vault tools
chat-history-vault mcp --archive "/path/to/backup" --print-config
chat-history-vault skill-path

search、read、attachments、call、tools 输出 UTF-8 JSON，诊断写入 stderr，失败返回非零退出码。search 支持 --tool、--project、--device、--archived all|yes|no；查询和列表通过 --offset、--limit 分页，按结果中的 next_offset 继续。read 的偏移与长度以字符计，支持 markdown、dialogue、manifest、operations。status 保留原含义，查看已保存配置与上次备份结果；档案数量和来源统计使用 call vault_status。

call TOOL 支持 --arguments 或 --arguments-file，调用写入工具时需加 --allow-write。mcp 沿用 vault_mcp.py 的选项，直接运行 chat-history-vault mcp 会等待客户端通过标准输入输出通信。原有 export、sync、migrate、skills 等显式操作命令保留原行为，不要求该开关。各命令的完整参数见 chat-history-vault COMMAND --help。

配置目录按以下优先级选择：环境变量 CHAT_HISTORY_VAULT_CONFIG_DIR；源码目录的 .local/（源码有 .git 或已有 .local/config.json）；最后使用 macOS 的 ~/Library/Application Support/ChatHistoryVault/tool/.local/，或 Windows/Linux 的 ~/ChatHistoryVault/tool/.local/。配置、导入缓存、锁和运行状态保存在同一目录，不写入 Python 安装目录。生成的 MCP 配置和新安装的 macOS 定时任务会携带所选配置目录；升级或重新安装 CLI 不迁移、删除已有档案。Python 后端已通过 macOS / Windows / Linux 的 CI 临时数据回归；源应用真实数据读取目前只在 macOS 本机核验。

Rust 桌面面板

desktop/ 是 Rust + egui 编写的原生桌面阅读器，直接读取同一份本地备份，不需要启动网页服务器。支持：

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗