Cloud Sync (cmem.ai Pro)
The worker syncs memories itself: every write nudges a background flusher that
drains unsynced rows to cmem.ai. There is no daemon to install or babysit. This
skill is a thin front-end — check status, and on first run collect credentials,
retire the old standalone client, and restart the worker so it picks them up.
Security rule for this entire skill: NEVER print the sync token, never put
it in a command-line argument (argv is visible to other processes), and never
log it. It travels only inside heredoc-fed stdin scripts or files that already
hold it. When confirming, report its length — not its value.
1. Check status
Resolve the worker port (env → ~/.claude-mem/settings.json → per-UID default
37700 + (uid % 100), matching how the worker picks its own port; re-run this
in any fresh shell before the curls in step 5):
PORT="${CLAUDE_MEM_WORKER_PORT:-$(node -e "const fs=require('fs'),p=require('path'),os=require('os');const uid=(typeof process.getuid==='function'?process.getuid():77);const fallback=String(37700+(uid%100));try{const s=JSON.parse(fs.readFileSync(p.join(os.homedir(),'.claude-mem','settings.json'),'utf-8'));process.stdout.write(String(s.CLAUDE_MEM_WORKER_PORT||fallback));}catch{process.stdout.write(fallback);}" 2>/dev/null)}"
curl -s "http://127.0.0.1:${PORT}/api/sync/status"
Responses:
{"configured": true, "deviceId": ..., "pending": {"observations": N, "summaries": N, "prompts": N}, "lastFlushAt": ..., "lastError": ...} → go to step 2.{"configured": false} → go to step 3.- 404 / 503 / connection refused → the route registers late during worker
startup, so a request right after a restart can miss it. Retry every 3s for
~15s before concluding anything. If 404 persists, the running worker predates
cloud sync — restart it with the command in step 5, wait, and retry.
2. Already configured → report and stop
Report the three pending counts, lastFlushAt, and lastError (null means
healthy). Pending counts near 0 mean the cloud copy is current. Done — do not
run the setup steps below.
3. Not configured → obtain credentials
Priority order:
(a) Legacy standalone client present. If ~/.claude-mem/.cloud-sync.env
exists, the user already set up the old standalone sync client. Tell them:
"Found your existing standalone cloud-sync setup — migrating it into the
worker. Your token and device identity carry over; nothing re-uploads." Do NOT
cat the file or print its values. Migrate it with this script (it reads the
file itself, so the token never enters the conversation):
node - <<'EOF'
const fs = require('fs'), os = require('os'), path = require('path');
const dir = path.join(os.homedir(), '.claude-mem');
const env = fs.readFileSync(path.join(dir, '.cloud-sync.env'), 'utf8');
const get = (k) => (env.match(new RegExp('^' + k + '=(.*)$', 'm')) || [])[1]?.trim().replace(/^["']|["']$/g, '') || '';
const token = get('CMEM_SYNC_TOKEN'), userId = get('CMEM_USER_ID');
if (!token || !userId) { console.error('legacy env file is missing CMEM_SYNC_TOKEN or CMEM_USER_ID'); process.exit(1); }
const file = path.join(dir, 'settings.json');
const settings = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
settings.CLAUDE_MEM_CLOUD_SYNC_TOKEN = token;
settings.CLAUDE_MEM_CLOUD_SYNC_USER_ID = userId;
fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
fs.chmodSync(file, 0o600);
console.log(`migrated: token length ${token.length}, user id length ${userId.length}`);
EOF
(b) No legacy file. Use AskUserQuestion to ask the user to paste two
values from cmem.ai → Connect: their sync token and their user id. Then
write them with the same merge script, embedding the two values as string
literals inside the quoted heredoc (heredoc body is stdin, not argv — the
token stays off the command line; do not echo it back afterward):
node - <<'EOF'
const fs = require('fs'), os = require('os'), path = require('path');
const token = 'PASTE_TOKEN_HERE';
const userId = 'PASTE_USER_ID_HERE';
const file = path.join(os.homedir(), '.claude-mem', 'settings.json');
const settings = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
settings.CLAUDE_MEM_CLOUD_SYNC_TOKEN = token;
settings.CLAUDE_MEM_CLOUD_SYNC_USER_ID = userId;
fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
fs.chmodSync(file, 0o600);
console.log(`saved: token length ${token.length}, user id length ${userId.length}`);
EOF
Merge rules (both paths, non-negotiable): parse the existing JSON and merge
the two keys in — never clobber other settings, never rewrite the file from a
template, and restore file mode 0600 after writing (both scripts above do
this).
4. Retire the legacy daemon
The standalone client is superseded by worker-native sync. If it is still
running it would double-upload, so shut it down and archive its artifacts:
D="$HOME/.claude-mem"
if [ -f "$D/cloud-sync.pid" ]; then
LEGACY_PID=$(cat "$D/cloud-sync.pid")
if [ -n "$LEGACY_PID" ] && ps -p "$LEGACY_PID" -o command= 2>/dev/null | grep -q cloud-sync; then
kill "$LEGACY_PID"
fi
fi
for f in cloud-sync.mjs .cloud-sync.env cloud-sync.pid; do
[ -f "$D/$f" ] && mv "$D/$f" "$D/$f.retired"
done
ls "$D" | grep retired
Leave ~/.claude-mem/cloud-sync-state.json exactly where it is. The
worker's migration stamps already-synced rows from its cursors and adopts its
device id — renaming or deleting it forks every cloud row into a duplicate.
5. Restart the worker and watch it drain
The worker reads credentials at startup, so restart it:
curl -s -X POST "http://127.0.0.1:${PORT}/api/admin/restart"
The old worker spawns its own successor once its port closes — do not spawn or
kill anything yourself; the POST is the entire restart. Then poll:
curl -s "http://127.0.0.1:${PORT}/api/sync/status"
every ~5s. Tolerate connection-refused/404 for the first ~30s (successor
booting, route registering late). Expect configured: true with the pending
counts falling as the flusher drains. Stop polling when either:
- all three pending counts reach 0, or
- the counts stop changing across 3 consecutive polls with
lastError null —
a large first backfill flushes in batches and can take minutes; report the
current counts and note the worker keeps draining in the background.
If lastError is non-null and pending is not moving, report the error text
verbatim (it never contains the token) and suggest re-checking the token and
user id against cmem.ai → Connect.
6. Report
- Status check (already configured): pending counts, last flush time,
last error.
- First-time setup: device id from the status response, what the counts
drained to, whether a legacy client was migrated/retired, and this one-line
privacy note:
Cloud sync uploads your observation narratives and full prompt text to your
cmem.ai account.