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

---

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

```bash
fable-agent run <task>          # Run a task through the system
fable-agent session start|list  # Manage autonomous sessions
fable-agent skills list|sharpen # Manage accumulating skills
fable-agent skills sync         # Sync SKILLS/ markdown with TS registry
fable-agent state               # View knowledge base
fable-agent status              # System overview
fable-agent daemon start|stop   # 24/7 autonomous daemon
fable-agent daemon queue <goal> # Add goals to daemon queue
fable-agent benchmark run       # Run benchmarks, measure compounding
fable-agent benchmark trend     # Show compounding trend over time
fable-agent cost report         # Show model usage costs
fable-agent workflow <file>     # Register a workflow DAG
```

---

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