Only memory that still works gets kept.

Public homepage for this project is this repository: github.com/recertia/recertia. Docs: docs/architecture.md · changelog: CHANGELOG.md · contributing: CONTRIBUTING.md.

Recertia is a self-improving agent system for recurring work. It solves a task against locked, machine-checkable criteria, saves what worked as versioned memory, and measures whether that memory actually helps the next time.

It does not improve by updating model weights. It improves by updating how knowledge is stored, retrieved, and re-certified.

Related work: SealedKeep keeps a code or experiment change only when a real evaluation metric improves. Recertia is the memory side of the same honesty rule of retrieve, solve, check, and keep only what still earns its place.

Retrieve before invent.
Solve always queries memory first. The agent is not allowed to skip straight to invention.

Lock success before you solve.
Criteria are fixed at intake from a structured Goal. They must be able to fail. Natural language is optional context, not the contract.

Version everything.
Skills, facts, and cases change by writing a new version with lineage. There is no silent in-place edit of “what we know.”

Failures are knowledge.
Dead ends are stored and retrieved so the system does not fall into the same hole twice.

Measure with a control arm.
Some runs suppress memory on purpose. “It got better” is only allowed when treatment beats control — not when a transcript sounds confident.

Bound the library.
The active skill set is capped. Weak entries retire on measured contribution. Unbounded growth is not treated as progress.

Do not self-edit the referee.
The agent may not change the machinery that measures or constrains it.

Count what you dispatch.
Fan-in reconciles expected work against received work. Model-scored checks run in a fresh context so the solver cannot grade its own homework.

If you remember one sentence: progress is real only when a run without memory is part of the comparison.

The claim that matters is lift: same task class, with memory vs without.

pip install -e ".[dev]"
recertia lift --task-class <name> --trials 10

You should see success (and cost or step counts, when tracked) for the treatment arm and the control arm, plus a delta. The integrity ledger records both.

Lift is measured, not guaranteed. Some task classes will not improve. That result is still useful — it means the library did not earn its keep on that class.

Seed skills live under skills/. Golden evals live under evals/. Open empirical claims are tracked in docs/assumptions.md.

Python 3.11+.

pip install -e ".[dev]"

# preferred entry: structured Goal -> locked criteria
recertia run --goal goal.json

# inspect / resume / verify
recertia runs show <run_id>
recertia resume
recertia ledger verify

# library
recertia skills search <query>
recertia skills lint
recertia skills promote <skill_id>

HTTP API: POST /v1/runs (install with pip install -e ".[api]"). Issue keys with recertia keys.

Execution backend. Production solves default to an OCI container (RECERTIA_EXECUTION_BACKEND=container). Install Docker or Podman, then:

export RECERTIA_EXECUTION_BACKEND=container
python3 scripts/smoke_container.py

For local development only:

recertia run --goal goal.json --local-exec

Models. Unscripted solves need a real provider; the stub leaves the model unset on purpose so empty config fails loud. Anthropic, OpenRouter, and other OpenAI-compatible gateways are documented in docs/architecture/go-live.md. Keep keys out of the repo.

Offline jobs and retention:

recertia jobs run curator --dry-run
recertia gc --older-than-days 14

Policy defaults live in policy/default.json.

                    ┌─────────────┐
                    │  Goal / API │
                    └──────┬──────┘
                           │
                           v
┌─────────────────────────────────────────────────────────┐
│  EXECUTION (one request)                                 │
│  intake → retrieve → plan → solve → validate             │
│              │                         │                 │
│              │                    pass / fail            │
│              │                         │                 │
│              │              distill or dead end          │
└──────────────┬─────────────────────────┬────────────────┘
               │                         │
               v                         v
┌─────────────────────────┐   ┌──────────────────────────┐
│  MEMORY (durable)        │   │  IMPROVEMENT (scheduled)  │
│  skills · facts · cases  │◀──│  curate · practice        │
│  utterances · policy     │──▶│  re-certify → quality gate│
│  versioned, reversible   │   └──────────────────────────┘
└───────────┬────────────┘
             │
             v
      ┌─────────────┐
      │ control arm │  same tasks, memory off → measure lift
      └─────────────┘

Compounding happens across runs, through durable memory that later runs read before inventing. Offline jobs (refine, evolve, practice, distill) reorganize and re-certify that memory on a schedule. Promotion always passes a quality gate.

Three planes stay separate on purpose:

Keeping them apart is what stops “self-improving” from meaning “one long process you have to trust.”

Primary input is a structured Goal of outcomes and constraints, compiled to locked TaskCriterion[] at intake. Details: docs/specifications/goal-objects.md.

• A fine-tuning or weight-training loop
• An unbounded autonomous agent
• A chat log you are expected to believe
• A promise that every task class will show positive lift
• An MIT-licensed free-for-commercial product

Validate it on your own workload before you rely on it.

Built and under test:

• Contracts-as-code in contracts/ (source of truth) with generated schema/
• Graph runtime with budgeted loops and explicit failure signals
• Plural memory planes, promotion gates, and control-arm lift measurement
• Container sandbox for production solves; --local-exec for development
• CLI (recertia) and optional FastAPI surface
• CI on every push

Research outcomes that are still open are listed in docs/assumptions.md, separate from engineering acceptance gates.

PolyForm Noncommercial 1.0.0 (PolyForm-Noncommercial-1.0.0). Personal use, research, experimentation, and use by many noncommercial organizations are permitted. This is not MIT. Commercial production use requires a separate license from the copyright holder.

Copyright (c) 2026 Robert Schmidt. See NOTICE.