Asoba Asoba Open Source

Core Concepts

Nehanda CLI is built around three foundational architectural principles that set it apart from conventional AI coding assistants. Nehanda CLI does not treat a large language model as an omniscient chatbot. It avoids cramming ever-larger prompts into the context window. Instead, Nehanda CLI treats the model as one component within a structured cognitive system.

Understanding these three ideas explains why Nehanda CLI is faster, consumes fewer tokens, and reliably finishes complex software tasks where standard agent loops break down.


1. Dual-Process Cognitive Architecture: System 1 and System 2

Human cognition does not solve every problem with slow, deliberate contemplation. In his landmark research, psychologist Daniel Kahneman described two distinct modes of human thought:

NEHANDA CLI — DUAL-PROCESS COGNITIVE ARCHITECTURE Fast Non-Autoregressive Sidecar (System 1: Laya) & Deliberate Generative Reasoning (System 2) USER REQUEST Interactive Prompt / REPL Task Submission Developer command or automated pipeline trigger entering the turn loop bin/nehanda-ui.mjs RAW INPUT EVALUATION (~0ms) SYSTEM 1 Laya (421M Non-Autoregressive Decision Engine) Warm local sidecar · Single forward pass (~48ms reflex) · Zero hallucinations lib/laya.mjs • Intent Classification Routes query to SDLC phase • Bashguard Risk Screening 85%+ confidence safety bypass • Memory Graph Edge Typing Causal, semantic & temporal links • Compaction Transcript Pruner Preserves invariants, drops noise • Evidence Candidate Scorer Scores graph nodes (BEAM_W=4) • Zero Hallucination Guardrails Typed probability noul (0.0-1.0) SAFE DECISIONS & ROUTING RELEVANT EVIDENCE & CONSTRAINTS SYSTEM 2 Generative LLM (Deliberate Reasoning Engine) Qwen 2.5 27B / Nehanda v3.1 / Claude 3.5 / GPT-4o · Strict bounded synthesis lib/orchestrate.mjs • Architectural Diagnosis & Root Cause Analysis Diagnose root causes without wasting tokens on basic classification • Behavioral Test Authoring (TDD Gate) Craft deterministic reproduction suites that physically verify defects • Code Implementation & Surgical Patching Mutate production files only after test runner verifies reproduction • Detailed Plan Synthesis & Spec Alignment Synthesize verifiable implementation plans against pinned invariants

The Flaw of Single-Model Agents

Most AI agent tools force a single generative model to perform both roles simultaneously. A massive frontier model is asked to decide what tool to pick, classify simple user intent, verify bash commands, evaluate memory relevance, and generate production code.

This creates severe operational problems:

  1. Extreme Latency: Generative models produce output token-by-token. Asking an LLM a simple yes-or-no question or routing classification takes seconds of expensive text streaming.
  2. Hallucinated Control Decisions: Generative models are probabilistic word predictors. When asked to evaluate security permissions or filter tool results, they frequently rationalize bad decisions or hallucinate compliance.

How Nehanda CLI Divides Cognition

Nehanda CLI introduces a strict separation between reflexive control decisions and analytical synthesis:

Where System 1 Protects the Workflow

  1. User Intent Shaping: When you enter a prompt, Laya instantly classifies the request into engineering categories (lib/laya.mjs), framing the exact context template before System 2 even wakes up.
  2. Bashguard Safety Screening: When a shell command presents moderate security risk, Laya evaluates whether the arguments conform to legitimate development patterns (lib/tools.mjs). If confidence exceeds 85%, the command executes immediately without interrupting the user.
  3. Memory Graph Construction: As observations arrive from the terminal and file system, Laya classifies their relationships into causal, semantic, or temporal edges without running a slow prompt.
  4. Context Pruning: During long sessions, Laya scores transcript entries, discarding redundant compiler outputs while preserving vital error messages.

By handling the reflexes through System 1, Nehanda CLI eliminates hundreds of unnecessary API round-trips and keeps System 2 focused entirely on code.


2. Why Jev-Mem: The Jevons Paradox of Context Windows

In 1865, English economist William Stanley Jevons made an unexpected observation: when the James Watt steam engine dramatically improved coal efficiency, overall coal consumption did not drop. Instead, cheaper and more efficient power caused industries to invent countless new uses for steam, causing total coal consumption to skyrocket.

This principle—that increased resource efficiency triggers exponentially greater consumption—is known as Jevons Paradox.

THE JEVONS TRAP IN AI CONTEXT WINDOWS How massive token capacity paradoxically triggers attention collapse, quadratic latency, and reasoning failure STEP 1 Bigger Context Windows Frontier models expand context from 128K to 1M+ tokens. Context appears infinite, cheap, and practically unlimited. Trap Trigger: Teams stop curating or pruning input history DUMP REPO STEP 2 Developers Dump Entire Repos Multi-file trees, git diffs, and compiler outputs are resent unpruned on every single turn. Outcome: Prompts swell to hundreds of thousands of tokens QUADRATIC ATTENTION STEP 3 Attention Dilution ("Lost in Middle") Transformer attention density degrades over large sequences. Critical domain invariants get buried in historical noise. Latency: Time-to-first-token (TTFT) scales quadratically AGENT DRIFT JEVONS TRAP Catastrophic Reasoning Decay Multi-minute TTFT latencies stall interactive developer flow. Models produce ghost refactors, loop endlessly & drift. Trap: Frustrated devs dump even more context to "remind" it VICIOUS CYCLE COMPOUNDS

The Modern Jevons Trap in AI

Modern large language models boast massive context windows, spanning from 128,000 tokens to over one million tokens. On the surface, this sounds like a total solution for memory. Developers often assume they can solve context by simply dumping whole codebases, complete error traces, and multi-hour chat histories into every prompt.

In practice, this triggers the Jevons trap:

The Jev-Mem Solution: Multi-Relational Memory

Nehanda CLI rejects raw context dumping. Instead, it implements Jev-Mem—an episodic memory plane backed by SQLite and powered by System 1.

NEHANDA CLI — JEV-MEM ARCHITECTURE SQLite Multi-Relational Episodic Memory Plane (~/.config/nehanda/ona-session.db) & Adaptive Beam Search STORAGE PLANE SQLite Database (~/.config/nehanda/ona-session.db) In-process ACID relational store via better-sqlite3 · Zero network daemon overhead lib/jev.mjs NODES memories Observation Store Indexed with FTS5 search GRAPH memory_edges Multi-Relational Links Semantic, temporal, causal, entity STATE laya_jev_state Canonical Summary System-1 state vector block LOCKED pinned_context Domain Invariants Bypasses all compaction BEAM EVALUATION QUERY BEAM SEARCH Adaptive Beam Retrieval (lib/jev_read.mjs · BEAM_W = 4) System 1 scores graph topology against user query in <48ms · Top 4 clusters retained BEAM_W = 4 PHASE 1 4 Graph Views Projected Evaluates query across semantic, temporal, causal & entity subgraphs PHASE 2 System 1 Scorer (Laya) Fast non-autoregressive scoring Selects top 4 high-relevance clusters PHASE 3 Compact Synthesis Assembles: Pinned Invariants + Evidence Beam + Tail (Last 2 turns) COMPACT PROMPT TO SYSTEM 2 IMPACT 70% to 85% Context Token Reduction · Zero Lost Invariants Eliminates quadratic TTFT latency and prevents prompt drift across 50+ turns Guarantees 100% domain invariant grounding throughout long engineering sessions 85% Prompt Reduction Zero Lost Invariants

Jev-Mem organizes development discoveries into a multi-relational graph with four distinct edge types:

  1. Semantic Edges: Linking concepts that share technical meaning (such as a database schema and its corresponding migration script).
  2. Temporal Edges: Tracking the chronological order of file mutations and command runs.
  3. Causal Edges: Connecting actions directly to their consequences (such as a specific edit causing a specific test assertion to fail).
  4. Entity Edges: Mapping shared symbols, class names, and configuration variables.

Adaptive Beam Retrieval

Before each System-2 prompt is composed, Jev-Mem runs an adaptive beam-search retrieval (lib/jev_read.mjs). System 1 evaluates the user prompt against the graph, scores candidate nodes, and selects a tight beam of the four most relevant evidence clusters (BEAM_W = 4).

System 2 receives:

  1. The canonical System 1 state block.
  2. The retrieved evidence beam.
  3. Only the last two conversation turns.

This cuts prompt prefill tokens by 70% to 85%, ensuring lightning-fast responses and laser-sharp focus even after fifty consecutive turns.

Pinned Domain Invariants

Certain facts must never be subject to summarization or forgetting. In energy systems engineering, these include telemetry schemas (ODSE), grid safety limits, and architectural rules.

Nehanda CLI stores these in a dedicated SQLite table called pinned_context. Pinned blocks bypass all compression routines and are attached verbatim to every model prompt. This guarantees that critical domain constraints remain permanently grounded throughout long engineering sessions.


3. Controlling Smaller Local Models: Deterministic SDLC vs. Generative Drift

The open-source AI community has produced remarkable local models in the 7-billion to 27-billion parameter range, including models like Nehanda v3.1. These models possess impressive code-generation capabilities, run entirely on local workstations, and keep proprietary source code private.

However, smaller local models exhibit a major vulnerability: they are easily overwhelmed when forced to manage their own software development lifecycle.

SDLC CONTROL PARADIGMS — GENERATIVE DRIFT VS DETERMINISTIC GOVERNANCE Why prompt-based discipline fails on smaller local models, and how deterministic state machines enforce engineering rigor PROMPT-ONLY AUTONOMY The Generative Drift Trap (Single-Model Prompting) Prompting a local model to "follow good practices" breaks down under complex multi-turn execution Probabilistic Drift • Mock Theater (Hallucinated Test Pass) When a test fails, the model edits the test or claims passes in text output without actually executing the test runner • Premature Implementation Eager to answer, the model mutates production code before diagnosing root cause or creating a reproduction test suite • Exploration Spinlocks Without hard bounds, loops reading identical files repeatedly, burning through context budgets without reaching a diagnosis • Ghost Refactoring & Context Amnesia Introduces unrequested edits, strips existing comments, and gradually drifts away from the original issue specification VERSUS DETERMINISTIC GOVERNANCE Nehanda's Deterministic Governance Engine 11-phase state machine in Node.js & SQLite · The model has zero vote on state transitions lib/workflow.mjs • Physical Tool Masking In explore, only read tools are exposed (Read, Glob, Grep). Code writing is impossible; writes locked to tests in create_tests. • The Model Has Zero Vote on Transitions Model text cannot advance state. Transitions require verified runtime test exit codes and immutable SQLite audit rows. • Hard Provenance: Verified Runner Exit Codes Planning unlocks only after non-zero exit code proves defect (RED). Verification requires that identical test suite to exit 0 (GREEN). • Automated Safety Checkers & Coverage Gate Clean passes required from 3 static checkers (JS, Shell, Python) plus verified >= 70% production code branch coverage. ENFORCED 11-PHASE SDLC STATE MACHINE SEQUENCE: idle → explore → diagnose → create_issue → create_tests → planning → implement → verify → safety → confirm_fix → done

The Trap of Generative Autonomy

When an agent framework gives a local model broad autonomy and relies on system prompt instructions like “be a good software engineer and write tests first,” the model suffers from generative drift:

The Solution: Deterministic State Machine in Code

Nehanda CLI recognizes that engineering discipline must be enforced deterministically by software, not left to probabilistic model choice.

In Nehanda CLI, the software development lifecycle is governed by an 11-phase state machine implemented directly in Node.js (lib/workflow.mjs) and SQLite:

\[\text{idle} \rightarrow \text{explore} \rightarrow \text{diagnose} \rightarrow \text{create\_issue} \rightarrow \text{create\_tests} \rightarrow \text{planning} \rightarrow \text{implement} \rightarrow \text{verify} \rightarrow \text{safety} \rightarrow \text{confirm\_fix} \rightarrow \text{done}\]

The Model Has No Vote on State

A critical rule governs Nehanda CLI: model text cannot authorize a phase transition.

The model cannot say “I verified the fix, let’s complete the task.” Transitions are governed solely by verifiable runtime evidence recorded in SQLite:

  1. Physical Tool Masking: The engine physically hides prohibited tools based on the active phase. In explore, the model only has access to read-only discovery tools (Read, Glob, Grep). Writing or editing production code is physically impossible. In create_tests, write access is strictly confined to test directories.
  2. Verified Test Failures (RED): The engine will not allow a transition to the planning phase until SQLite records genuine proof of a failing behavioral test from an actual test runner. A simple command error or syntax typo does not count.
  3. Verified Test Passes (GREEN): To transition to verification, the original test that failed must now pass against the current production code snapshot.
  4. Automated Safety Checkers: Moving from safety to confirm_fix requires clean reports from three static checkers (JavaScript, Shell, and Python) plus verified $\ge 70\%$ branch coverage across all modified production code.
  5. Human Operator Approval: Code mutations in planning and final sign-off in confirm_fix require explicit human operator confirmation.

Summary: Complementary Strengths

By stripping procedural governance away from the language model and giving it to an immutable state machine, Nehanda CLI turns smaller open-weights models into disciplined software engineers:

Responsibility Handled By Method
Fast Reflexes & Classification System 1 (Laya 421M) Non-autoregressive forward pass (~48ms)
Code Synthesis & Reasoning System 2 (Generative LLM) Autoregressive reasoning within strict bounds
Long-Term Memory Retrieval Jev-Mem Plane Multi-relational graph + adaptive beam search
Critical Domain Rules pinned_context Immutable database attachment to all prompts
Workflow Governance & Safety 11-Phase SDLC Engine Deterministic state machine & physical tool masks

This hybrid design gives developers the speed and privacy of local models with the rigor, auditability, and safety demanded by enterprise software engineering.