engram-memory

name	engram-memory
description	Trigger: backup memories, restore memories, máquina nueva, respaldar engram, sync memoria, engram-memories. Backup/restore Engram chunks + Claude auto-memory to gonaas/engram-memories. Skip: in-session mem_save/search (use engram MCP).
author	Gonzalo Astudillo
version	1.0.0
date	"2026-06-29T00:00:00.000Z"
user-invocable	true

Engram Memory — Backup & Restore Lifecycle

Manages the portable half of memory: exporting Engram chunks and Claude Code auto-memory to the private backup repo gonaas/engram-memories, and restoring them on a new machine. In-session capture/recall stays with the engram MCP tools (mem_save, mem_search, mem_session_summary) — this skill does NOT replace them.

The Iron Law

NEVER run engram sync --import against a populated DB without confirming. Import merges remote chunks into ~/.engram/engram.db. On a machine that already has memories, confirm with the user first — restore is for fresh machines.

Hard Rules

• Backup repo lives at ~/engram-memories. If absent, clone https://github.com/gonaas/engram-memories first.
• A backup is incomplete until committed AND pushed. Always finish with git push.
• Two independent systems — back up BOTH:
  • .engram/ chunks ← engram sync --all (one global SQLite at ~/.engram/engram.db)
  • claude-memory/<project>/ ← ~/.claude/projects/*/memory/ (NOT covered by engram sync)
• Engram is global; project scope is irrelevant for sync. Never pass --cloud unless asked.

Decision Gates

Intent	Action
"en qué punto / status"	engram sync --status + git -C ~/engram-memories status -sb
"backup / respaldar memoria"	Backup flow ↓
"restore / máquina nueva"	Restore flow ↓ — confirm first if the DB is non-empty

Execution — Backup

engram sync --all                                   # refresh chunks → ~/engram-memories/.engram/
for d in ~/.claude/projects/*/memory; do            # mirror Claude auto-memory
  proj=$(basename "$(dirname "$d")")
  rsync -a --delete --exclude='*.lock' "$d/" ~/engram-memories/claude-memory/"$proj"/
done
cd ~/engram-memories && git add -A && git commit -m "sync memories" && git push
engram sync --status                                # expect: Pending import: 0

Execution — Restore (new machine)

brew tap gentleman-programming/tap && brew install engram
git clone https://github.com/gonaas/engram-memories ~/engram-memories
cd ~/engram-memories && engram sync --import        # confirm first if DB already populated
cp -R claude-memory/* ~/.claude/projects/
engram sync --status                                # expect: Pending import: 0

Output Contract

Report: local chunks, remote chunks, pending import, files changed under claude-memory/, and the pushed commit hash (or "nothing to commit").

References

• ~/engram-memories/README.md — canonical backup/restore commands
• _shared/engram-convention.md — Engram artifact naming