SEA - Self-Evolving Agent

An autonomous research agent that produces tagged knowledge stores from complex questions. You give it a problem. It decomposes it into sub-questions, dispatches specialised expert personas, kills bad ideas, finds cross-domain connections, and tells you what it doesn't know.

What it actually produces

On its first real-world project — designing a neutral freight capacity exchange for South Africa — SEA ran 20 iterations and produced:

262 tagged findings (126 verified with source URLs, 136 provisional with reasoning chains)
23 research questions autonomously generated and resolved (plus 2 flagged as requiring real-world data)
Convoy autopsy — identified why a $900M startup failed and used it as a kill-check for every subsequent design decision
4 architectures evaluated, 3 killed — data cooperative (cartel risk), open standards (doesn't solve trust), smart contracts (blockchain is a tool, not a product)
Visa cold-start playbook — mapped 7 of Visa's cold-start mechanisms to the freight problem after a human asked one question
7.5/10 confidence architecture with explicit assumptions, kill-checks, and testable next steps

Browse the full example output: examples/sa-freight-exchange/

How it works

SEA has two operating modes:

Conductor mode (recommended)

The two-loop architecture selects questions, creates bespoke expert personas, and dispatches research autonomously.

Terminal
  sea conduct <project>             thin CLI, runs until goal met
        |
        |  OUTER LOOP (Conductor)
        |
        |-- LLM "SELECT..."            reads knowledge frontier
        |   picks highest-value          ranks by info gain, feasibility,
        |   open question                domain data density
        |
        |-- LLM "CREATE..."            fresh context window
        |   crafts expert persona        200-300 lines, 6-section anatomy
        |   from creation framework      the "80% investment"
        |
        |   INNER LOOP (Expert)
        |   |-- LLM "RESEARCH..."       1-5 iterations
        |   |   plan → search → synth    until convergence or exhaustion
        |   |   writes findings           epistemic tags on every claim
        |   '-- converge? loop or exit
        |
        |-- LLM "INTEGRATE..."         validates + persists
        |   merges into knowledge store  deduplicates, checks contradictions
        |   updates summary              tracks goal progress
        |
        |-- (every ~3 iters) META       evolves the conductor itself
        |
        '-- repeat until goal met

Pipeline mode

The original 6-step pipeline for single-project deep-dive iterations with self-evaluation and persona evolution.

Terminal
  sea loop <project>                thin CLI, runs forever
        |
        |-- PLAN      → research plan from goal + knowledge
        |-- RESEARCH   → web search, source gathering
        |-- SUMMARIZE  → persist findings to knowledge store
        |-- SYNTHESIZE → write report from knowledge
        |-- EVALUATE   → score output (uses Sonnet for Axiom 1 separation)
        |-- EVOLVE     → improve persona (3 candidates, novelty-scored)
        |
        '-- repeat, auto-rollback on regression

First-principles reasoning

When a project's knowledge store is mature (≥5 verified findings in a domain), the conductor can dispatch reasoning experts instead of research experts. These derive novel conclusions from existing findings rather than searching the web.

Three reasoning question types:

Type	What it does	Iter cap	Search budget
`first-principles`	Derive from axioms + verified findings (cost models, mechanism predictions, feasibility calculations)	3	1 (validation only)
`design-space`	Map solution space from constraints, generate ≥3 approaches with trade-off analysis	4	2 (validation only)
`divergence` (EXPERIMENTAL)	Structured white-space provocation at governing-principle level — Subtraction + Integrative techniques ported from MAESTRO	3	4

Reasoning experts produce [DERIVED] findings with a derivation chain — machine-readable premises, method, assumptions, and uncertainty notes:

{
  "claim": "Binder cost R455/t at Mpumalanga plant",
  "tag": "DERIVED",
  "source": null,
  "derivationChain": {
    "premises": ["F255: mix ratio", "F260: transport cost", "F166: FA source"],
    "method": "estimation",
    "assumptions": ["R1.00/t-km road transport", "FA grinding R150/t"],
    "uncertaintyNote": "Grinding cost uncertain (R100-250/t range)"
  }
}

Guard rails against hallucination-as-reasoning:

Every conclusion must trace to stated premises (derivation chain integrity)
DERIVED findings only graduate to verified when all premises are themselves verified (trust cascade)
Confidence threshold is stricter: 0.90 vs 0.85 for SOURCE findings
Low iteration caps prevent runaway speculation (3 iterations max)
Store prerequisites ensure reasoning starts from solid empirical ground

The conductor dispatches reasoning experts automatically when it detects questions that need derivation rather than lookup — or you can tag a question with questionType: "first-principles" directly.

Two-speed evolution

Layer	File	Evolves	Purpose
Conductor	`CLAUDE.md` or `AGENTS.md`	Every ~3-5 iterations	Orchestration protocols, meta-strategies
Expert Persona	`projects/{name}/persona.md`	Every iteration	Domain expertise, heuristics, strategies

The conductor learns meta-lessons slowly across projects. Expert personas adapt rapidly to each project's domain. The conductor playbook filename matches the active provider (CLAUDE.md for Claude Code, AGENTS.md for Codex).

Current capabilities (v0.3)

Wave	Feature	What it does
7	Cross-model evaluate	Evaluate step uses Sonnet while all other steps use Opus. Axiom 1: separate producer from evaluator.
7	Structured spans	Every step records timing, token counts, and findings to `metrics/spans.jsonl`. Credit assignment analysis.
7	Success/failure patterns	High-IG dispatches auto-record strategy. Both success and failure patterns feed into expert creation.
7	Novelty pressure	Evolution generates 3 candidates scored on `performance0.7 + novelty0.3`. Diversity budget every 5th iteration.
7	Expert library	Scores and reuses high-performing personas. Adapts existing persona instead of creating from scratch.
8	Engineering wiki	Per-project Obsidian-compatible wiki generated from findings. Domain-grouped index with fact/relationship/decision nodes.
8	Global wiki	Cross-project promotion of verified findings. New projects seed from the global wiki.
8	Audit command	Integrity checks on findings, wiki consistency, question convergence, and efficiency metrics.
8	Convergence detection	Advisory signals for the conductor loop — detects when the knowledge frontier is mapped.
9	First-principles reasoning	Derive novel conclusions from verified findings instead of web search. Derivation chains with trust cascade.
9	Design-space analysis	Map solution spaces from constraints. Generate 3+ approaches with trade-off analysis.
9	Trust cascade graduation	DERIVED findings only graduate when ALL premises are verified. Prevents hallucination-as-reasoning.
Infra	Store clobber guard	Pre-integration snapshot; auto-restore on zero-out, >50% loss, or verified-finding removal. Closes iter-18 clobber class of bugs.
Infra	Selection guards	Pre-dispatch code enforcement: non-open re-dispatch swap, type-mismatch correction, 3rd-consecutive same-type block.
Infra	Question caps	Post-integration trim: per-type queue cap, iter-boundary caps (12/15/18/20), per-dispatch new-question cap.
Infra	Lineage writer	Deterministic `lineage/changes.jsonl` entry every iteration — no silent drift.
Infra	SOURCE-URL gate	`[SOURCE]` findings downgrade to `[UNKNOWN]` if no valid http(s) URL; `needsReview` blocks graduation on URL/claim mismatch.
Infra	Summary freshness	Deterministic store-derived fallback when `summary.md` is stale or missing.
Exp	Divergence question type	Ported from MAESTRO — structured white-space provocation (Subtraction + Integrative) at governing-principle level. EXPERIMENTAL.

Quick start

Prerequisites

Node.js 20+
At least one supported LLM CLI:
- Claude Code (claude command) — default
- OpenAI Codex CLI (codex command)

Install

git clone https://github.com/Loodt/sea.git
cd sea
npm install

Create a project

npx tsx src/cli.ts new my-research

Answer the discovery questions (goal, success criteria, domain, source preferences, output format). SEA creates:

projects/my-research/
  goal.md              problem statement + acceptance criteria
  persona.md           expert persona tailored to your domain
  state.json           iteration tracker
  knowledge/           structured findings store (JSONL)
  experts/             per-dispatch expert personas
  expert-library/      persona reuse with utility scores
  references/          all sources (links, PDFs, notes)
  experiments/         what was tried + results + WHY analysis
  traces/              raw execution logs with timing
  reflections/         scored evaluations per iteration
  metrics/             scores + spans + conductor metrics (JSONL)
  lineage/             what changed, why, before/after scores
  output/              final deliverables

Run with conductor (recommended)

npx tsx src/cli.ts conduct my-research

The conductor selects questions, creates expert personas, dispatches research, and integrates results. Walk away — it runs until your goal criteria are met.

Run with pipeline

npx tsx src/cli.ts loop my-research

The pipeline runs plan → research → summarize → synthesize → evaluate → evolve in a loop. The evaluate step uses Sonnet by default (Axiom 1 separation).

Commands

sea new <project>                    # interactive project creation
sea conduct <project>                # two-loop conductor (recommended)
sea dispatch <project>               # single conductor iteration
sea loop <project>                   # continuous pipeline loop
sea run <project>                    # single pipeline iteration
sea status [project]                 # show current state and scores
sea history <project>                # evolution timeline with scores
sea wiki <project>                   # generate/update engineering wiki from findings
sea global-wiki [project]            # promote verified findings to cross-project wiki
sea global-experts [project]         # promote high-scoring expert personas across projects
sea audit <project>                  # integrity audit: findings, wiki, questions, convergence
sea rollback <project> [version]     # restore persona to earlier version
sea rollback conductor [version]     # restore conductor to earlier version

# Use a different provider
sea --provider codex conduct <project>
SEA_PROVIDER=codex sea conduct <project>

Replace sea with npx tsx src/cli.ts until you build and link globally.

Key options

Flag	Commands	Default	Purpose
`--provider <name>`	all	claude	LLM backend: `claude` or `codex`
`-c, --cooldown <seconds>`	conduct, loop	30	Pause between iterations
`-m, --max <n>`	conduct, loop	unlimited	Stop after N iterations
`-e, --expert-max <n>`	conduct, dispatch	5	Max expert inner iterations
`--meta-every <n>`	conduct, loop	3 / 5	Conductor/meta evolution frequency
`--evaluate-model <model>`	run, loop, conduct, dispatch	sonnet	Model for evaluate step (Axiom 1)

Architecture

sea/
  CLAUDE.md / AGENTS.md        THE CONDUCTOR - evolving playbook (provider-dependent)
  conductor-history/           every version of the conductor playbook
  failure-patterns/            cross-project failure library
  success-patterns/            cross-project success library (gitignored — domain-specific)
  eval/
    rubrics.md                 5-dimension scoring rubrics
    integrity.md               10 truthfulness axioms (evolvable)
  templates/
    expert-creation-framework.md   6-section persona anatomy
  src/                         TypeScript CLI
    cli.ts                     command dispatcher
    conductor.ts               outer loop orchestration
    expert-loop.ts             inner loop iteration
    expert-factory.ts          persona creation + library lookup
    expert-library.ts          persona scoring and reuse
    global-expert-library.ts   cross-project persona promotion
    selection-guards.ts        pre-dispatch: non-open, type-mismatch, same-type cap
    question-caps.ts           post-integration: type queue / iter-boundary / per-dispatch caps
    store-snapshot.ts          pre-integration snapshot + clobber auto-restore
    knowledge.ts               findings + questions JSONL store + graduation gates
    wiki.ts                    engineering wiki generator (per-project)
    global-wiki.ts             cross-project wiki promotion/seeding
    audit.ts                   integrity auditor (findings, wiki, questions)
    metrics.ts                 scores + spans + convergence detection
    context.ts                 prompt assembly for pipeline steps
    conductor-context.ts       prompt assembly for conductor steps
    runner.ts                  spawn LLM CLI sessions (claude/codex)
    loop.ts                    pipeline iteration flow
    safety.ts                  regression detection + rollback
    versioner.ts               snapshot/restore
    file-lock.ts               atomic JSONL read/write via proper-lockfile
    discovery.ts               interactive project setup
    integrity.ts               knowledge store validation
    pattern-filter.ts          domain/question-type filtering for patterns
    hybrid-agent.ts            legacy v035 hybrid pipeline (retained for back-compat)
    types.ts                   all interfaces + defaults
  global-wiki/                 cross-project verified findings (gitignored)
  projects/
    {name}/
      goal.md                  problem statement
      persona.md               expert persona (evolves every iteration)
      persona-history/         every version of persona.md
      knowledge/
        findings.jsonl         structured fact store with lifecycle
        questions.jsonl         open research frontier
        summary.md             compressed state (max 2KB)
      wiki/                    engineering wiki (Obsidian-compatible)
        index.md               domain-grouped finding index
        facts/                 MEASUREMENT + STANDARD nodes
        relationships/         DERIVED nodes
        decisions/             DESIGN nodes
        assumptions/           ASSUMPTION + HYPOTHESIS nodes
        manifest.json          content-hash diffing state
      experts/                 per-dispatch expert personas
      expert-library/          persona reuse library (JSONL)
      metrics/
        scores.jsonl           pipeline score trajectory
        spans.jsonl            structured timing per step
        conductor-metrics.jsonl dispatch outcomes
      lineage/changes.jsonl    evolution decisions
      traces/                  raw session output
      reflections/             scored evaluations
      output/                  deliverables + audit reports

Knowledge layer

Every finding carries a lifecycle and epistemic tag:

Tags: [SOURCE] (URL-backed), [DERIVED] (computed/reasoned), [ESTIMATED] (judgment), [ASSUMED] (untrusted), [UNKNOWN] (honest gap)
Lifecycle: provisional → verified or refuted/superseded
- SOURCE graduation: confidence ≥ 0.85, URL present, age ≥ 3 dispatches, not contradicted
- DERIVED graduation: confidence ≥ 0.90, derivation chain present with ≥ 2 verified premises, age ≥ 3 dispatches (trust cascade)
Questions: open → resolved (by finding ID), deferred, or empirical-gate (needs physical measurement)

Scoring rubrics

Pipeline iterations are scored on five dimensions (1-10):

Dimension	Weight	What it measures
Accuracy	0.25	Factual correctness, proper sourcing
Coverage	0.20	Breadth of relevant topics addressed
Coherence	0.15	Logical flow, structure, readability
Insight Quality	0.20	Novel connections, depth, actionability
Process Compliance	0.20	Artifacts, epistemic tags, references

For reasoning types (first-principles, design-space), Insight Quality increases to 0.30 and Coverage drops to 0.10 — depth of derivation matters more than breadth.

If the rolling 3-iteration average drops >15%, the persona auto-rollbacks to the previous version.

Design principles

Never delete anything. Every mutation snapshots the old file. Full audit trail.
Persona is strategy. 80% of research quality comes from expert persona fit. The creation framework is the core investment.
Exhaustion is knowledge. When a question exhausts, the negative result becomes a structured finding documenting what was searched.
Structure over rules. Constraints are architectural (iteration caps, separate scoring model, staged workflow) not instructional.
Kill fast, invest slow. Question types have iteration caps (first-principles: 3, divergence: 3, design-space: 4, others: 5) to prevent wasted iterations.
Think, don't just search. When the knowledge store is rich enough, reasoning experts derive novel conclusions from verified findings instead of dispatching more web searchers.
Learn bidirectionally. Both failure patterns AND success patterns feed into expert creation.
Knowledge compounds. Verified findings promote to a global wiki that seeds new projects.

Running SEA

SEA spawns LLM CLI sessions for each step — every session gets a fresh context window. The TypeScript CLI orchestrates files and the loop; all intelligence lives in the LLM sessions.

Supported providers

Provider	CLI	Conductor playbook	Example
Claude Code (default)	`claude -p`	`CLAUDE.md`	`sea conduct my-project`
OpenAI Codex	`codex exec`	`AGENTS.md`	`sea --provider codex conduct my-project`

When switching providers on an existing project, the conductor playbook is read from whichever file exists (falls back across providers). The first meta-evolution step writes the playbook to the new provider's native filename.

The simplest way to start

Open Claude Code (or Codex) in the sea/ directory:

cd sea
claude         # or: codex

Then:

Create a project called "lithium-recycling" with the goal below, then run
sea conduct for 5 iterations. Use npx tsx src/cli.ts to run commands.

Goal:
Find technically viable methods for recovering lithium from spent EV
batteries at >90% recovery rate. Compare hydrometallurgical vs
pyrometallurgical vs direct recycling routes.

The LLM will run sea new interactively, then start the conductor loop.

Monitoring

npx tsx src/cli.ts status my-research    # state + scores
npx tsx src/cli.ts history my-research   # evolution timeline

Or read files directly:

What you want to know	Where to look
Current knowledge	`knowledge/summary.md`
All findings	`knowledge/findings.jsonl`
Open questions	`knowledge/questions.jsonl`
Browsable wiki	`wiki/index.md` (Obsidian-compatible)
Cross-project findings	`global-wiki/manifest.jsonl`
Integrity issues	`output/audit-report.md`
Convergence status	`output/convergence-report.md`
Last iteration output	`output/`
How it was scored	`reflections/iter-NNN.md`
Persona evolution	`lineage/changes.jsonl`
Step timing	`metrics/spans.jsonl`

Roadmap

Research foundation

SEA synthesizes ideas from frontier AI agent research. Key influences:

Source	What SEA takes from it
ACE (Stanford/SambaNova)	Evolving playbook via execution feedback
HyperAgents (Meta AI)	Self-referential meta-agent that modifies its own improvement logic
Bilevel Autoresearch	Outer meta-loop that injects new code mechanisms at runtime
ARIS (Auto-claude-code-research)	Cross-model adversarial review for evaluation integrity
Agent Lightning (Microsoft)	Structured spans and credit assignment across trajectories
AgentEvolver / GEA	Novelty pressure in evolution to escape local optima
Memento-Skills	Skill libraries with utility scores

Full list of influences and what SEA takes from each: ACE, HyperAgents, Bilevel Autoresearch, Pattern Language, TurboQuant, ARIS, Agent Lightning, AgentEvolver, GEA, Memento-Skills, OpenSpace.

License

MIT

Name		Name	Last commit message	Last commit date
.claude/rules		.claude/rules
.github		.github
CLAUDE-history		CLAUDE-history
conductor-history		conductor-history
docs		docs
eval		eval
examples/sa-freight-exchange		examples/sa-freight-exchange
failure-patterns		failure-patterns
scripts		scripts
skills		skills
src		src
templates		templates
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

SEA - Self-Evolving Agent

What it actually produces

How it works

Conductor mode (recommended)

Pipeline mode

First-principles reasoning

Two-speed evolution

Current capabilities (v0.3)

Quick start

Prerequisites

Install

Create a project

Run with conductor (recommended)

Run with pipeline

Commands

Key options

Architecture

Knowledge layer

Scoring rubrics

Design principles

Running SEA

Supported providers

The simplest way to start

Monitoring

Roadmap

Research foundation

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

SEA - Self-Evolving Agent

What it actually produces

How it works

Conductor mode (recommended)

Pipeline mode

First-principles reasoning

Two-speed evolution

Current capabilities (v0.3)

Quick start

Prerequisites

Install

Create a project

Run with conductor (recommended)

Run with pipeline

Commands

Key options

Architecture

Knowledge layer

Scoring rubrics

Design principles

Running SEA

Supported providers

The simplest way to start

Monitoring

Roadmap

Research foundation

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages