Ouroboros: a self-modifying AI agent that keeps its identity across restarts

The problem Ouroboros is built around

Most agent frameworks treat a session as the unit of work. You start a process, hand it a task, it answers, and the process exits. Anything learned during that run lives in a transcript you may or may not keep. Ouroboros takes the opposite position: the agent is the durable thing, and tasks are episodes inside it. The README states that its identity, durable memory and history continue across tasks and restarts, and that reflection can change how it understands itself without severing that continuity. That is the design claim the whole project rests on.

The audience follows from that. This is not a library you import into an existing service. It is a runtime you install, point at a model, and let work on external projects. The README describes it as general purpose, able to coordinate a live swarm of specialist agents and to rewrite the implementation it runs on, including code, architecture, prompts, tools and dependencies. If you want a small deterministic helper that turns text into JSON, Ouroboros is far more machinery than the job needs.

How the runtime, memory and self-editing loop fit together

The repository layout shows the split plainly. There is a top-level server.py and launcher.py, an ouroboros/ package, a supervisor/ directory, separate prompts/ and skills/ directories, and a web/ front end. The Dockerfile builds a web UI runtime and sets OUROBOROS_SERVER_HOST to 0.0.0.0 and OUROBOROS_SERVER_PORT to 8765, exposing that port and entering through python server.py. So the agent process is a server with a browser-facing interface, not a one-shot script.

Model access is deliberately pluggable. The README says model inference can use remote APIs you configure or a local GGUF model, and that the runtime keeps its repository, durable memory, history and interface on your machine. That is the important boundary: state is local, inference may not be. The dependency list in pyproject.toml includes openai, gigachat, httpx and huggingface_hub, which matches a multi-provider setup rather than a single vendor.

Self-modification is not free-form. The README points to CONTRIBUTING.md, which it says defines the required project context, verification, and separate-agent review flow. The technical report is titled around a reviewed core-evolution system. The commit path is also gated: a comment in pyproject.toml explains that the hermetic commit gate's parallel pass hard-blocks with PREFLIGHT_PLUGIN_MISSING rather than degrading to serial, which is why pytest and its required preflight plugins are runtime dependencies rather than test-only ones. In other words, an environment that carries pytest without those plugins cannot commit at all. That is an unusually strict stance for an agent runtime, and it is the mechanism that keeps self-editing from being unconstrained.

Installing Ouroboros from the desktop packages

The README is explicit that you do not need to clone the repository or install Python or uv to use the app. Pick the package for your platform: a .dmg for macOS 12+ on Apple silicon, a .zip for Windows x64, .deb and .rpm packages for Debian-family, Fedora, RHEL and RED OS 8, and an AppImage or tar.gz for other x86_64 Linux. Files named SHA256SUMS, release-evidence.json, release-smoke-*.json and sbom-*.cdx.json are verification evidence, not installers.

On Debian, Ubuntu or Astra Linux the README gives this command, run from the directory holding the downloaded package:

sudo apt install ./ouroboros_*_amd64.deb

On Fedora or RHEL the equivalent is:

sudo dnf install ./ouroboros-*.x86_64.rpm

On another x86_64 distribution you make the AppImage executable and run it. The README notes that Git must already be installed for that path:

chmod +x Ouroboros-*.AppImage
./Ouroboros-*.AppImage

Before the agent can run a task you must configure at least one supported remote provider API key or a local GGUF model. The first-run wizard walks through model access, review policy and budget setup. The desktop packages also carry an optional CLI installer that creates a user-local ouroboros command without sudo and without Python or uv; on macOS you double-click Install CLI.command in the mounted DMG, on Linux you run ./Ouroboros/bin/install-ouroboros-cli, and on Windows you run Ouroboros\bin\install-ouroboros-cli.cmd.

Building the container and running the test gate

If you want the server rather than the desktop app, the Dockerfile is the shortest path. It builds from python:3.10-slim, copies uv in from ghcr.io/astral-sh/uv:0.12.1, installs git, and resolves dependencies with uv sync against the reviewed lock file before copying the application. Browser tools are installed during the build, including Playwright's Chromium and WebKit binaries and their native system dependencies.

The README's Docker usage comment gives these two commands:

docker build -t ouroboros-web .
docker run --rm -p 8765:8765 ouroboros-web

The container listens on port 8765, matching OUROBOROS_SERVER_PORT in the image environment. Note the layering choice in the Dockerfile comments: dependencies are installed in their own layer so that source edits reuse the expensive Python package and browser downloads. That matters when you are iterating on an agent that edits its own source.

For development, the Makefile defines the commands the project itself uses. The test target runs the smoke suite against the lock, and lint is a narrow deterministic gate rather than a full style check:

make test
make lint

make lint runs ruff with --select F only, which catches the NameError class of mistakes. The Makefile comment says this matches the CI quick-test step. Do not read it as a general lint pass.

Where the self-editing design gets uncomfortable

The most obvious limitation is that the README does not document rollback. There is no described command to revert the agent to a previous self-authored state, no snapshot policy, and no recovery procedure if a self-edit leaves the runtime unable to start. Given that the project's headline capability is rewriting its own code, architecture, prompts, tools and dependencies, the absence of a documented undo path is the thing to weigh hardest. The repository does carry a BIBLE.md and an ADOPTION_v7next.md at the top level, but the README does not explain what either covers.

The second limitation is verification. The README presents benchmark charts for Terminal-Bench 2.1, OSWorld-Verified and CL-Bench, and states plainly that these are self-reported results, measured against Codex, Claude Code, Cursor and Hermes on the same model where a matched pair was run and against the public leaderboard where it was not. That is more candid than most projects, but it still means you cannot treat the numbers as independently reproduced. The technical report on arXiv is the place to look for the method.

Third, the dependency surface is wide and includes pip itself, because the pyproject.toml comment notes that runtime self-update and install paths execute sys.executable -m pip. An agent that installs packages at runtime is an agent that can change its own environment in ways your normal dependency review will not catch. The project classifies itself as Development Status 4 - Beta, and the README's own warning that coding agents and people must read CONTRIBUTING.md before editing is a signal that naive edits are expected to break things.

Ouroboros compared with a conventional coding agent

The closest comparison in the README is the set of agents Ouroboros benchmarks against: Codex, Claude Code and Cursor. Those tools are session-oriented coding assistants. You open an editor or a terminal, they operate on a repository you point them at, and their state is largely the conversation plus whatever files they wrote. They do not maintain a persistent identity, they do not run background consciousness between requests, and they do not rewrite their own implementation.

Ouroboros inverts each of those. The README describes background consciousness supporting reflection, initiative and preparation outside the immediate request-response loop. It also describes delegation through Claudexor, which the README says Ouroboros bundles as its local execution layer for delegated coding and hosted-agent review: Ouroboros owns the task, memory, review and final integration, while Claudexor runs the selected connected coding harness and returns durable execution evidence. That division of labour is the architectural difference worth understanding. If you already have a coding agent you trust, Ouroboros is not replacing it so much as wrapping it in a persistent, self-reviewing loop.

The trade-off is legibility. A conventional agent's behaviour is inspectable from its transcript. Ouroboros's behaviour depends on a memory store, a review pipeline and a commit gate that the README describes only at a high level. You get continuity and self-direction; you give up the ability to predict the runtime from a single log.

Licence, releases and what upgrades cost

The project is MIT licensed, stated both in the repository metadata and in pyproject.toml. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and licence text travel with it. This is not legal advice, and the self-modifying nature of the runtime raises questions MIT does not answer, such as who is responsible for code the agent writes into its own tree.

Upgrade cadence is high. The release list shows v6.109.0 and v6.108.1 landing on the same day, 2026-08-21, with v6.106.0 earlier that same day, while pyproject.toml already declares version 7.0.0. The last push to the repository was on 2026-08-21. That combination means the packaged release line and the source tree are not obviously in step, and you should check VERSION against the package you install rather than assuming they match.

The upgrade cost is structural, not just a matter of pulling a new binary. Because the agent can modify its own dependencies and because the commit gate hard-blocks when preflight plugins are missing, an upgrade that changes the lock file or the preflight plugin set can leave a previously working environment unable to commit. Treat the lock file as part of your deployment artifact.

Editorial conclusion

Adopt Ouroboros if you want an agent whose memory, history and identity survive restarts, and you are willing to read CONTRIBUTING.md before touching its code. Do not adopt it if you need a stable frozen runtime, a documented rollback path, or a benchmark you can reproduce without the paper's harness. Verify first that a local GGUF model or a remote provider key is configured, that the commit gate's preflight plugins are present, and that you can read the self-reported benchmark charts as self-reported.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes