richfrem Forge Soul Exporter
Status: Active
Author: Sanctuary Guardian
Domain: Obsidian Integration
Depends On: huggingface-utils (hf-config, hf-upload), obsidian-vault-crud (WP06)
Purpose
The Forge Soul Exporter is the final link in the persistence chain. It:
- Checks git state is clean (no uncommitted changes)
- Identifies sealed notes (frontmatter
status: sealed) - Takes a snapshot hash of all source files
- Formats notes into JSONL matching the HF schema (ADR 081)
- Verifies no files changed during export (snapshot isolation)
- Uploads to HuggingFace with exponential backoff
Usage
Full Export (Rebuild soul_traces.jsonl from scratch)
python plugins/obsidian-integration/skills/forge-soul-exporter/scripts/forge_soul.py \
--vault-root <path> --full-sync
Incremental Export (Sealed notes only)
python plugins/obsidian-integration/skills/forge-soul-exporter/scripts/forge_soul.py \
--vault-root <path>
Dry Run (No Upload)
python plugins/obsidian-integration/skills/forge-soul-exporter/scripts/forge_soul.py \
--vault-root <path> --dry-run
Safety Guarantees
- Git Pre-Flight (T041): Refuses to export if uncommitted changes exist
- Snapshot Isolation (T043): Captures file mtimes before export, verifies none changed
- Lossless Frontmatter: Uses
ruamel.yamlfor YAML extraction - Binary Stripping: All image/embed references removed from export payload
- Exponential Backoff: Survives HF API rate limits gracefully