Self-improving agents, governed. Areev is the substrate for adaptive agents — agents that get better from their own history, under human authority, in steps you can inspect, undo, and re-measure.
⭐ If agents that learn under human authority are where you think this is heading, star the repo — it helps other teams find Areev.
One substrate: typed grains in, a budget-shaped pseudonymized context out, a person on the gate —
and what the agent did comes back as the evidence its next improvement is proposed from.
Every team that ships an agent wants the same next thing: an agent that gets better from its own experience. Almost none ship one — because an agent that rewrites its own memory unsupervised fails every security review on the same four questions: what changed, on what evidence, on whose authority, and can we take it back?
Areev makes all four mechanical. The agent proposes from its own recorded history, citing evidence by hash; a named person approves, with a written reason; every apply stores its inverse; and the change is re-measured afterwards — a late regression proposes its own revert. This is enforceable rather than aspirational because the agent's knowledge and its execution history live in one content-addressed store, queried with one language (CAL).
Three honest limits, by design: it improves memory, never model weights · nothing applies itself without an explicit host grant · no daemon — everything runs when you run it. The full argument →
| What it is | Why it's unusual | |
|---|---|---|
| Areev Loop — the learning | Thirteen deterministic analyzers read the agent's history and propose changes, each citing its evidence by hash | It proposes; a named person disposes. Four gates, a written reason, a stored inverse, re-measurement after apply. Starts at zero model calls |
| Areev Run — the execution graph | Plans as content-addressed grains, runs as journals, humans as nodes in the graph | Intent is journaled before the effect; verify replays the journal and byte-compares every checkpoint |
| Areev Trigger — the cadence | Standing rules that start workflows — eight kinds, from cron to memory-predicates | The rule is a grain, so the cadence travels with the memory. No daemon — evaluation is a cheap idempotent command |
| CAL — the context | A query language that assembles, not just retrieves: budget-aware rendering, Full → Summary → Omit | A turn needs a budget-shaped prompt, and deterministic allocation is what makes a replay comparable |
| The store — the record | A provenance graph in a plain SQLite file (Turso), or a PostgreSQL schema for the server tier | ~30 µs recall in-process; one conformance suite pins both backends to identical semantics |
Every screen below is the real console over the demo memory committed to this repo — click through:
The knowledge graph walk and rewind what it knows |
The learning loop it proposes, you dispose |
Governed runs a person on the gate |
Anyone can show a number going up. The honest test is whether the learning caused it — so we remove what was learned and watch the gain leave, then put it back and watch it return. One frozen model at temperature 0, three seeded runs over 100 held-out tasks each (n=300) the agent has never seen; the only thing that changes between bars is whether the lessons Areev learned from the agent's own failures are in its prompt:
| what the memory holds | tasks passed | |
|---|---|---|
| nothing learned yet | 39.0% | the agent keeps repeating its mistakes |
| the lessons, applied | 59.7% ▲ | it stops |
| the lessons, rolled back | 37.7% ▼ | the proof — take them away and the gain leaves with them |
| the lessons, re-applied | 56.3% ▲ | put them back and it returns |
Every transition is significant at p < 0.0001 (paired McNemar, n=300); the two lessons-off states are statistically indistinguishable. There is no benchmark mode: the prompt is assembled from live memory on every run, so rolling the lessons back empties it structurally. Three results behind the chart:
- It learned for free. The lessons come from deterministic clustering over the agent's own tool calls — zero model calls — and each one cites the failures it was computed from, by hash.
- It improved without regressing. Every hidden rule the loop touched got better, none got worse. The per-rule numbers →
- It matches heavyweight retrieval at a fraction of the cost. The same store with the loop off — raw failure history retrieved into the prompt three different ways — never significantly outscored the lessons, paid 1.3–6.2× the prompt tokens every turn doing it, and its best-scoring variant doubled a class of mistakes the loop had eliminated. The baselines →
One synthetic workload, built to make learning measurable rather than to mimic production traffic — and we wrote the test, so re-run it yourself: the whole three-seed comparison costs about $2.30. Full results & caveats → · Reproduce it → · How the loop works →
| ~30 µs recall, in-process | runs on a $35 Raspberry Pi | 2,504 tests · 81.0% coverage | FORGET SUBJECT is one operation |
|---|---|---|---|
| benchmarks → | edge results → | quality, measured → | GDPR map → |
The demo memory behind every screenshot is committed to this repo — 466 grains, 9 governed runs, 13 real recommendations, one open fork:
areev ui --db data/demo.db --ns accounting # → http://127.0.0.1:7437
The people, vendors, invoices and processes this agent knows — as a graph you can walk, and rewind.
A real console over the real demo.db in this repo. Nothing here is a mockup.
Rebuild it from scratch with scripts/build_demo.sh:
every run in it is a real journal and every recommendation is a real analyzer
output, not rows written to look convincing.
Areev Loop reads the agent's own history back as evidence — "this tool failed 40% of its calls", "these two facts contradict", "this workflow failed 4 of its last 8 runs" — and turns it into recommendations that are evidence-cited, reviewable, undoable, and re-measured after apply. Thirteen deterministic analyzers, zero model calls required; attach an LLM for what determinism can't see and its findings are grounded against the cited grains and independently verified before a human ever sees them.
Thirteen findings from the demo memory, in plain language, each undoable. Nothing here applies itself.
Every recommendation passes propose → review → apply → verify with
separation of duties, a mandatory written reason, a hash-chained audit grain
per transition, and a stored inverse. Applied advice is re-measured at
1d / 7d / 30d — a late regression proposes its own revert. It runs where you
already run things: a Claude Code SessionEnd hook, cron, or CI, where
areev loop list --fail-on high exits 2 and turns governance into a merge
gate. Full guide: docs/loop.md · analyzers, gates, and
policy in depth: why-areev.
The same history is a training asset. areev corpus exports on-policy
trajectories as chat JSONL with step-level loss weights and lineage that
survives an erasure; areev tune --cmd hands that corpus to your trainer
and registers the returned adapter as a grain. Promotion is then what every
other change here already is: proposed by the loop, graded against a pinned
evalset, admitted through a clean recorded gating run, and revocable — the
gate cannot be weakened by the thing it gates (Rule E1). Areev still never
trains and ships no trainer: it supplies the corpus, grades the result, and
owns the lineage. The tuning seam →
Every agent framework executes graphs; almost none can prove an execution
afterwards. Here the plan is a grain, the run is a journal in the same file,
and the approver is a node in the graph. An effect is written down before
it is allowed to happen, so a crash-window effect is redelivered under the
same idempotency key instead of paid twice — and areev run verify re-drives
the whole run from its journal and byte-compares every checkpoint.
Nine real runs: six posted, one a person refused, one that failed honestly, one still waiting.
Approving requires your own sign-in — the approver's identity is the audit record.
LangGraph-grade control flow (Send fan-out, subgraphs, typed reducers, streaming, time-travel forks) with budgets that actually stop the run and a kill switch whose drain time is measured into the oversight report (EU AI Act Art. 12/14 map). Standing rules start runs on a schedule or an event with no daemon — the cadence is data (triggers). Full guide: docs/run.md · hands-on: quickstart.
Vector-store memory fails quietly — duplicates crowd the prompt, stale values
outrank current ones, provenance is a log grep, a crash pays twice, and
erasure is a project. Areev makes each failure structurally impossible, and
proves it with a deterministic benchmark, no LLM in the loop:
cargo run -p areev-bench --bin honesty_metrics.
Each failure, in detail →
cargo install areev # the CLI (prebuilt binaries: see the quickstart)
pip install areev # Python
npm install @areev/areev # Node (unscoped `areev` is pending an npm exception)Store a fact, recall it, hand it to a model:
areev add john prefers "window seat"
areev recall john --render sml # → a model-ready context block
areev ui # → the web consoleGive Claude Code (or any MCP client) persistent memory in one line:
claude mcp add areev -- areev serve --mcp --db ~/.areev/code.db --ns claude-codeOr skip the toolchains entirely — the repo's Dockerfile
builds the same binary with the Postgres and TLS features already on:
docker build -t areev .
docker run --rm -v areev-data:/data areev add john prefers "window seat"
AREEV_UI_TOKEN=$(openssl rand -hex 16) docker compose --profile console upThe image serves every role — console and a trigger heartbeat — and one box runs a whole fleet of agents, one memory each. Containers, compose files, and the AWS / GCP / Azure / Kubernetes mappings: docs/docker.md.
Want a complete agent, not a snippet?
examples/agents/invoice-to-accounting
is an accounts-payable agent that takes corrections by email reply — no
credentials, no network, no model key. python/smoke.sh runs week one (it
does the job, under governance); python/improve.sh runs week two (it
proposes its own fix from its run journals, and you decide). The same agent
ships in Python, TypeScript, and Rust — one file each, and all three mint
the identical content-addressed plan.
Watch that agent run for real — two and a half minutes, from an invoice landing in an unwatched mailbox, to the desk asking "may I remember this?", to a person signing the lesson and the next invoice being categorised from what was signed:
Or browse the whole gallery — examples/agents/ is
ten vertical agents, each built around an outcome a team has to prove, not a
feature to admire: a screening desk that can show an examiner the exact
rule bytes that decided every payment — and refuses to run a stale rule; an
on-call desk where the next identical page arrives with its cause
attached; a remittance desk that turns a wall of denials into one signed
fix the next remittance applies by itself; a privacy desk that can prove
what it disclosed is exactly what it erased; a referral desk that
consults an outside service with zero patient identifiers on the wire; a
claims desk that pays the cover in force on the date of loss, not
whatever the file says today; and a diligence desk where, after one signed
rule, the same budget buys three times the findings. All keyless, all
fixture-driven, all run by CI on every release.
Rust / Python / Node embedding, the areev run walkthrough, the PostgreSQL
backend, encryption at rest, migration from other stores, and fleet sync:
docs/quickstart.md. Task recipes:
cookbook. Keep your LangGraph or CrewAI stack and govern
its state with the pip adapters.
Recall is microseconds, not milliseconds, because there is no server in
the recall path — fast enough inside a real-time voice agent's 50 ms frame,
where a network call cannot go. The same engine, installed with
pip install areev in 16 seconds, serves recall on a $35 Raspberry Pi 3
from 2016 at ~361 µs — flat from 500 to 8,000 grains, so a device can
accumulate memory for months and answer as fast on day 200 as on day 1.
Measured on the devices themselves, clock-certified:
RESULTS.md.
Areev is local-first and collects no telemetry. Optional AES-256-GCM
encryption at rest (Argon2id-derived key) covers the database and its
attachment sidecar; deleting a memory is a tombstone or crypto-erasure.
Destruction is authorization-gated and takes a hash, an identity, or an age —
never a predicate: DELETE is not even a token in the query grammar.
Handling a data-subject request is three commands:
areev subject-report "pat" --db memory.db --ns caller --out pat.jsonl --bundle pat.mgb
areev forget-subject "pat" --db memory.db --ns caller --yes --because "Art. 17 request #42"
areev audit export --db memory.db --out evidence.jsonlThe report and the erasure run one selector, so a disclosure describes exactly what an erasure removes; the audit names a fingerprint, never the identity. GDPR article→capability map · erasure scope · threat model · report vulnerabilities per SECURITY.md.
The numbers below are regenerated from the tree on every CI run, which fails the build if they drift — they cannot go stale without turning the build red.
- Tests are about a third of the codebase; roughly half of that drives the real binary over real stdio, not mocks.
- Coverage counts source lines only (no test code scoring itself) — the lowest of the three numbers we could have quoted — and is floored per crate in CI, so one crate's regression cannot hide behind another's gain.
- Every user-facing error carries a stable, append-only
DOMAIN-Ennncode (ERROR_CODES.md); both storage backends run one conformance suite; the CAL examples in the reference are executable and fail CI when stale.
How each number is produced, and the benchmark receipts: docs/quality.md · per-crate table: docs/repo-stats.md · LoCoMo accuracy + honesty metrics.
| Doc | For |
|---|---|
docs/quickstart.md |
Install, CLI, MCP, Rust/Python/Node, Postgres, encryption, fleets |
docs/why-areev.md |
The full argument: the problem, the three systems, the honest limits |
docs/quality.md |
How every published number is produced and gated |
ARCHITECTURE.md |
How Areev works: grains, .mg format, CAL, recall, sync |
docs/loop.md |
Areev Loop — governed self-improvement (analyzers, four gates, policy, every surface) |
docs/run.md |
areev run — the governed runtime: plans, the journal, verify, HITL, budgets, forks |
examples/how-to-create-an-areev-agent.md |
Building an agent on Areev: architecture, grain selection, the autonomy spectrum, dynamic planning, do/don't |
docs/triggers.md |
Standing rules that start workflows — the cadence as data |
docs/eu-ai-act.md · docs/procurement.md |
EU AI Act article→capability→command map; procurement questionnaire answers |
docs/cal-reference.md |
The CAL query language reference |
docs/mcp-reference.md |
The MCP server + its 25 tools |
docs/migrate.md |
Importing an existing corpus, with its edit history |
docs/memory-tool.md |
The Anthropic memory-tool backend (Python / Node / CLI) |
docs/cookbook.md |
Task-oriented recipes |
docs/deployment-profile.md |
Deploying the runtime + adapters: modes, auth, SSO |
docs/docker.md |
The container image: compose, the trigger heartbeat, cloud deploys, multi-agent fleets |
docs/scale-and-tenancy.md |
Laying out a large shared corpus: why the partition boundary IS the permission boundary, and what each boundary costs |
FAQ.md |
Questions & answers (also LLM-friendly) |
SECURITY.md · docs/security-model.md |
Security policy & threat model |
docs/gdpr.md · docs/erasure.md |
GDPR obligations → capabilities (for a DPIA); the erasure requirement record |
AGENTS.md · llms.txt |
For AI agents working in / with this repo |
CONTRIBUTING.md |
How to contribute (DCO sign-off) |
Runnable material lives in examples/ — vertical agents,
notebooks, CI gates, policy variants, custom analyzers — every one keyless
and deterministic at its floor; the guide to assembling your own agent is
examples/how-to-create-an-areev-agent.md. The workspace layout and crate map are in
ARCHITECTURE.md; Areev is built on
Turso Database (MIT — see
THIRD-PARTY-NOTICES.md). The .mg format and CAL are stable, documented,
and OMS-conformant;
CHANGELOG.md records each release.
Contributions are welcome under the DCO — see CONTRIBUTING.md and our Code of Conduct. Questions and ideas: GitHub Discussions · community: r/Areev.
Licensed under either of Apache License 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion is dual-licensed as above, with no additional terms. The OMS specification itself is CC0.
Areev is built and backed by MindGryd Software Private Limited.