Ouroboros
A local general-purpose agent with durable memory, managed task execution, and traceable self-modification.
What does this agent do, and when should you use it?
Ouroboros is an open-source general-purpose AI agent delivered as a native desktop application or headless CLI. Its agent core is in `ouroboros/`, the interface is in `web/`, and the process plane is in `supervisor/`; durable identity, state, history, logs, and skills live locally under `~/Ouroboros/data/`. It can work in a separate Git workspace while keeping its own repository and governance boundary distinct, producing reviewable patches and JSON results. The runtime can use configured remote providers, compatible endpoints, or a local GGUF model. It also provides managed tasks, progress streams, schedules, background consciousness, and live specialist-agent coordination.
ouroboros server starts the local runtime and browser interface on 127.0.0.1:8765 by default. ouroboros run starts and manages work; --workspace targets an external Git worktree, --memory-mode forked selects forked memory, and --patch-out plus --result-json-out export a patch and JSON result. --jsonl emits machine-readable events, while --detach lets a caller follow asynchronous work with ouroboros tasks watch <task_id>. The CLI also exposes task, progress, artifact, log, schedule, setting, skill, and evolution controls; /evolve on|off, /review, and /bg start|stop|status control autonomous evolution, deep self-review, and background consciousness. Its documented editable surface includes application code, architecture, prompts, tools, and dependencies, with Git history, review evidence, protected surfaces, and restart checks intended to make self-changes inspectable.
- A developer fixing a failing test in a separate Git worktree who wants a reviewable `result.patch` instead of an unbounded in-place change.
- An engineering team scheduling a nightly maintenance review through `ouroboros schedule add`.
- A solo builder who wants a desktop view of specialist subagents researching, building, and returning work for integration.
- A CI or automation author that needs to invoke a local agent through a CLI, consume JSONL events, and inspect detached task results.
- A local-first user who wants task history, memory, dialogue, knowledge, and reflections to survive runtime restarts.
What are this agent's strengths and limitations?
- The native app and gateway-backed CLI expose the same managed tasks, progress, artifacts, logs, and schedules.
- Identity, memory, dialogue, knowledge, reflections, and version history persist locally across restarts.
- External work uses a separate Git worktree and can export patch and JSON artifacts for review.
- The documented runtime supports configurable remote providers, compatible endpoints, and local GGUF inference rather than a single hosted-model path.
- Source operation requires Python 3.10+, Git, and dependency installation; GitHub CLI is additionally needed for GitHub integration.
- A usable runtime still needs either remote-provider credentials or a local GGUF model, with corresponding API cost, hardware, and model-quality tradeoffs.
- External workspaces must be separate Git worktree roots and cannot overlap the Ouroboros repository or data directory.
- The server binds to loopback by default; a non-local bind requires `OUROBOROS_NETWORK_PASSWORD` or an explicitly trusted external access layer.
- Benchmark claims in the README are self-reported, with some submissions or trace capsules described as open or pending.
How do you install or deploy this agent?
For source setup: git clone https://github.com/razzant/ouroboros.git, cd ouroboros, python3.11 -m venv .venv, source .venv/bin/activate, python -m pip install --upgrade pip setuptools wheel, python -m pip install -r requirements.txt, and python -m pip install -e . --no-deps. Start it with ouroboros server, then open http://127.0.0.1:8765. First run requires at least one supported remote-provider API key or a local GGUF model. Release artifacts are also documented for Apple-silicon macOS, Linux x86_64, and Windows x64.
How do you use this agent?
Start the service with ouroboros server and use the first-run wizard to configure model access, review policy, and budget. Check the runtime with ouroboros status, or run a first task with ouroboros run --start "2+2?". For an external project, use a separate Git worktree that does not overlap Ouroboros’s repository or data directory: ouroboros run --start --workspace /path/to/project --memory-mode forked --patch-out result.patch --result-json-out result.json "Investigate the task, act, and verify the result".
How does this agent compare with similar options?
Its benchmark table reports model-matched comparisons with Claude Code, Codex CLI, Cursor CLI, Hermes, and Pointer on specified harnesses. Those self-reported benchmark rows are not a general equivalence claim across models or product workflows.