Lens / E.D.I.T.H.

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.