# EpiphanyAgent Epiphany is an opinionated fork of Codex built around one demand: the model must model the thing it is changing. The failure mode this repo is hunting is not "the model cannot write code." It can. Annoyingly well. The failure mode is local plausibility after global coherence has already wandered into traffic wearing headphones. Epiphany answers that by moving important state out of transcript fog and into typed, inspectable surfaces: maps, scratch, evidence, retrieval state, observations, graph/frontier state, churn pressure, and client reflections. ## Current Shape This is no longer just an external-file prompting experiment. The landed spine now includes: - durable `EpiphanyThreadState` in vendored Codex protocol/core session state - rollout snapshots and replay reconstruction for resume, rollback, fork, and compaction - bounded `` prompt injection - typed client reads through `Thread.epiphanyState` - read-only hybrid 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` - first Phase 6 reflection through read-only `thread/epiphany/scene` - repo-owned heavy organs in `epiphany-core/`, with vendored Codex kept as the host seam where practical Phase 1 through Phase 5 are complete enough. Phase 6 is about reflection and observable harness state, not more anxious polishing of the Phase 5 control plane. For exact current status, trust: - `state/map.yaml` - `notes/fresh-workspace-handoff.md` - `notes/epiphany-fork-implementation-plan.md` - `notes/epiphany-current-algorithmic-map.md` Git history and smoke artifacts carry proof. `state/evidence.jsonl` carries only distilled belief-changing evidence, not every little victory lap with a timestamp. ## Core Artifacts - `AGENTS.md`: project-specific operating discipline for future Codex sessions - `state/map.yaml`: canonical current project map and accepted design - `state/scratch.md`: disposable working memory for one bounded subgoal - `state/branches.json`: branch hypotheses and outcomes, not volatile phase status - `state/evidence.jsonl`: distilled durable evidence, decisions, rejected paths, and scars - `notes/fresh-workspace-handoff.md`: compact re-entry packet - `notes/epiphany-fork-implementation-plan.md`: distilled forward implementation plan - `notes/epiphany-current-algorithmic-map.md`: source-grounded live control-flow map - `notes/epiphany-core-harness-surfaces.md`: stable surface contract - `notes/architecture-rationale.md`: why the map/scratch/evidence architecture exists - `notes/codex-repository-algorithmic-map.md`: background map of the vendored Codex substrate - `protocol/controller-actions.md`: legacy/manual controller discipline for local state maintenance - `tools/epiphany_state.py`: compact state inspection and distilled evidence helper - `eval-plan.md`: evaluation sketch for comparing Epiphany discipline against plain prompting ## Next Move When implementation resumes, choose one Phase 6 organ: 1. Live-smoke `thread/epiphany/scene` through app-server. 2. Design and land a minimal read-only job/progress reflection surface for indexing, remap, verification, and future specialist work. The scene-smoke path is tighter. The job/progress path is the larger missing organ. ## Working Loop 1. Rehydrate from canonical state before touching code. 2. Restate the current mechanism and intended change before substantial edits. 3. Keep one bounded hypothesis per iteration. 4. Verify the seam that matters. 5. Revert failed regression or benchmark fixes immediately. 6. Record only distilled evidence that changes future belief. 7. Commit completed work before it rots in the worktree. Do not confuse a growing diff, growing notes, or a local green check with understanding. That is how the tower learns to smirk. ## Re-entry From the repo root: ```powershell & 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' status Get-Content '.\state\map.yaml' Get-Content '.\notes\fresh-workspace-handoff.md' Get-Content '.\notes\epiphany-current-algorithmic-map.md' Get-Content '.\notes\epiphany-fork-implementation-plan.md' git status --short --branch git log --oneline -5 Get-Content '.\state\evidence.jsonl' -Tail 8 ``` After compaction or resume, rehydrate and reorient first. Do not continue implementation just because a note names a next move. ## Verification Use focused checks for the surface being changed. For Phase 5 control-plane behavior changes: ```powershell & 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_phase5_smoke.py' ``` For Codex Rust work on this Windows machine: ```powershell $env:CARGO_TARGET_DIR='C:\Users\Meta\.cargo-target-codex' ``` Do not parallelize cargo builds or tests against the same target directory. ## Licensing 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.