| name | memory-sync |
| description | Proactively sync session learnings to persistent memory files. Auto-invoked after significant work milestones. Keeps memory current without user prompting.
|
| user-invocable | false |
| context | fork |
| allowed-tools | ["Read","Edit","Write","Grep","Glob"] |
| metadata | {"version":"2.0","effort":"low","auto-invocable":true,"category":"workflow","compatible-claude-code":{"when_to_use":"After significant work milestones, connection discoveries, or workflow rule changes","allowed-tools":["Read","Edit","Write","Grep","Glob"],"user-invocable":false,"context":"fork"}} |
Memory Sync Skill
You are syncing session learnings to persistent files that the built-in auto-memory system cannot update: CLAUDE.md files, skill files, and project-local memory/MEMORY.md. This runs in a forked context to avoid bloating the main conversation.
Scope — What This Skill Owns vs Auto-Memory
| Target | Owner | Examples |
|---|
~/.claude/projects/*/memory/*.md | Auto-memory (built-in) | User prefs, feedback, project context, references |
~/.claude/CLAUDE.md | This skill | Global workflow rules, tool prefs |
.claude/CLAUDE.md | This skill | Project-specific safety rules, conventions |
memory/MEMORY.md (project-local) | This skill | Connection methods, architecture, sprint state |
~/.claude/skills/*/SKILL.md | This skill | Pitfalls, patterns, dimensions, changelog |
Do NOT save here (auto-memory handles these):
- User role, preferences, or knowledge level → auto-memory
user type
- Feedback on Claude's approach ("don't do X", "yes, keep doing that") → auto-memory
feedback type
- Pointers to external systems (Linear projects, Grafana boards) → auto-memory
reference type
- One-off project context that doesn't affect file conventions → auto-memory
project type
When to Trigger
Auto-invoke when ANY of these occur during a session:
- A new SSH host, API endpoint, device address, or connection method was used
- A workflow rule was established that should be enforced via CLAUDE.md (not just remembered)
- A project convention was discovered that isn't documented in CLAUDE.md
- A sprint was opened or closed (version state changed)
- A skill was used and a pitfall, correction, or new pattern was confirmed
- A significant debugging session revealed non-obvious gotchas worth codifying
Do NOT trigger for:
- Code patterns, architecture, or file paths derivable from reading the codebase
- Git history or who-changed-what (use
git log/git blame)
- Debugging solutions (the fix is in the code; the commit message has context)
- Ephemeral task state or current conversation context
- Anything the user said to "remember" that fits auto-memory types above
What to Update (priority order)
1. Skill Files (~/.claude/skills/*/SKILL.md or .claude/skills/*/SKILL.md)
Highest value — skills compound. Only update skills that were actually used in the session AND any of these occurred:
- A pitfall/gotcha was discovered (e.g., "OLED shelf creates split-body in slicer")
- A pattern or technique worked well and should be reusable
- The user corrected the skill's output (wrong default, missing step, bad assumption)
- A new tool integration was discovered
- Component dimensions were verified against real hardware
- A workflow step was missing or in the wrong order
Where to add:
- Pitfalls/gotchas →
## Pitfalls or ## Common Pitfalls section
- New patterns → relevant patterns section
- Corrections → fix wrong content in-place
- New dimensions/specs → reference tables
- Workflow changes → process section
- Session learning →
## Changelog at bottom
Changelog format:
## Changelog
- 2026-03-12: Added split-body pitfall for slicer import (OLED shelf was disconnected geometry)
Rules:
- Only add verified learnings (tested and confirmed)
- Keep entries concise — one line per learning
- Don't duplicate content already in the skill body (move it to the right section instead)
2. CLAUDE.md Files
Global (~/.claude/CLAUDE.md) — only rules that apply across ALL projects:
- Workflow corrections the user gave (e.g., "never do X")
- Tool preferences (e.g., "always use py not python")
Project (.claude/CLAUDE.md) — project-specific:
- Safety rules or conventions specific to this project
- Proactive behavior rules (e.g., "before doing X, always check Y")
3. Project Memory (memory/MEMORY.md)
Lowest priority — only for structured project state that doesn't fit CLAUDE.md:
- Connection methods: host, port, user, auth, gotchas
- Current state: version, sprint status
- Architecture patterns: new modules, data flows, integration points
- Gotchas: non-obvious issues that wasted debugging time
Rules
- Read before writing. Always read the target file first to avoid duplicates.
- Merge, don't append. Update existing sections rather than adding new ones when the topic already exists.
- Keep MEMORY.md under 200 lines. It's loaded into every conversation context. Be ruthless about conciseness.
- Never store secrets. No API keys, passwords, or tokens. Store the pattern (e.g., "uses env var FREESOUND_API_KEY") not the value.
- Verify before writing. Don't write speculative or unverified information. If you saw it work, write it.
- Delete stale info. If you notice outdated entries (old versions, removed files, changed patterns), remove them.
- Check auto-memory first. If the learning fits a
user, feedback, project, or reference memory type, let auto-memory handle it. Only use this skill for CLAUDE.md, skill files, and project-local MEMORY.md.
