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.
This note is not a full machine map for Codex. We already have that in [E:/Projects/EpiphanyAgent/notes/codex-repository-algorithmic-map.md](E:/Projects/EpiphanyAgent/notes/codex-repository-algorithmic-map.md).
This one is narrower and meaner: it documents where the current Epiphany prototype already diverges from upstream Codex in the code we actually have in the working tree.
Scope: current state after Phase 1, Phase 2, the minimal Phase 3 typed read surface, and the first bounded Phase 4 repo-local hybrid retrieval slice. It does **not** describe planned invalidation, GUI reflection, or multi-agent scheduling as if they already exist.
Current Epiphany is a thin but real overlay on Codex's thread harness: Codex now carries structured thread state through persistence, replay, prompt assembly, hydrated client thread payloads, and one typed repo-local hybrid retrieval surface.
Stock Codex persists turn context and transcript-shaped history, but it does not persist a dedicated repo-understanding state plane with its own graph, evidence, and churn structures.
Current Epiphany adds exactly that.
### Why it matters
This is the first place where Epiphany stops being "remember this in prose" and becomes "there is a canonical object for current understanding."
## Divergence 2: per-turn persistence and replay
### What changed
Session persistence and replay now carry Epiphany state through the thread lifecycle:
-`thread/start` can hydrate it from a live loaded thread
-`thread/resume` can hydrate it from a live loaded thread
-`thread/fork` can hydrate it from a live loaded thread
-`thread/read` can hydrate it:
- from live thread state when loaded
- otherwise from rollout reconstruction
-`thread/unarchive` and detached review-thread startup can hydrate it too
### How this differs from plain Codex
Plain Codex clients can inspect thread metadata, turns, items, and diffs, but there is no typed thread field for "the thread's current structured repo understanding."
Epiphany adds the first piece of that client-visible state plane.
### Important limit
This is a **read surface**, not a full Epiphany control plane.
We do **not** yet have:
-`thread/epiphany/read`
-`thread/epiphany/update`
-`thread/epiphany/stateUpdated`
-`thread/epiphany/evidenceAppended`
So the client can now see the state, but cannot yet steer or subscribe to it as a first-class live surface.
- exact/path-ish hits via existing `codex_file_search`
- semantic hits via workspace-local BM25 chunk search over a gitignore-respecting corpus
- live `thread.epiphanyState` hydration backfills a lightweight retrieval summary when the thread has Epiphany state but no persisted retrieval metadata yet
### How this differs from plain Codex
Plain Codex has pieces of repo search substrate scattered around:
- fuzzy/exact-ish file search
- BM25 usage in tool-search paths
- shell access if the operator wants to rummage manually
What it does not have is one Epiphany-owned retrieval organ that says:
- this query is for repo understanding
- this thread/workspace is the scope
- exact and semantic lookup are the same machine
- results come back in a typed shape instead of as transcript confetti
### Why it matters
This is the first time Epiphany can ask a structured repo question without falling back to file-by-file terminal spelunking.
That changes the shape of the harness. The map is no longer just a notebook the prompt can read. It now has a first retrieval organ hanging off the same typed spine.
