Feature request: auto-restore from latest snapshot on daemon startup

[yingliang-zhang]

Summary

The snapshot system has mem::snapshot-create (write) and mem::snapshot-restore (read) functions, plus REST endpoints POST /agentmemory/snapshot/create and POST /agentmemory/snapshot/restore. Both work correctly when called manually.

However, on daemon startup, no auto-restore is performed. Even if a valid snapshot exists at ~/.agentmemory/snapshots/state.json with git history, the daemon starts with an empty in-memory store. This means:

1. Daemon crashes / gets killed / host reboots
2. launchd/systemd restarts the daemon
3. Daemon starts with 0 memories, 0 sessions, 0 observations
4. All curated facts are gone unless manually restored

This is closely related to #843 (data lost on restart) and #913 (file_based silently degrades to in-memory). The stop-order fix in #849 helps graceful shutdowns, but does not help with crashes, kill -9, or host reboots.

Current workaround

I modified ~/.agentmemory/start.sh to auto-restore after daemon startup:

# After starting agentmemory in background, wait for it to be ready,
# then restore from latest snapshot commit
SNAPSHOT_DIR="$HOME/.agentmemory/snapshots"
COMMIT_HASH=$(git -C "$SNAPSHOT_DIR" rev-parse HEAD 2>/dev/null)

# Retry up to 3 times (daemon may need time to register REST routes)
for attempt in 1 2 3; do
    RESULT=$(curl -sf -X POST http://localhost:3111/agentmemory/snapshot/restore \
        -H "Content-Type: application/json" \
        -d "{\"commitHash\": \"$COMMIT_HASH\"}" 2>/dev/null)
    if [ $? -eq 0 ]; then
        echo "Auto-restore succeeded from $COMMIT_HASH" >> restore.log
        exit 0
    fi
    sleep 3
done

This works reliably (tested with 19 memories, restore succeeds on every restart). But it requires modifying user-owned files outside the npm package.

Suggested approaches (for maintainer discussion)

Option A: Auto-restore in start.sh / CLI bootstrap

After the iii-engine and worker are ready, check if ~/.agentmemory/snapshots/state.json exists and has git commits. If so, call mem::snapshot-restore with the HEAD commit hash.

Considerations:

• Should this be opt-in (env var) or default behavior?
• Should it only restore when the store is empty (to avoid overwriting new data)?
• The REST API takes ~5-10s to be ready after the iii-engine starts, so the restore needs a retry loop or health-check gate.

Option B: Auto-restore in the worker initialization (src/index.ts)

After registerSnapshotFunction and before the boot log, if snapshotConfig.enabled and a snapshot exists, call sdk.trigger({function_id: "mem::snapshot-restore", payload: {commitHash: HEAD}}).

This is cleaner (no external script) but needs to handle:

• Empty snapshot dir (first run)
• Version mismatch between snapshot and current schema
• Whether to always restore or only when store is empty

Environment

• agentmemory v0.9.27 (npm global)
• iii engine v0.11.2 (native)
• macOS, launchd-managed daemon

Context

Combined with the snapshot interval timer bug (#1006), these two issues mean the snapshot system exists but provides no actual data protection without external tooling. I am happy to submit a PR for either approach if the maintainers indicate which direction they prefer.