memory-update— agent skill

Scan session history, surface save-worthy moments, propose → confirm → write. Never fabricate — every proposal must cite a transcript turn.

Scope

Creates or revises memory files in the agent's memory directory. Does not delete, merge-stale, or audit existing files (that is memory-clean). Does not redact or sanitize (that is memory-sanitize).

Path resolution

SKILL_SCRIPTS="${MEMORY_UPDATE_SKILL_SCRIPTS:-$HOME/.claude/claude/skills/memory-update/scripts}"
MEMORY_DIR=$("$SKILL_SCRIPTS/resolve-paths.sh" memory_dir)
SESSION_HISTORY_GLOB=$("$SKILL_SCRIPTS/resolve-paths.sh" session_history_glob)

Abort on non-zero exit. Override MEMORY_UPDATE_SKILL_SCRIPTS if installed outside $HOME/.claude. Override MEMORY_DIR / SESSION_HISTORY_GLOB env vars to target a non-Claude-Code agent's layout.

Memory types and required sections

Read references/MEMORY-FRONTMATTER.md for the full schema. Key rules:

Filename: <type>_<slug>.md. Slug: lowercase, hyphens only, ≤ 40 chars.

Workflow

1. Resolve paths (above)

2. Scan session history for proposals

Run scripts/scan-session.sh "$SESSION_HISTORY_GLOB" → JSON array:

[{ "type": "feedback", "slug": "prefer-foo", "evidence_turn_ids": ["uuid-123"],
   "draft_body": "...", "draft_index_entry": "- [Title](file.md) — hook" }, ...]

Read references/SIGNAL-HEURISTICS.md to understand which turns qualify. If the user triggered the skill with an explicit instruction ("remember that X"), synthesize a proposal from that instruction directly instead of scanning.

3. Present proposals and wait for confirmation

Render each proposal as:

Proposal N — type: feedback
Evidence: turn uuid-123 ("the user said 'stop doing X'")
Draft:
  ---
  name: …
  description: …
  type: feedback
  ---
  Rule text. **Why:** … **How to apply:** …
Index entry: - [Title](file.md) — hook (N chars)

Accept / Reject / Edit?

Wait for explicit user response per proposal. Never write without confirmation.

4. Check for near-duplicates before writing

rg -l -F "<key phrase from draft>" "$MEMORY_DIR"

rg works on any directory regardless of git worktree boundaries. If a hit exists, show the existing file's content and ask whether to merge into it or create new.

5. Write

• Write "$MEMORY_DIR/<type>_<slug>.md" with frontmatter + body.
• Append (or update) one-line entry in "$MEMORY_DIR/MEMORY.md" (≤ 150 chars).

6. Verify

Read back each written file; confirm frontmatter parses as YAML (key: value lines present, no tab-indentation errors). Report which files were written and their line counts.

Anti-patterns (never do)

• Fabricate a memory without citing a transcript turn or explicit user statement.
• Write without per-proposal user confirmation.
• Store code patterns, fix recipes, git history, or ephemeral task state.
• Create MEMORY.md entries exceeding 150 chars.