empirica 1.0.0

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

🧠 Empirica - Honest AI Through Epistemic Self-Awareness

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

What is Empirica?

Empirica enables AI agents to genuinely assess their knowledge and uncertainty.

Instead of false confidence and hallucinations, Empirica provides:

• ✅ 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

# 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]

🆕 First-time user? → First-Time Setup Guide (explains data isolation & privacy)

Your First Session

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

# Legacy CLI (still supported)
empirica session-create --ai-id myagent --output json

Output:

{
  "ok": true,
  "session_id": "abc-123-...",
  "project_id": "xyz-789-...",
  "message": "Session created successfully"
}

---

🎯 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 -

Integrates with BEADS (issue tracking) for dependency-aware workflows.

🔄 Session Continuity

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

Shows:

• Recent findings (what was learned)
• Open unknowns (what's unclear)
• Dead ends (what didn't work)
• Reference docs & skills

🤝 Multi-Agent Coordination

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/*

Privacy: You control what gets shared!

---

📦 Optional Integrations

BEADS Issue Tracking

Install BEADS (separate Rust project):

cargo install beads

Features:

• Dependency-aware task tracking
• Git-friendly (JSONL format)
• AI-optimized JSON output
• Auto-links with Empirica goals

Learn more: BEADS Integration Guide

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"

API & Dashboard

pip install empirica[api]

# Start monitoring dashboard
empirica monitor

---

📚 Documentation

Getting Started

• 📖 First-Time Setup - Data isolation & privacy
• 🚀 Empirica Explained Simply - Core concepts
• 📘 System Prompt (v4.1) - AI-first JSON reference

Guides

• 🎯 CASCADE Workflow
• 📊 Epistemic Vectors
• 🎯 Goal Tree Usage
• 🤝 Multi-Agent Teams

Reference

• 📋 CLI Commands
• 🗄️ Database Schema
• 🐍 Python API
• ⚙️ Configuration

---

🔒 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)

Each user gets a clean slate - no inherited data from other users or projects.

---

🛠️ Development

Running Tests

# Core tests
pytest tests/

# Integration tests
pytest tests/integration/

# MCP tests
pytest tests/mcp/

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
• Visual Guide

Use Cases

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

---

📞 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.

See LICENSE for details.

---

Built with genuine epistemic transparency 🧠✨