claude-memory-sync

Sync Claude Code memory files across machines via GitHub.

Claude Code stores per-project memory in ~/.claude/projects/<dirname>/memory/. When you switch between a Windows desktop and a MacBook, that memory stays behind. This tool syncs it to a private GitHub repo so your memory follows you everywhere.

Features

• Cross-platform sync — Works across Windows, macOS, and Linux via GitHub
• Smart conflict resolution — Section-aware markdown merging (not last-write-wins)
• Cross-device alias system — Maps machine-specific dirnames (C--Users-ktanm on Windows, -Users-phoenix on Mac) to shared alias names
• Auto-sync hooks — Memory syncs automatically on Claude Code session start/stop
• Secret scanning — Blocks push if API keys, tokens, or private keys are detected
• Diff before sync — Preview what would change with claude-memory diff
• Security audit — Scan all memory files for leaked secrets with claude-memory scan
• Zero infrastructure — Just a private GitHub repo, no servers or databases
• Single dependency — Only requires requests

Install

pip install claude-memory-sync

Quickstart

# 1. Run setup (needs gh CLI authenticated or a GitHub token)
claude-memory setup

# 2. Push your local memory to GitHub
claude-memory push

# 3. Pull memory on another machine
claude-memory pull

# 4. Bidirectional sync (pull then push)
claude-memory sync

How It Works

Machine A (Windows)                    GitHub (private repo)                Machine B (Mac)
~/.claude/projects/                    projects/home/                       ~/.claude/projects/
  C--Users-ktanm/memory/    push -->     MEMORY.md              pull -->     -Users-phoenix/memory/
    MEMORY.md                <-- pull    patterns.md             push -->      MEMORY.md
    patterns.md                          debugging.md                         patterns.md

1. Push uploads changed memory files to projects/<alias>/ in your GitHub repo
2. Pull downloads remote changes to your local memory directory
3. Aliases map different machine dirnames to the same project (e.g., both point to home)
4. Conflict resolution merges edits from different machines at the section level

Cross-Device Setup

Different machines encode project paths differently. Aliases map these to a shared name so syncing works seamlessly.

# Auto-create aliases from matching project names
claude-memory alias auto

# Or manually add an alias
claude-memory alias add home --dirname C--Users-ktanm

# See what aliases exist
claude-memory alias list

# Sync aliases to/from remote
claude-memory alias sync

When you run claude-memory setup on a new device, the setup wizard will automatically discover remote projects and let you map them to local ones.

Migrating Existing Data

If you already pushed data under a raw dirname and want to consolidate under an alias:

claude-memory alias migrate --dirname C--Users-ktanm --alias home

Auto-Sync with Claude Code Hooks

Install hooks so memory syncs automatically when Claude Code sessions start and stop:

# Install hooks into ~/.claude/settings.json
claude-memory hooks install

# Remove hooks
claude-memory hooks remove

Security

claude-memory-sync takes security seriously:

• Secret scanning — Before every push, files are scanned for GitHub tokens (ghp_, gho_), API keys (sk-), AWS keys (AKIA), and private keys. Pushes are blocked if secrets are detected.
• Audit command — Run claude-memory scan to check all memory files for leaked secrets.
• Public repo warning — Setup wizard warns if your target repo is public.
• Path traversal prevention — Alias/dirname names are validated to prevent directory traversal attacks.
• Token privacy — Token values are never printed; only the source is shown (e.g., "gh auth token (CLI)").

Commands

All sync commands support --dry-run, --project <alias>, and --verbose flags.

Configuration

Config is stored at ~/.claude-memory-sync/config.json:

• device_name: Identifier for this machine
• github_repo: GitHub repo in owner/repo format
• conflict_strategy: How to handle conflicts (merge, latest-wins, or ask)

GitHub token is resolved from (in order):

1. CLAUDE_MEMORY_SYNC_TOKEN env var
2. GH_TOKEN env var
3. gh auth token CLI

FAQ

Q: Do I need a GitHub account? A: Yes. The tool stores memory files in a private GitHub repo using the GitHub Contents API.

Q: Is my data private? A: Yes, if you use a private repo (recommended). The setup wizard warns you if the repo is public.

Q: What happens if I edit memory on two machines? A: The default merge strategy combines edits at the section level. Bullets are deduplicated. You can also set conflict_strategy to latest-wins or ask.

Q: Does this sync settings.json or CLAUDE.md? A: Currently, it syncs only ~/.claude/projects/*/memory/*.md files. Full config sync is planned.

Q: Does it work with Claude Code Teams? A: It works with any Claude Code installation that uses the standard ~/.claude/projects/ directory structure.

License

MIT