clio-agent 0.5.0

CLIO Agent — Autonomous AI agent framework for scientific data management. Part of the IOWarp platform.

---

What is CLIO Agent?

An autonomous agent for scientific data management — HDF5, Parquet, and CSV inspection through a FastMCP tool gateway, with a Bubbletea terminal UI (gact) for interactive work. CLIO is the Intelligence Layer (CEI) of the IOWarp platform.

The agent runs in three tiers: a main orchestrator (planner loop over registered tools and experts), domain experts (data / analysis / visualization), and ephemeral nanoagents for parallel sub-tasks. State lives in a local-first memory layer (ARC) that all tiers read and write.

• Multi-expert orchestration with capability-based routing
• FastMCP tool gateway, HDF5 + Parquet servers out of the box
• ARC memory with O(log N) context retrieval
• Optimizer layer for offline tuning + online learning
• Runtime doctor for LM / gateway / file-policy health
• Works with LM Studio, Ollama, OpenAI, Anthropic, and the Argonne ALCF inference gateway

---

Quick Start

One line installs clio-agent + the gact TUI, builds them, and drops a clio command on your PATH.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.sh | sh
clio

Windows (PowerShell)

irm https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.ps1 | iex
clio

clio boots the server (if it isn't already up) and attaches the TUI. On first connect, pick an LM provider in the modal and you're chatting.

Prerequisites: git, uv, and go 1.26+ — the installer tells you if any are missing.

---

Using the clio command

clio with no arguments is the one-command UX. The subcommands manage the backing server without hunting PIDs:

Command	What it does
clio	ensure the server is up, then attach the TUI
clio start / stop / restart	server lifecycle (process-tree kill on stop)
clio status / ps	PID, port, health
clio logs [N]	tail server + TUI stderr logs
clio doctor	check prerequisites and install layout
clio report	diagnostics bundle for filing GitHub issues
clio completion <shell>	tab-completion (bash / zsh / powershell)
clio uninstall	remove CLIO (--purge / -Purge to drop config too)

Override paths with CLIO_PREFIX / CLIO_BIN_DIR and the server port with CLIO_PORT. Full install + uninstall reference: install/README.md.

---

Architecture

For the design rationale (three-tier hierarchy, ARC memory, optimizer layer, IOWarp integration), see docs/CLIO_AGENT_ARCHITECTURE.md.

---

Documentation

Doc	What's in it
docs/CLIO_AGENT_ARCHITECTURE.md	Three-tier design, ARC memory, optimizer layer
docs/SYSTEM_IDENTITY.md	What the agent is, design principles
docs/SETUP.md	From-scratch install + smoke test (manual path)
docs/CONTRIBUTOR_QUICKSTART.md	Dev environment, quality checks, where to put code
docs/MCP_TOOL_INTEGRATION.md	Adding tools via FastMCP
docs/EXPERT_SYSTEM_DESIGN.md	Adding new experts
docs/ARC_MEMORY_LAYER.md	Memory model and storage
docs/SELF_IMPROVEMENT.md	Optimizer layer
docs/PERMISSIONS.md	Tool permission system
docs/providers/	LM provider configuration
docs/CAPABILITIES_MATRIX.md	Feature matrix
PLAN.md	Roadmap

---

Contributing

Start with docs/CONTRIBUTOR_QUICKSTART.md. For guidance specific to AI agents working on the codebase, see AGENTS.md.

---

License + Citation

BSD-3-Clause.

@software{clioagent2026,
  title  = {CLIO Agent: Autonomous Agent for Scientific Data Management},
  author = {IOWarp Team},
  year   = {2026},
  url    = {https://github.com/iowarp/clio-agent},
}