Formal diagnostic sessions for memory system health and structural analysis
The doctor pattern provides structured diagnostic sessions for evaluating memory system health. It checks instruction file compliance, seed belief integrity, platform hook installation, and performs deep structural analysis of the memory graph.
Memory systems degrade over time. References break, beliefs accumulate contradictions, relationships go stale, and goals lose relevance. The doctor pattern provides a principled approach to memory health:
Early detection: Find problems before they affect SI behavior
Privacy-safe: Structural checks use IDs and scores only, never memory content
Audit trail: Diagnostic sessions and reports are persisted for review
Operator-initiated sessions are gated by trust. The stack-owner entity must have trust at or above the diagnostic threshold (0.85) for the session to proceed.
The default doctor command checks instruction file compliance:
Copy
kernle -s my-project doctor
Copy
╔══════════════════════════════════════════════════╗║ Kernle Doctor - System Health ║╚══════════════════════════════════════════════════╝ Stack: my-project Seed Beliefs Version: 3 Instruction File: CLAUDE.mdStatus: Good - required checks pass, some recommendations missing Required: 3/3 Recommended: 2/3──────────────────────────────────────────────────INSTRUCTION FILE CHECKS────────────────────────────────────────────────── [required] Instruction file found: CLAUDE.md [required] Load instruction found [required] Health check instruction found [recommended] Per-message health check instruction found [recommended] Checkpoint instruction found [recommended] Dedicated memory section found
from kernle import Kernlefrom kernle.storage.base import DiagnosticSession, DiagnosticReportimport uuidfrom datetime import datetime, timezonek = Kernle(stack_id="my-stack")# Run the basic doctor check (instruction file compliance)# This is primarily a CLI command; programmatic usage works through storage# Create a diagnostic sessionsession = DiagnosticSession( id=str(uuid.uuid4()), stack_id=k.stack_id, session_type="self_requested", access_level="structural", status="active", consent_given=True, started_at=datetime.now(timezone.utc),)k._storage.save_diagnostic_session(session)# Run structural checks (internal API)from kernle.cli.commands.doctor import run_structural_checksfindings = run_structural_checks(k)# Create a report from findingsreport = DiagnosticReport( id=str(uuid.uuid4()), stack_id=k.stack_id, session_id=session.id, findings=[f.to_dict() for f in findings], summary=f"Found {len(findings)} issue(s)", created_at=datetime.now(timezone.utc),)k._storage.save_diagnostic_report(report)# Complete the sessionk._storage.complete_diagnostic_session(session.id)# List past sessionssessions = k._storage.get_diagnostic_sessions(limit=10)for s in sessions: print(f" [{s.status}] {s.session_type} - {s.started_at}")# Get reports for a sessionreports = k._storage.get_diagnostic_reports(session_id=session.id)for r in reports: print(f" {r.summary}") for f in (r.findings or []): print(f" [{f['severity']}] {f['description']}")# Trust gating for operator-initiated diagnosticsresult = k.gate_memory_input( source_entity="stack-owner", action="diagnostic")if result["allowed"]: print("Operator diagnostic permitted")
