hmem-wipe

name	hmem-wipe
description	Prep for /clear: save high-value knowledge and update project Next Steps, then prompt the user to clear. Use on /wipe, 'clear/wipe context', 'context is full', or 'start fresh'. Not for deleting hmem entries, clearing terminal output, or cleaning up nodes.

Wipe — Prepare & Clear Context

Follow these steps in order.

Step 0: Abort if repos touched this session have uncommitted changes

Hard gate — must complete before any other step. Wiping context with unfinished local work risks losing track of why those changes exist. The post-clear session has no memory of the chat that produced them.

Scope this check to only the repos the session actually touched — not every repo on the machine. Unrelated work on other projects is not your concern here.

1. Look back over this session's tool history and identify every file path you've modified (Edit, Write, NotebookEdit, or any Bash commands that wrote to a tracked file). If no files were modified at all, skip Step 0 entirely and proceed to Step 1.

2. For each unique path, resolve its git repo root:

   git -C <path> rev-parse --show-toplevel 2>/dev/null
   

   Dedupe to a set of repo roots. Drop any path that isn't inside a repo.

3. For each repo root, check status:

   git -C <repo-root> status --porcelain
   

4. If any repo has non-empty status output:

   • Do not proceed to Step 1 or beyond. Do not tell the user to /clear.
   • Print the dirty file list per repo so the user sees exactly what's at risk.
   • Reply with:

     Wipe aborted — uncommitted changes in repo(s) you worked on this session. Commit, stash, or discard the listed files first, then re-run /wipe. (If the changes are intentional WIP you want to keep across the wipe, stash them with a clear message: git stash push -m "WIP: <what + why>".)

   • End the skill.

Only proceed to Step 1 when every session-touched repo is clean.

Why session-scoped, not whole-machine: other repos may have intentional WIP unrelated to this conversation — those aren't your responsibility to gate on. The risk this guard prevents is losing the why behind changes you just helped make.

Step 1: Optionally save high-value knowledge

Check checkpointMode in hmem.config.json to decide what to do:

checkpointMode: "auto"

The Haiku subagent already extracts L/D/E entries every 20 exchanges automatically. Skip manual writes unless you have specific high-value knowledge that:

• Was discovered in the last few exchanges (too recent for the last auto-checkpoint)
• Is critical enough that losing it would cost significant rework
• Is NOT already covered by a recent auto-checkpoint

If nothing qualifies, proceed directly to Step 2.

checkpointMode: "remind"

Manually save unsaved insights from this project context:

• New lessons learned: write_memory(prefix="L", ...)
• Project progress: append_memory(id="P00XX.7", ...) (Protocol node)
• Decisions made: write_memory(prefix="D", ...)
• Errors encountered: write_memory(prefix="E", ...)

Skip if the last checkpoint was fewer than 5 messages ago.

Why gate on checkpointMode?

Redundant writes waste tokens and create duplicates that clutter memory. Auto-checkpoints already call read_memory to deduplicate before writing — manual writes during wipe bypass that check and risk creating noise.

Step 2: Update Next Steps

Before clearing context, ensure the active project's "Next Steps" section is up to date. This is critical for session handoff — after /clear, the next session (or restored context) needs to know what to work on next.

1. Find the "Next Steps" section: read_memory(id="P00XX") at depth 2 to list L2 children, then identify the "Next Steps" node by title (seq may vary per project).
2. Review current content: read_memory(id="P00XX.N") where N is the Next Steps seq.
3. Update with current priorities: write_memory(id="P00XX.N", content="...") with:
   • What was being worked on
   • What's done vs. still open
   • Immediate next actions for the next session
   • Any blockers or decisions pending
4. Mark completed steps as irrelevant: update_memory(id="P00XX.N.M", irrelevant=true) for each L3 child under Next Steps that has been fully completed. This keeps the section clean for the next session — irrelevant nodes are hidden from load_project output.

Skip if Next Steps is already current (updated within the last few exchanges).

Step 3: Tell the user to /clear

O-entries are auto-logged by the Stop hook — every exchange is already saved to the active project's O-entry. No need to manually create O-entries or call flush_context for conversation history.

Reply with exactly:

Context ready for clear. Type /clear — the SessionStart hook will automatically restore your project context.

Do NOT attempt to run /clear yourself — it is a built-in CLI command only the user can execute.

What happens after /clear

Context is restored automatically by the SessionStart[clear] hook — no agent action needed after /clear. Do NOT call load_project or read_memory during or after this skill; the next session's first UserPromptSubmit hook will trigger the normal hmem-read flow with a verified active project ID.

The hook:

1. Resets the MCP session cache
2. Injects recent conversation exchanges from the project's O-entry transcript
3. Injects the active project briefing (overview expanded)
4. Injects recent O-entry titles + rules

Why this flow works

• O-entries are covered. The Stop hook logs every exchange to the active project's O-entry. Wipe does not need to handle conversation history.
• Checkpoints are covered (auto mode). The Haiku subagent extracts knowledge every 20 exchanges. Wipe only needs to catch the tail end, if anything.
• Context restoration is covered. The SessionStart[clear] hook handles re-injection automatically. The agent just needs the user to type /clear.