108 lines
5.4 KiB
Markdown
108 lines
5.4 KiB
Markdown
# 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
|