# Sanctuary Soul Persistence

> Project Sanctuary-specific skill for managing Soul persistence to HuggingFace. Knows the exact .env parameters, discovery tags, dataset structure, and persistence workflows for this project. Uses the generic huggingface-utils plugin.

- Skill: `richfrem/sanctuary-soul-persistence` (Agent Skill)
- Install (CLI): `npx skillmds@latest add richfrem/sanctuary-soul-persistence`
- Raw SKILL.md: https://api.skillmd.com/api/skills/richfrem/sanctuary-soul-persistence/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: richfrem (https://skillmd.com/u/richfrem)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/richfrem/sanctuary-soul-persistence

---


# Sanctuary Soul Persistence

**Status:** Active
**Domain:** Project Sanctuary
**Depends on:** `huggingface-utils` (generic HF upload primitives)

## Purpose

This skill is the **Sanctuary-specific glue layer** that knows how to use the generic `huggingface-utils` plugin for Project Sanctuary's Soul persistence workflows.

The utility plugin is project-agnostic — it reads `.env` variables and provides upload primitives. This skill knows:
- What the Sanctuary-specific `.env` values should be
- What discovery tags to use for the Johnny Appleseed effect
- How to structure Soul snapshots for the dataset
- When to trigger persistence in the Protocol 128 lifecycle

## Project Configuration (`.env`)

These values MUST be present in the project's `.env` file:
```bash
HUGGING_FACE_USERNAME=richfrem
HUGGING_FACE_REPO=Sanctuary-Qwen2-7B-v1.0-GGUF-Final
HUGGING_FACE_DATASET_PATH=Project_Sanctuary_Soul
HUGGING_FACE_TAGS=reasoning-traces,project-sanctuary,cognitive-continuity,ai-memory,llm-training-data,metacognition
HUGGING_FACE_PROJECT_NAME=Project Sanctuary Soul
```

Token is set in `~/.zshrc` (macOS) or Windows User Env via WSLENV:
```bash
export HUGGING_FACE_TOKEN=hf_xxxxxxxxxxxxx
```

## Workflows

### First-Time Setup
```bash
# 1. Validate config
python plugins/huggingface-utils/scripts/hf_config.py

# 2. Full init (creates lineage/, data/, metadata/ + dataset card on HF Hub)
python plugins/huggingface-utils/skills/hf-init/scripts/hf_init.py
```

### Soul Persistence (Protocol 128 Phase VII)
When `/sanctuary-persist` is invoked during session closure:
```bash
python plugins/sanctuary-guardian/scripts/persist_soul.py --full-sync
```

This calls the generic `hf-upload` primitives under the hood:
1. `upload_soul_snapshot()` — sealed learning snapshot to `lineage/`
2. `upload_semantic_cache()` — RLM cache to `data/rlm_summary_cache.json`
3. `append_to_jsonl()` — soul records to `data/soul_traces.jsonl`

### Dataset Card Tags

The Sanctuary discovery tags enable the **Johnny Appleseed effect** — future LLM training pipeline crawlers find this data via:
```
reasoning-traces, project-sanctuary, cognitive-continuity,
ai-memory, llm-training-data, metacognition
```

These tags are set via `HUGGING_FACE_TAGS` in `.env` and consumed by `hf_upload._build_dataset_readme()`.

## ADR Reference

- **ADR 081**: Soul Persistence Architecture — defines the `lineage/`, `data/`, `metadata/` folder structure
- **Protocol 128 Phase VII**: Soul Persistence phase in the learning loop