# Getting Started

<figure><img src="https://2876188756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaYWMnSvvJAE6Ubi1SkCT%2Fuploads%2FHHU5kqeQgW8jUWMMOJeL%2Fimage.png?alt=media&#x26;token=c244d9a8-e9c0-4e7f-8f2f-a0df4eedaffa" alt=""><figcaption></figcaption></figure>

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

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

#### 2. Setup a Virtual Environment

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

#### 3. Install Dependencies

```bash
bashCopyEditpip install -r requirements.txt
```

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

```bash
bashCopyEditpip install faiss-cpu playwright langchain openai
```

#### 4. Configure Environment Variables

Copy the `.env.example` file and rename it:

```bash
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

```bash
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.

```python
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:

```python
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.