Research and design effort
How the character, the pipeline and the safety model were researched and decided.
A paper trail before the code
The work started with a written plan rather than a prototype. The repository holds an architecture decision register, an architecture plan, a phases plan, a cost-and-risks note, an open-items list, nine specifications and an owner-supplied reference set.
- Decision register: packages/edith/plans/DECISIONS.md records 91 numbered decisions (D01 to D89 plus DA1 and DA2) and was edited in 15 commits between 2026-11-15 and 2026-11-17.
- Plans (5 files): ARCHITECTURE, COST_AND_RISKS, DECISIONS, OPEN_ITEMS, PHASES.
- Specs (9 files): API and data contracts, Arcade E.D.I.T.H. Picks, conversation and memory, knowledge and guides, OS integration, QA and acceptance, safety and permissions, UX settings and Studio, visual and entrances.
- Reference originals (13 files): the owner's character bible, lore, personality, voice, relationships, core and agent documents, the 8-bit PNG and a layered editable pixel SVG, and a states JSON.
- Architecture docs: edith.md (388 lines), edith-agent.md (100) and edith-call.md (45) in docs/architecture.
- In total about 25,700 words of plans, specs, reference text and architecture documentation (wc -w over those files).
Themes in the decision log
- Grounding and determinism: deterministic-first answers over published facts, a language model last (D05, D29 to D31, D41 to D43).
- Safety and consent: an allowlisted action contract, ticketed one-use authorization, never trust the client, and DOM-only knowledge of the UI for hands-on mode (D03, D38, D43, D58, D59, D85, D86).
- Privacy: session-only by default, saved chat local-only with moderation before persisting, no tracking of capability data (D04, D13, D57 to D60, D80).
- Presence and performance: a lazy host chunk, no assets in public/, CSS-only movement, bounded timers (D24 to D26, D47, D77, D87).
- Owner tooling and platform: a CMS Studio global, an Express 5 and Next adapter over one handler, in-memory rate limits with honest caveats (D09, D15 to D21, D62 to D69).
- Games and character: Phaser behind a single lazy door, original pixel art only (D08, D20, D70 to D73, DA1, DA2).
Models and providers considered
Needle (via Orivyn / cactus-needle)
A small tool-calling model from Cactus Compute running in browser WebAssembly.
- Role in E.D.I.T.H.
- Optional proposer of a single 'open this app' navigation for explicit open commands; a router, not her personality
- Where it runs
- In the visitor's browser (lazy worker and WASM, same origin)
- Documented size
- About 35 MB of weights, downloaded on first use
- Status in the product
- Wired and lazy; model score is never trusted and nothing auto-executes from it
Whistle (via Orivyn)
A small speech-to-text model for the browser.
- Role in E.D.I.T.H.
- Planned local speech input for E.D.I.T.H. Call; not used today
- Where it runs
- In the visitor's browser
- Documented size
- About 17 MB of weights; English, German, French, Spanish, Italian, Dutch and Polish
- Status in the product
- Evaluated and documented, not wired
Cactus server inference
Orivyn's optional server-side provider using the cactus-compute package.
- Role in E.D.I.T.H.
- Not used by E.D.I.T.H.; available in Orivyn only
- Where it runs
- On an Orivyn API server
- Documented size
- Models may download on first inference
- Status in the product
- Not wired
Gemini fallback
A hosted model behind a server-only, grounded, budgeted guard.
- Role in E.D.I.T.H.
- Last-resort grounded phrasing after the deterministic pipeline declines
- Where it runs
- On the Node server (key from GEMINI_API_KEY)
- Documented size
- Hosted; default model id gemini-2.5-flash, to be re-verified when enabling
- Status in the product
- Wired but disabled (gemini.enabled is false in the committed config)
VerdictThe design rule that falls out of the evaluation: the cheapest reliable path wins. Exact, deterministic matching handles what it can; a small local model may only propose a navigation the app then re-validates; a hosted model can only rephrase facts she already found; and voice waits for an explicit consent flow.