Mem sync

mem-sync — Cross-Device Memory Sync (DEPRECATED)

[!NOTE] mem-sync is deprecated. Project short-term memory has been migrated out of Git repositories to central device-local storage under ~/.agents/memories/projects/<proj-slug>/. Git-based memory synchronization commands are no longer required.

Per-User Branch

The sync branch is derived from git config user.email: the part before @, lowercased and slugified (non-alphanumeric runs become -). [email protected] → memories/user. Each user pushes/pulls only their own branch, so two developers on the same repo never collide on same-date log filenames.

Windows

On Windows, run this skill's script through Git Bash (Git for Windows). A PATH guard at the top of the script prepends the MSYS usr/bin so find/tar are not shadowed by the native same-name tools; if a required POSIX tool is still missing, the script aborts with an explicit error naming the missing tool.

Commands

Discover the script path dynamically (do NOT hardcode):

1. Global scope: ~/.agents/skills/mem-sync/scripts/mem-sync-git.sh
2. Project scope: <repo>/skills/mem-sync/scripts/mem-sync-git.sh
3. Fallback: search for mem-sync-git.sh.

• mem-sync-git.sh pull — record local WIP, fetch+rebase remote, copy back. Run at session start.
• mem-sync-git.sh push — same merge, then push. Run at session end or after promoting candidates.
• mem-sync-git.sh (no argument) — defaults to status.
• mem-sync-git.sh status — read-only: print the resolved remote/branch header, then summarize how local .memories/ differs (in sync, or local-only / remote-only / modified files).
• mem-sync-git.sh diff — read-only: like status but prints the full unified diff (local vs remote).
• mem-sync-git.sh print-branch — print the derived per-user branch and exit (machine-readable, used by tooling/tests).
• mem-sync-git.sh print-remote — resolve and print just the sync remote (env → auto-detect) and exit (machine-readable). status already shows this; use print-remote when a script needs the bare value. Exits non-zero with guidance if the remote is ambiguous.

See references/git-sync-workflow.md for mechanics, anti-pollution rules, and conflict handling.

Avoid a Race with pull

pull, push, and compact mutate .memories/ — treat them as a critical section. Do not read .memories/ in parallel with those commands.

pull briefly removes and recreates the local .memories/ directory while copying the synchronized snapshot back from the isolated worktree. A read racing against that window — grep, Select-String, Get-Content, cat, or similar — can observe the transient missing-directory state and report a false error. Wait for the sync command to finish successfully before scanning handoffs, candidates, or daily logs.

Remote resolution

The sync remote is resolved in this order:

1. MEM_SYNC_REMOTE env var — explicit one-off override; highest priority, never persisted.
2. Auto-detect from the repo's own push configuration (not by remote name):
   • the current branch's push target resolved by Git itself (git for-each-ref --format='%(push:remotename)': branch.<name>.pushRemote → remote.pushDefault → tracking remote) → use that remote, so memory follows wherever the repo actually pushes (e.g. a fork's writable remote), regardless of the name origin;
   • no push target configured but exactly one remote exists → use it;
   • no push target and multiple remotes → ambiguous: the command lists the remotes and exits non-zero. Give the current branch a push target (git push -u <remote> <branch>) or rerun with MEM_SYNC_REMOTE=<name>, then retry.

The remote is recomputed from live Git config on every run, so retargeting your push remote is picked up automatically — there is no stored memory-sync remote to go stale. The per-user branch name (memories/<email-localpart>) is unaffected by the remote choice.

If a command reports an ambiguous remote set, relay the printed remote list to the user and ask which remote to use, then set a push target (or MEM_SYNC_REMOTE=<name>) before retrying.

Anti-Pollution

Never commit .memories/ to an ordinary development branch. If the user asks to "commit memory" or "sync daily notes to Git", intercept and route through this syncer.