sync82

sync82

🌐 语言： English · Português

sync82 是一款 模型上下文协议（MCP） 服务，可为 AI 编码 Agent 提供跨会话持久且结构化的软件项目记忆，涵盖目标、架构、技术栈、决策和进度；所有内容都存储在本地，并会在 Agent 下次打开项目时自动调取。

目录

• 概览
• 前置条件与快速安装
• 客户端设置
• 更新与维护
• 文档
• 本项目中的 AI 用法
• 许可证

概览

记忆存储在嵌入式 SQLite 数据库中，并以单个独立二进制文件的形式提供——无需运行时工具链，也无需 npm 包，只需将 sync82 放在 PATH 中即可。Agent 通过 MCP 工具读写记忆；你只需用日常语言与 Agent 对话。

• 每个项目有六个标准记忆文件，还可添加自定义文件，适用于项目及其子项目（单体仓库、插件生态系统）。
• 自动发现项目——工作区中有 .sync82.json，Agent 就无需再询问项目名称。
• 19 个 MCP 工具——一次调用即可加载整个项目的上下文，一次调用即可保存会话，还可搜索整个记忆库、归档旧历史记录、导出／导入纯 Markdown；此外还提供只读 MCP 资源，包含每个项目的记忆，以及 start_session／end_session 提示词。
• 一步完成客户端设置——sync82 install 可在 Claude Code、Claude Desktop、Antigravity、Codex、OpenCode、Cursor、Zed 和 Cline 中注册 sync82；sync82 uninstall 可将其移除。
• 本地且私密——仅使用 stdio 传输，不提供网络服务；每个记忆库对应一个 SQLite 文件。
• 可验证的发行版本——提供 SHA-256 校验和、Sigstore 签名和 GitHub 构建来源证明；同时提供 Claude Desktop 扩展（sync82.mcpb）和 MCP Registry 条目。

文件	类型	用途
memory	覆盖写入	项目概览：名称、描述、目标
architecture	覆盖写入	组件及其协作方式
stack	覆盖写入	语言、框架、基础设施
decisions	仅追加，带日期	已作出的决策及原因
progress	仅追加，带日期	按会话记录已完成的工作
next_steps	覆盖写入	后续工作

工具（19 个）

AI Agent 通过 MCP 调用这些工具，不会直接操作数据库。完整参数说明请参阅工具参考。

工具	功能
list_projects	列出存储库中的所有项目和子项目
create_project	创建新项目或子项目
delete_project	永久删除项目或子项目（需要确认）
rename_project	就地重命名项目或子项目
get_vault_config	报告当前存储库路径和配置
list_files	列出某个项目记录的所有记忆文件
read_memory	读取记忆文件的内容
write_memory	覆盖记忆文件的全部内容
append_memory	向 progress、decisions 或自定义追加类别中添加带日期的条目
delete_memory	删除自定义记忆文件（六个标准文件受保护）
edit_entry	替换、取代或删除 progress、decisions 或自定义追加类别中的一个条目
archive_memory	归档较早的带日期条目，仅保留最近 N 天的活跃条目，并可选择添加摘要
search_memory	按单词（忽略重音符号和大小写，最佳匹配优先）、短语或精确文本搜索记忆文件
load_project_context	将项目记忆（当前状态和近期历史）加载到一个上下文块中
check_project_health	报告六个标准文件的存在情况，并警告看起来已过时的文件
init_project_memory	引导式初始化，可选择从代码库自动检测
update_project_memory	一次调用即可保存一个会话的工作内容（进展、决策、后续步骤等）
export_memory	将项目记忆导出为磁盘上的纯 .md 文件
import_memory	从纯 .md 文件导入项目记忆，与 export_memory 相反

list_projects、list_files、check_project_health 和 search_memory 也会返回 JSON（format: "json"）。除了工具，sync82 还会通过 MCP 资源（sync82://projects/<project>/context）提供各项目的记忆，并提供两个 MCP 提示词：start_session 和 end_session。不知道该对 Agent 输入什么？请参阅示例提示词。

CLI 命令

命令	功能
sync82（不带参数）	通过 stdio 启动 MCP 服务，这是客户端启动的命令
sync82 install [target]	将 sync82 接入一个或所有受支持的 MCP 客户端
sync82 uninstall [target] [--purge]	从一个或所有客户端移除 sync82；--purge 还会在单独确认后删除 ~/.sync82 文件
sync82 config set-vault|get-vault|unset-vault	管理全局存储库路径覆盖设置
sync82 self-update [--check] [--yes] [--require-signature] | --rollback	检查 GitHub Releases 并原地更新二进制文件；如果已安装 cosign，则验证签名（--rollback 会恢复到上一版本）
sync82 export <project> [subproject] <output-dir>	将项目记忆导出为纯 .md 文件（使用 --all 可导出整个存储库）
sync82 import <project> [subproject] <input-dir> [--dry-run]	从纯 .md 文件还原项目记忆，与 export 相反；--dry-run 仅报告将发生的更改
sync82 search <query> [--project P] [--json]	搜索记忆，类似于 search_memory 工具
sync82 context <project> [subproject] [--full]	打印项目记忆，类似于 load_project_context 工具
sync82 health <project> [subproject] | --all	检查某个项目或所有项目是否缺少文件或记忆已过时
sync82 help / --help / -h	打印子命令列表
sync82 version / --version / -v	打印已安装的版本

所有命令的完整标志、退出代码和示例，请参阅：CLI 参考。

前置条件与快速安装

前置条件： Linux、macOS 或 Windows（amd64/arm64）——发布二进制文件无需其他依赖；从源代码构建需要与 go.mod 匹配的 Go 工具链（1.26+）。你还需要一个 MCP 客户端（参见客户端设置）。Claude Desktop 用户可以跳过本节，改为安装 .mcpb 扩展。

在任何操作系统上获取二进制文件有两种方式——任选其一，但请勿混用更新方式（参见 CLI 参考 — 自行更新）。

Linux

预编译二进制文件（无需 Go 工具链）：

curl -LO https://github.com/oito2/mcp-sync82/releases/latest/download/sync82_linux_amd64   # or sync82_linux_arm64
curl -LO https://github.com/oito2/mcp-sync82/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing   # must print "sync82_linux_amd64: OK"
chmod +x sync82_linux_amd64
sudo mv sync82_linux_amd64 /usr/local/bin/sync82

从源代码构建（需要 Go 1.26+——从 go.dev/dl 下载；Debian/Ubuntu 的 golang-go 等发行版软件包通常版本较旧）：

go install github.com/oito2/mcp-sync82/cmd/sync82@latest

macOS

预编译二进制文件（无需 Go 工具链）：

curl -LO https://github.com/oito2/mcp-sync82/releases/latest/download/sync82_darwin_arm64   # Intel: sync82_darwin_amd64
curl -LO https://github.com/oito2/mcp-sync82/releases/latest/download/checksums.txt
grep ' sync82_darwin_arm64$' checksums.txt | shasum -a 256 -c   # must print "sync82_darwin_arm64: OK"
chmod +x sync82_darwin_arm64
sudo mv sync82_darwin_arm64 /usr/local/bin/sync82

从源代码构建（需要 Go 工具链——brew install go）：

go install github.com/oito2/mcp-sync82/cmd/sync82@latest

Windows

预编译二进制文件（无需 Go 工具链——PowerShell）：

$base = "https://github.com/oito2/mcp-sync82/releases/latest/download"
Invoke-WebRequest -Uri "$base/sync82_windows_amd64.exe" -OutFile sync82_windows_amd64.exe
Invoke-WebRequest -Uri "$base/checksums.txt" -OutFile checksums.txt
$expected = ((Select-String -Path checksums.txt -SimpleMatch "sync82_windows_amd64.exe").Line -split '\s+')[0]
if ((Get-FileHash sync82_windows_amd64.exe -Algorithm SHA256).Hash -ne $expected) { throw "checksum mismatch" }
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\sync82" | Out-Null
Move-Item sync82_windows_amd64.exe "$env:LOCALAPPDATA\sync82\sync82.exe"
# add $env:LOCALAPPDATA\sync82 to PATH: System Properties > Environment Variables

从源代码构建（需要 Go 工具链——安装程序）：

go install github.com/oito2/mcp-sync82/cmd/sync82@latest

---

每个版本都附带一个 checksums.txt（已在上述步骤中验证）、一个为其签名的 Sigstore 证书包（checksums.txt.sigstore.json），以及针对每个二进制文件和 .mcpb 包的 GitHub 构建来源证明（gh attestation verify <file> --repo oito2/mcp-sync82）——参见安装指南。

go install/go build 会直接生成可运行的最终二进制文件——请确保 $(go env GOPATH)/bin（或 %GOBIN%/$GOBIN）位于你的 PATH 中；使用 which sync82 检查（Windows 上使用 where sync82）。

客户端设置

一步将 sync82 注册到本机检测到的所有受支持客户端：

sync82 install            # lists the detected clients, asks to confirm, configures each of them
sync82 install claude     # configure a single client instead

目标客户端：claude、claude-desktop、antigravity、codex、opencode、cursor、zed、cline。每个客户端都会注册你运行的 sync82 二进制文件的绝对路径，因此如果移动了二进制文件，请再次运行 sync82 install。每个目标客户端都会显示 configured. 或 updated.；未检测到的客户端（其命令不在 PATH 中或其配置目录不存在）会被跳过。

手动配置 Claude Code（用户范围，适用于所有项目）：

claude mcp add --scope user sync82 -- /usr/local/bin/sync82   # the path printed by `which sync82`
claude mcp list

Claude Desktop——无需二进制文件：下载 sync82.mcpb，并通过 Claude Desktop 的 设置 → 扩展 → 高级设置 → 扩展开发者 → 安装扩展… 进行安装。sync82 也已作为 io.github.oito2/mcp-sync82 列入 MCP 注册表。

各客户端的指南（含手动配置和故障排除）：Claude Code · Claude Desktop · Antigravity · Codex · OpenCode · Cursor · Zed · Cline。其他客户端只需将 command 设置为二进制文件的绝对路径——参见安装程序。

更新与维护

sync82 self-update --check   # report whether a newer release exists (exit code 10 when one does)
sync82 self-update           # download, verify (signature with cosign, SHA-256) and install the latest release
sync82 self-update --rollback   # restore the previous version, kept as <binary>.bak

self-update 可用于发布版二进制文件或通过 go install .../[email protected] 构建的版本。如果你通过 go install 安装，请改用 go install github.com/oito2/mcp-sync82/cmd/sync82@latest 更新——不要混用这两种方式。Claude Desktop 扩展可通过安装较新的 sync82.mcpb 更新。发布版本可能会升级保险库架构（1.1.0 和 1.2.0 就会）；新版本打开保险库后，之前的二进制文件（包括通过 --rollback 恢复的版本）将无法再使用该保险库，因此请更新所有共用该保险库的客户端，不要回滚到此类发布版本之前（参见故障排除）。

要从所有检测到的客户端中移除 sync82，请运行 sync82 uninstall（添加 --purge 还会删除 ~/.sync82 中的默认保险库和配置）——完整移除说明（包括二进制文件）请参见卸载。

文档

文档网站提供了完整的详细信息（也有葡萄牙语版）：

• 安装 · 快速入门 · 卸载
• 概念 — 架构和内部机制
• 参考：工具 · 资源 · MCP 提示词 · CLI · 配置
• 提示词示例 · 使用示例
• 故障排除 · 更新日志

**贡献：**有关开发工作流、CI 运行的检查（go build ./...、go vet ./...、gofmt -l .、golangci-lint、go test ./... -race、govulncheck）以及发布流程，请参见 CONTRIBUTING.md。所有参与者都应遵守行为准则。

本项目中的 AI 使用情况

本项目在开发过程中使用了生成式 AI 工具：

• **范围：**生成样板代码、单元测试，并重构辅助函数。

• **监督：**所有生成的代码在集成前均经过人工审查、测试和验证。

许可证

GPL-3.0 — 详见 LICENSE。