The Codex

Live persistent file system

The Codex

The Codex is the live, persistent file system that holds every project's spatial state. It is the single source of truth for designs, feeds, runs, automations, and session memory. Every view in Nexma — the Globe, the Skill canvas, the data strip, mobile — reads from and writes to the same Codex.

Why a file system

A file system is the simplest substrate that an autonomous agent and a human can both reason about. Files have paths, contents, and history. They compose, fork, diff, and merge. Every primitive an engineer needs to coordinate work is already there.

Jax interacts with the Codex through eight generic primitives — Read, Write, Edit, Delete, Glob, Grep, Run, Solve — named after the corresponding Claude Code tools. There are no domain-specific tools. A water valve and a fiber splitter are both files.

Layout

A typical Codex looks like:

_meta/
  schema.json              # Active agent skill — domain types and constraints
layers/
  zones/                   # Service polygons
  poles.geojson            # Existing infrastructure
  meters.geojson           # Customer endpoints
designs/
  current/                 # Working design
  baseline/                # Reference comparison
feeds/
  weather.geojson          # Live data feeds
  flights.geojson
runs/
  2026-04-12T10-22Z/       # Solver runs with inputs and results
automations/
  daily-replan.json        # Scheduled or event-driven workflows
sessions/
  jax/                     # Conversation history per session
selections/
  current.geojson          # Ephemeral polygon selections

Persistence

The Codex is database-backed. Reads and writes are durable across sessions, across team members, and across the desktop and mobile apps. Earlier prototypes were in-memory; that limitation is gone.

Every write is versioned. Point-in-time replay is available for design reviews and audits. Branches give you parallel design workflows backed by real git semantics underneath — see Branches.

Reactivity

All views render reactively from the Codex. A new feature in designs/current/ appears on the Globe within a frame; a new feed in feeds/ populates the data strip immediately; a new automation in automations/ shows up in the canvas.

There is no separate "AI workspace" — Jax writes to the same files a human would edit. Diffs are reviewable. Conflicts are mergeable.

What does not belong in the Codex

Application code — that lives in the repo, not the Codex.
Secrets — handled by the integration layer, never written to Codex files.
Long-form unstructured documents — the Codex carries spatial state, not

knowledge-base content.