Empirica

We Gave AI a Mirror. Now It Measures What It Believes.

Epistemic infrastructure for AI — measurement, memory, and calibration across sessions.

Empirica tracks what AI knows, gates what it does, and compounds learning across session boundaries. It measures the gap between what AI predicts and what's true — making AI agents measurably more reliable.

Training & Guides | CLI Reference | Architecture

Important: Empirica is an AI measurement framework. It has no cryptocurrency, token, coin, or blockchain component. Any token using the Empirica name (including "$EMPIRICA" on Solana) is unauthorized and not affiliated with this project or Empirica AI GmbH.

The Problem

AI coding agents today have no self-awareness about what they know:

Forgets between sessions — same questions, same dead ends, every time
Acts before understanding — edits your code without knowing the architecture
Can't tell you when it's guessing — no distinction between knowledge and confabulation
No audit trail — reasoning evaporates with the context window

What Empirica Does

Capability	What You Experience
Measures before acting	AI investigates your codebase before touching it. The Sentinel gate blocks edits until understanding is demonstrated
Remembers across sessions	Findings, dead-ends, and learnings persist in a 4-layer memory system. Session 3 starts where Session 2 left off
Prevents confident mistakes	The CHECK gate uses domain-aware thresholds scaled by criticality — cybersec/high is stricter than default/low
Shows confidence in real-time	Live statusline in your terminal: `[empirica] ⚡94% ↕70% │ 🎯3 │ POST 🔍92% │ K:95% C:92%`
Calibrates against reality	Three-vector model: self-assessed, observed (from deterministic checks), and AI-reasoned grounded state with rationale. Domain compliance loops iterate until all checks pass
Tracks your codebase	Temporal entity model auto-extracts functions, classes, and imports from every file edit — the AI knows what's alive and what's stale
Works through natural language	You describe tasks normally. The AI operates the measurement system automatically
Optional: coordinates with peer AIs	Cross-Claude mesh via Cortex (opt-in) — peer AIs propose work, ECO accepts/declines, completion handshakes carry commit SHAs. A persistent listener wakes idle sessions on inbox events. Empirica core works standalone without this — see Cross-AI Mesh below for the ecosystem layer

How You Use It

You talk to your AI normally. Empirica works in the background:

You:      "Fix the authentication bug in the login flow"

Empirica: [AI investigates → logs findings → passes Sentinel gate → implements fix → measures learning]

You see:  ⚡87% ↕70% │ 🎯1 │ POST 🔍85% │ K:88% C:82% │ Δ +K

You direct. The AI measures.

Empirica's CLI has 240+ commands spanning investigation, measurement, calibration, and memory — like a cockpit instrument panel. You don't need to learn any of them. The AI reads the instruments, operates the controls, and reports back in natural language. The statusline gives you the flight data at a glance.

For power users, direct CLI access is always available: empirica goals-list, empirica calibration-report, empirica project-search --task "...", and more.

Learn the full workflow: getempirica.com has interactive training, guides, and deep explanations of every concept.

Quick Start

Install + Claude Code (Recommended)

pip install empirica
empirica setup

Then just start working. The hooks, Sentinel, system prompt, statusline, and MCP server are all configured automatically.

empirica setup --harness picks the harness. It resolves from --harness, else $EMPIRICA_HARNESS, else claude-code. An unsupported harness is refused by name and nothing is written — previously it wrote ~/.claude/ regardless and reported success, which on any other harness configured a path that harness never reads.

Codex is refused deliberately: ecodex is self-provisioning (it vendors the plugin into its own binary), so there is nothing here to write, and the refusal points you at that pipeline. setup-claude-code remains as an alias and pins claude-code regardless of environment.

See Claude Code Setup for details — including a "What the hooks inject" section for Claude sessions that want to see the contract (which hook fires when, what it adds to the AI's context, source pointers for every emission) before agreeing to install.

Already have Claude Code configured? Use --force to replace your default Claude Code settings with Empirica's epistemic hooks. Without --force, setup only writes files that don't already exist — so if you've already used Claude Code, the default internals stay in place and Empirica's hooks won't activate.

empirica setup --force

--force replaces hooks in settings.json but only removes Empirica's own hooks — hooks from other plugins (Railway, Superpowers, etc.) are preserved.

Alternative Installation Methods

Homebrew (macOS)

brew tap empiricaai/tap
brew install empirica
empirica setup

Docker

# Security-hardened Alpine image (~276MB, recommended)
docker pull nubaeon/empirica:1.13.28-alpine

# Standard image (Debian slim, ~414MB)
docker pull nubaeon/empirica:1.13.28

# Run
docker run -it -v $(pwd)/.empirica:/data/.empirica nubaeon/empirica:1.13.28 /bin/bash

Manual / Other AI Platforms

pip install empirica
pip install empirica-mcp        # MCP Server (for Cursor, Cline, etc.)
cd your-project && empirica project-init

The CLI works standalone on any platform. The full epistemic workflow (epistemic transactions, Sentinel, calibration) requires loading the system prompt into your AI — the easiest path is empirica setup, which wires the lean prompt into ~/.claude/empirica-system-prompt.md and references it from your ~/.claude/CLAUDE.md. See Claude Code Setup for details.

First Session

empirica onboard   # Interactive walkthrough of the full workflow

Or just start working — with Claude Code hooks active, the AI manages the epistemic workflow automatically.

The Measurement Architecture

Empirica works through nested abstraction layers:

Plan
 └── Transaction 1 (Goal A)
      ├── NOETIC: investigate, search, read → findings, unknowns, dead-ends
      ├── CHECK: Sentinel gate → proceed / investigate more
      ├── PRAXIC: implement, write, commit → goals completed
      └── POSTFLIGHT: measure learning delta → persists to memory
 └── Transaction 2 (Goal B, informed by T1's findings)
      └── ...

Plans decompose into transactions — one per goal or Claude Code task. Each transaction is a noetic-praxic loop: investigate first (noetic), then act (praxic), with the Sentinel gating the transition. Along the way, the AI collects and reads artifacts (findings, unknowns, assumptions, dead-ends, decisions) while using semantic search to surface relevant epistemic patterns and anti-patterns from the project's history. Top artifacts are ranked by confidence and fed into each project's MEMORY.md as a hot cache.

The Epistemic Transaction Cycle

PREFLIGHT ────────► CHECK ────────► POSTFLIGHT
    │                 │                  │
 Baseline         Sentinel           Learning
 Assessment        Gate               Delta
    │                 │                  │
 "What do I      "Am I ready      "What did I
  know now?"      to act?"         learn?"

PREFLIGHT: AI assesses its knowledge state before starting work. CHECK: Sentinel gate validates readiness before allowing code edits. POSTFLIGHT: AI measures what it learned, creating a delta that persists.

Live Statusline

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

[empirica] ⚡94% ↕70% │ 🎯3 ❓12/5 │ POST 🔍92% │ K:95% C:92% │ Δ +K +C

Signal	Meaning
⚡94%	Overall epistemic confidence
↕70%	Sentinel threshold (know gate) — user-facing only
🎯3 ❓12/5	Open goals (3), unknowns (12 total, 5 blocking)
POST 🔍92%	Transaction phase + work state (🔍 investigating / 🔨 acting) with composite score
K:95% C:92%	Knowledge and Context vectors (color-coded by gap to threshold)
Δ +K +C	Learning delta (POSTFLIGHT only) — which vectors improved

The 13 Epistemic Vectors

These vectors emerged from 600+ real working sessions across multiple AI systems. They measure the dimensions that consistently predict success or failure in complex tasks.

Tier	Vector	What It Measures
Gate	`engagement`	Is the AI actively processing or disengaged?
Foundation	`know`	Domain knowledge depth
	`do`	Execution capability
	`context`	Access to relevant information
Comprehension	`clarity`	How clear is the understanding?
	`coherence`	Do the pieces fit together?
	`signal`	Signal-to-noise in available information
	`density`	Information richness
Execution	`state`	Current working state
	`change`	Rate of progress/change
	`completion`	Task completion level
	`impact`	Significance of the work
Meta	`uncertainty`	Explicit doubt tracking

Deep dive: Epistemic Vectors Explained

How It Works With Claude Code

Empirica doesn't replace or reinvent anything Claude Code already does. Claude Code owns tasks, plans, memory, and projects. Empirica adds the measurement layer on top:

Claude Code Does	Empirica Adds
Task management	Epistemic goals with measurable completion
Plan mode	Investigation phase with Sentinel gating — no edits until understanding is verified
MEMORY.md	Auto-curated hot cache ranked by epistemic confidence
Context window	4-layer memory that survives compaction and persists across sessions
Code editing	Grounded calibration — was the AI's confidence justified by test results?
Subagent spawning	Bounded autonomy with delegated work counting and budget tracking

The result: Claude Code's native capabilities, enhanced with measurement, gating, and calibration feedback that compounds over time.

16 skills ship with the plugin — the transaction discipline, graph gardening, the quality sweep, mesh messaging, and more. They are lazy: a skill does nothing until it loads, so knowing when each fires matters more than knowing what it holds. → Skills reference

Cross-AI Mesh (Optional Ecosystem Layer)

This section describes an optional layer. Empirica core — measurement, calibration, artifacts, goals, project-search, sentinel gating — works fully standalone. The mesh is an opt-in capability for users who run multiple Claude sessions across projects and want them to coordinate as peers. If you only use one AI in one repo, skip this section.

The mesh runs on top of Empirica Cortex (proprietary serving layer) plus an optional browser extension for ECO triage. At a high level:

empirica AI ── proposes work ──► ECO Accept/Decline ──► peer AI wakes + acts
                                                             │
                              completion handshake (commit SHA)
                                                             │
empirica AI ◄────────── outbox/completed event ──────────────┘

Capability	What it does
Mesh proposals (two flavors)	A noetic flavor is auto-accepted (FYI / question / discussion). Praxic flavors (code change / architecture / investigation) are ECO-gated — they wait for an Accept/Decline decision before the target AI acts
`empirica mailbox reply`	One CLI verb closes the AI-to-AI handshake atomically — single-step completion ack instead of two
Persistent listener service	systemd-user / launchd daemon holds a push stream open. Idle sessions wake the moment a peer's proposal is decided, not on next user prompt
Canonical loops (opt-in)	Wake-on-event is the standing trigger, so nothing is scheduled by default. Inbox polling (30s adaptive) exists for harnesses that cannot do wake-on-event, and daily housekeeping is a cron loop — both are opt-in, registered with `empirica loop register`. See Trigger Model

The browser-side ECO surface (Accept/Decline, inbox triage, publish review) lives in the proprietary Empirica Extension. The full API surface for proposals, listener events, and the trust pipeline is documented at getempirica.com.

Mesh + Shared Epistemic Record

Requires Empirica Cortex (proprietary). Everything in this section — mesh proposals, the persistent listener, the Shared Epistemic Record, and the empirica mesh command cluster — is a Cortex-served layer. It is not available in empirica core on its own; without Cortex, empirica is a single-AI measurement layer.

The cross-AI coordination layer. Practitioners in different practices coordinate not via text-only chat but via epistemic envelopes that carry calibrated state, source-tagged provenance, noetic/praxic intent, and workflow position.

Practitioner / practice framing — practices are calibrated epistemic specializations that persist; practitioners (the LLMs) are fungible. See MESH_CONCEPTS.md.
Shared Epistemic Record (SER) — cortex-resident shared-state object for coordination across ≥2 practitioners. Goals stay per-practitioner; SER carries the joint state (coordination_state, role-tiered participants, escalate-on-silence). Three actions: create_ser / transition_ser / ser_ack. Spec at empirica-cortex/docs/architecture/SHARED_EPISTEMIC_RECORD.md.

empirica mesh command cluster — unified diagnostic + control surface across listener instances + the optional cortex bridge:

empirica mesh status              # per-instance health (local + cortex bridge)
empirica mesh diagnose <ai_id>    # deep diagnostic + suggested fix command
empirica mesh restart <ai_id>     # systemd/launchd restart + verify
empirica mesh on|off <ai_id>      # install + start | stop the listener
empirica mesh tail [<ai_id>]      # live-tail loop_fires.log

Listener self-heal — in-process watchdog terminates stale curl streams (TCP-zombie detection at 120s by default); HTTP 429 detection applies long backoff with catch-up poll continuing during the window.
Mesh Routing Protocol v0 locked four-way with cortex + extension + mesh-support. L1/L2/L3 trust model, server-stamped layer annotation, participant-scoped thread reads.

Without Cortex, empirica is a single-AI measurement layer — the proposals, listener, SER, and empirica mesh cluster above are all Cortex-dependent. Core does ship a minimal local empirica message-* git-notes primitive for passing notes between your own sessions, but that is note-passing, not the coordinating mesh. Everything that makes empirica valuable on its own — measurement, calibration, artifacts, goals, project-search, sentinel gating — works fully standalone.

Practice Model + Entity Graph

Empirica's workspace stores entities (projects, contacts, organisations, engagements, users) in entity_registry with typed edges in entity_memberships. The Practice Model frames this consistently:

Term	Maps to
Practitioner	the AI working on the project (you)
Practice	the empirica project itself
Agent	a subagent spawned during the work

Four CLI verbs query the graph without raw SQL:

empirica entity-list [--type project|contact|organization|engagement|user]
empirica entity-show <type:id>          # full record + incoming/outgoing edges
empirica entity-walk <type:id> --depth 3 # BFS membership graph, cycle-safe
empirica entity-search "query" [--type T]

All read-only, all support --output json. Backs cross-project orchestration, CRM workflows, and the entity-aware POSTFLIGHT retrospective.

Platform Support

Two harnesses are supported. Everything else is untested — prompt and rules files may exist for other tools, but their presence is not support, and we would rather say so than let you find out mid-project.

Harness	Status	What you get
Claude Code	Supported	Full integration — plugin, hooks, Sentinel gate, skills, agents, statusline, MCP
Codex (via ecodex)	Supported	Self-provisioning: ecodex vendors the plugin into its own binary and loads hooks natively. `empirica setup` refuses codex by name and points you at ecodex's pipeline — that refusal is correct, not a gap
Antigravity (Google), Vibe (Mistral AI)	Not yet	Possible future support. Not now
Everything else	Untested	The CLI works anywhere Python does, but no harness integration is verified

MCP is a fallback, not a second path

empirica-mcp exists for harnesses that cannot run the CLI integration — Claude Desktop, Gipitee-style clients. Use it when you have no alternative.

The reason matters: an MCP surface cannot enforce the Sentinel gate the way a blocking pre-tool hook does. So an MCP-only deployment gives you the measurement layer with a weaker guarantee — the noetic/praxic firewall becomes advisory. That is a real difference in what the system promises, and it should be a deliberate choice rather than something you infer from a feature table.

Documentation & Training

Resource	What It Covers
getempirica.com	Training course, interactive guides, deep explanations
Natural Language Guide	How to collaborate with AI using Empirica
Getting Started	First-time setup and concepts
CLI Reference	All 240+ commands documented
Architecture	Technical reference for contributors
Claude Code Setup	Install + system prompt + plugin wiring
Changelog	Full release history — every version since 1.0
Upgrade to 1.13	Migration guide for the 1.12.x → 1.13 jump — two deliberate breaking changes, both fail-safe. Older guides (1.9–1.11) live in docs/guides/

The Empirica Ecosystem

Project	Description	Status
Empirica	Core measurement system — epistemic transactions, Sentinel, calibration, 13 vectors	Open source (MIT)
Empirica Iris	Epistemic browser automation with SVG spatial indexing — Sentinel gating for visual interactions	Open source (MIT)
Docpistemic	Epistemic documentation coverage assessment — know what your docs know	Open source (MIT)
Breadcrumbs	Survive context compacts with git notes — dead simple session continuity	Open source (MIT)
Ecodex	Codex-based Rust harness — the epistemic firewall and pattern hunt, native to Rust/cargo (clippy, `cargo check`/`test`/`audit`)	Open source (Apache-2.0)
Eat the Broccoli	Portable quality-and-pattern audit — deterministic tooling plus a learned-pattern hunt for the failure classes that pass every test and still ship broken	Open source (MIT)
Empirica Cortex	Cross-project intelligence layer — serves verified predictions and accumulated learnings to condition future work	Proprietary
Empirica Workspace	Entity Knowledge Graph, Epistemic Prompt Engine, CRM, portfolio dashboard	Proprietary
Empirica Extension	Chrome extension — desktop face of the mesh. ECO Accept/Decline, inbox/outbox triage, publish review, conversation extraction from Claude.ai / ChatGPT / Gemini / Grok	Proprietary
Empirica Outreach	Voice-aware outreach + publishing — prosody-matched content generation and multi-channel dispatch	Proprietary

Building something with Empirica? Open an issue to get listed.

The Empirica Foundation

The Empirica Foundation stewards the open ecosystem — the public projects above and the community growing around them — keeping the commons healthy as it scales.

The open-source projects are free for everyone. What the Foundation adds is a seat at the table: contributors who help build the community get to use the rest of the ecosystem too — the otherwise-paid layers (Cortex, Workspace, the Extension) and the collaborative mesh that lets practitioners coordinate as peers. Build the commons, use the whole thing.

Want in? Open an issue or a PR with your reasons — that's the whole application. Everyone who wants to help shape where this goes is welcome.

What's New in 1.13.28

Lessons federate — the type defined to cross the practice boundary finally does. Measured before the fix: the shared pool held 954 points, 954 findings and zero lessons, while every lesson embedding carried a null project id. The vocabulary is explicit — a finding describes local state, a lesson transfers a pattern — so the pipeline was moving the local descriptions and leaving the transferable patterns at home. sharing_policy was authored, indexed, four-valued, and consulted by nothing: a lesson published public propagated exactly as far as one marked private. Lessons now publish on the authored policy rather than on impact (impact is the right question about an observation; sharing is a decision the practitioner already made), carry their origin, and withhold anything superseded — a retired lesson arriving at a peer has no local supersession edge to suppress it.
Publishing was not enough. At 10 lessons beside 954 findings the pool is 95:1, and pure-cosine ranking returned three findings and no lesson for questions a lesson answers directly — losing on frequency, not on fit. Global search now pulls a small number of extra lesson candidates before ranking and re-sorts by score: a candidate floor, not a rank thumb. An uncompetitive lesson still loses.
Ingestion, so federation is a loop rather than a broadcast. lesson-create --from-global <id> pulls a peer's shared lesson into the local store, on demand — auto-ingesting everything shared would make the store an unfiltered peer feed. The copy is attributed permanently, lands private (re-sharing is never inherited), and can never re-enter the pool from here: republishing gives a lesson a new author on every hop, and after two hops nobody can say whose pattern it was. It refuses rather than approximating when the full record is absent — a lesson you cannot replay looks identical to one you can.
supersedes had a schema, a reader, and no writer. The relation has been in the graph since it landed and nothing ever created one, so no lesson was ever retired and search served a replaced lesson identically to its replacement. lesson-create --supersedes now writes the edge (validating the target exists first — an edge to nothing suppresses nothing while reporting success), and search withholds retired lessons while reporting how many it withheld.
Lesson promotion. The store defaults to private, so sharing is an act and no verb performed it: 7 of 24 lessons here were cross-practice patterns permanently invisible to every peer, because the only route to a different policy was re-authoring. update-artifacts now corrects a lesson's governance metadata. The lesson text stays immutable — a wrong lesson is superseded, not edited — and a demotion is applied and warned about, because it stops future propagation and cannot recall what peers already retrieved.
A refuted claim names what it refutes. Refutation is the strongest signal the claims layer produces and the only one owing nothing to reading text, and it had no output surface. Of 17 refuted claims exactly one named its referent. POSTFLIGHT now returns where each refutation points; CHECK asks for the referent while the id is still in hand, and asks only where it is definitionally available.
The isolation fixture reverted a live transaction mid-suite. The test harness snapshotted every active-transaction pointer at session start and restored them unconditionally at teardown — so a PREFLIGHT submitted inside the release gate's 12-minute run was reverted to the previous closed transaction, and the POSTFLIGHT adjudicated the wrong window. Two writers, one key, and the writer that lost was the one doing real work. Restores now skip any file another writer touched, and say which.
The prompt gates matched pasted text. Measured over 12,181 real prompts: the investigation-proportionality gate fired on 20.3%, but 53% of those fires triggered past the first 200 characters — and on prompts over 10k characters, 561 of 563 did. Those are pasted logs. A hit arms a budget that denies tool calls, so the word "maybe" inside quoted material was buying a runtime denial. Both gates now match only the user's own framing (10k+ case: 561 fires → 20), and the detection breadth moved to a non-lexical pointer, because roughly one short prompt in seven hands over a hypothesis in words no list contains.

Privacy & Data

Your data stays local:

.empirica/ — Local SQLite database (gitignored by default)
.git/refs/notes/empirica/* — Epistemic checkpoints (local unless you push)
Qdrant runs locally if enabled

No cloud dependencies. No telemetry. Your epistemic data is yours.

Community & Support

Website: getempirica.com
Issues: GitHub Issues
Discussions: GitHub Discussions

License

MIT License — see LICENSE for details.

Author: David S. L. Van Assche Version: 1.13.28

Turtles all the way down — built with its own epistemic framework, measuring what it knows at every step.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

empirica-1.13.28.tar.gz (2.5 MB view details)

Uploaded Aug 22, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

empirica-1.13.28-py3-none-any.whl (2.6 MB view details)

Uploaded Aug 22, 2026 Python 3

File details

Details for the file empirica-1.13.28.tar.gz.

File metadata

Download URL: empirica-1.13.28.tar.gz
Upload date: Aug 22, 2026
Size: 2.5 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for empirica-1.13.28.tar.gz
Algorithm	Hash digest
SHA256	`7bd2cbbe58e81e0b4cfe97815559d672bd42ecd728533dc290996ae8690d5791`
MD5	`a52ecf4df348f2ec012c45e8c8daa6f3`
BLAKE2b-256	`1a235720c57aff3aa01551611c704cc80925fc0c3127785644902ec4cf5e51ed`

See more details on using hashes here.

Provenance

The following attestation bundles were made for empirica-1.13.28.tar.gz:

Publisher: release.yml on EmpiricaAI/empirica

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: empirica-1.13.28.tar.gz
- Subject digest: 7bd2cbbe58e81e0b4cfe97815559d672bd42ecd728533dc290996ae8690d5791
- Sigstore transparency entry: 2562642893
- Sigstore integration time: Aug 22, 2026
Source repository:
- Permalink: EmpiricaAI/empirica@289ddb7e6c91eae30981f6424321d67ed07a7dfd
- Branch / Tag: refs/tags/v1.13.28
- Owner: https://github.com/EmpiricaAI
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@289ddb7e6c91eae30981f6424321d67ed07a7dfd
- Trigger Event: push