empirica 1.2.4

Genuine AI epistemic self-assessment framework - Universal interface for single AI tracking

🧠 Empirica - Epistemic Vector-Based Functional Self-Awareness Framework

AI agents that know what they know—and what they don't

What's New in 1.2.3

• 🚦 Sentinel Safety Gates - Human-in-the-loop gates (PROCEED/HALT/BRANCH/REVISE) that bound AI autonomy
• 🤖 Multi-Agent Spawning - Spawn epistemic sub-agents with agent-spawn, aggregate findings with agent-aggregate
• 🎭 Persona System - AI identity profiles that emerge from successful epistemic patterns (persona-list, persona-promote)
• 🔧 108 CLI Commands - Full coverage including assessment, trajectory projection, and drift detection
• 🌙 3-Layer Signaling - Moon phase indicators (🌑→🌕) for epistemic health at a glance
• 📈 Trajectory Projection - Project epistemic learning curves with trajectory-project
• 🐢 Turtle Principle - Recursive grounding: every claim must trace to verifiable source

⚡ Claude Code Quick Start

What You Do vs What Claude Does

You Do (Once)	Claude Does (Automatic)
pip install empirica	Runs project-bootstrap to load prior learnings
Add snippet to ~/.claude/CLAUDE.md	Logs findings as it works
Work normally	Runs CHECK gates before risky actions
	Saves what it learned at session end

Setup (2 minutes)

Step 1: Install

pip install empirica

Step 2: Add to ~/.claude/CLAUDE.md Copy this to ~/.claude/CLAUDE.md (Claude Code) or your AI's system prompt:

# Empirica - Epistemic Self-Assessment

You have Empirica installed. Use it to track what you know and learn.

## Quick Start
```bash
# Start session
empirica session-create --ai-id claude-code --output json

# Before work: What do I know?
empirica preflight-submit -

# After work: What did I learn?
empirica postflight-submit -

Core Vectors (0.0-1.0)

• know: Domain knowledge (0.7+ = ready)
• uncertainty: Doubt level (0.35- = ready)
• context: Information access
• do: Execution capability

Log As You Work

empirica finding-log --finding "Discovered X" --impact 0.7
empirica unknown-log --unknown "Need to investigate Y"

When Uncertain

Run CHECK gate: empirica check-submit -

Full docs: empirica --help

**Full setup guide:** [CLAUDE_CODE_SETUP.md](docs/guides/CLAUDE_CODE_SETUP.md) (hooks, MCP, troubleshooting)
**Full system prompt:** [CLAUDE.md](docs/system-prompts/CLAUDE.md) | [CANONICAL_CORE.md](docs/system-prompts/CANONICAL_CORE.md)

### Step 3: (Optional) MCP for Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "empirica": {
      "command": "empirica-mcp",
      "env": { "EMPIRICA_AI_ID": "claude-desktop" }
    }
  }
}

Docker

docker pull nubaeon/empirica:1.2.3

How It Works Day-to-Day

You don't need to type Empirica commands. Just talk to Claude normally:

You Say (Natural Language)	Claude Does (Behind the Scenes)
"Continue working on the auth refactor"	Runs project-bootstrap → loads what it learned last session
"I'm not sure about this approach"	Runs check-submit → assesses if it knows enough to proceed
"Good work, let's wrap up"	Runs postflight-submit → saves learnings for next time

What is project-bootstrap?

When Claude starts a session, project-bootstrap loads ~800 tokens of structured context:

📊 Epistemic State: know=0.85, uncertainty=0.15
🎯 Active Goals: Refactor auth module (in_progress)
💡 Recent Findings: "Auth uses JWT with 15min expiry"
❓ Open Unknowns: "Token rotation mechanism unclear"

This replaces 200k tokens of conversation history with just the important bits.

Will Claude ignore the commands?

Sometimes, especially mid-task. But after a memory compact (when context summarizes), Claude naturally looks for context—that's when bootstrap shines. The CLAUDE.md instructions make this reliable.

Live Metacognitive Signal

With Claude Code hooks enabled, you see Claude's epistemic state in real-time:

[empirica] ⚡79% │ ⚡ PRAXIC │ POSTFLIGHT │ K:80% U:20% C:90% │ Δ K:+0.30 U:-0.30 C:+0.30 │ ✓ stable

What this tells you:

• ⚡79% - Overall epistemic confidence
• PRAXIC - Claude is in action mode (vs NOETIC = investigation mode)
• POSTFLIGHT - Just completed a task and logged learnings
• K:80% U:20% - 80% knowledge, 20% uncertainty (healthy state)
• Δ K:+0.30 - Gained 30% knowledge this session (learning delta)
• ✓ stable - No epistemic drift detected

Why this matters: You can see when Claude is uncertain before it acts, when it's learning, and when it might be drifting from reality. No more guessing if Claude actually knows what it's doing.

What is Empirica?

Empirica is an epistemic self-awareness framework for AI agents that enables genuine self-assessment, systematic learning tracking, and effective multi-agent collaboration.

Unlike traditional AI tools that rely on static prompts or heuristic-based evaluation, Empirica provides 13-dimensional epistemic vector tracking that allows AI agents to know what they know (and don't know) with measurable precision.

Core Philosophy: Epistemic Self-Awareness

The Problem: AI agents often exhibit "confident ignorance" - they confidently generate responses about topics they don't actually understand.

The Solution: Empirica enables genuine epistemic self-assessment through:

1. 13-Dimensional Vector Space - Track knowledge, capability, context, and uncertainty across multiple dimensions
2. CASCADE Workflow - Structured reasoning process with explicit epistemic gates
3. Dynamic Context Loading - Resume work with compressed project memory
4. Multi-Agent Coordination - Seamless handoffs between AI agents

Key Features

• ✅ Honest uncertainty tracking: "I don't know" becomes a measured response
• ✅ Focused investigation: Direct effort where knowledge gaps exist
• ✅ Genuine learning measurement: Track what you learned, not just what you did
• ✅ Session continuity: Resume work across sessions without losing context
• ✅ Multi-agent coordination: Share epistemic state across AI teams

Result: AI you can trust—not because it's always right, but because it knows when it might be wrong.

🚀 Quick Start

Installation

PyPI (Recommended)

# Core installation
pip install empirica

# With API/dashboard features
pip install empirica[api]

# With vector search
pip install empirica[vector]

# Everything
pip install empirica[all]

Docker

# Pull the latest image
docker pull nubaeon/empirica:1.2.3

# Run a command
docker run -it nubaeon/empirica:1.2.3 empirica --help

# Interactive session with persistent data
docker run -it -v $(pwd)/.empirica:/data/.empirica nubaeon/empirica:1.2.3 /bin/bash

From Source

# Latest stable release
pip install git+https://github.com/Nubaeon/empirica.git@v1.2.3

# Development branch
pip install git+https://github.com/Nubaeon/empirica.git@develop

Initialize a New Project

# Navigate to your git repository
cd your-project
git init

# Initialize Empirica
empirica project-init

Your First Session

# AI-first JSON mode (recommended for AI agents)
echo '{"ai_id": "myagent", "session_type": "development"}' | empirica session-create -

🎯 Core Workflow: CASCADE

Empirica uses CASCADE - a metacognitive workflow with explicit epistemic phases:

# 1. PREFLIGHT: Assess what you know BEFORE starting
cat > preflight.json <<EOF
{
  "session_id": "abc-123",
  "vectors": {
    "engagement": 0.8,
    "foundation": {"know": 0.6, "do": 0.7, "context": 0.5},
    "comprehension": {"clarity": 0.7, "coherence": 0.8, "signal": 0.6, "density": 0.7},
    "execution": {"state": 0.5, "change": 0.4, "completion": 0.3, "impact": 0.5},
    "uncertainty": 0.4
  },
  "reasoning": "Starting with moderate knowledge of OAuth2..."
}
EOF
cat preflight.json | empirica preflight-submit -

# 2. WORK: Do your actual implementation
#    Use CHECK gates as needed for decision points

# 3. POSTFLIGHT: Measure what you ACTUALLY learned
cat > postflight.json <<EOF
{
  "session_id": "abc-123",
  "vectors": {
    "engagement": 0.9,
    "foundation": {"know": 0.85, "do": 0.9, "context": 0.8},
    "comprehension": {"clarity": 0.9, "coherence": 0.9, "signal": 0.85, "density": 0.8},
    "execution": {"state": 0.9, "change": 0.85, "completion": 1.0, "impact": 0.8},
    "uncertainty": 0.15
  },
  "reasoning": "Successfully implemented OAuth2, learned token refresh patterns"
}
EOF
cat postflight.json | empirica postflight-submit -

Result: Quantified learning (know: +0.25, uncertainty: -0.25)

✨ Key Features

📊 Epistemic Self-Assessment (13 Vectors)

Track knowledge across 3 tiers:

• Tier 0 (Foundation): engagement, know, do, context
• Tier 1 (Comprehension): clarity, coherence, signal, density
• Tier 2 (Execution): state, change, completion, impact
• Meta: uncertainty (explicit tracking)

🎯 Goal-Driven Task Management

# Create goals with epistemic scope
echo '{
  "session_id": "abc-123",
  "objective": "Implement OAuth2 authentication",
  "scope": {
    "breadth": 0.6,
    "duration": 0.4,
    "coordination": 0.3
  },
  "success_criteria": ["Auth works", "Tests pass"],
  "estimated_complexity": 0.65
}' | empirica goals-create -

🔄 Session Continuity

# Load project context dynamically (~800 tokens)
empirica project-bootstrap --project-id <PROJECT_ID>

🤝 Multi-Agent Coordination

Spawn epistemic sub-agents:

# Spawn a sub-agent for parallel investigation
empirica agent-spawn --session-id <ID> --task "Investigate auth patterns" --depth medium

# Sub-agent reports back
empirica agent-report --session-id <SUB_ID> --findings '[...]' --confidence 0.8

# Aggregate findings from multiple agents
empirica agent-aggregate --parent-session-id <ID> --merge-strategy weighted

Share epistemic state via git notes:

# Push your epistemic checkpoints
git push origin refs/notes/empirica/*

# Pull team member's state
git fetch origin refs/notes/empirica/*:refs/notes/empirica/*

🚦 Sentinel Safety Gates

Bounded AI autonomy with human oversight:

# Check if operation is safe to proceed
empirica sentinel-check --operation '{"type": "code_generation", "scope": "high"}' --session-id <ID>

# Returns: PROCEED | HALT | BRANCH | REVISE

# Orchestrate multi-step workflow with gates
empirica sentinel-orchestrate --workflow workflow.json --session-id <ID>

Gate types:

• PROCEED - Safe to continue autonomously
• HALT - Requires human approval before continuing
• BRANCH - Spawn investigation before proceeding
• REVISE - Modify approach and resubmit

🎭 Persona System

AI identity profiles that emerge from successful patterns:

# List available personas
empirica persona-list

# Find persona matching current task
empirica persona-find --task "security audit" --session-id <ID>

# Promote traits based on successful outcomes
empirica persona-promote --persona-id researcher --trait thoroughness --evidence "Found 3 critical bugs"

📈 Drift Detection & Trajectory

Monitor epistemic health and project learning curves:

# Check for behavioral drift
empirica check-drift --session-id <ID>

# Project epistemic trajectory
empirica trajectory-project --session-id <ID> --horizon 5

# Assess current epistemic state
empirica assess-state --session-id <ID> --include-history

Moon phase indicators for health at a glance:

• 🌑 Critical (coverage < 25%)
• 🌒 Low (25-50%)
• 🌓 Moderate (50-75%)
• 🌔 Good (75-90%)
• 🌕 Excellent (90%+)

📦 Optional Integrations

BEADS Issue Tracking

Install BEADS (separate Rust project):

cargo install beads

MCP Server (Model Context Protocol)

For AI tools that support MCP:

# Install MCP server
pip install empirica-mcp

# Run server
empirica-mcp

Features: 57 tools including 9 Human Copilot tools for enhanced human oversight.

Claude Code Integration

Automatic epistemic continuity across memory compacts:

# Install plugin (bundled with Empirica)
./scripts/install_claude_plugin.sh

Vector Search (Qdrant)

pip install empirica[vector]

# Start Qdrant
docker run -p 6333:6333 qdrant/qdrant

# Embed docs
empirica project-embed --project-id <PROJECT_ID>

# Search
empirica project-search --project-id <PROJECT_ID> --task "oauth2"

📚 Documentation

Getting Started

• 📖 First-Time Setup
• 🚀 Empirica Explained Simply

Guides

• 🎯 CASCADE Workflow
• 📊 Epistemic Vectors

Reference

• 📋 CLI Commands
• 🗄️ Database Schema

🔒 Privacy & Data Isolation

Your data is isolated per-repo:

• ✅ .empirica/ - Local SQLite database (gitignored)
• ✅ .git/refs/notes/empirica/* - Epistemic checkpoints (local by default)
• ✅ .beads/ - BEADS database (gitignored)

🛠️ Development

Running Tests

# Core tests
pytest tests/

# Integration tests
pytest tests/integration/

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📊 System Requirements

• Python: 3.11+
• Git: Required for epistemic checkpoints
• Optional: Docker (for Qdrant), Rust/Cargo (for BEADS)

🎓 Learn More

Research & Concepts

• Why Empirica?
• Epistemic Architecture

Use Cases

• Research & Development
• Multi-Agent Teams
• Long-Running Projects
• Training Data Generation
• Epistemic Audit Trails

🔗 Related Projects

• Empirica MCP - Model Context Protocol server for Empirica integration
• Empirica EPRE - Epistemic Pattern Recognition Engine

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

📜 License

MIT License - Maximum adoption, trust-aligned with Empirica's transparency principles.

See LICENSE for details.

---

Built with genuine epistemic transparency 🧠✨