sync82

sync82

🌐 言語： English · Português

sync82 は Model Context Protocol（MCP） サーバーです。AI コーディングエージェントに、セッションをまたいでソフトウェアプロジェクトの永続的で構造化されたメモリ（目標、アーキテクチャ、技術スタック、決定事項、進捗状況）を提供します。これらはすべてローカルに保存され、エージェントが次回プロジェクトを開いたときに自動的に呼び出されます。

目次

• 概要
• 前提条件とクイックインストール
• クライアントのセットアップ
• 更新とメンテナンス
• ドキュメント
• このプロジェクトでの AI の利用
• ライセンス

概要

メモリは組み込みの SQLite データベースに保存され、自己完結型の単一バイナリとして提供されます。ランタイムツールチェーンも npm パッケージも不要で、PATH に sync82 を置くだけです。エージェントは MCP ツールを介してメモリを読み書きし、ユーザーはエージェントと自然言語でやり取りできます。

• プロジェクトごとに6つの標準メモリファイルに加えて、カスタムファイルも利用できます。モノレポやプラグインエコシステムなど、プロジェクトとそのサブプロジェクトに対応します。
• プロジェクトを自動検出 — ワークスペースに .sync82.json があれば、エージェントがプロジェクト名を再度指定する必要はありません。
• 19個の MCP ツール — 1回の呼び出しでプロジェクト全体のコンテキストを読み込み、1回の呼び出しでセッションを保存し、保管庫全体を検索し、古い履歴をアーカイブし、プレーンな Markdown をエクスポート／インポートできます。各プロジェクトのメモリを提供する読み取り専用 MCP リソースと、start_session／end_session プロンプトも利用できます。
• クライアントをワンステップでセットアップ — sync82 install で Claude Code、Claude Desktop、Antigravity、Codex、OpenCode、Cursor、Zed、Cline に sync82 を登録し、sync82 uninstall で削除できます。
• ローカルでプライベート — stdio トランスポートのみを使用し、ネットワークサービスはなく、保管庫ごとに SQLite ファイルを1つ使用します。
• 検証可能なリリース — SHA-256 チェックサム、Sigstore 署名、GitHub のビルド来歴証明アテステーション、Claude Desktop 拡張機能（sync82.mcpb）、および MCP Registry の登録情報を提供します。

ファイル	種類	用途
memory	上書き	プロジェクトの概要：名前、説明、目標
architecture	上書き	コンポーネントとその連携方法
stack	上書き	言語、フレームワーク、インフラストラクチャ
decisions	追記のみ、日付付き	決定事項とその理由
progress	追記のみ、日付付き	セッションごとに完了した作業
next_steps	上書き	次に行うこと

ツール（19）

AI エージェントは MCP 経由でこれらを呼び出します。データベースに直接アクセスすることはありません。パラメーターの詳細はツールリファレンスをご覧ください。

ツール	機能
list_projects	vault 内のすべてのプロジェクトとサブプロジェクトを一覧表示します
create_project	新しいプロジェクトまたはサブプロジェクトを作成します
delete_project	プロジェクトまたはサブプロジェクトを完全に削除します（確認が必要です）
rename_project	プロジェクトまたはサブプロジェクトの名前をその場で変更します
get_vault_config	アクティブな vault のパスと設定を報告します
list_files	プロジェクトに記録されているすべてのメモリファイルを一覧表示します
read_memory	メモリファイルの内容を読み込みます
write_memory	メモリファイルの内容全体を上書きします
append_memory	progress、decisions、またはカスタムの追記種別に日付付きのエントリーを追加します
delete_memory	カスタムメモリファイルを削除します（標準の6ファイルは保護されています）
edit_entry	progress、decisions、またはカスタムの追記種別のエントリーを置換、置き換え、または削除します
archive_memory	古い日付付きエントリーをアーカイブし、直近N日分のみをアクティブな状態で残します。必要に応じて要約も追加できます
search_memory	単語（アクセント記号と大文字・小文字を無視し、一致度の高い順）、フレーズ、または完全一致のテキストでメモリファイルを検索します
load_project_context	プロジェクトのメモリ（現在の状態と最近の履歴）を1つのコンテキストブロックに読み込みます
check_project_health	標準の6ファイルの有無を報告し、古くなっているように見えるファイルについて警告します
init_project_memory	コードベースからの自動検出をオプションで利用できる、ガイド付きの初期化を行います
update_project_memory	セッションの作業内容（進捗、決定事項、次のステップなど）を1回の呼び出しで保存します
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）として提供し、2つのMCP プロンプト、start_sessionとend_sessionも提供します。エージェントに何を入力すればよいかわからない場合は、プロンプトの例をご覧ください。

CLI コマンド

コマンド	機能
sync82 (引数なし)	stdio経由でMCPサーバーを起動します。クライアントが起動するのはこちらです
sync82 install [target]	sync82を1つまたはすべての対応MCPクライアントに接続します
sync82 uninstall [target] [--purge]	sync82を1つまたはすべてのクライアントから削除します。--purgeを指定すると、別途確認したうえで~/.sync82ファイルも削除します
sync82 config set-vault|get-vault|unset-vault	グローバルなvaultパスの上書き設定を管理します
sync82 self-update [--check] [--yes] [--require-signature] | --rollback	GitHub Releasesを確認してバイナリをその場で更新し、cosignがインストールされている場合は署名を検証します（--rollbackで以前のバージョンに戻します）
sync82 export <project> [subproject] <output-dir>	プロジェクトのメモリをプレーンな.mdファイルに出力します（vault全体の場合は--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 拡張機能をインストールできます。

どの OS でもバイナリを入手する方法は 2 つあります。どちらでも構いませんが、更新方法を混在させないでください（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）で確認できます。

クライアントのセットアップ

次のコマンドを 1 回実行するだけで、マシン上で検出されたすべての対応クライアントに 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 の Settings → Extensions → Advanced settings → Extension Developer → Install Extension… からインストールしてください。sync82 は MCP Registry に io.github.oito2/mcp-sync82 としても登録されています。

クライアントごとのガイド（手動設定とトラブルシューティングを含む）：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 を実行してください。デフォルトのボールトと ~/.sync82 内の設定も削除するには、--purge を追加します。バイナリも含めた完全な削除については、アンインストールを参照してください。

ドキュメント

ドキュメントサイトに詳細が記載されています（ポルトガル語版もあります）。

• インストール · クイックスタート · アンインストール
• 概念 — アーキテクチャと内部構造
• リファレンス：ツール · リソース · MCP プロンプト · CLI · 設定
• プロンプトの例 · 使用例
• トラブルシューティング · 変更履歴

貢献： 開発ワークフロー、CI で実行されるチェック（go build ./...、go vet ./...、gofmt -l .、golangci-lint、go test ./... -race、govulncheck）、リリースの公開方法については、CONTRIBUTING.mdを参照してください。参加者は全員、行動規範に従うことが求められます。

このプロジェクトでの AI の利用

このプロジェクトは、生成 AI ツールの支援を受けて開発されました。

• 範囲： ボイラープレート、ユニットテストの生成、ヘルパー関数のリファクタリング。

• 監督： 生成されたコードはすべて、統合前に手作業でレビュー、テスト、検証されました。

ライセンス

GPL-3.0 — LICENSEを参照してください。