https://github.com/iowarp/clio-agent
A science agent supporting any general AI agent in performing data management operations at scale. Builds upon the heritage of the IOWarp platform and proudly represents work done at Gnosis Research Center at Illinois Tech. Supported by NSF.
https://github.com/iowarp/clio-agent
a2a ai ai4hpc ai4science dspy hpc hpc-ai mcp
Last synced: about 1 month ago
JSON representation
A science agent supporting any general AI agent in performing data management operations at scale. Builds upon the heritage of the IOWarp platform and proudly represents work done at Gnosis Research Center at Illinois Tech. Supported by NSF.
- Host: GitHub
- URL: https://github.com/iowarp/clio-agent
- Owner: iowarp
- License: other
- Created: 2025-10-18T12:45:29.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-05-29T14:33:25.000Z (about 1 month ago)
- Last Synced: 2026-05-29T15:15:59.068Z (about 1 month ago)
- Topics: a2a, ai, ai4hpc, ai4science, dspy, hpc, hpc-ai, mcp
- Language: Python
- Homepage:
- Size: 12.1 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
---
## 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](https://github.com/iowarp/gact-tui)) for interactive work. CLIO is the Intelligence Layer (CEI) of the [IOWarp](https://iowarp.org) 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**
```sh
curl -fsSL https://raw.githubusercontent.com/iowarp/clio-agent/main/install/install.sh | bash
clio
```
**Windows (PowerShell)**
```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`](https://astral.sh/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 ` | 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](install/README.md).
---
## Architecture
For the design rationale (three-tier hierarchy, ARC memory, optimizer layer, IOWarp integration), see [docs/CLIO_AGENT_ARCHITECTURE.md](docs/CLIO_AGENT_ARCHITECTURE.md).
---
## Documentation
| Doc | What's in it |
|---|---|
| [docs/CLIO_AGENT_ARCHITECTURE.md](docs/CLIO_AGENT_ARCHITECTURE.md) | Three-tier design, ARC memory, optimizer layer |
| [docs/SYSTEM_IDENTITY.md](docs/SYSTEM_IDENTITY.md) | What the agent is, design principles |
| [docs/SETUP.md](docs/SETUP.md) | From-scratch install + smoke test (manual path) |
| [docs/CONTRIBUTOR_QUICKSTART.md](docs/CONTRIBUTOR_QUICKSTART.md) | Dev environment, quality checks, where to put code |
| [docs/MCP_TOOL_INTEGRATION.md](docs/MCP_TOOL_INTEGRATION.md) | Adding tools via FastMCP |
| [docs/EXPERT_SYSTEM_DESIGN.md](docs/EXPERT_SYSTEM_DESIGN.md) | Adding new experts |
| [docs/ARC_MEMORY_LAYER.md](docs/ARC_MEMORY_LAYER.md) | Memory model and storage |
| [docs/SELF_IMPROVEMENT.md](docs/SELF_IMPROVEMENT.md) | Optimizer layer |
| [docs/PERMISSIONS.md](docs/PERMISSIONS.md) | Tool permission system |
| [docs/providers/](docs/providers/) | LM provider configuration |
| [docs/CAPABILITIES_MATRIX.md](docs/CAPABILITIES_MATRIX.md) | Feature matrix |
| [PLAN.md](PLAN.md) | Roadmap |
---
## Contributing
Start with [docs/CONTRIBUTOR_QUICKSTART.md](docs/CONTRIBUTOR_QUICKSTART.md). For guidance specific to AI agents working on the codebase, see [AGENTS.md](AGENTS.md).
---
## License + Citation
BSD-3-Clause.
```bibtex
@software{clioagent2026,
title = {CLIO Agent: Autonomous Agent for Scientific Data Management},
author = {IOWarp Team},
year = {2026},
url = {https://github.com/iowarp/clio-agent},
}
```