Skip to content

README.md

Latest commit

 

History

History
310 lines (233 loc) · 14.1 KB

README.md

File metadata and controls

310 lines (233 loc) · 14.1 KB
Raw

Zouroboros — Self-Enhancing AI Platform

CI Release v2.0.0 npm License: MIT Zo Computer

Overview

Zouroboros is a self-enhancing AI platform built natively on Zo Computer. It provides production-grade multi-agent orchestration, persistent memory, and autonomous self-healing — all in a unified monorepo. Every module is native to the Zo ecosystem, not ported from external platforms.

Key Features

  • Hybrid Memory System — SQLite + vector embeddings with episodic, procedural, and cognitive memory. Domain context injection bridges operational knowledge into swarm tasks.
  • Swarm Orchestration (v5) — Multi-agent DAG execution with 5 executors (Claude Code, Gemini, Codex, Hermes, Mimir), adaptive routing (6-signal core with budget/role-aware 8-signal path), MetaGPT SOP coverage across all 57 roles, trace_id end-to-end observability, executor retry/fallback cascades, and mandatory pipeline gates.
  • Transport Abstraction — Bridge, ACP (Agent Client Protocol), and Mimir transports with real-time streaming where supported, enabling communication with executor backends and the memory gate.
  • Resilience-First — Category-aware circuit breakers (8 failure types), cascade failure propagation with 4 recovery policies, stagnation detection with auto-recovery, and 5-layer loop guards (ECC-009).
  • Pipeline Gates — Mandatory seed validation, post-flight evaluation, and gap audit loops enforce quality at every stage of swarm execution.
  • Consensus Gate — Multi-vendor validation (GLM-5.1, Kimi-K2.6, MiniMax-M2.5 in parallel) gates procedure evolution before commits; structured objection classification (PATCH_SPECIFIC / PRE_EXISTING / OUT_OF_SCOPE) separates signal from noise.
  • RAG Enrichment — OpenAI embeddings (text-embedding-3-small) + Qdrant vector search across 5 RAG surfaces (swarm, vault, autoloop, eval, persona) with RAPTOR L1/L2 hierarchical retrieval over the research corpus.
  • Budget Governance — Per-executor token tracking with USD conversion, alert thresholds, hard caps, and automatic cost-aware executor downgrade.
  • Role Registry — 57 seeded roles mapped from personas to executors, with hierarchical delegation and write scope isolation for child tasks.
  • Persona Framework — SOUL/IDENTITY architecture with 8-phase creation workflow and persona-scoped fact storage.
  • Spec-First Development — Interview, three-stage evaluate with Self-RAG token enrichment, gap audit (4 checks), unstuck, and autoloop tools.
  • Self-Healing — Daily introspection, prescription, and autonomous evolution with 8 playbooks (A–H), Reflexion failure critique, and a governor safety gate.
  • Health Council — Four autonomous watchers (Healer, Doctor, Introspector, Steward) monitor runtime, orchestration, capability, and knowledge layers with zero overlap.
  • API Server — Hono REST API with SSE event streaming for real-time budget, heartbeat, and task events.
  • Heartbeat Scheduler — Persistent wake cycles with SQLite state for long-running swarm campaigns.

Architecture

Zouroboros Architecture

The architecture is organized into 5 layers:

Layer Components
Interface orchestrate-v5 CLI, Hono REST API, SSE Event Stream, TUI dashboard, scheduled agents
Core Systems Memory System, Swarm Orchestration, Workflow Tools
Execution & Intelligence Executor System (5 executors, Bridge/ACP/Mimir transports), adaptive routing, RAG Enrichment (Qdrant, 5 surfaces, RAPTOR L1/L2)
Resilience & Governance Pipeline gates, Cascade Manager, Stagnation Detector, Budget Governor, Consensus Gate
Foundation Personas & Role Registry (57 roles), Self-Heal Engine (8 playbooks), Health Council, Heartbeat Scheduler

Quick Start

Install from npm

# Core types and utilities
npm install zouroboros-core

# Memory system (SQLite + vector embeddings)
npm install zouroboros-memory

# Multi-agent swarm orchestration
npm install zouroboros-swarm

# Spec-first workflow tools
npm install zouroboros-workflow

# Self-healing pipeline
npm install zouroboros-selfheal

# Persona framework
npm install zouroboros-personas

# RAG enrichment toolkit
npm install zouroboros-rag

# CLI (global install)
npm install -g zouroboros-cli

Or install everything:

npm install zouroboros-core zouroboros-memory zouroboros-swarm zouroboros-workflow zouroboros-selfheal zouroboros-personas zouroboros-rag

Prerequisites

  • Node 20+ and pnpm 9+ (or bun 1.x) for source installs.
  • OPENAI_API_KEY — required for vector search, HyDE expansion, and graph cohesion. Embeddings use text-embedding-3-small via the OpenAI API.
    • If unset, Zouroboros soft-degrades to text/FTS-only memory with a one-time warning. SQL fact storage and full-text search continue to work; semantic retrieval is skipped.
    • Set ZOUROBOROS_VECTOR_FORCE=1 to bypass the gate when proxying embeddings through a non-OpenAI compatible endpoint.
  • At least one swarm executor binary if you plan to run multi-agent campaigns: claude, codex, gemini, or hermes. zouroboros doctor reports availability.

From Source

git clone https://github.com/marlandoj/zouroboros.git
cd zouroboros
pnpm install
pnpm run build
export OPENAI_API_KEY="sk-..."   # required for semantic retrieval
zouroboros init
zouroboros doctor

Skill Install (Zo Computer)

For distributing to other Zo Computers as standalone Bun scripts:

bun ~/Skills/zouroboros/scripts/install.ts
bun ~/Skills/zouroboros/scripts/doctor.ts

Packages

Package Version Description
zouroboros-core npm Types, config, utilities
zouroboros-memory npm Hybrid SQLite + vector memory with domain context injection
zouroboros-swarm npm v5 orchestration: DAG execution, 8-signal routing, MetaGPT SOP roles, trace_id observability, circuit breakers, pipeline gates, executor retry/fallback
zouroboros-workflow npm Interview, three-stage eval with Self-RAG tokens, gap audit, unstuck, autoloop
zouroboros-selfheal npm Introspection, prescription & evolution with 8 playbooks + Reflexion failure critique
zouroboros-personas npm SOUL/IDENTITY persona framework with scoped fact storage
zouroboros-rag npm RAG enrichment: OpenAI embeddings + Qdrant, 5 RAG surfaces, RAPTOR L1/L2 hierarchical retrieval
zouroboros-cli npm Unified CLI
zouroboros-tui npm Terminal dashboard

Swarm Orchestration

The swarm orchestrator runs multi-agent campaigns with mandatory quality gates:

Seed Spec → Seed Eval Gate → Execute DAG → Post-Flight Eval → Gap Audit Loop

Executor System

5 executors communicate through a transport abstraction layer:

Executor Transport Best For
Claude Code ACP Complex implementation, architecture
Gemini ACP Research, analysis, content
Codex ACP Code generation, refactoring
Hermes Bridge Autonomous investigation, web research
Mimir Mimir Historical context injection, institutional memory synthesis

Executors are selected via a 5-priority routing decision tree:

  1. Explicit executor ID in task
  2. Role-based resolution (57 seeded roles)
  3. Budget override (< 20% remaining → cheapest executor)
  4. 8-signal composite routing (capability, health, complexity, history, procedure, temporal, budget, role)
  5. Tag-based heuristic fallback

When an executor fails, the retry/fallback cascade automatically reroutes to the next healthy executor with circuit breaker protection (10-min cooldown on credit exhaustion).

Pipeline Gates

All three gates are enabled by default:

  • Seed Validation — Pre-execution audit for file paths, schema correctness, DAG conflicts
  • Post-Flight Evaluation — Success rate analysis with 50% threshold
  • Gap Audit Loop — 4-question validation: reachability, data prerequisites, cross-boundary state, eval-production parity

Resilience

  • Circuit Breakers — 8 error categories with distinct thresholds and cooldowns (rate_limited: 1 failure/60s, timeout: 2 failures/30s, permission_denied: 1 failure/300s)
  • Cascade Manager — 4 policies: abort_dependents, skip_dependents, retry_then_skip, isolate
  • Stagnation Detector — Monitors no_output, repetitive_output, progress_plateau, timeout_approaching
  • ECC-009 Loop Guard — 5-layer recursion prevention (origin headers, depth limits, cycle detection, chain timeout, circuit breaker)
  • Consensus Gate — GLM-5.1, Kimi-K2.6, and MiniMax-M2.5 run in parallel to validate procedure evolution; structured objection classification prevents premature commits

Usage

CLI

# Memory
zouroboros memory store --entity user --key preference --value "dark mode"
zouroboros memory search "technology preferences"

# Swarm campaigns
zouroboros swarm run --tasks campaign.json

# Workflow
zouroboros workflow interview --topic "Design a database schema"
zouroboros workflow evaluate --seed seed.yaml --artifact ./src
zouroboros workflow unstuck --signal "same error keeps happening"

# Persona creation
zouroboros persona create --name "Security Auditor" --domain security

# Self-healing
zouroboros heal introspect
zouroboros heal prescribe
zouroboros heal evolve

# Dashboard
zouroboros tui

Programmatic (TypeScript)

import { Memory } from 'zouroboros-memory';
import { SwarmOrchestrator } from 'zouroboros-swarm';

const memory = new Memory({ dbPath: './memory.db' });

await memory.store({
  entity: 'user',
  key: 'preference',
  value: 'TypeScript',
  category: 'preference',
  decayClass: 'permanent',
});

const results = await memory.search({ query: 'programming languages' });

const orchestrator = new SwarmOrchestrator();
await orchestrator.run({
  tasks: [
    { id: '1', persona: 'Backend Developer', task: 'Design API' },
    { id: '2', persona: 'Frontend Developer', task: 'Build UI', dependsOn: ['1'] },
  ],
});

Natural Language (Zo Chat)

Store in memory that I prefer TypeScript for backend development
Run a spec-first interview for building a REST API
Check my Zouroboros system health

Scheduled Agents

After installation, create scheduled agents from Zo Chat:

Create all Zouroboros agents from agents/manifest.json

This registers 5 agents on your Zo Computer:

  • Memory Embedding Backfill — indexes new facts nightly
  • Memory Capture — captures conversation facts
  • Unified Decay — runs memory decay and cleanup
  • Self-Enhancement Summary — daily introspect → prescribe → evolve
  • Vault Indexer — indexes workspace files into the knowledge graph

Configuration

# ~/.zouroboros/config.yaml
defaults:
  memory:
    dbPath: ~/.zouroboros/memory.db
    embeddingProvider: openai
    embeddingModel: text-embedding-3-small
    embeddingDimension: 1536
    vectorEnabled: true   # auto-disabled at runtime if OPENAI_API_KEY is unset
  swarm:
    localConcurrency: 8
    timeoutSeconds: 600
    routingStrategy: balanced  # fast | reliable | balanced | explore
    pipelineGates:
      seedValidation: true
      postFlightEval: true
      gapAudit: true

Development

git clone https://github.com/marlandoj/zouroboros.git
cd zouroboros
pnpm install
pnpm run build
pnpm test  # 757+ tests

Documentation

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License — see LICENSE for details.

Acknowledgments

  • Inspired by Q00/ouroboros for spec-first development patterns
  • Inspired by Karpathy's AutoResearch and 2ndBrain concepts for auto-loop and memory enhancements
  • Built natively on Zo Computer — try Zo Computer
  • Thanks to all contributors and the Zo community

Made with care for the Zo Computer ecosystem