Etta Cognitive OS — Skill Runtime

Etta Cognitive OS is a cognitive control layer that sits between user input and LLM execution. It transforms probabilistic LLM reasoning into a structured, deterministic cognitive system.

Core principle: Claude thinks → Etta decides → Workspace executes.

System Architecture

USER INPUT
    │
    ▼
 LLM Core (Claude)           ← probabilistic reasoning, hypothesis generation
    │  structured JSON output only
    ▼
 Etta Cognitive Layer
    ├── Goal Engine           ← extract & hierarchize intent
    ├── State Engine          ← merge & track cognitive state (versioned)
    ├── Memory Engine         ← multi-tier persistence (fact/obs/decision/failure)
    ├── Decision Engine       ← propose actions with confidence scores
    ├── Critic Engine         ← validate decisions (hard gate — no bypass)
    ├── Compression Engine    ← prune redundant state
    └── Evolution Engine      ← adapt policies from history
    │
    ▼
 Workspace OS                ← sole executor of external effects
    ├── Permission Engine
    ├── Transaction Manager
    ├── Audit Logger
    └── Tool Interface Layer
    │
    ▼
 OUTPUT + STATE UPDATE

Authority hierarchy (highest → lowest): Protocol → Workspace OS → Execution Runtime → Etta Cognitive Layer → LLM Core → User Input

Core Execution Loop

Every Etta cycle follows this strictly ordered state machine:

INIT → LOAD_STATE → PLAN → DECIDE → VALIDATE → EXECUTE → COMMIT → COMPRESS → COMPLETE

Steps:

1. Ingest user input
2. Call LLM → get structured JSON output
3. Goal Engine → extract {goal, subgoals, priority, constraints}
4. State Engine → merge into versioned state object
5. Memory Engine → inject relevant memory snapshot
6. Decision Engine → propose {actions, rationale, confidence, hypothesis_branch}
7. Critic Engine → validate (HARD GATE — loop until valid or escalate)
8. Workspace OS → execute validated action transactionally
9. State Engine → commit state update + increment version
10. Memory Engine → write decision record (immutable append)
11. Compression Engine → prune redundant state
12. Return output

Invariants — never violate:

• No execution without Critic approval
• No state mutation outside State Engine
• No memory writes without schema validation
• No LLM → Workspace direct path (always through Etta Runtime)
• All actions must be logged and auditable

Implementation

Read references/implementation.md for full Python code covering:

• ClaudeBridge — LLM integration with structured JSON output enforcement
• StateEngine — versioned state merge and mutation
• MemoryEngine — JSONL append-only persistence
• DecisionEngine — action proposal with confidence scoring
• CriticEngine — validation gate with retry loop
• WorkspaceOS — transactional execution layer
• EttaRuntime — orchestration loop (run_cycle())
• main.py — CLI entrypoint

Read references/schemas.md for all canonical data schemas:

• Canonical State Object
• Memory Entry Schema
• Decision Object
• Global Message Envelope
• Event Contract
• Error Contract
• All Engine I/O Contracts

When Implementing Etta as a SKILL/Plugin

Minimal Viable Etta (context-window only, no persistence)

For LLM agents operating inside a single context window (e.g., Claude SKILL):

# Etta state lives as a structured dict injected into every prompt
etta_state = {
    "goal": "",
    "subgoals": [],
    "hypotheses": {"active": [], "rejected": []},
    "decisions": [],          # append-only
    "memory": {"facts": [], "observations": [], "failures": []},
    "constraints": [],
    "confidence": 1.0,
    "version": 0,
    "execution_state": "INIT"
}

Inject state into every LLM system prompt. Enforce JSON-only output. Run the Critic check inline before acting on any decision.

As a Claude SKILL

The SKILL prompt instructs Claude to:

1. Always begin a session by loading/initializing Etta state
2. Parse every user turn through the Goal Engine logic
3. Maintain state explicitly in its reasoning (or via tool/storage)
4. Apply Critic validation before outputting any action
5. Log decisions and failures to memory (JSONL or storage API)
6. Compress state when context fills up

As a Python Plugin / External Agent

Use the full implementation from references/implementation.md. Etta Runtime wraps any LLM call and enforces the cognitive loop externally.

Failure Handling

Key Design Rules

• Claude outputs JSON only — never free-text reasoning inside Etta loop
• State is the single source of truth — all engines read from and write to state
• Decisions are immutable — append-only, never deleted
• Failures cannot be deleted — only deprecated (they inform Critic calibration)
• Workspace is the sole executor — no engine bypasses it
• All communication is schema-validated — reject partial or untyped messages