autocontext

autocontext is a harness for agent improvement. Give it a goal, it runs the task against evaluation, keeps the useful lessons, discards dead ends, and leaves traces, reports, playbooks, datasets, and optional local-model training artifacts for the next run.

Docs: autocontext.ai/docs · quickstart · CLI reference · changelog

Experimental Python research: the Qwen weight-space reproduction pins model/data/scorer assets, verifies the published checkpoint, and provides bounded paired inference with replayable reproduction reports. The GPU acceptance workflow gates full execution; live reproduction remains pending. The comparison-condition harness exercises baseline, context, weight, combined and decoding conditions with offline synthetic fixtures. The CPU-only editing sessions create context, weight-descriptor and decoding candidates with finite durable budgets, practice-only adapter views and sealed exports into that comparison harness. Real GPU editing and benchmark practice selection remain deferred. The adaptive editing fixtures add feedback-conditioned proposals, equal search caps, practice-based selection, and a separate confirmation gate before the final fixture audit. The checkpoint-backed editing fixtures apply typed edits to tiny CPU safetensors and carry independently verified input/program/output hashes through selection and confirmation. Model and GPU inference remain deferred. The CPU inference study runs a pinned tiny classifier on verified checkpoint bytes and measures baseline, context, weight, combined, and decoding conditions. Its constructed tasks establish execution correctness; Qwen reproduction and GPU execution remain deferred. The adaptive CPU search uses those measured practice scores to choose bounded context, tensor, and decoding edits, restore an earlier winner, and freeze selection before confirmation. Linux acceptance covers real memory/CPU limit failures and cleanup; GPU execution remains deferred. The generated CPU campaign compares adaptive, fixed-order, and seeded-random search at equal capacity across pinned task instances. Complete schedule accounting, read-only replay, and paired task-level reports retain failures and vetoes without treating repeated seeds as independent tasks.

The CPU search diagnostics freeze completed selections before probing every declared single-surface option on practice cases. Separate reference costs and descriptive reports distinguish unavailable improvements, missed options, duplicate outputs, and confirmation vetoes. GPU execution remains deferred.

The controlled CPU transfer experiments add deterministic weight-repair, already-correct and practice-shortcut controls. A separate pinned contract preserves earlier evidence while family-specific reports test transfer under the unchanged confirmation gate. These constructed controls do not establish benchmark gains; GPU execution remains deferred.

The CPU failure supervisor records bounded live exception chains under a separate implementation pin. It preserves earlier journals, keeps unavailable observations unknown, and runs one declared CPU campaign with conditional practice references. GPU execution remains deferred.

The measured CPU outcomes add a pinned v2 failure codec, deterministic prompt redaction, and process measurements that survive errors. A small declared comparison checks native-versus-measured receipt parity without retries. Earlier evidence remains intact; GPU execution is deferred.

The measured CPU search integration carries those outcomes through practice, restoration, confirmation, conditional audit, and exhaustive practice references. A pinned 18-search native-versus-measured schedule checks semantic parity and preserves failed or uncertain operations and their charges. GPU execution remains deferred.

Install

For Python CUDA/SFT installation, follow the maintained Accelerate build guide. Published installations must install the bundled security build before adding the CUDA extra; source checkouts use the locked uv source.

The PyPI package is autocontext; the CLI is autoctx. The npm package is autoctx (not the unrelated autocontext npm package). Provider variables live in .env.example. The npm CLI and TUI require Node.js 22.19.0 or newer; contributors should use the version pinned in ts/.nvmrc.

30-Second Run

Pi is the lowest-friction provider because it uses your local agent auth:

AUTOCONTEXT_AGENT_PROVIDER=pi \
AUTOCONTEXT_PI_COMMAND=pi \
autoctx solve "improve customer-support replies for billing disputes" --iterations 3

Use AUTOCONTEXT_AGENT_PROVIDER=anthropic, openai-compatible, openrouter, claude-cli, codex, pi-rpc, or another provider when you need that runtime. See agent integration for the full matrix.

Running it on your own GPU instead? Self-hosted models covers the whole loop on vLLM, Ollama, or any OpenAI-compatible endpoint — including what each role actually resolves to, and why constrained output matters more on open weights. Self-hosted endpoints can additionally declare AUTOCONTEXT_PROVIDER_HOSTING=local and a fast, mid_tier, or frontier AUTOCONTEXT_PROVIDER_CAPABILITY; role-specific endpoints use matching <ROLE>_PROVIDER_* declarations.

Prime remote execution also supports opt-in accelerator requests with explicit type/count, immutable-image, region, and telemetry capability validation. It fails before provider creation when the configured pool cannot satisfy the request and never downgrades accelerator work to CPU; see remote execution sessions. Shipped Prime generation and campaign paths persist a durable pre-dispatch claim plus the complete result/ledger projection before returning paid work; restart never treats an unresolved or already committed request as permission to provision another sandbox.

Agent Entry Points

• Pi: install pi-autocontext, then ask Pi to solve, judge, improve, list, or inspect runs through the packaged skill.
• MCP clients: run autoctx serve mcp or bunx autoctx serve mcp and expose the tools to Claude Code, Cursor, or another MCP client.
• Hermes: export the CLI-first skill with uv run autoctx hermes export-skill --with-references --json.

Full setup: autocontext/docs/agent-integration.md.

What A Run Leaves Behind

runs/<run_id>/
├── trace.jsonl
├── generations/<n>/{strategy.json,analysis.md,score.json}
├── report.md
└── artifacts/

knowledge/<scenario>/
├── playbook.md
├── hints.md
├── tools/
└── context_bundles/{bundles,candidates,promotions,active.json}

Everything is filesystem-first: inspect it, diff it, replay it, export it, or feed it into training. Kernel campaigns extend that contract with exact provider-generation receipts, bounded paid-call accounting, content-addressed lineage, and safe stop/status/resume. Coach and architect context changes are stored as immutable candidates and are not served until matched candidate/incumbent trials confirm them. The live serving boundary can additionally require a can