Elution — Timer-Bound AI Research Loop for Code Optimization

Elution runs a timer-bound optimization loop inside your coding agent: subagents research → propose → review → implement → measure until the deadline, remembering everything in local BM25 memory. Born for the Yukon competition, works with any benchmark script.

npx skills add gdonninelli/elution   # the skill → your harness (table below)
pipx install elution                 # the memory + timer CLI (Python 3.13+, stdlib only)

/elution 120   # start a 120-minute loop

Why Elution

• Timer is the only stop rule. No iteration caps, no failure caps — the loop runs until elution deadline says expired.
• One change at a time. Each iteration proposes exactly one hypothesis, reviews it, and implements the smallest diff — no sprawling rewrites.
• Evaluator decides. Agents never score themselves; only yukon run (or your benchmark) counts.
• Memory that fits in context. SQLite FTS5 BM25 store with a human-readable Markdown mirror; agents retrieve via search --top 8, never by dumping the DB.
• Disciplined submits. Mid-run submit only on >0.10% gain over best-so-far, else one final submit at deadline.
• Zero-dependency runtime. The CLI is stdlib only; the skill is Markdown files, not a server.

Compatibility

Harness	Skill	Subagents + /elution command
OpenCode	npx skills add gdonninelli/elution -a opencode	copy .opencode/commands + .opencode/agents (native lane planned)
Claude Code	npx skills add gdonninelli/elution -a claude-code	copy .claude/commands + .claude/agents (marketplace planned)
Codex	npx skills add gdonninelli/elution -a codex	native lane planned
Pi / generic	copy .agents/skills/elution/SKILL.md	copy prompts manually if no subagent tool
Cursor, Copilot, …	npx skills add gdonninelli/elution	skill only

How it works

/elution 120
    ↓
researchers gather facts + papers (read-only, URLs cited)
    ↓
lead proposes ONE change (after BM25 search, lists checked_ids)
    ↓
reviewer approve / refine / reject (refine ends iteration, no code)
    ↓
coder implements smallest diff in editable scope
    ↓
you measure (yukon run or repo benchmark)
    ↓
save to memory, update best.json, repeat until deadline

Quickstart (Yukon)

yukon clone <setter>/<challenge>[/<track>]
cd <challenge-workdir>
yukon setup [--track <track>]
yukon run [--track <track>]   # baseline

Then in your harness:

/elution 120

See examples/yukon-generic.md and skills/elution/SKILL.md.

Memory CLI

elution init --minutes 120 --baseline 1.0 --direction minimize
elution search "sparse carry path" --top 8
elution add --kind knowledge --text "..." --source "https://..."
elution deadline   # running | expired — timer is the only stop rule
elution best --show

Kinds: observation | knowledge | constraint | hypothesis | experiment | measurement | decision | failure. Every record needs text plus source — web findings need a real URL or they are blockers, never facts. Secrets never enter memory or notes. State lives in .elution/ (state.db, deadline.txt, best.json, memory/, iterations/) and is gitignored.

Update: pipx upgrade elution (or uv tool upgrade elution). Uninstall: pipx uninstall elution + rm -rf .elution.

Yukon result

Record-holder run on matrices.fast (sparse elimination ordering): 0.86136× cheapest ordering, rank 01/11.

Layout

skills/elution/SKILL.md          # canonical orchestrator skill
.opencode/commands + agents/     # OpenCode entry + 5 subagent roles
.claude/skills + agents/ + commands/  # Claude Code mirrors
.agents/skills/elution/          # Pi / generic mirror
src/elution/memory.py            # SQLite FTS5 store + submit rule
src/elution/cli.py               # elution CLI
templates/submission-note.md     # Yukon-ready note skeleton
examples/yukon-generic.md        # generic walkthrough
.elution/                        # generated run state (gitignored)

Development

uv sync --group dev
uv run ruff check . && uv run ruff format --check .
uv run mypy src
uv run pytest

For AI agents: read AGENTS.md, then skills/elution/SKILL.md.

License

MIT. See LICENSE.