/memex-sync

name: memex-sync
description: Sync Zettelkasten cards across devices via git.
whenToUse: When the user asks to sync, backup, or share their memory cards across devices. Handles git-based push/pull and initial setup of sync remotes.

Memory Sync

Sync your Zettelkasten cards across devices using git.

Tools Available

• `memex sync --init <url>` — initialize sync with a git remote
• `memex sync --init` — auto-create a private GitHub repo via `gh` CLI
• `memex sync` — pull remote changes, commit local changes, push
• `memex sync --status` — show sync configuration and last sync time
• `memex sync on|off` — enable/disable auto-sync after every write/archive

Process

digraph sync {
    "User invokes /memex-sync" -> "memex sync --status";
    "memex sync --status" -> "Configured?" [shape=diamond];
    "Configured?" -> "memex sync" [label="yes"];
    "Configured?" -> "Ask user for repo URL" [label="no"];
    "Ask user for repo URL" -> "User provides URL?" [shape=diamond];
    "User provides URL?" -> "memex sync --init <url>" [label="yes"];
    "User provides URL?" -> "memex sync --init (auto-create via gh)" [label="no, use gh"];
    "memex sync --init <url>" -> "Report success";
    "memex sync --init (auto-create via gh)" -> "Report success";
    "memex sync" -> "Report result";
}

Step 1: Check status

Run `memex sync --status` to see if sync is already configured.

Step 2: Initialize (if needed)

If sync is not configured: 1. Ask the user if they have a git repo URL for their cards 2. If yes: `memex sync --init <url>` 3. If no: `memex sync --init` (auto-creates a private `memex-cards` repo on GitHub via `gh` CLI)

Step 3: Sync

If already configured, run `memex sync` to push and pull changes.

Step 4: Report

Tell the user the result. If sync failed, show the error message.

Rules

• **Never force-push** — `memex sync` uses `git fetch` + `git merge` then `git push`
• **On conflict** — report the error and tell the user to resolve manually in `~/.memex`
• **Auto-sync** — only suggest `memex sync on` if the user asks about it; don't enable by default