Claude Code にセッション間の記憶を持たせる自作メモリ層。外部サービス不要・コストゼロ・Git で完全自己管理。
毎回 Claude Code に「MUI の sx は px 禁止」「pnpm を使う」などを言い直していませんか?
このツールを入れると、そういう方針を ~/.claude-memory/global.md に書いておくだけで、次回起動時から Claude Code が自動的に覚えています。プロジェクトごとの文脈は repos/{project-key}.md に分かれて保存され、ディレクトリを移動するだけで切り替わります。
記憶はあなた自身のプライベート Git リポジトリ上にあるので、外部サービスにソースコードが送信されることは一切ありません。複数 PC でも git push/pull で同期できます。
- TL;DR
- 何を解決するか (before / after)
- アーキテクチャ
- 特徴
- Getting Started (5 分)
- 日常の使い方
- 記憶ファイルの書き方
- 注入の仕組み
- 複数 PC 運用
- セキュリティ
- トラブルシューティング
- FAQ
- 環境変数
- アンインストール
- コントリビューション
- License
あなた: 「このコンポーネントに sx で padding 追加して」
Claude: 「sx={{ padding: '16px' }} で追加しました」
あなた: 「いや、px じゃなく spacing 単位で。前も言ったよね」
Claude: 「申し訳ない。sx={{ padding: 2 }} に修正します」
— 翌日 —
あなた: 「この Button に margin 足して」
Claude: 「sx={{ margin: '8px' }} に...」
あなた: 😩
# 最初に 1 度だけ書く:
# ~/.claude-memory/global.md
# ## MUI
# - sx の padding/margin は数値のみ (px 禁止、spacing 単位で)
あなた: 「このコンポーネントに sx で padding 追加して」
Claude: 「sx={{ padding: 2 }} で追加しました」
あなた: 😊
Claude Code は毎セッション開始時にこの記憶を自動で読み込みます。指示し直す必要はありません。
┌──────────────────────────────────────────────────────────────┐
│ あなたの Mac │
│ │
│ ┌──────────────────────┐ │
│ │ ~/.claude-memory/ │ ← あなた専用のプライベート │
│ │ (Git リポジトリ) │ Git リポジトリ (GitHub等) │
│ │ │ │
│ │ global.md │ ← 全 PJ 共通の方針 (手動編集) │
│ │ repos/ │ │
│ │ github.com-you- │ ← PJ 固有の記憶 (Claude が追記) │
│ │ project-a.md │ │
│ │ github.com-you- │ │
│ │ project-b.md │ │
│ └──────────┬───────────┘ │
│ │ │
│ │ SessionStart hook │
│ │ (cd 先の git remote URL に応じて自動切替) │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ ~/.claude/CLAUDE.md │ ← グローバル CLAUDE.md に注入 │
│ │ (手書きの内容…) │ │
│ │ <!-- cms:begin --> │ ← begin/end マーカーで sandwich │
│ │ (global.md の内容) │ │
│ │ (repos/*.md の内容) │ │
│ │ <!-- cms:end --> │ │
│ └──────────┬───────────┘ │
│ │ │
│ ▼ │
│ Claude Code │
│ (毎セッション、この記憶を読んでから動作) │
└──────────────────────────────────────────────────────────────┘
プロジェクト内の CLAUDE.md には一切書きません。
OSS リポジトリを汚しません。
- プロジェクトを汚さない: 注入先は
~/.claude/CLAUDE.md(グローバル) のみ。リポジトリ内のCLAUDE.mdは触らないので、OSS / チーム共有リポジトリでも安全 - 記憶は Git 管理: プライベート Git リポジトリに置くので、バックアップ・履歴・複数 PC 同期が全て Git の仕組みで完結
- 自動 push はデフォルト OFF: Claude が誤って API キー等を書き込んだ場合にリモートへ漏洩しないよう、push は
cmコマンドで明示的に実行することを推奨 - シークレットスキャナ内蔵: commit 前に
sk-*,ghp_*,AWS AKIA*, JWT, PEM 等の典型パターンを検出
- ✨ プロジェクトを汚さない — 注入先は
~/.claude/CLAUDE.mdのみ - 🔒 外部サービス不要 — 全ての記憶はあなた自身の Git リポジトリに
- 💻 複数 PC 対応 —
cmコマンドで git pull / push するだけ - 📁 複数リポジトリ対応 — ディレクトリごとに記憶を自動切替
- 🎯 プロジェクト衝突回避 — git remote URL ベースの slug で識別
- 🛡️ シークレットスキャナ内蔵 — API キー / 秘密鍵の誤 commit を防ぐ
- 🟢 opt-in な自動 push — 意図しないリモート反映を防止
- 🧹 クリーンなアンインストール — 自分が登録した hook だけを削除
(上記は機能要約です。実装の詳細は CHANGELOG.md を参照)
初めて使う人向けのステップバイステップです。
以下がインストール済みであることを確認してください。
# Claude Code (公式): https://claude.ai/code
claude --version # インストール確認
# Git と Node.js v18 以上
git --version
node --version # v18.0.0 以上もし Claude Code をまだ入れていない場合は、先に 公式サイト からインストールしてください。
あなた専用の記憶を保存するためのプライベートリポジトリを GitHub に作ります。既存のメインのリポジトリとは別に、新規で 1 つ作ってください。
GitHub CLI で作る場合 (推奨):
gh repo create claude-memory-private --private --clone=false \
--description "My personal Claude Code memory"
# → git@github.com:あなたのユーザー名/claude-memory-private.gitWeb UI で作る場合:
- https://github.com/new を開く
- Repository name:
claude-memory-private(名前は任意) - Visibility: Private を必ず選択
- README/gitignore/license は全て不要 (空の repo にする)
- Create → 表示される URL (例:
git@github.com:you/claude-memory-private.git) をコピー
重要: 必ず Private にしてください。public だと全世界があなたの設計方針を見られます。
curl -fsSL https://raw.githubusercontent.com/BoxPistols/claude-memory-sync/main/install.sh | bashインストーラは対話で以下を聞いてきます:
Git URL: ← Step 1 でコピーした URL を貼る
(空 Enter でローカルのみ運用も可能です。後から git remote add で追加できます。)
さらに ~/.local/bin が PATH に無い場合は ~/.zshrc / ~/.bashrc への追記を聞いてきます。y で OK。
cm editエディタ ($EDITOR / nano / vim) が開くので、あなたの好みを書きます:
# グローバル設計方針
## Claude への指示スタイル
- 差分だけ返す。ファイル全体を返さない
- 変更理由を 1 行コメントで添える
## 禁止事項
- any 型の使用
- console.log の commit保存して終了。
cm sync初回は pull → commit → push を実行。Step 1 で指定したプライベート repo に保存されます。
cm statusで状態を確認できます。
claude起動すると ~/.claude/CLAUDE.md に Step 3 で書いた方針が自動注入されます。試しに何か頼んでみて、記憶が効いているか確認してください。
確認の小ネタ: Claude に「今ロードされているメモリを要約して」と聞くと、注入内容が見えます。
プロジェクトで作業中、学んだことを Claude に伝えると記憶してくれます:
あなた: このプロジェクトは pnpm を使う。npm は使わない。これ記憶して
Claude: 記憶しました。~/.claude-memory/repos/github.com-you-project-a.md に追記しました。
この記憶はセッション終了時に自動 commit されます (push はされません — 安全のため)。push したい時は cm を実行。
claude # いつも通り起動するだけ。記憶が自動注入される
# 作業中に…
あなた: 今日学んだことを記憶して
Claude: ~/.claude-memory/repos/{project-key}.md に追記しました
# セッション終了時
→ 自動 commit (push はされない)
# 複数 PC に同期したい時、または区切りで
cm # pull --rebase → secret scan → commit → push| コマンド | 説明 |
|---|---|
cm または cm sync |
pull --rebase → scan-secrets → commit → push |
cm status |
ファイル一覧 + ahead/behind + 未 commit 変更 + 最終 commit |
cm log |
最近の commit 10 件 |
cm edit |
global.md を $EDITOR で開く |
cm clean |
~/.claude/CLAUDE.md から注入ブロックを削除 (再インストール時など) |
cm --help |
ヘルプ表示 |
記憶ファイルの構造:
~/.claude-memory/
├── global.md # 全 PJ 共通の設計方針 (手動編集)
└── repos/
├── github.com-you-project-a.md # Claude が自動追記する PJ 固有の記憶
├── github.com-you-project-b.md
└── gitlab.com-you-internal-tool.md
ファイル名は git remote origin URL を slug 化したもので、以下の順で決定されます:
git remote get-url originが取れたら →github.com-owner-repo形式の slug (HTTPS / SSH どちらでも同じ結果)- 取れなければ →
git rev-parse --show-toplevelの basename - git リポジトリでなければ → 現在ディレクトリの basename
同じ project-a という basename でも remote が違えば別ファイルとして管理されます。
- 自分のコーディングスタイル / 命名規則
- 普遍的に使うツール (pnpm 派 / npm 派、tabs vs spaces 等)
- Claude への指示スタイル (差分だけ欲しい、長い説明は不要 等)
- 絶対に使ってほしくないパターン (any 型禁止、console.log commit 禁止 等)
- そのプロジェクト特有の制約 (「この repo は Node 18、新機能は使えない」等)
- 過去の意思決定の背景 (「なぜ X ではなく Y を選んだか」)
- ファイル配置のクセ
- デバッグで見つかった罠
- コード本体 — メモリはあくまで方針・パターン用。Claude は読みますが、長大なコードは session context を圧迫します
- API キー / トークン / 秘密鍵 — シークレットスキャナが検出して commit をブロックします
- 機密情報 — プライベート repo でもバックアップが流出する想定を常に持つ
~/.claude/CLAUDE.md (グローバル) にのみ書き込みます。プロジェクト内の CLAUDE.md には一切触りません。
~/.claude/CLAUDE.md
(あなたの手書きコンテンツ — そのまま残る)
<!-- claude-memory-sync:begin -->
## グローバル設計方針
(global.md の内容)
## プロジェクト固有の記憶 (github.com-you-project-a)
(repos/github.com-you-project-a.md の内容)
<!-- claude-memory-sync:end -->
begin / end マーカーで sandwich されているので、セッション開始ごとにブロック内だけが再生成されます。ユーザーの手書きコンテンツは上書きされません。
Stop hook（応答の終わり、非同期）とSessionEnd hook（セッション終了時）は以下の順で動きます:
- 記憶リポジトリに変更があれば、シークレットスキャナで変更内容を検査。API キー / 秘密鍵の典型パターンにマッチしたら commit を中止
- 問題がなければ
git commit。対象は.mdファイルと、すでに追跡しているファイルの変更（git add -u）。スクリプトなど.md以外を同期したいときは、記憶リポジトリの.gitignoreで許可して一度だけ手でgit addする。以後の変更は自動でcommitされる CLAUDE_MEMORY_AUTO_PUSH=1が設定されていれば自動 push (デフォルト: off)。Stopでは前回のpushからCLAUDE_MEMORY_PUSH_INTERVAL秒（既定600）経っているときだけ、SessionEndでは常にpushする。他のマシンが先にpushしていたら1回だけrebaseして再試行し、競合したらrebaseを戻してログに残す
Stopでもpushするのは、ターミナルを閉じたときにSessionEndが最後まで走る保証がないためです。記憶の取得（pull）とCLAUDE.mdの合成はSessionStartで1回だけ行います。CLAUDE.mdはセッション開始時と/compact後にしか読まれないため、プロンプトごとに合成しても効果がありません。
CLAUDE.mdはSessionStart hookより先に読み込まれるため、合成した内容が効くのは次のセッションからです（claude -pで実測）。--global-contextを付けると、global.mdをhookの出力として渡すので、pull直後の内容がそのセッションで効きます。hookの出力には公式の上限（10,000文字）があるため、プロジェクト固有の記憶はCLAUDE.local.mdのままです。記憶リポジトリのrules/*.mdは~/.claude/rules/へコピーされ、pathsを指定したルールは該当ファイルを読んだときだけ読み込まれます。
push がデフォルト off なのは、Claude が誤って API キーを記憶ファイルに書き込んだときに意図せずリモートへ漏洩することを避けるため。日常的な push は cm を明示的に実行することを推奨します。
2 台目以降は install.sh を同じコマンドで実行して、Step 1 で作った同じ URLを入力するだけ。
# 2 台目の Mac
curl -fsSL https://raw.githubusercontent.com/BoxPistols/claude-memory-sync/main/install.sh | bash
# Git URL: git@github.com:you/claude-memory-private.git ← 1 台目と同じ URLあとは両方の PC で cm を叩くと git push/pull で同期されます。cm status で ahead/behind を確認可能。
- セッション開始時:
git pull --ff-onlyで最新を自動取得 (失敗は/tmp/claude-memory-sync.logに記録) - セッション終了時:
git commit(push はデフォルト off) - 手動:
cmで pull → commit → push を明示実行
異なる PC で同じファイルを編集して競合したら、cm が pull --rebase で取り込みを試みます。自動解決できない場合は明示的なエラーで止まり、手動で解決するよう促します (以前の pull --ff-only + 黙殺とは違います)。
本ツールは以下の前提で動きます:
- memory リポジトリに書き込める人 = あなたの Claude Code の振る舞いを実質的に操作できる人です。memory repo の内容は
~/.claude/CLAUDE.mdに注入され、Claude Code の全セッションのプロンプトになります。プロンプトインジェクションで情報漏洩・不正指示を仕込むことが可能です - したがって memory repo は 必ず private にしてください。public にすると全世界がコンテンツを見られるだけでなく、PR 経由であなたの CLAUDE.md に任意のプロンプトを仕込まれる可能性があります
- collaborator 権限を与える相手は慎重に選んでください。信頼できない相手に write 権限を与えるのは、あなたの Claude セッションを渡すのと等価です
~/.claude/skills/memory-sync/hooks/*.shを上書きできる人 (= あなたのホームディレクトリに書き込める人) は、セッション開始のたびに任意コードを実行できます。ホームディレクトリのパーミッションを 700 / 750 に保ってください
- シークレットスキャナが commit 前と push 前 (未 push 履歴) の両方を scan します
- 検出パターン (v0.1.0):
- OpenAI / Anthropic:
sk-*/sk_live_* - GitHub:
ghp_*/gho_*/ghu_*/ghs_*/ghr_*/github_pat_* - AWS:
AKIA*/ASIA* - Google:
AIza*/GOCSPX-* - Azure:
DefaultEndpointsProtocol=...AccountKey=... - Slack:
xox[baprs]-*/ webhookT.../B.../* - Stripe:
sk_live_*/rk_live_* - npm:
npm_* - Docker Hub:
dckr_pat_* - DigitalOcean:
dop_v1_* - Databricks:
dapi* - Shopify:
shpat_*/shpca_* - GitLab:
glpat-* - Hugging Face:
hf_* - Replicate:
r8_* - JWT (3 セグメント形式)
- PEM private key ブロック
- OpenAI / Anthropic:
- 入力サニタイズ: memory ファイル内に偽の
<!-- claude-memory-sync:begin -->/:endマーカーが混入していても、注入時に grep で除去されるので CLAUDE.md の構造が破壊されない (プロンプトインジェクションでの永続汚染を防止) - マーカー付き hook 管理:
_claude_memory_sync: trueプロパティで本ツール所有の hook を識別。他の hook と衝突しない、誤って壊さない - Atomic settings.json 書き込み: 一時ファイル + rename で、install 途中のクラッシュでも
~/.claude/settings.jsonを破損させない - ログは自ユーザ領域に: pull 失敗などのログは
~/.claude/logs/以下 (mode 700) に保存。/tmp経由の symlink 攻撃や情報漏洩を避ける
- memory repo に collaborator として書き込める攻撃者: 上記信頼モデルの通り、これはツールの守備範囲外です。collaborator 管理を慎重に
- 本スキャナのパターン漏れ: best-effort です。カスタムのシークレット形式、長期的な keyスキーマ変更、難読化された秘密情報は検出できません。真剣な検査には trufflehog / gitleaks を併用してください
- MITM at install time:
curl | bashでインストールするので、TLS が破られたら任意コードが実行されます。これを避けたい場合は手動 clone + 確認後に./install.shを実行してください
一時的な解除手段:
CLAUDE_MEMORY_SKIP_SECRET_SCAN=1 cm # シークレットスキャナをバイパス
CLAUDE_MEMORY_AUTO_PUSH=1 claude # セッション終了時に自動 push する
node bin/setup.js --auto-push # 自動pushをhookのコマンドに埋め込む（マシンごとに1回）後者は危険 (push 前に人間が確認できない) なので、信頼できる環境でのみ 使ってください。
インストール時に ~/.local/bin が PATH に入っていません。
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # zsh の場合
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # bash の場合
source ~/.zshrc # または新しいターミナルを開くまず手動で確認:
cat ~/.claude/CLAUDE.md<!-- claude-memory-sync:begin --> から :end --> までのブロックがあればインジェクションは成功しています。
もしブロックが無い場合:
# hook が登録されているか確認
cat ~/.claude/settings.json | grep -A 3 SessionStart
# 手動で start.sh を実行してみる
bash ~/.claude/skills/memory-sync/hooks/start.shそれでも動かない場合は /tmp/claude-memory-sync.log を見てみてください。
リモートと分岐している可能性があります。
cd ~/.claude-memory
git status # 未コミットの変更があるか確認
git log --oneline -5
git fetch
git log origin/main --oneline -5手動で git pull --rebase して競合を解決してから、もう一度 cm sync。
一時的にバイパスするには:
CLAUDE_MEMORY_SKIP_SECRET_SCAN=1 cm syncただし、本当に機密情報が紛れていないかは必ず自分で確認してください。
本ツールはマーカー (_claude_memory_sync: true) 付きで hook を登録するため、同イベントに別の hook があっても干渉しません。逆に本ツール以外の hook が壊れている場合は、本ツールとは無関係の問題です。
それは意図通りです。~/.claude-memory/ は uninstall.js では削除されません。
rm -rf ~/.claude-memory # 完全削除手書きのコンテンツは絶対に触らないので大丈夫ですが、念のため:
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backupでバックアップを取ってから始めることをおすすめします。
A. Claude Code 組み込みのメモリはプロジェクトごとにローカル保存されるだけで、複数 PC 間の同期・Git 履歴・バックアップが無い。本ツールは同じ問題を Git で解決し、さらに global.md (全 PJ 共通) という概念を追加します。両者は併用できます。
A. 読まれます。本ツールが触るのは グローバルの ~/.claude/CLAUDE.md だけなので、プロジェクトの CLAUDE.md はそのまま Claude Code が読み込みます。両方とも有効です。
A. どちらも CLAUDE.md に注入されて Claude が読みます。内容が矛盾した場合の動作は未定義です。矛盾しないように書いてください。一般には「global.md は一般方針」「repos/*.md は例外やプロジェクト固有」という切り分けが自然です。
A. SessionStart / Stop / SessionEnd hook は Claude Code を起動したときだけ発火するので、他のエディタ作業中には何も起きません。
A. セッション終了時または cm sync 実行時にシークレットスキャナが検出して commit を中止します。記憶ファイルから該当行を削除して再実行してください。
もし既に push してしまった場合は、即座に該当トークンを revoke して、git history を書き換え (git filter-repo など) してください。この場合の対応は本ツールの責務を超えます。
A. 問題ありません。プロジェクト固有の記憶は repos/{git-remote-slug}.md に分離され、注入先も <project-root>/CLAUDE.local.md とプロジェクトごとに分かれるので、何個でも並行可能です。global.md は全プロジェクトで共有され、~/.claude/CLAUDE.md へ注入されます。
v0.1.x までの注意: 以前はプロジェクト固有の記憶も
~/.claude/CLAUDE.md（全セッション共有）へ注入していました。複数リポジトリで Claude Code を同時起動すると後勝ちで上書きされ、別リポジトリの記憶が混入する不具合がありました。現在は注入先を分離して解消しています。
A. この 1 パターンだけ、親の記憶が子セッションに読まれます（既知の制限）。
Claude Code は cwd から親ディレクトリを遡り、各階層の CLAUDE.md / CLAUDE.local.md を読み込みます（公式ドキュメント: 「checking each directory along the way」）。そのため /repo-a/repo-b/（別リポジトリが物理的に内包されている構成）で作業すると、repo-b のセッションは /repo-a/CLAUDE.local.md も読みます。
これは Claude Code のメモリ読み込み仕様によるもので、本ツール側では回避できません。
入れ子を解消できるなら、そちらが確実です。 同じ経路で親の追跡対象の CLAUDE.md（別プロジェクトの指示そのもの）も読み込まれており、これは記憶ツールとは無関係の問題なので設定では塞ぎきれません。ディレクトリを並列に移せば両方まとめて消えます。
移動できない場合は claudeMdExcludes で除外してください。
// .claude/settings.local.json
{
"claudeMdExcludes": ["**/repo-a/**"]
}~/.claude/settings.json / ./.claude/settings.json / ./.claude/settings.local.json のいずれでも設定でき、設定層ごとに配列がマージされます。ただし組織のマネージドポリシーで配布された CLAUDE.md は除外できません。
未確認: 遡査がファイルシステムのどこまで続くか、
.gitの境界で止まるかは公式ドキュメントに明記がありません。上記は「親ディレクトリを遡る」という記載から導かれる挙動です。
A. macOS / Linux 前提です。install.sh と shell hook が POSIX シェルを要求します。WSL2 なら動くはずですが検証していません。
A. install.sh の PATH 自動追記プロンプトは zsh / bash を認識します。fish / nushell 等を使っている場合は手動で ~/.local/bin を PATH に追加してください。フック本体は /bin/bash で動くので、ログインシェルが何であれ問題ありません。
A. CLAUDE_MEMORY_SYNC_REPO 環境変数を設定して install.sh を実行すると、そのリポジトリから clone します。
CLAUDE_MEMORY_SYNC_REPO=https://github.com/you/claude-memory-sync-fork \
./install.shまたは開発中なら ~/.claude/skills/memory-sync を fork リポジトリへのシンボリックリンクにしても OK です。詳しくは CONTRIBUTING.md を参照。
| 変数 | 説明 | デフォルト |
|---|---|---|
CLAUDE_MEMORY_DIR |
記憶リポジトリのパス | ~/.claude-memory |
CLAUDE_MEMORY_AUTO_PUSH |
1 / true でセッション終了時の自動 push を有効化 |
(off) |
CLAUDE_MEMORY_PUSH_INTERVAL |
Stopでpushする最短間隔（秒） |
600 |
CLAUDE_MEMORY_PULL_TIMEOUT |
SessionStartのpullを打ち切るまでの秒数 |
5 |
CLAUDE_MEMORY_GLOBAL_MODE |
contextのとき、global.mdをCLAUDE.mdではなくSessionStartの出力で渡す（setup.js --global-contextで設定）。9,500文字を超えるとCLAUDE.mdへ戻す |
(未設定) |
CLAUDE_MEMORY_SKIP_SECRET_SCAN |
1 / true でシークレットスキャナをバイパス |
(off) |
CLAUDE_MEMORY_SYNC_REPO |
install.sh が skill を clone する元 URL (fork / private mirror 用) | 本リポジトリ |
EDITOR |
cm edit が使うエディタ |
nano |
node ~/.claude/skills/memory-sync/bin/uninstall.js- マーカー付きで登録した
SessionStart/Stop/SessionEndhook（旧版のUserPromptSubmitを含む）のみを~/.claude/settings.jsonから削除します - ユーザーが独自に登録した他の hook は触りません
~/.claude/CLAUDE.mdの注入ブロックも自動で削除しますが、手書きコンテンツは保持されます- 記憶リポジトリ (
~/.claude-memory/) は 削除されません。不要なら手動でrm -rfしてください
バグ報告・機能提案・Pull Request は歓迎です。CONTRIBUTING.md を参照してください。
変更履歴は CHANGELOG.md を参照。