Skip to content

Architecture

Jump to bottom
yohn1985 edited this page Jun 15, 2026 · 2 revisions

Architecture

Jarvis is a bounded loop with a real mind. The kernel is dumb and reliable; the intelligence is a single "mind" call per tick. Everything degrades safely — a missing dependency is skipped, never a crash.

wake → perceive → orient → decide (priority ladder) → act → reflect

The tick (jarvis/kernel.py)

One bounded unit of work per wake:

  • perceive — build the world from durable signals (jarvis/perceive.py). A source outage is surfaced, not silently treated as "nothing to do".
  • orient — rebuild "who am I" from config/memory.
  • decide — pick the highest non-empty rung of the priority ladder (incident → unfinished work → self-caused regression → self-maintenance → curiosity → human backlog).
  • act — route the decision to a worker. Enforces propose-only: it executes only when mode ≠ shadow and the action class is allow; otherwise it records the intent.
  • reflect — write the experience to memory so it changes future behavior.

The loop (jarvis/loop.py) wakes on a self-scheduled cadence, a heartbeat floor, or an alert; it self-heals via a pure-Python watchdog before each tick.

The mind — model router (jarvis/adapters/llm.py)

A role → backend:model router. Backends are either CLI (claude, codex, ollama) or HTTP (OpenAI-compatible, or the Anthropic Messages API). Features:

  • Per-role routing (cheap models for spawned agents, a frontier model for the main brain).
  • Streaming with separated thinking vs answer deltas (the dashboard's Thought block).
  • Per-role effort (OpenAI/o-series/codex) and thinking level (Claude).
  • Vision (image content blocks) for capable models.
  • Full fallback chain; a failing backend advances to the next.

Memory

  • Working (jarvis/memory/working.py) — Redis; degrades to in-process. Wake queue, cross-tick locks (owner-token), pheromones.
  • Episodic (jarvis/memory/store.py) — Postgres; degrades to a JSONL ledger. Jarvis writes its own reflections and reads them back (jarvis/feedback.py → store → perceive), so experience is causal.

Skepticism — verify (jarvis/verify.py)

The deep-fix discipline distilled: spawn a red-team agent to disprove a claim. Fail-closed — if the check can't run (no brain, error, no explicit verdict) it returns not verified; an un-run check never counts as a pass. Callers revise on a real break and record an honest "unverified" flag otherwise.

Self-modification seatbelt (jarvis/safety/seatbelt.py)

Editing its own code is the most powerful and dangerous thing it does, so:

  1. The mind never scores its own change — fitness is a separate, tamper-proof subprocess (jarvis/safety/fitness.py).
  2. Every version is archived (git tag) before an edit — rollback is one command.
  3. An edit is adopted only if it doesn't lower fitness AND survives an independent red-team; otherwise it's rolled back. self_modify is deny by default.

Dashboard (jarvis/dashboard/)

A zero-dependency (stdlib http.server) web UI: token-gated, streaming chat over SSE, knowledge browser, activity (runs + processes), and a unified Settings page. The /api/* JSON is stable — a richer front-end can be built on it.

Skills (skills/)

Self-contained capabilities with a skill.py (the hands) and a SKILL.md (the method). Shipped: web, discover, deep-search, youtube-research. Run from chat with /skill ….

Clone this wiki locally