Portfolio
MERLIN

Intelligence compiles.
Execution is deterministic.

MERLIN is a four-layer cognitive architecture that converts natural-language intent into controlled, auditable system actions. The LLM is a compiler — not a controller. Every plan is validated before a single action is taken.

$pip install merlin-assistant
View Source

48

Executable Skills

across 7 domains

<100

Milliseconds

reflex path latency

4

Cognitive Layers

strict separation

10

Dashboard Pages

full system visibility

Architecture

Four layers. Strict boundaries.

Intelligence never touches execution. Execution never reasons. Every layer has one job and enforced contracts at its boundaries.

01

Perception

The Senses

Multi-modal input handling — text, voice, Telegram, dashboard — with explicit cancellation semantics. Typing aborts voice. No race conditions.

Perception OrchestratorConversation FrameSTT Engine
02

Nervous System

The Router

BrainCore acts as a circuit breaker. It structurally analyzes every input and decides: is this a simple command or a complex intent? Simple commands never touch the LLM.

BrainCoreReflex EngineStructural AnalyzerAttention Manager
03

Mission Cortex

The Compiler

The LLM is used exactly once — as a compiler. It translates intent into a validated DAG with typed skill arguments. After compilation, the plan is frozen. No re-interpretation.

Cognitive CoordinatorCortex CompilerLLM RouterEscalation Policy
04

Execution Layer

The Physiology

Pure deterministic execution. Walks compiled DAGs, fires skills with enforced contracts, handles failures with bounded three-tier recovery. No LLM in the loop.

Mission ExecutorSkill RegistryTick SchedulerDecision Engine

Execution Flow

Where intelligence ends. Where determinism begins.

Most AI systems use the LLM at every step. MERLIN uses it at exactly two. Everything else is compiled, validated, and executed deterministically.

Deterministic — no LLM
LLM involved
User Input
Perception
BrainCore Router— routes to fast or complex path
↳ simple command
Reflex Engine
↳ complex intent
Cognitive Coordinator
Mission Cortex
Mission Executor
Recovery Loop
World Timeline

Engineering Decisions

What most AI agents do — and why MERLIN doesn't.

Dimension
Typical Agent
MERLIN
Execution model
ReAct loop — reason → act → observe → repeat
Compile once → execute deterministically → recover bounded
LLM usage
Every step invokes the LLM
LLM used at exactly 2 points — coordinator and compiler
Failure recovery
Ask LLM to figure it out (unbounded)
Three-tier bounded recovery: inline (max 2) → post-exec → recompile (max 1)
State management
Scattered mutable state across components
Append-only WorldTimeline → pure reducer → derived state
Skill invocation
LLM generates function calls with hallucinated args
Validated contracts — args checked before execution begins
Scheduling
Re-parse natural language when schedule fires
Compiled execution graph stored and fired as-is

System Laws

Enforced. Not aspirational.

These aren't guidelines — they're architecturally enforced at every layer. Violations are compile-time errors, not runtime hopes.

No global mutable state

WorldTimeline is append-only. State is derived.

Skills are isolated

No inter-skill calls. No DAG modification at runtime.

One LLM call per plan

Cortex compiles once. No reasoning loops.

Intelligence ≠ Infrastructure

Cortex cannot access OS, browser, or filesystem.

Failures are bounded

Max 2 inline recoveries per node. Max 1 recompile.

Proof

A compiled plan. A live trace. 48 skills.

mission_plan.jsonIR v1
{
  "id": "mission_a7f3c",
  "nodes": [
    {
      "id": "n1",
      "skill": "system.set_volume",
      "inputs": {
        "level": 40
      },
      "depends_on": [],
      "mode": "foreground"
    },
    {
      "id": "n2",
      "skill": "system.set_brightness",
      "inputs": {
        "level": 70
      },
      "depends_on": [],
      "mode": "foreground"
    }
  ],
  "metadata": {
    "ir_version": "1.0",
    "parallel": true
  }
}
execution_trace.log850ms total
00:00.000[INPUT]Percept: 'Set volume to 40 and brightness to 70'
00:00.003[BRAIN]BrainCore → MISSION (multi-skill)
00:00.015[COORD]Coordinator → SKILL_PLAN
00:00.820[CORTEX]Compiled → 2 nodes, parallel
00:00.825[VALID]Contracts validated ✓
00:00.830[EXEC]Launching 2 parallel nodes
00:00.842[SKILL]n1: set_volume(40) → OK
00:00.847[SKILL]n2: set_brightness(70) → OK
00:00.850[DONE]Mission complete — 850ms

⚡

System

19

volume, brightness, apps, battery, media

🌐

Browser

12

click, navigate, scroll, autonomous task

📧

Email

5

read inbox, draft, send, search

📁

Files

5

read, write, search, create folder

🧠

Memory

4

preferences, facts, policies

💬

WhatsApp

2

send message, send file

🔮

Reasoning

1

generate text

View on GitHub
$ pip install merlin-assistant
← Back to portfolio