Ouroboros

Self-learning for Claude Code. Ouroboros reviews your sessions, turns what is worth keeping into memories and skills, and shows on a local dashboard what it learned, how much that is used, and what it costs — in the spirit of Nous Research's Hermes Agent.

Website: https://lucamartins.github.io/ouroboros/

The screenshots on this page show demo data, not measured results.

How it works

• At session start, Claude gets a short learning protocol: save preferences, corrections, conventions and working paths as you go, without being asked.
• During the session, every 10 turns you typed (and right after a turn that found a working path: a command that failed repeatedly and then worked once it was changed, or once something else was run) Claude briefly reviews the recent turns and saves what is worth keeping. Tests that fail until the code is fixed, or a flaky command retried, do not ask for one; nor does a session whose context is very large, which is left to the end-of-session review.
• When the session ends, a small isolated model call reviews whatever was not reviewed yet. What it ties to something you said is saved; a new skill it proposes, or anything it only inferred from what happened, waits for you. A session that never ran its end hook (a crash, a killed terminal) is reviewed at the next session start, once it has been idle for 6 hours.
• Everything goes through one curator: checked against what your CLAUDE.md files, rules, skills and memories already say, deduplicated, routed to the file that owns the topic, budgeted and undoable. Changes to existing files and corrections wait for your approval.
• Daily maintenance archives what nobody uses and consolidates what grew too big.
• A local dashboard shows what was learned and why, whether corrections are going down, what it costs, and a graph of how your skills, memories and instruction files connect.

The full design, with the reasoning and measurements behind each decision, is in DESIGN.md.

Install

Requires Claude Code and Node.js ≥ 22.13 on PATH.

/plugin marketplace add lucamartins/ouroboros
/plugin install ouroboros@ouroboros

For a local checkout: /plugin marketplace add /path/to/ouroboros.

Update

Claude Code keeps auto-update off for third-party marketplaces, so Ouroboros does not update on its own until you turn it on once: run /plugin, open Marketplaces, select ouroboros and choose Enable auto-update. Claude Code then checks for a new version a few minutes into each session, installs it in the background and shows Plugin updated: ouroboros · Run /reload-plugins to apply; the next session loads it either way.

To update by hand instead, run /plugin marketplace update ouroboros in a session, or this in your shell:

claude plugin update ouroboros@ouroboros

Then run /reload-plugins or start a new session. Your learnings, settings and history live outside the plugin's install directory and are kept across updates. If you set DISABLE_AUTOUPDATER=1 (or DISABLE_UPDATES=1), also set FORCE_AUTOUPDATE_PLUGINS=1 to keep plugin updates. Changes are listed in CHANGELOG.md.

Use

Command	What it does
/ouroboros:learn [focus]	Saves what was learned (Claude also uses it on its own)
/ouroboros:inbox [this project | key]	Goes through what waits for your decision in the conversation, one entry at a time: Claude shows the diff, checks it and recommends; you approve, reject, skip, or discuss and edit it before it is saved. It opens only when you type it: Claude never starts it on its own, since it can approve
/ouroboros:undo [id]	Reverts the last (or a given) learning write
/ouroboros:forget <match>	Archives a learning so it stops loading
/ouroboros:dashboard	Opens the local dashboard (http://127.0.0.1:4747): an inbox of what waits for you, what was learned (each item with what it changed, why and from which session; undo, archive, keep), a graph of how skills, memories and instruction files connect, value, activity, cost and health
/ouroboros:backfill [measure | learn] [days] [limit]	Reviews past sessions: measure builds the correction baseline right away, learn sends what they would have taught to the inbox (asks before spending)

Everything else is automatic: capture hooks record turns, tool calls, error → fix recoveries, skill uses and memory reads/writes; a background reviewer runs when a session ends.

This is the beginning of the README. Read the rest at the original. Read the full README ↗