This repository has been archived on 2026-10-29. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
Epiphany/README.md
2026-04-26 07:10:48 +01:00

86 lines
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`
- read-only reflection surfaces through `thread/epiphany/scene`, `jobs`, `freshness`, `context`, and `pressure`
- 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.
## 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