Epiphany/README.md

EpiphanyAgent

Epiphany is an opinionated fork of Codex built around one demand: the model must model the thing it is changing.

The problem this repo is chasing is not "LLMs can't write code." They can. The problem is that they can keep making plausible local moves after the global design has already wandered off and died in a ditch.

Epiphany answers that by moving important state out of transcript fog and into typed, inspectable surfaces: maps, evidence, retrieval state, graph/frontier state, churn pressure, and compact client reflections. The goal is not maximal output. The goal is a machine whose parts visibly deserve to exist.

What Exists Now

The current spine is real, not aspirational:

• durable EpiphanyThreadState in the vendored Codex protocol/core session
• rollout snapshots and replay for resume, rollback, fork, and compaction
• bounded <epiphany_state> prompt injection
• typed client reads through Thread.epiphanyState
• read-only retrieval through thread/epiphany/retrieve
• explicit semantic indexing through thread/epiphany/index
• durable typed writes through thread/epiphany/update
• read-only observation distillation through thread/epiphany/distill
• read-only map/churn proposal through thread/epiphany/propose
• verifier-backed promotion through thread/epiphany/promote
• successful-write notifications through thread/epiphany/stateUpdated
• durable jobBindings as a thin Epiphany-owned launcher seam over runtime job backends
• explicit launch and interrupt authority through thread/epiphany/jobLaunch and thread/epiphany/jobInterrupt, still backed by runtime agent_jobs
• a bounded reorient-guided worker launch through thread/epiphany/reorientLaunch
• read-only CRRC next-action recommendations through thread/epiphany/crrc
• live bound-job progress notifications through thread/epiphany/jobsUpdated
• read-only reflection surfaces through thread/epiphany/scene, jobs, freshness, context, pressure, and reorient
• a first dogfood CLI operator view through tools/epiphany_mvp_status.py, including explicit implementation, modeling/checkpoint, verification/review, and reorientation lanes
• durable investigation checkpointing for compaction-safe planning
• repo-owned heavy Epiphany organs in epiphany-core/, with vendored Codex kept as the host seam where practical

Phase 1 through Phase 6 are landed enough for the current experiment. The open questions are now about observability, invalidation, coordination, authority, and safe capability growth, not whether typed state can exist at all.

Where This Leads

The architectural goal is not one giant agent that does archaeology, design, patching, and self-grading in a single token fog. The goal is a maintained control system:

• graph and source-modeling agents keep the machine map current
• freshness, watcher input, pressure, and reorientation signals decide whether that map still deserves trust
• verifier agents check claims, diffs, and outcomes against reality
• coding agents work from bounded packets of graph context, evidence, code refs, and local source reads instead of re-spelunking the repo from scratch every turn

That still leaves direct source reading where it belongs: at the last mile, when a patch has to be grounded in the real files. The difference is that broad exploration, coherence maintenance, and verification stop living in the same overworked skull.

Repo Tour

If you want the human-readable map of the project, start here:

• notes/architecture-rationale.md: why the map/scratch/evidence architecture exists
• notes/epiphany-current-algorithmic-map.md: source-grounded control flow of the live machine
• notes/epiphany-fork-implementation-plan.md: distilled forward plan
• notes/epiphany-safety-architecture.md: capability, authority, interruption, and anti-cage doctrine
• state/map.yaml: canonical current project map and accepted design

If you want the code:

• epiphany-core/: repo-owned Epiphany logic
• vendor/codex/: vendored Codex host substrate
• tools/: smoke tests and state helpers

If you are an agent or you are steering one, read AGENTS.md. That file is for operating discipline, re-entry protocol, and session hygiene. The README is for people, which is a lower-crime use of everyone's time.

Design Stance

Epiphany is built on a few stubborn ideas:

• externalized state is better than pretending the transcript is a brain
• local plausibility is not the same thing as global coherence
• evidence should survive, but activity feed sludge should not
• cognition should grow faster than authority
• interruption, legibility, and explicit permissions matter more as the machine becomes more coherent

This repo is not trying to make the model louder. It is trying to make it less likely to build a Jenga tower and call it understanding.

License

The root LICENSE is the operative repository notice. In short: vendor/codex/** and other third-party material keep their upstream licenses; project-authored material outside vendor/codex/** is publicly available under PolyForm Noncommercial 1.0.0 and is intended to be available under separate commercial terms by written agreement.

External contributions require CONTRIBUTOR_LICENSE_AGREEMENT.md or a separate written agreement accepted by the project steward.

The publishing stance is:

• FOSS where that is viable
• source-available where the economics or capability profile make unrestricted release a bad idea
• commercial terms where organizations are extracting real enterprise value