Self-Sanitation

PiSovereign’s Automated Self-Sanitation phase runs during every dream cycle, positioned between NREM (consolidation) and REM (creative synthesis). It autonomously detects and repairs degradation across six subsystems without manual intervention.

Architecture

Dream Cycle Flow
────────────────
  NREM (consolidation)
    ↓
  SANITATION (this feature)
    ↓
  REM (creative synthesis)

The sanitation phase takes a snapshot of system state before any changes. If a critical failure occurs during processing, the service performs an automatic rollback to the snapshot, ensuring that a failed sanitation run never leaves the system in a worse state.

Six Subsystems

1. Memory Hygiene

Scans all active memories in configurable batch sizes, sending each batch to the LLM for verdict classification:

Verdict	Action
`ok`	No action
`stale`	Quarantined with reason
`poisoned`	Quarantined immediately
`contradicted`	Losing memory quarantined, winner kept

Quarantined memories receive a MemoryType::Quarantined classification and are automatically purged after the configured TTL (default: 7 days).

2. Knowledge Graph Integrity

Detects orphan nodes (no incoming or outgoing edges)
Detects dangling edges (source or target node missing)
Counts total structural issues

3. Adversarial Defense Evolution

When integrated with the red-team service, analyzes recent red-team results (bypasses) and:

Extracts attack patterns from successful bypass payloads
Generates DynamicDefensePattern entries with normalized regex patterns
Deduplicates against existing active patterns via hash-based lookup

4. Config Drift Correction

Compares current SanitationConfig parameters against observed system behavior and adjusts within safe bounds:

quarantine_ttl_days: floor 1, ceiling 30
memory_batch_size: floor 5, ceiling 50

Adjustments are logged via the event bus.

5. Quality Regression Detection

Computes a composite quality score from three weighted signals:

score = 1.0 - (re_ask_rate × W_re_ask + correction_rate × W_correction + abandonment_rate × W_abandon)

Compares against the previous sanitation result. Score drops trigger QualityRegression domain events. The quality trend is classified as Improving, Stable, or Degrading.

6. Behavioral Anomaly Detection

Monitors for anomalous patterns:

Latency spikes: p99 latency exceeding N× the rolling average
Error rate surges: error fraction above threshold

High-severity anomalies can trigger an automatic process restart with exponential backoff.

Configuration

All parameters live under [dream.sanitation] in config.toml:

Parameter	Type	Default	Description
`enabled`	bool	`true`	Enable the sanitation phase
`quarantine_ttl_days`	u32	`7`	Days before quarantined memories are purged
`memory_batch_size`	usize	`10`	Memories per LLM evaluation batch
`max_restart_count`	u32	`4`	Max restarts before giving up
`restart_backoff_base_secs`	u64	`30`	Base delay for exponential backoff
`anomaly_window_secs`	u64	`300`	Anomaly detection time window
`latency_spike_multiplier`	f32	`2.0`	p99 latency spike threshold
`error_rate_threshold`	f32	`0.05`	Error rate alarm threshold
`quality_re_ask_weight`	f32	`0.4`	Re-ask rate weight in quality score
`quality_correction_weight`	f32	`0.4`	Correction rate weight
`quality_abandonment_weight`	f32	`0.2`	Abandonment rate weight

Quarantine Lifecycle

Memory detected as suspect
  ↓
MemoryType set to Quarantined
  ↓
quarantined_at timestamp recorded
  ↓
(7 days pass — configurable via quarantine_ttl_days)
  ↓
NREM phase purges expired quarantined memories

Prometheus Metrics

All metrics are exposed at /metrics with the pisovereign_sanitation_ prefix:

Metric	Type	Description
`pisovereign_sanitation_memories_quarantined`	counter	Total memories quarantined
`pisovereign_sanitation_contradictions_resolved`	counter	Contradictions resolved
`pisovereign_sanitation_graph_orphans`	counter	Graph orphan nodes detected
`pisovereign_sanitation_defense_patterns_added`	counter	New defense patterns created
`pisovereign_sanitation_defense_score_x100`	gauge	Defense score × 100
`pisovereign_sanitation_quality_score_x100`	gauge	Quality score × 100
`pisovereign_sanitation_anomalies_detected`	counter	Behavioral anomalies detected
`pisovereign_sanitation_rollbacks`	counter	Snapshot rollbacks performed

API Endpoints

GET `/v1/sanitation/latest`

Returns the most recent sanitation result for the current user.

GET `/v1/sanitation/results/{session_id}`

Returns all sanitation results for a specific dream session.

GET `/v1/sanitation/defense-patterns`

Lists all active dynamic defense patterns.

DELETE `/v1/sanitation/defense-patterns/{id}`

Deactivates a specific defense pattern by ID.

GET `/v1/sanitation/quality`

Returns the current quality assessment including composite score and trend direction.

Troubleshooting

Quarantined memories you want to keep: Currently, quarantined memories must be restored via direct database update before the TTL expires. Set memory_type = 'fact' (or the original type) and clear quarantined_at / quarantine_reason.

Defense score declining: Check GET /v1/sanitation/defense-patterns for recently added patterns. Patterns with low effectiveness can be deactivated via the DELETE endpoint.

Quality score regression: Inspect GET /v1/sanitation/quality for the recommendations array. Common causes include increased re-ask rates (unclear responses) or high correction rates (factual errors from stale memories).

PiSovereign Documentation