Reflexio: a self-improvement harness that turns user corrections into persisted agent playbooks

The problem Reflexio targets: agents that never learn from the correction they just received

Most agent stacks treat a user correction as a one-off event. The user says the agent got the format wrong, the agent apologises, the conversation ends, and the next session starts from the same blank slate. Reflexio is built for the case where that repetition has a cost: support agents, internal copilots, domain workflows where the same class of mistake recurs across sessions and across users. The README frames the target directly, calling Reflexio an "AI agent self-improvement harness" that turns user corrections into persisted behavioural improvements and captures successful execution paths for reuse. The audience is developers running their own agent loop in Python, not end users. The README states that user-specific learnings stay scoped to the individual user, while lessons that recur across users can be aggregated into shared playbooks and approved for reuse. That scoping rule matters more than the marketing line: it means the system has a notion of per-user memory and a separate, reviewable promotion step before anything becomes shared behaviour. If your agent has no persistent user identity and no correction signal, there is nothing here to ingest.

How the loop actually closes: conversations in, profiles, playbooks and success evaluation out

The README's own flowchart is the most concrete description of the architecture available. An AI agent sends conversations to Reflexio, and a human expert can send ideal responses alongside them. From that input the system produces four things: user profiles, playbook extraction, playbook aggregation, and success evaluation. Two details in the diagram are worth reading carefully. First, playbook extraction and playbook aggregation are separate stages, which implies extraction happens at the level of an individual interaction or user, and aggregation is the step that finds recurring patterns across users before anything is promoted to a shared playbook. Second, success evaluation is a distinct branch, not part of extraction, so the system appears to judge whether an execution path worked rather than assuming every completed run is a good example. The README also states the system extracts actionable playbooks from the differences between agent responses and expert-provided ideal responses. That is a comparison-based mechanism, not a summarisation of the whole transcript. What the material does not specify is the storage schema, the extraction prompt, or how conflicts between an existing playbook and a new correction are resolved. Those are open questions you would answer by reading the source.

Getting it running: two install paths, one CLI, and the ports you need free

The README gives two setup paths. From PyPI, the command is pip install reflexio-ai, followed by reflexio services start, which the README says starts the API on port 8061, the inference service on port 8069, and SQLite storage, with data saved under ~/.reflexio. The PyPI package does not ship the local docs site. From a source checkout, the sequence is git clone, cp .env.example .env, then set at least one LLM API key (the README names OpenAI and Anthropic as examples), uv sync, and npm --prefix docs install for the API docs. Starting from source uses uv run reflexio services start, which additionally brings up the docs site on port 8062. The README notes python -m reflexio.cli services start and ./run_services.sh as alternatives. Prerequisites are Python 3.12 or newer, uv for source installs, Node.js 18 or newer only for the local docs site, and a Python-linked SQLite runtime of at least 3.35.0. The README is explicit that this is the SQLite library linked into Python, not the standalone sqlite3 CLI, and gives the check: python -c "import sqlite3; print(sqlite3.sqlite_version_info)". One environment detail is easy to miss: the launcher starts the local inference service on 8069 unless REFLEXIO_EMBEDDING_SERVICE_URL points to a remote service, and the README states that even cloud embedding configurations still use the local service for reranking. So pointing embeddings at a cloud provider does not let you drop the local process.

The benchmark claim and what the README does not say about it

The README leads with a headline: 81% fewer planning steps and 72% less tokens on real GDPVal knowledge-work tasks, described as coming on top of what a self-improving Hermes agent already learns on its own. The stated setup is a Hermes agent running minimax/MiniMax-M2.7, measured against a warm baseline, meaning the same agent re-running the task after it has already learned from itself. The README says the result holds on 4 of 5 tasks, so one task did not show the reduction. That framing is more honest than most agent benchmarks: comparing against a warm baseline is a harder test than comparing against a cold one, and the README links to benchmark/gdpval/RESULTS.md for the full writeup. What the README does not disclose in the text available here is the variance across runs, the absolute step counts, or how the five tasks were selected. A median reduction across four tasks is a directional signal, not a guarantee for your workload. Treat the numbers as a reason to look at the benchmark directory, not as a reason to expect the same ratio in your own agent.

Where Reflexio is the wrong tool: local process, SQLite ceiling, and no retrieved releases

Three constraints stand out. The first is operational. Running Reflexio locally means running a service stack: API on 8061, inference on 8069, SQLite under ~/.reflexio. The README says the inference service serves embeddings and an optional cross-encoder reranker, and that cloud embedding configurations still route reranking through it. If your deployment model is a single stateless container with no sidecar process, this is friction you have to plan for. The second is storage. SQLite is the local backend, and the README pins it at 3.35.0 or newer via Python's linked runtime. Nothing in the material describes a production database backend or a migration path off SQLite, so multi-tenant scale is an open question rather than a documented capability. The third is release cadence. The repository metadata shows no releases retrieved, and the README's own install path is a PyPI package rather than a versioned release line. For a library that will sit in your agent's decision path, that absence is a real adoption risk: you cannot pin to a changelog you cannot see. The README also points to a managed hosted option with a 30-day Pro trial and describes it as including enhanced retrieval and continuous RL-driven improvement. That is an admission that the self-hosted path and the hosted path are not feature-identical, which is worth knowing before you build on the local stack.

How Reflexio differs from a vector-store memory layer

The obvious comparison is a retrieval-augmented memory store: embed past interactions, retrieve the nearest ones at inference time, and paste them into the prompt. That approach scales recall but does nothing about behaviour. Reflexio's stated mechanism is different in kind. It extracts playbooks, aggregates recurring ones across users, evaluates success, and keeps user-specific learnings scoped to that user until a shared playbook is approved. The output is a reusable procedure, not a similar transcript. The trade-off is real: a vector store is stateless and easy to reason about, while Reflexio introduces an extraction step that can be wrong, an aggregation step that can promote a pattern you did not intend, and an approval gate that someone has to operate. In exchange you get artifacts you can inspect and edit, which is closer to how teams actually curate agent behaviour. If your only need is "remember what this user said last week", a plain retrieval layer is less machinery. Reflexio earns its place when the same correction keeps arriving from different users and you want it fixed once.

Licence, maintenance and what a year of running this looks like

Reflexio is Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. It also means you carry the obligation to preserve licence notices and state significant changes if you redistribute a modified version. That is a general description of the licence, not legal advice; check the LICENSE file and your own counsel for your situation. On maintenance, the material supports only a limited picture: the last push to main is dated 2026-09-10, the project is not archived, and there is a Discord community linked from the README, plus a developer.md covering project structure, environment setup, testing and coding guidelines. There is no retrieved release history, so upgrade cost is hard to estimate. Practically, the upgrade surface is the Python package plus the local service stack, and any change to the inference service or the SQLite schema would land on you at upgrade time. The README's own advice for contributors is to read developer.md, which is also the right first stop if you plan to fork rather than track upstream.

Editorial conclusion

Adopt Reflexio if you already run a Python 3.12+ agent stack, you can set an LLM API key in .env, and you want corrections and expert responses turned into persisted playbooks rather than a chat log nobody reads. Do not adopt it if you cannot run or point at the inference service on port 8069, if your Python links SQLite below 3.35.0, or if you need a published API stability contract before you commit, because no releases were retrieved for this repository. Verify three things first: the output of python -c "import sqlite3; print(sqlite3.sqlite_version_info)", whether reflexio services start brings up API 8061 and inference 8069 cleanly on your machine, and whether the GDPVal benchmark scripts under benchmark/gdpval reproduce the reported planning-step and token reductions on your own task set.

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. ReflexioAI/reflexio on GitHub