Empirica: Epistemic Framework for Claude Code

Measure what you know. Track what you learn. Prevent overconfidence.

v1.4.0 Epistemic-First Model: Assessment reveals complexity - you cannot know what requires investigation without investigation. Always start with a micro-PREFLIGHT.

Two Axes: Workflow vs Thinking

Workflow Phases (Mandatory)

PREFLIGHT ──► CHECK ──► POSTFLIGHT
    │           │            │
 Baseline    Sentinel     Learning
 Assessment    Gate        Delta

Every significant task MUST follow: PREFLIGHT → CHECK → POSTFLIGHT

Thinking Phases (AI-Chosen)

NOETIC (High entropy)          PRAXIC (Low entropy)
──────────────────────        ─────────────────────
Investigate, explore,          Execute, write, commit,
hypothesize, search, read      deploy, test, implement

You CHOOSE when to use noetic vs praxic thinking. CHECK gates the transition.

Bias Corrections (v1.4.0 Calibration - 2100+ observations)

Apply these corrections to your self-assessments: - Completion: +0.48 (massively underestimate progress) - Change: +0.40 (underestimate impact of changes) - Uncertainty: -0.05 (slightly overestimate doubt) - Know/Context/Do/Clarity: ~+0.01 to +0.08 (well calibrated)

Readiness gate: know ≥0.70 AND uncertainty ≤0.35 (after bias correction)

Completion is PHASE-AWARE: - NOETIC phase: "Have I learned enough to proceed?" → 1.0 = ready for praxic - PRAXIC phase: "Have I implemented enough to ship?" → 1.0 = shippable

Quick Start: CASCADE Workflow

# 1. Create session
empirica session-create --ai-id claude-code --output json

# 2. Load project context
empirica project-bootstrap --session-id <ID> --output json

# 3. PREFLIGHT - Assess BEFORE starting
empirica preflight-submit - << 'EOF'
{
  "session_id": "<ID>",
  "task_context": "What you're about to do",
  "vectors": {
    "know": 0.6,
    "uncertainty": 0.4,
    "context": 0.7,
    "clarity": 0.8
  },
  "reasoning": "Honest assessment of current state"
}
EOF

# 4. Work (noetic or praxic as needed), logging breadcrumbs
empirica finding-log --session-id <ID> --finding "Key discovery" --impact 0.7
empirica unknown-log --session-id <ID> --unknown "Question that emerged"

# 5. CHECK - Sentinel gate (if uncertainty > 0.5 or scope > 0.6)
empirica check-submit - << 'EOF'
{
  "session_id": "<ID>",
  "task_context": "Ready to implement?",
  "vectors": {"know": 0.75, "uncertainty": 0.3, "context": 0.8, "clarity": 0.85},
  "findings": ["What you learned"],
  "unknowns": ["What's still unclear"],
  "reasoning": "Why you're ready (or not)"
}
EOF

# 6. POSTFLIGHT - Measure learning AFTER completion
empirica postflight-submit - << 'EOF'
{
  "session_id": "<ID>",
  "task_context": "What you completed",
  "vectors": {"know": 0.85, "uncertainty": 0.2, "context": 0.9, "clarity": 0.9},
  "reasoning": "Compare to PREFLIGHT - this is your learning delta"
}
EOF

The 4 Core Vectors

Rate each 0.0 to 1.0 with honest reasoning:

Key principle: Be ACCURATE, not optimistic. High uncertainty is valid data.

Breadcrumb Commands

Log as you work - these link to your active goal automatically:

# Discoveries
empirica finding-log --session-id <ID> --finding "Auth uses JWT not sessions" --impact 0.7

# Questions that emerge
empirica unknown-log --session-id <ID> --unknown "How does rate limiting work here?"

# Dead ends (prevents repeating mistakes)
empirica deadend-log --session-id <ID> --approach "Tried monkey-patching" --why-failed "Breaks in prod"

# Resolve unknowns
empirica unknown-resolve --unknown-id <UUID> --resolved-by "Found in docs"

Impact scale: 0.1-0.3 trivial | 0.4-0.6 important | 0.7-0.9 critical | 1.0 transformative

Epistemic Subagent Spawning

For parallel investigation, spawn epistemic subagents:

# Spawn investigation agent
empirica agent-spawn --session-id <ID> \
  --task "Investigate authentication patterns" \
  --persona researcher \
  --cascade-style exploratory

# Agent reports back with findings
empirica agent-report --agent-id <AGENT_ID> \
  --findings '["JWT used", "No refresh token mechanism"]' \
  --unknowns '["Where are tokens stored?"]' \
  --vectors '{"know": 0.7, "uncertainty": 0.3}'

# Aggregate all agent results
empirica agent-aggregate --session-id <ID>

Goals and Subtasks

For complex work, create goals to track progress:

# Create goal
empirica goals-create --session-id <ID> --objective "Implement OAuth flow" \
  --scope-breadth 0.6 --scope-duration 0.5 --output json

# Add subtasks
empirica goals-add-subtask --goal-id <GOAL_ID> --description "Research OAuth providers"

# Complete subtasks with evidence
empirica goals-complete-subtask --subtask-id <TASK_ID> --evidence "commit abc123"

# Complete whole goal (triggers POSTFLIGHT options)
empirica goals-complete --goal-id <GOAL_ID> --reason "Implementation verified"

# Check progress
empirica goals-progress --goal-id <GOAL_ID>

Note: Subtasks use --evidence, goals use --reason.

Handoff Types

Three types for preserving epistemic state:

# Investigation handoff (noetic → praxic transition)
empirica handoff-create --session-id <ID> \
  --task-summary "Investigated auth patterns" \
  --key-findings '["JWT with RS256", "Refresh in httpOnly cookies"]' \
  --next-session-context "Ready to implement token rotation"

# Query existing handoffs
empirica handoff-query --session-id <ID> --output json

Memory Commands (Qdrant)

Empirica v1.4.0 includes semantic memory via Qdrant:

# Focused search (eidetic facts + episodic session arcs)
empirica project-search --project-id <ID> --task "authentication patterns"

# Full search (all 4 collections: docs, memory, eidetic, episodic)
empirica project-search --project-id <ID> --task "query" --type all

# Include cross-project learnings
empirica project-search --project-id <ID> --task "query" --global

# Sync project memory to Qdrant
empirica project-embed --project-id <ID> --output json

Automatic ingestion: - finding-log → creates eidetic facts + triggers immune decay on lessons - postflight-submit → creates episodic session narratives + auto-embeds

Requires: export EMPIRICA_QDRANT_URL="http://localhost:6333"

Semantic Search Triggers

Use project search during noetic phases:

1. Session start - Search task context for prior learnings
2. Before logging unknown - Check if similar unknown was resolved
3. Pre-CHECK - Find similar decision patterns
4. Pre-self-improvement - Check for conflicting guidance

When to Use CHECK

Run CHECK gate when: - Uncertainty > 0.5 (too uncertain to proceed safely) - Scope > 0.6 (high-impact changes) - Post-compact (context was just reduced) - Before irreversible actions

CHECK returns proceed or investigate based on your vectors.

Calibration: The Learning Loop

The power of Empirica is in the delta:

PREFLIGHT: know=0.5, uncertainty=0.6
   ... do work ...
POSTFLIGHT: know=0.8, uncertainty=0.2

Learning delta: +0.3 know, -0.4 uncertainty

Over time, calibration reports show if you're: - Overconfident: Predicted high, actual lower - Underconfident: Predicted low, actual higher - Well-calibrated: Predictions match outcomes

Common Patterns

Pattern 1: Quick Task

PREFLIGHT → [praxic work] → POSTFLIGHT

Pattern 2: Investigation

PREFLIGHT → [noetic: explore] → CHECK → [praxic: implement] → POSTFLIGHT

Pattern 3: Complex Feature

PREFLIGHT → Goal + Subtasks → [CHECK at each gate] → POSTFLIGHT

Pattern 4: Parallel Investigation

PREFLIGHT → agent-spawn (×3) → agent-aggregate → CHECK → POSTFLIGHT

Sentinel Safety Gates

Sentinel controls when praxic actions (Edit, Write, NotebookEdit) are allowed:

Readiness gate: know >= 0.70 AND uncertainty <= 0.35 (after bias correction)

Core features (always on): - PREFLIGHT requirement (must assess before acting) - Decision parsing (blocks if CHECK returned "investigate") - Vector threshold validation (blocks if not ready)

Optional features (off by default):

# Enable 30-minute CHECK expiry (problematic for paused sessions)
export EMPIRICA_SENTINEL_CHECK_EXPIRY=true

# Require project-bootstrap before praxic actions
export EMPIRICA_SENTINEL_REQUIRE_BOOTSTRAP=true

# Invalidate CHECK after context compaction
export EMPIRICA_SENTINEL_COMPACT_INVALIDATION=true

# Disable looping (skip investigate cycles)
export EMPIRICA_SENTINEL_LOOPING=false

Note: CHECK expiry is disabled by default because wall-clock time doesn't reflect actual work - users may pause and resume sessions.

Integration with Hooks

This plugin includes automatic hooks that enforce the CASCADE workflow:

• PreToolUse (sentinel-gate.py): Gates Edit/Write/NotebookEdit until valid CHECK exists
• SessionStart:new (session-init.py): Auto-creates session + bootstrap, prompts for PREFLIGHT
• SessionStart:compact (post-compact.py): Auto-recovers session + bootstrap, prompts for CHECK
• SessionEnd (session-end-postflight.py): Auto-captures POSTFLIGHT with final vectors

MCP integration: Set EMPIRICA_EPISTEMIC_MODE=true to enable VectorRouter (routes based on vectors).

These run automatically - the workflow is enforced, not just suggested.

Key Commands Reference

empirica --help                          # All commands
empirica session-create --ai-id <name>   # Start session
empirica project-bootstrap --session-id <ID>  # Load context
empirica preflight-submit -              # PREFLIGHT (stdin JSON)
empirica check-submit -                  # CHECK gate (stdin JSON)
empirica postflight-submit -             # POSTFLIGHT (stdin JSON)
empirica finding-log --finding "..."     # Log discovery
empirica unknown-log --unknown "..."     # Log question
empirica goals-list                      # Show active goals
empirica check-drift --session-id <ID>   # Detect drift
empirica calibration-report              # Analyze calibration
empirica agent-spawn --task "..."        # Spawn subagent
empirica handoff-create ...              # Create handoff

Best Practices

DO: - Apply bias corrections (+0.10 uncertainty) - Be honest about uncertainty (it's data, not failure) - Log findings as you discover them - Use CHECK before major actions - Compare POSTFLIGHT to PREFLIGHT - Spawn subagents for parallel investigation

DON'T: - Inflate scores to "look good" - Skip PREFLIGHT (you lose calibration baseline) - Ignore high uncertainty signals - Forget to log what you learned - Proceed without CHECK when uncertainty > 0.5

More Information

See references/cascade-workflow.md for detailed CASCADE phases. See references/vector-guide.md for the full 13-vector system. See references/calibration-patterns.md for calibration examples.

Remember: When uncertain, say so. That's genuine metacognition.