empirica 1.1.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

Choose your preferred installation method:

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]

Homebrew (macOS/Linux)

brew tap nubaeon/tap
brew install empirica

Docker

# Pull the image
docker pull nubaeon/empirica:1.0.3

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

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

Chocolatey (Windows)

choco install empirica

From Source

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

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

🆕 First-time user? → Installation Guide

Initialize a New Project

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

# Initialize Empirica (creates config files, optional BEADS integration)
empirica project-init

# Follow interactive prompts:
# - Project name
# - Enable BEADS issue tracking? (y/N)
# - Create documentation index template? (y/N)

Result:

• ✅ .empirica/config.yaml - Infrastructure settings
• ✅ .empirica/project.yaml - Project metadata & BEADS config
• ✅ docs/SEMANTIC_INDEX.yaml - Documentation index (optional)
• ✅ Project registered in database

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

Claude Code Integration

Automatic epistemic continuity across memory compacts:

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

Features:

• 🔄 Auto-saves epistemic state before Claude Code memory compacts
• 📥 Auto-restores context after compacts (MCO config + bootstrap)
• 📊 Drift detection - measures epistemic drift across compacts
• 🎯 Zero configuration - automatically finds latest session
• 💾 Token efficient - 97.5% reduction vs manual reconstruction

What it does:

• PreCompact hook → Saves checkpoint + MCO config before compact
• SessionStart hook → Loads bootstrap + MCO config after compact
• SessionEnd hook → Curates old snapshots (keeps high-impact, removes low-impact)

Result: Epistemic drift reduced from 60% → 10% across memory compacts.

Learn more: Claude Code 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

---

🔗 Related Projects

• Empirica MCP - Model Context Protocol server for Empirica integration
• Empirica EPRE - Epistemic Pattern Recognition Engine (privacy-preserving platform integrations for Twitter, Slack, Discord, and more)

---

📞 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 🧠✨