Getting Started

Welcome to Cleo, a modular, self-hosted AI automation framework designed for building intelligent agents with native support for task chaining, long-term memory, and secure local execution.

Cleo provides a developer-first environment for orchestrating autonomous systems capable of acting on data, integrating APIs, and evolving workflows over time. Whether you’re looking to automate personal tasks, prototype intelligent agents, or deploy scalable internal tools, Cleo is designed to get you from concept to execution efficiently.

---

Key Concepts

Before diving into installation, it’s important to understand what makes Cleo distinct:

• Self-Hosted Autonomy: Run intelligent agents entirely on your own hardware or cloud environment.

• Extensible Agents: Customize core behaviors and logic using modular components.

• Data-Driven Reasoning: Access local or remote datasets for context-aware decisions.

• Command Routing: Use natural-language task inputs and direct them through actionable functions.

• Memory Models: Optional support for embedding-based long-term memory using vector databases.

---

Quickstart Guide

The following instructions will get a local instance of Cleo running in under 10 minutes.

1. Clone the Repository

bashCopyEditgit clone https://github.com/HUADA999/Cleo.git
cd Cleo

2. Setup a Virtual Environment

bashCopyEditpython -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

3. Install Dependencies

bashCopyEditpip install -r requirements.txt

You may also choose to install optional dependencies for extended functionality (e.g., memory persistence, browser control):

bashCopyEditpip install faiss-cpu playwright langchain openai

4. Configure Environment Variables

Copy the .env.example file and rename it:

bashCopyEditcp .env.example .env

Edit it with your preferred credentials. At minimum, you’ll want:

iniCopyEditOPENAI_API_KEY=your_key_here

5. Run the Main Entry Point

bashCopyEditpython main.py

You’ll see Cleo boot up and enter an interactive command loop or task handler mode depending on your configuration.

---

Sample Task Execution

Once Cleo is running, you can start issuing commands or feeding tasks into the agent loop.

pythonCopyEdit>>> from cleo.agent import Agent

>>> agent = Agent(name="Atlas", persona="Research Assistant")
>>> agent.run_task("Summarize the latest updates from NASA’s Mars program.")

This will engage the agent pipeline, route the task through the appropriate toolsets (e.g., web search, summarizer), and output structured results.

---

Agent Configuration Example

Agents can be initialized using config files or directly via Python. Here’s a minimal example:

pythonCopyEditagent_config = {
    "name": "Lex",
    "persona": "Technical Writer",
    "tools": ["WebScraper", "Summarizer"],
    "memory": True,
    "voice": False
}

agent = Agent(**agent_config)
agent.run_task("Generate a report on recent AI policy developments in Europe.")

---

Developer Note

Cleo was designed with modular extensibility in mind. You’ll find key folders like:

• /core: Task engine, memory interfaces, and routing logic

• /tools: Pluggable capabilities (e.g., web browsing, summarization, API connectors)

• /agents: Templates and profiles for AI personas

• /config: Environment settings and default agent setups

The framework encourages small composable tools, each with isolated responsibilities, following the UNIX philosophy.

---

Next Steps

Once you’ve installed Cleo and run your first task:

• Explore the agents/ directory and define your first custom agent.

• Extend tool capabilities by writing a module inside tools/.

• Enable memory and persistence features via vector DB backends like FAISS or Chroma.

• Connect external APIs for real-world task execution.

---

Suggested Sub-Pages

• System Requirements & Dependencies Understand which libraries power Cleo, how to install optional capabilities, and what’s needed for full-stack deployment.

• Project Structure & Key Components A breakdown of the directory layout, architectural decisions, and best practices for extending Cleo.