hmem-migrate-o

/hmem-migrate-o — O-Entry Migration to Project-Bound Structure

Prerequisite: This skill uses move_nodes and rename_id from the hmem-curate MCP server. Tell the user to activate it via /mcp before proceeding.

This is a one-time migration from the old flat O-entry format to the new 5-level hierarchy where each O-entry is permanently bound to a P-entry (O0048 belongs to P0048).

What Changes

Before (old format):

• New O-entry created per session, loosely linked via links field
• Flat structure: L2 (exchange) -> L4 (user msg) -> L5 (agent msg)
• active flag on O-entries to track current session

After (new format):

• One O-entry per project, ID matches P-entry (O0048 <-> P0048)
• 5-level hierarchy: L2 (session) -> L3 (batch) -> L4 (exchange) -> L5 (user/agent)
• No active flag needed — O is derived from the active P
• P0000/O0000 exist as "Non-Project" catch-all

---

Step 1: Pre-Migration Check

Understand what you're working with before changing anything.

hmem --version   # must be >= 5.3.0

Then use read_memory() to see current O-entries. Check:

• How many O-entries exist?
• Which P-entries are they linked to?
• Are any O-entries already using the new format (have L3 depth=3 nodes)?

If the version is too old, run /hmem-update first.

Step 2: Backup

Create a backup of the hmem database before migrating. This is critical — the migration rewrites entry IDs.

# Find the active hmem file
HMEM_FILE=$(find ~/.hmem -name "*.hmem" -not -path "*/Agents/*" | head -1)
echo "Backing up: $HMEM_FILE"
cp "$HMEM_FILE" "${HMEM_FILE}.pre-migration-backup"

# Also backup agent-specific hmem files
find ~/.hmem/Agents -name "*.hmem" -exec sh -c 'cp "$1" "$1.pre-migration-backup"' _ {} \;

Verify backups exist before continuing.

Step 3: Run Migration

The migration script handles everything:

hmem migrate-o-entries

This will:

1. Create P0000 "Non-Project" and O0000 catch-all if they don't exist
2. For each existing O-entry:
   • Find its linked P-entry via the links JSON field
   • Rename it to match the P-entry's sequence number (e.g., O0042 linked to P0048 becomes O0048)
   • Handle ID conflicts by moving blockers to temporary IDs (O9XXX range)
   • Tag all migrated entries with #legacy
3. Tag unlinked O-entries as #legacy (they'll go to O0000 eventually)
4. Clear all active flags from O-entries