Git Memory Sync

Use this skill to safely synchronize WorkBuddy memory files with a user-provided Git remote. The remote can be Gitee, GitHub, GitLab, self-hosted Git, or any standard Git URL.

Script: scripts/git_memory_sync.py

Core rule

Never back up the whole ~/.workbuddy directory. Only use the script's whitelist:

• ~/.workbuddy/MEMORY.md
• ~/.workbuddy/USER.md
• ~/.workbuddy/IDENTITY.md
• ~/.workbuddy/SOUL.md
• ~/.workbuddy/memory/**
• optional workspace memory: <workspace-root>/*/.workbuddy/memory/**

The script excludes databases, logs, sessions, traces, token/key-looking files, connector config, settings, plugin state, and .git directories.

First-time setup

If no config exists, ask for or infer:

• Remote Git URL, for example git@gitee.com:user/repo.git, https://github.com/user/repo.git, or a GitLab URL
• Local backup repo path, default ~/workbuddy-memory-backup
• Branch, optional; leave blank to auto-detect current branch after clone/init
• Whether to include workspace memory
• Workspace root path if workspace memory is needed

Save config:

python3 scripts/git_memory_sync.py configure \
  --repo-url <remote-git-url> \
  --repo-dir ~/workbuddy-memory-backup \
  --branch main

With workspace memory:

python3 scripts/git_memory_sync.py configure \
  --repo-url <remote-git-url> \
  --repo-dir ~/workbuddy-memory-backup \
  --branch main \
  --workspace-root ~/WorkBuddy \
  --include-workspace-by-default

Config is saved to:

~/.workbuddy/git-memory-sync.json

Commands

Prefer the available managed Python runtime when the environment provides one; otherwise use python3.

Health check

Run when context is unclear:

python3 scripts/git_memory_sync.py doctor

Status

python3 scripts/git_memory_sync.py status

Initialize or clone local repo

If the local repo already exists, this verifies it and creates backup subfolders:

python3 scripts/git_memory_sync.py init

If the local repo is missing and the user agrees to clone:

python3 scripts/git_memory_sync.py init --allow-clone

Backup

Commit backup locally without pushing:

python3 scripts/git_memory_sync.py backup

Pull, commit, and push:

python3 scripts/git_memory_sync.py backup --pull --push

Include workspace memory only when requested or configured:

python3 scripts/git_memory_sync.py backup --include-workspace --workspace-root ~/WorkBuddy --push

Restore

Restore is dry-run by default. It prints all source and destination paths and refuses to write unless --yes is passed.

Dry-run first:

python3 scripts/git_memory_sync.py restore --pull --include-workspace --workspace-root ~/WorkBuddy

Actual restore after explicit confirmation:

python3 scripts/git_memory_sync.py restore --pull --include-workspace --workspace-root ~/WorkBuddy --yes

Before actual restore, tell the user it will overwrite local memory files. The script creates a pre-restore snapshot under:

~/.workbuddy/backups/pre-memory-restore-YYYYMMDD-HHMMSS

Parameter precedence

Command-line flags override config file values. Config file values override safe defaults.

Safe defaults:

• repo_dir: ~/workbuddy-memory-backup
• repo_url: none; required before clone/push workflows
• branch: auto-detect current branch from local repo
• include_workspace_by_default: false
• workspace_roots: empty

Safety rules

• Treat restore as destructive because it overwrites memory files. Do a dry-run first unless the user already provided explicit confirmation in the same turn.
• Never use rm -rf or broad shell deletion on ~/.workbuddy, Desktop, Downloads, Documents, Home, or WorkBuddy project directories.
• Never add the whole ~/.workbuddy folder to Git.
• Never store Git credentials, tokens, passwords, SSH keys, or connector configs in the skill or backup repo.
• If git push or git pull fails for authentication, report the failure and ask the user to configure Git credentials locally. Do not retry with guessed credentials.
• If the backup repo has unexpected uncommitted manual changes, inspect status before proceeding.
• For restore, only write to ~/.workbuddy and explicitly configured workspace roots.

Typical response

After a successful backup, summarize:

• Whether it committed and pushed
• Number of files in manifest.json
• Repo path, remote, and branch
• Whether workspace memory was included
• Any warning, such as no changes or Git authentication failure