ouro-ai 0.3.0

General AI Agent System

An open-source AI agent — run it as a Coding agent CLI or deploy it as a bot just like JARVIS.

Ouro is derived from Ouroboros—the ancient symbol of a serpent consuming its own tail to form a perfect circle. It represents the ultimate cycle: a closed loop of self-consumption, constant renewal, and infinite iteration.

At Ouro AI Lab, this is our blueprint. We are building the next generation of AI agents capable of autonomous evolution—systems that learn from their own outputs, refine their own logic, and achieve a state of infinite self-improvement.

Installation

Prerequisites: Python 3.12+.

pip install ouro-ai

Or install from source (for development):

git clone https://github.com/ouro-ai-labs/ouro.git
cd ouro
./scripts/bootstrap.sh   # requires uv

Quick Start

1. Configure Models

On first run, ~/.ouro/models.yaml is created with a template. Edit it to add your provider and API key:

models:
  openai/gpt-4o:
    api_key: sk-...

  anthropic/claude-sonnet-4:
    api_key: sk-ant-...

  chatgpt/gpt-5.2-codex:
    timeout: 600

  ollama/llama2:
    api_base: http://localhost:11434

default: openai/gpt-4o
current: openai/gpt-4o

For chatgpt/* subscription models, run ouro --login (or /login in interactive mode) and select provider before use. OAuth models shown in /model are seeded from ouro's bundled catalog (synced from pi-ai openai-codex model list). Maintainer note: refresh this catalog via python scripts/update_oauth_model_catalog.py. Login uses a browser-based OAuth (PKCE) flow with a localhost callback server. If browser auto-open fails, ouro prints a URL you can open manually (for remote machines, SSH port-forwarding may be required). Advanced OAuth overrides (rarely needed) are documented in docs/configuration.md.

See LiteLLM Providers for the full list.

2. Run

# Interactive mode
ouro

# Single task (returns raw result)
ouro --task "Calculate 123 * 456"

# Resume last session
ouro --resume

# Resume specific session (ID prefix)
ouro --resume a1b2c3d4

CLI Reference

Flag	Short	Description
--task TEXT	-t	Run a single task and exit
--model ID	-m	LiteLLM model ID to use
--resume [ID]	-r	Resume a session (latest if no ID given)
--login	-	Open OAuth provider selector and login
--logout	-	Open OAuth provider selector and logout
--verify		Enable self-verification (Ralph Loop) in --task mode
--reasoning-effort LEVEL	-	Set run-scoped reasoning effort (`default
--verbose	-v	Enable verbose logging to ~/.ouro/logs/

Interactive Commands

Slash Commands

Command	Description
/help	Show help
/reset	Clear conversation and start fresh
/stats	Show memory and token usage statistics
/resume [id]	List or resume a previous session
/model	Pick a model (arrow keys + Enter)
/model edit	Open ~/.ouro/models.yaml in editor (auto-reload on save)
/login	Open OAuth provider selector and login
/logout	Open OAuth provider selector and logout
/theme	Toggle dark/light theme
/verbose	Toggle thinking display
/reasoning	Open reasoning menu
/compact	Trigger memory compression and show token savings
/exit	Exit (also /quit)

Keyboard Shortcuts

Key	Action
/	Command autocomplete
Ctrl+C	Graceful interrupt (cancels current operation, rolls back incomplete memory)
Ctrl+L	Clear screen
Ctrl+T	Toggle thinking display
Ctrl+S	Show quick stats
Up/Down	Navigate command history

Bot Mode (IM Assistant)

Run ouro as a persistent IM bot — message it from Lark or Slack, get agent responses. No public URL needed; the bot uses outbound long connections (WebSocket / Socket Mode).

Bot data is isolated under ~/.ouro/bot/ (sessions, memory, skills) so it never conflicts with interactive or task mode.

Install

pip install ouro-ai[bot]

Quick Start

Add credentials to ~/.ouro/config:

# Lark
LARK_APP_ID=cli_xxx
LARK_APP_SECRET=xxx

# Slack
SLACK_BOT_TOKEN=xoxb-xxx
SLACK_APP_TOKEN=xapp-xxx

ouro --bot

Session Persistence

Bot conversations are automatically saved to disk and resumed across restarts. Each IM conversation gets its own session, mapped via ~/.ouro/bot/sessions/conversation_map.yaml.

Commands (send as a message to the bot):

Command	Description
/new or /reset	Start a fresh session
/sessions list	List all saved sessions
/sessions resume <id>	Switch to a previous session
/compact	Compress conversation memory to save tokens
/status	Show session statistics (age, messages, tokens, compressions)
/heartbeat	Show heartbeat status (interval, last run, next run)
/cron list	List all scheduled cron jobs
/cron add <schedule> <prompt>	Create a new cron job
/cron remove <id>	Delete a cron job
/help	List all available commands

Sessions untouched for 30 days are automatically cleaned up.

Proactive Mechanisms

The bot can act on its own between conversations:

• Heartbeat: Periodic self-checks — the agent runs through a checklist and broadcasts results to active IM sessions when action is needed.
• Cron: Schedule recurring or one-time tasks via cron expressions, second intervals, or one-time ISO timestamps.

See Bot Configuration for BOT_HEARTBEAT_INTERVAL, BOT_ACTIVE_HOURS_*, and other settings.

Personality

~/.ouro/bot/soul.md defines the bot's identity and tone. It is injected into the agent's system prompt for all bot sessions. A default template is created automatically on first launch — edit it to customize your bot's personality.

Platform Guides

• Lark (Feishu) Setup
• Slack Setup

Features

• Dual mode: Interactive CLI with rich TUI + persistent IM bot (Lark, Slack) — same agent core, two deployment modes
• Unified agent loop: Think-Act-Observe cycle — planning, sub-agents, and tool use all happen in one loop
• Self-verification: Ralph Loop verifies the agent's answer against the original task and re-enters if incomplete (--verify)
• Parallel execution: Concurrent readonly tool calls in a single turn, plus multi_task for spawning parallel sub-agents with dependency ordering
• Memory system: LLM-driven compression, long-term memory, and YAML session persistence resumable across restarts
• Proactive mechanisms: Heartbeat self-checks + cron-scheduled tasks, with results broadcast to active IM sessions
• Personality: Customizable soul file (~/.ouro/bot/soul.md) defines bot identity and tone
• Skills: Extensible skill registry — dynamically loaded per session
• OAuth login: --login / /login to authenticate with ChatGPT Codex subscription models
• Benchmarks: First-class Harbor integration for agent evaluation (see Evaluation)

Evaluation

Ouro can be evaluated on agent benchmarks using Harbor. A convenience script harbor-run.sh is provided at the repo root:

1. Edit harbor-run.sh to set your model, dataset, and ouro version.
2. Run:

export OURO_API_KEY=<your-api-key>
./harbor-run.sh                    # run with defaults in the script
./harbor-run.sh -l 5               # limit to 5 tasks
./harbor-run.sh --n-concurrent 4   # 4 parallel workers

Extra flags are forwarded to harbor run, so any Harbor CLI option works. See ouro_harbor/README.md for full details.

Configuration

See Configuration Guide for all settings.

Documentation

• Configuration -- model setup, runtime settings, custom endpoints
• Examples -- usage patterns and programmatic API
• Memory Management -- compression, persistence, token tracking
• Extending -- adding tools, agents, LLM providers
• Packaging -- building, publishing, Docker

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

For development setup, see the Installation section (install from source).

License

MIT License