Nomos OS Docs

Appearance

The Dual-Core Architecture (Substrate Core vs. Intent Core) ​

The central architectural insight of Nomos OS is the Inverted Control Flow: We do not let a stochastic Large Language Model (LLM) act as the autonomous orchestrator of a software repository. Instead, the compiled Go engine (nomos) runs the immutable core state machine, treating the LLM as a bounded "Cognitive Co-Processor" or heuristic search function.

🏛️ The Dual-Core Split ​

📐 The Four Core Architectural Axioms ​

1. Axiom of Topological Symmetry ​

The harness underneath the AI agent must mirror the state topology of the agent's reasoning loop.

If the agent transitions from exploratory planning to code modification and verification, the host filesystem must procedurally transition from read-only mounts to sandboxed transient worktrees and machine verification gates.

2. Axiom of Dual-Core Division ​

Intent Core explores, designs, and refactors; Substrate Core enforces, verifies, and guarantees.

Stochastic neural networks are exceptional at pattern synthesis, refactoring intuition, and semantic diff generation. They are fundamentally unsuited for counting indentation, tracking transactional locks, or verifying AST invariants. Substrate Core relieves the model of self-policing by making rules structural.

3. Axiom of Non-Verbal Proof ​

We never ask an LLM if code is correct; we compile it, verify AST invariants, and run tests through deterministic Go binaries.

Conversational self-attestation ("I have verified that there are no regressions") is rejected as an invalid proof in Nomos OS. Only a 0 exit code from nomos verify unlocks release execution.

4. Axiom of Topological Slicing ​

Cognitive size is the early-warning indicator; Domain and Layer separation is the structural remedy.

Monolithic tasks spanning compiled Go engines, UI components, and declarative playbooks inevitably induce context hallucination. Tasks must be cleanly sliced along topological domain boundaries rather than arbitrary agile sizing.

🛡️ The Physical Totem (Inception Paradigm) ​

During recursive agent delegation or complex swarm execution, stochastic reasoning loops can experience cognitive drift. In Nomos OS, the compiled Go engine acts as an immutable physical totem:

  • State Persistence: State is transactionally recorded in SQLite (~/.nomos/data/db/nomos_global.db).
  • Memory Topology: Subconscious memories and Git Notes (refs/notes/agent) anchor long-term context across session restarts.
  • Fail-Safe Snapping: No matter how deep into recursive reasoning an agent descends, running nomos status or nomos handshake snaps execution back to host reality.