fable-agent/README.md

# Fable Agent

**Harness-agnostic, model-agnostic, self-improving agent system — loops, dynamic workflows, routines.**

The harness, not the model. Swap any executor, any model, any provider — the system compounds regardless.

```
node dist/index.js demo
# 3 seconds. Research → Learn → Sharpen → Compound. Live data.
```

Every run leaves the next run smarter. Every state file accumulates. Every skill sharpens.

```bash
git clone https://github.com/movez/fable-agent
cd fable-agent
npm install
npm run build
node dist/index.js demo
```

```
┌──────────────────────────────────────────────────────────────────┐
│                    DREAM → ACT → VALIDATE → CODIFY                │
│                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌─────────────┐ │
│  │  DREAM   │ →  │   ACT    │ →  │ VALIDATE │ →  │   CODIFY    │ │
│  │  Sleep   │    │ Feedback │    │  Self-   │    │  Episodic   │ │
│  │  Reflect │    │  Loop    │    │ Validate │    │  Semantic   │ │
│  │  Extract │    │  Rubric  │    │  Vision  │    │  Procedural │ │
│  │  Sharpen │    │  Multi-  │    │  Check   │    │  Skills     │ │
│  │          │    │  Agent   │    │  Guard   │    │  State.md   │ │
│  └──────────┘    └──────────┘    └──────────┘    └─────────────┘ │
│         ↑                                              │        │
│         └────────────────── LOOP ──────────────────────┘        │
│              Every run starts from a higher baseline             │
└──────────────────────────────────────────────────────────────────┘
```

---

## Quick Start

```bash
# Install
git clone https://github.com/movez/fable-agent
cd fable-agent
npm install
npm run build

# See the system in action (no API keys needed)
node dist/index.js demo

# Run a task
node dist/index.js run "Review the auth module for security issues" --loop 5

# Web search via Exa (set EXA_API_KEY in .env or export it)
export EXA_API_KEY=your_key_here
node dist/index.js exa search "self-improving agent systems"

# Start the 24/7 daemon
node dist/index.js daemon start --detach
node dist/index.js daemon queue "Refactor error handling" --priority 1
node dist/index.js daemon status

# Manage skills
node dist/index.js skills list
node dist/index.js skills sharpen
node dist/index.js skills sync

# Measure compounding
node dist/index.js benchmark run
node dist/index.js learned
```

---

## Architecture — 14 Steps, 3 Tiers

### Tier 1: Foundation (Steps 1-3)

The durable layer that persists across sessions.

| Step | Module | Purpose |
|------|--------|---------|
| 1 | `session-engine.ts` | Days-long sessions with checkpoint/resume, heartbeat stall detection |
| 2 | `context-manager.ts` | Sliding window with priority summarization, token budget enforcement |
| 3 | `tool-orchestrator.ts` | Reliable tool dispatch with exponential backoff, timeout, validators |

### Tier 2: Primitives (Steps 4-12)

The three primitives that make the system compound.

**Loops (Steps 4-6):**
| Step | Module | Purpose |
|------|--------|---------|
| 4 | `feedback-loop.ts` | Phase machine: plan → execute → observe → reflect → refine |
| 5 | `state-accumulator.ts` | Append-only event log with aggregation, trend analysis, snapshots |
| 6 | `convergence-check.ts` | Diminishing returns, quality plateau, target-achieved detection |

**Workflows (Steps 7-9):**
| Step | Module | Purpose |
|------|--------|---------|
| 7 | `workflow-graph.ts` | DAG execution engine with topological sort, conditional branching |
| 8 | `adaptive-router.ts` | Epsilon-greedy branch selection, historical path scoring |
| 9 | `recovery-handler.ts` | Retry with backoff, fallback steps, graceful degradation |

**Routines (Steps 10-12):**
| Step | Module | Purpose |
|------|--------|---------|
| 10 | `skill-registry.ts` | CRUD for skill templates with versioning, tagging, search |
| 11 | `execution-engine.ts` | Deliberate practice execution with timing, validation, hooks |
| 12 | `routine-evolution.ts` | Analyze history, auto-suggest improvements, version bump |

### Tier 3: Compounding (Steps 13-14 + Meta)

| Step | Module | Purpose |
|------|--------|---------|
| 13 | `state-repository.ts` | Cross-session knowledge base with tagging, query, compaction |
| 14 | `skill-sharpener.ts` | Meta-review, quality gate, auto-apply improvements |
| — | `meta-agent.ts` | Orchestrator: select skill → execute → sharpen → store → compound |

---

## Upgrades — Fable 5 Elite Patterns

All modules in `src/upgrades/`.

| Pattern | Module | What It Does |
|---------|--------|-------------|
| Dreaming | `dreaming-system.ts` | Sleep → review → extract → distill → codify. Core compounding primitive. |
| Self-Validation | `self-validator.ts` | Wraps any executor with per-phase quality gates. High-effort reasoning. |
| Multi-Agent | `multi-agent.ts` | Orchestrator → specialists → collect → synthesize → verify. |
| Rubric Engine | `rubric-engine.ts` | N-criteria evaluation with weights, exit conditions, dynamic re-planning. |
| Persistent Memory | `persistent-memory.ts` | Episodic (what happened), semantic (what it means), procedural (how to). |
| Enhanced Meta | `enhanced-meta-agent.ts` | Full Dream → Act → Validate → Codify loop. |
| Vision Self-Check | `vision-self-check.ts` | Automated visual verification against goal via vision model. |
| Safety Boundary | `safety-boundary.ts` | Tier-aware routing, blocked model detection (Fable 5/Mythos 5). |
| Content Safety | `content-safety-gate.ts` | Classifies tasks by risk domain before the loop starts. |
| Prompt Boundary | `prompt-boundary-adapter.ts` | Restructures prompts to stay within classifier boundaries. |
| Decomposition Guard | `decomposition-guard.ts` | Detects jailbreak-by-decomposition across rolling query window. |
| Routine Scheduler | `routine-scheduler.ts` | Cron-like scheduled execution with task queue. |
| Goal Queue | `goal-queue.ts` | Persistent priority queue for daemon mode. |
| Daemon Engine | `daemon-engine.ts` | 24/7 autonomous operation. Pick → run → dream → loop. |
| Benchmark Runner | `benchmark-runner.ts` | Measures compounding metrics. Proves the system is learning. |
| PAI Adapter | `pai-adapter.ts` | Maps to PAIMM / TELOS / LifeOS framework. |
| GodMode Classic | `godmode-classic.ts` | Races model candidates in parallel and selects the best/first passing output. |
| UltraPlinian | `ultra-plinian.ts` | Scores outputs through a 5-tier composite evaluation pass. |
| Parseltongue | `parseltongue.ts` | Perturbs inputs and tests whether the content safety gate still catches them. |
| AutoTune | `auto-tune.ts` | Adapts sampling parameters from rubric-score feedback. |
| STM Pipeline | `stm-modules.ts` | Applies semantic transformation modules for tone, citations, structure, refusals, fact checks, and concision. |
| Abliteration Awareness | `abliteration-awareness.ts` | Detects and categorizes refusal patterns for escalation or reformulation. |
| Prompt Observatory | `prompt-observatory.ts` | Queryable catalog of known system prompt patterns. |
| Prompt Liberation | `prompt-liberation.ts` | Prompt-transparency metadata and constraint analysis without executing extraction attacks. |
| Transparency Module | `transparency-module.ts` | Records prompt hashes, routing decisions, parameters, and call summaries. |

---

## Model Routing

| Tier | Model | Use | Status |
|------|-------|-----|--------|
| Mythos | ~~Fable 5~~ | Orchestration | **Blocked** (June 12, 2026) |
| Opus | Opus 4.8 | Orchestration, vision, planning | Available |
| Sonnet | Sonnet 4.6 | Bounded subtasks, code review | Available |
| Haiku | Haiku | Grading, quick tasks | Available |
| Frontier | GPT-4.1 / o3 | Alternative orchestrator | Available |
| Local | Ollama / vLLM | Offline, cheap | Check status |

See `CONFIG.md` for full routing configuration.

---

## Executors

Plug any model into the `PhaseExecutor` interface:

```typescript
const sonnet = new SonnetExecutor({ apiKey: process.env.ANTHROPIC_API_KEY });
const result = await agent.run(task, { executor: sonnet });
```

Available in `src/examples/executors/`:
- `sonnet-executor.ts` — Claude Sonnet 4.6
- `openai-executor.ts` — GPT-4.1 / o3
- `local-executor.ts` — Ollama, vLLM, any OAI-compatible endpoint
- `composite-executor.ts` — Route different phases to different models
- `weak-to-strong.ts` — Bootstrap skills from weak model iterations

---

## CLI Commands

The runtime command surface is documented in [COMMANDS.md](/C:/Users/Artale/fable-agent/COMMANDS.md), which is kept in parity with `src/index.ts`.

```bash
fable-agent run <task>
fable-agent session start|resume|list|inspect <id>
fable-agent skills list|create|inspect|evolve|sync|sharpen
fable-agent pai <subcommand>
fable-agent daemon start|stop|status|queue
fable-agent fable5 <subcommand>
fable-agent fusion run|panels
fable-agent plinius <subcommand>
fable-agent generate image|video
```

### Docs parity

To avoid drift, any CLI change in `src/index.ts` should include:

- Command surface updates in [COMMANDS.md](/C:/Users/Artale/fable-agent/COMMANDS.md).
- Environment/runtime implications in [CONFIG.md](/C:/Users/Artale/fable-agent/CONFIG.md) if startup behavior changes.
- A one-line verification command in [STATE.md](/C:/Users/Artale/fable-agent/STATE.md) when major command behavior changes.

### Runtime bootstrap

- Environment loading happens at startup (`loadEnv()`).
- Load order: `.env`, `.env.<NODE_ENV>`, `.env.local`.
- Existing process env values always win over file values.

---

## The Key Insight

**It's the harness, not the model.** Fable 5 was built for this architecture — but the architecture works with any model. The harness accumulates context, state, and skills. The model just executes phases.

Every run compounds. Every failure adds a failure mode. Every success sharpens a skill. That's what makes it a self-improving system, not a prompted session.

Follow [movez.substack.com](https://movez.substack.com) for fresh AI alpha.