areev-loop

The governed self-improvement engine for AI-agent memory — the reference implementation of the Areev Loop layer described in docs/loop-proposal.md.

Areev Loop turns an agent's own history into recommendations — evidence-cited, reviewable, undoable, measured — and governs every change through four gates (propose → review → apply → verify). The deterministic core produces useful recommendations with zero model calls by computing over declared grain semantics, never raw prose.

What's here (build-order item 1)

A standalone engine over an OmsSubstrate (CAL text + grains) with zero Areev dependencies — serde only. Areev is the first substrate; the in-repo ReferenceSubstrate lets tests run with no store at all and doubles as the conformance kit for third-party substrates.

• OmsSubstrate / SubstrateRead — the store protocol (read split out so analyzers get a read-only view, enforced by the type system).
• The recommendation model (OMS 0x0C): RecDraft → engine-stamped Recommendation, deterministic Summary templates, dedup_key (family-excluding-major ⟂ target ⟂ action), the lifecycle state machine, and hash-chained AuditRecords.
• Engine: the analyze → validate/dedup → store pipeline with the run-outcome contract (RunResult: outcome / skip-reason / counts), plus review / apply / rollback with scopes, the mandatory BECAUSE, the self-approval block, and destructive gating.
• The default analyzers: tool-failure clustering, duplicate sweep, contradiction sweep, fork surfacing, staleness, outcome review, and the default-off retention_sweep and run_outcome passes over run journals.
• LOP error domain (see the repo's ERROR_CODES.md).

Status

Workspace member during the churn phase; lifted to its own repo when semantics freeze (proposal §10).

The surfaces this crate deliberately does not carry live around it: the Areev substrate adapter is areev-loop-adapter, the LLM enrichment layer is areev-llm, and the CLI/MCP/console surfaces belong to their own crates. That separation is the point — the engine stays substrate-agnostic and depends on no areev-* sibling. Auto-apply execution remains conservative by design: the gate is present, and code, evalset and definition targets are excluded from it by name.

use areev_loop::{Engine, ReferenceSubstrate, RunOptions};

let mut store = ReferenceSubstrate::new();
let engine = Engine::with_builtins();
let result = engine.run(&mut store, &RunOptions::default(), 1_000).unwrap();
assert!(result.ran());

Test

cargo test -p areev-loop
cargo clippy -p areev-loop --all-targets -- -D warnings

Licensed under MIT OR Apache-2.0.