Session Memory Architecture — Production Context Persistence

Every session restart is a memory wipe. Your agent does not know what it decided yesterday, what it shipped last week, or what you explicitly told it to remember. This SKILL.md is the architecture that fixes that permanently.

---

⚡ What's Inside

• Dual memory system Rolling daily logs at memory/YYYY-MM-DD.md capture raw session events; a long-term vector store holds the curated, semantically retrievable knowledge that persists across weeks and months

• Extraction agent protocol Forked agent pattern for zero re-context cost. The extraction agent runs at end-of-cycle, reads the session, produces a structured memory entry, and upserts to the vector store without consuming the main agent's budget

• Cache-sharing architecture How forked agents share context without duplicating it, and the UUID cursor integrity check that prevents double-extraction and memory contamination

• Trigger conditions Exactly when extraction fires versus when it is skipped. End-of-cycle only. Not heartbeat. Not mid-task. The timing is not arbitrary — it is the difference between clean extraction and partial garbage

• Drain protocol The 60-second shutdown wait that lets in-flight extractions complete before the session closes, preserving everything instead of losing the last task

---

🏭 Proven in Production

This architecture ran across months of daily agent operation — the same agent, waking up each session with accurate context from prior sessions without a single manual note from the user.

---

🆕 What's New in v1.1

• Supabase pgvector integration notes added
• Incremental cursor pattern documented for large compaction backlogs

---

✅ Core Capabilities

• ✅ Dual memory system — daily rolling logs + long-term vector store
• ✅ Forked extraction agent — zero re-context cost, runs at end-of-cycle
• ✅ UUID cursor integrity — prevents double-extraction and memory contamination
• ✅ Cache-sharing pattern — forked agents share context without duplicating it
• ✅ Drain protocol — 60s graceful shutdown, nothing lost on session close
• ✅ Trigger spec — extraction fires at end-of-cycle, never mid-task