v1: Migration plan — from hooks to working cross-platform memory

[maxtechera]

Context

The architecture (3-tier HOT/WARM/COLD), protocols (WAL, TTL, boundary rules), and hooks are well-defined. The gap is between what the docs describe and what actually works when someone installs this on a clean machine. v1 closes that gap.

Current State

Component	Status
3-tier architecture (SKILL.md, WORKFLOW.md)	✅ fully specified
7 session hooks (files exist)	⚠️ not auto-installed — require manual setup or /memory setup
/memory setup wizard	⚠️ described in README, implementation completeness unknown
Mode 1–4 sync commands	⚠️ documented, end-to-end untested on clean install
Mode 5 — wiki sync (Notion)	⚠️ in SKILL.md but absent from README — status unclear
OpenClaw sync (Mode 2)	⚠️ pull-based, manual, requires OPENCLAW_CONFIG_PATH
Dream cycle (Mode 4)	⚠️ manual trigger works, cron setup untested
OpenCode platform support	⚠️ documented, untested

v1 Milestone — What "Working" Means

A user installs, runs /memory setup, and from that point forward: session state is automatically captured on start/compact/stop, /memory sync writes to their Obsidian vault, and /memory dream consolidates weekly. No manual hook wiring required.

Work Required

1. Setup wizard (/memory setup)

• Detect Obsidian vault path (app running → CLI auto-detect → fallback to env var prompt)
• Symlink all 7 hooks to ~/.claude/hooks/
• Patch ~/.claude/settings.json to register hooks
• Validate Obsidian CLI version (≥1.12.7)
• Output: clear success/failure per step

2. Session hooks — verify all 7 fire correctly

• session-start-vault.sh — injects vault stats into session context
• pre-compact-vault.sh — flushes SESSION-STATE to vault daily journal
• session-stop-vault.sh — persists state to vault + ~/.claude/compaction-state/
• agent-start.sh / agent-stop.sh — agent counter tracking
• compact-notification.sh — post-compaction vault stats print
• force-mcp-connectors.sh — MCP connector flag

3. Sync modes — end-to-end test

• Mode 1 (/memory sync) — session → topics → vault, dedup working
• Mode 2 (/memory sync openclaw) — OpenClaw journals → Obsidian
• Mode 3 (/memory sync projects) — ~/.claude/projects/ → Obsidian
• Mode 4 (/memory dream) — journal analysis, prune, TTL audit

4. Mode 5 — wiki sync (Notion)

• Decide: implement for v1 or document as v1.1
• If v1: add to README with setup instructions
• If v1.1: remove from SKILL.md triggers or mark as experimental

5. Boundary rules + health checks

• grep -c "NEVER\|ALWAYS\|must\|rule" MEMORY.md returns 0 (boundary test passes)
• Dream health alerts fire correctly (bloated file, missing TTL, boundary violation)

6. Distribution

• End-to-end install test: Claude Code plugin
• End-to-end install test: clawhub install memory
• End-to-end install test: manual git clone + manual hook setup
• OpenCode platform: hooks fire on session lifecycle events

Out of Scope for v1

• Real-time OpenClaw sync (pull-based is fine for v1)
• Multi-vault support
• Automated TTL expiry (manual audit via Dream is sufficient)
• Notion publishing beyond wiki sync

Definition of Done

• /memory setup on a clean Claude Code install wires all 7 hooks with no manual steps
• /memory sync writes a real entry to a real Obsidian vault
• Pre-compact hook fires during a real compaction event and preserves state
• README install instructions match actual behavior
• Mode 5 status documented (in or out of v1 scope)