memory-guardian

Memory Guardian

You are running a memory protection system. This skill has two jobs:

1. Auto-Save - Every ~30 minutes of active conversation, save the current state to persistent files
2. Passphrase Canary - Every ~10 minutes, silently verify you still have full context fidelity

Both mechanisms work by piggybacking on your normal response processing. You don't have real timers, so you track elapsed time by checking timestamps.

---

Setup (do this ONCE at session start)

Step 1: Find the memory system

Look for these files in the user's workspace. They're typically organized like this:

• system-memory/MEMORY.md - Living context document (current state, decisions, calibration)
• system-memory/SESSION_LOG.md - Append-only history
• orient.md - Quick-start guide with file map and pipeline numbers (usually at project root, NOT in system/)

If you can't find them at these paths, search with glob for **/MEMORY.md, **/SESSION_LOG.md, and **/orient.md. They may be in different locations depending on the project structure. If they don't exist at all, offer to create them. The memory system needs somewhere to write.

Step 2: Load the passphrase

Read the passphrase file:

<project-root>/system-memory/.passphrase

If it doesn't exist, generate one and save it. The passphrase should be:

• 6-8 words long
• Mix of concrete nouns, a number, and a color
• Semantically unrelated words (not a sentence)
• Example: telescope 47 crimson walnut frequency jade orbit

Why these properties matter: a passphrase that's too simple ("hello world") will be recallable even with severe degradation - it won't catch anything. A passphrase that's too complex will fail checks even with healthy context. The sweet spot is a string that's easy to hold in full context but impossible to reconstruct if context has actually compressed away from it.

Store the passphrase in your working memory. You'll need it for integrity checks.

Step 3: Record session start

Note the current time using bash (date +%s). Store this as your session start timestamp. Also note it as your "last save" and "last check" timestamps.

Step 4: Confirm to the user

Tell them briefly: "Memory guardian is active. I'll auto-save every 30 minutes and run silent integrity checks every 10 minutes. If I detect context degradation, I'll pause and reload from files."

---

Auto-Save Protocol (every ~30 minutes)

When to trigger

At the START of processing each user message, check elapsed time:

date +%s

Compare against your last save timestamp. If 30+ minutes have passed, run the save before responding to the user's actual request.

If you can't remember your last save timestamp, that itself is a degradation signal - do an immediate save.

What to save

Run this checklist. Not every item will apply every time - only update what's changed.

1. MEMORY.md (replace, don't append) Update these sections with current state:

• Pipeline numbers (counts by verdict, outreach status)
• Active decisions and open questions
• Any new calibration notes from scoring done this session
• Any new candidate-specific context
• Any new technical gotchas discovered
• Last refreshed timestamp

2. SESSION_LOG.md (append only) Add a mid-session checkpoint entry:

### Session N - Checkpoint [timestamp]
- What's happened since last save: [brief summary]
- Key decisions made: [list]
- Files modified: [list]

3. orient.md (update if numbers changed) Only touch this if pipeline numbers, file locations, or priorities have changed.

4. Spreadsheet state (verify, don't modify) If you've been editing a spreadsheet, read it back to verify your changes persisted. Report any discrepancies.

After saving

Update your "last save" timestamp. Tell the user briefly: "Context saved." Then continue with their actual request.

Emergency save

If at any point you sense your context is getting long or you've been going for a while without a save, do one proactively. Don't wait for the 30-minute mark. Signals that you should save early:

• You're about to do something that will generate a lot of output
• The conversation has covered many different topics
• You had to re-read a file you previously read in this session
• The user mentions "don't forget" or "make sure you remember"

---

Passphrase Integrity Check (every ~10 minutes)

How it works

This is a silent, internal check. The user should not see it in your response.

At the start of processing each user message, check elapsed time against your "last check" timestamp. If 10+ minutes have passed:

1. In your internal reasoning, attempt to recall the full passphrase
2. Compare it against what you loaded at session start
3. Update your "last check" timestamp

Interpreting results

Full match - Context is healthy. Continue normally.

Partial match (1-2 words wrong or missing) - Early degradation detected. Take these steps:

1. Re-read the passphrase file to refresh it
2. Re-read MEMORY.md to refresh your context
3. Do an immediate auto-save of everything you currently know (before more degrades)
4. Tell the user: "I noticed some context drift. I've refreshed from my memory files and saved current state. We're good to continue."

Major mismatch (3+ words wrong) or can't recall at all - Severe degradation. Take these steps:

1. STOP what you're doing
2. Tell the user: "I'm experiencing significant context degradation. Let me reload everything."
3. Re-read ALL memory files: MEMORY.md, SESSION_LOG.md, orient.md
4. Re-read the passphrase file
5. Re-read any project-specific files referenced in MEMORY.md
6. Do a full auto-save
7. Summarize to the user what you still know and what might need re-establishing

Why this works

Context degradation in long conversations is gradual. The passphrase acts as a canary in a coal mine - it's arbitrary information with no semantic connections to the rest of the conversation, so it's among the first things to degrade when the context window compresses. By the time you forget project-critical details, you've already lost the passphrase. Checking the passphrase lets you catch degradation before it affects your actual work.

---

Interaction with Scheduled Tasks

This skill handles WITHIN-session memory protection. If the project also has a scheduled task for BETWEEN-session memory refresh (e.g., a daily cron that updates MEMORY.md), that's complementary - not redundant. The scheduled task catches drift when no session is active. This skill catches drift during active work.

If you find a scheduled task already exists (check with list_scheduled_tasks), note it in your setup confirmation so the user knows both layers are active.

---

Configuration

These defaults work well for most sessions. The user can adjust them.

Setting	Default	Adjust when...
Save interval	30 min	Shorter (15 min) for very complex sessions with many file edits
Check interval	10 min	Shorter (5 min) if the user is worried about degradation
Passphrase length	6-8 words	Longer (10 words) for extra-long sessions where you want earlier detection

---

Recovery Procedures

If you can't find the memory files

The user may have restructured or renamed things. Search for MEMORY.md, SESSION_LOG.md, and orient.md using glob. If they don't exist at all, create them from what you currently know - even partial context saved is better than none.

If the memory files seem outdated

Check the "Last refreshed" timestamp in MEMORY.md. If it's old, the scheduled task may have stopped running. Update the files yourself and flag it to the user.

If you're in a new session after compaction

Read orient.md first (it's the quick start), then MEMORY.md (current state), then SESSION_LOG.md (history). The passphrase file should still be on disk - load it fresh. Run setup as if starting a new session.

---

What NOT to do

• Don't save after every single user message. That's too noisy and slows the conversation.
• Don't show the passphrase to the user or include it in your visible responses. It's an internal diagnostic tool.
• Don't skip saves because "nothing important changed." The point of regular saves is that you might not realize something important happened until after it's lost.
• Don't treat this as optional once it's active. If the skill is loaded, the guardian runs until the session ends.