claude-memory-sync 0.3.0
Sync Claude Code memory files across machines via GitHub
License: MIT
Requires Python: >=3.9

# claude-memory-sync

[![PyPI version](https://img.shields.io/pypi/v/claude-memory-sync)](https://pypi.org/project/claude-memory-sync/)
[![Python](https://img.shields.io/pypi/pyversions/claude-memory-sync)](https://pypi.org/project/claude-memory-sync/)
[![Tests](https://github.com/TanmayKallakuri/claude-memory-sync/actions/workflows/test.yml/badge.svg)](https://github.com/TanmayKallakuri/claude-memory-sync/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**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

```bash
pip install claude-memory-sync
```

## Quickstart

```bash
# 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.

```bash
# 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:

```bash
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:

```bash
# 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

| Command | Description |
|---------|-------------|
| `setup` | Interactive setup wizard |
| `push` | Upload local memory to GitHub |
| `pull` | Download memory from GitHub |
| `sync` | Bidirectional sync (pull then push) |
| `diff` | Preview differences between local and remote |
| `scan` | Audit memory files for secrets |
| `alias` | Manage project aliases (add, remove, list, suggest, auto, sync, migrate) |
| `hooks` | Install/remove Claude Code auto-sync hooks |
| `status` | Show configuration and sync state |
| `doctor` | Diagnose configuration issues |

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