| name | Meta Update |
| description | Promote a session's durable cross-project learnings to the shared union store (~/.claude-sync — the MISTAKES.md ledger, LIBRARY.md and its Index in SHARED-MEMORY.md, and the SHARED-MEMORY.md Journal) and to per-project auto-memory. This is the /meta-update ritual. |
| when_to_use | when the user asks to "update memory" / "promote learnings" / runs /meta-update, or at session close or handover when the work produced cross-project learnings, mistakes, or reusable techniques worth persisting for the next agent on any machine. Run AFTER handover. |
| version | 1.0.0 |
Meta-Update (/meta-update)
Durably capture what this session learned so the next agent — any machine, any
project — inherits it. Do it deliberately, not mechanically. If the user named a
focus (e.g. "just the codex trap", "project only"), scope to that; otherwise cover
everything worth keeping.
Announce at start: "Running Meta-Update — promoting this session's learnings to the union store."
Not to be confused with /mu. In current fleet environments /mu aliases
expansion:skill-update (learning from how a skill was used and patching the
skill). This skill is the separate, cross-project memory-promotion ritual that
/meta-update has long referred to. If they run together, order is
/handover → /mu (skill-update) → /meta-update (this).
This skill assumes the union store at ~/.claude-sync/ (SHARED-MEMORY.md,
LIBRARY.md, MISTAKES.md), imported by ~/.claude/CLAUDE.md. If that store isn't
present, tell the user and fall back to editing the relevant project CLAUDE.md /
auto-memory directly.
0. Guard first — the store silently loses edits
SHARED-MEMORY.md is sendreceive across devices and the fleet's highest-centrality
file, so concurrent edits resolve last-writer-wins and park the loser in an unread
conflict copy.
ls ~/.claude-sync/*sync-conflict* 2>/dev/null — if any conflict copy exists,
UNION-merge it into the live file (diff the Index + Journal, keep both sides),
then delete the copy. Never last-writer-wins by hand.- Prefer append-only edits; re-run this check again after writing (step 4).
1. Decide what is worth keeping
Three buckets. Skip anything the repo/git already records, or that only mattered to
this one conversation.
- Cross-project / cross-machine learnings → the union store (step 2).
- Project-specific facts → this project's auto-memory
(
~/.claude/projects/<encoded-cwd>/memory/ + its MEMORY.md index) and/or the
project's CLAUDE.md (step 3).
- Mistakes (yours or ones you caught) → the ledger (step 2).
2. Promote to the union store (~/.claude-sync/)
MISTAKES.md — one tagged line per mistake (format + fixed tag vocabulary live
at the file top; date = when it OCCURRED, not when logged). Escalation rule: when a
tag reaches 3 instances still fixed only by notes, stop writing notes — build the
tool/guard that kills the class, and update those lines' fix-state.LIBRARY.md — append durable, reusable knowledge under the right topic (create
one if none fits). The Library is NOT auto-loaded, so if the topic or sub-point is
new, add a pointer to it in the Index inside SHARED-MEMORY.md — the Index is
the only part loaded into a session, so an unlisted topic is invisible forever.SHARED-MEMORY.md Journal — add ONE entry at the top, directly under the
<!-- newest --> marker:
### [NNNN] YYYY-MM-DD HH:MM TZ · <model-id> · <project> · <device-hostname>
then one dense line, cross-referencing related entries by [NNNN]. NNNN =
previous top index + 1, zero-padded. Never edit another writer's entry (moving a
clearly-misplaced one verbatim to its correct slot is fine). Keep this file lean
(Index + Standing facts + Journal only); archive old Journal entries to
SHARED-MEMORY-archive.md when it grows.
Get date/time/host from the shell, don't guess: date '+%F %H:%M %Z' and hostname.
Tag each promotion with its source project.
3. Project auto-memory
For project-specific facts, write/update one file per fact under this project's memory
directory (one fact per file, with frontmatter), and add/update its one-line pointer
in that directory's MEMORY.md. Update an existing file rather than duplicating;
delete memories that turned out wrong. Link related memories with [[name]].
4. Verify
- Re-run the sync-conflict check (a peer may have written while you did).
- Sanity-check Journal order (newest first) and that any Index pointer you added
resolves to a real
LIBRARY.md topic.
Report concisely what you promoted and where. Do not commit or push anything unless
the user asks.
