# Etta Cognitive Os

> >

- **Type:** Skill
- **Install:** `agentstack add skill-bluem-dev-etta-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bluem-dev](https://agentstack.voostack.com/s/bluem-dev)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bluem-dev](https://github.com/bluem-dev)
- **Source:** https://github.com/bluem-dev/Etta/tree/main/skill
- **Website:** https://github.com/bluem-dev

## Install

```sh
agentstack add skill-bluem-dev-etta-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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):

```python
# 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

| Failure | Response |
|---|---|
| Critic rejection | Retry Decision Engine (max 3 iterations, then escalate) |
| Execution failure | Rollback transaction, log to failure memory |
| State desync | Rehydrate from last valid version |
| Memory corruption | Skip entry, log deprecation |
| LLM parse error | Re-prompt with explicit JSON schema |

---

## 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bluem-dev](https://github.com/bluem-dev)
- **Source:** [bluem-dev/Etta](https://github.com/bluem-dev/Etta)
- **License:** MIT
- **Homepage:** https://github.com/bluem-dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bluem-dev-etta-skill
- Seller: https://agentstack.voostack.com/s/bluem-dev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.