Yules Agent Documentation

Yules installs on Linux, macOS, WSL2, native Windows, and Android (Termux). The installer handles dependencies, creates the virtual environment, and sets up the gateway.

What the installer does

• Downloads the latest Yules Agent release from GitHub
• Creates a Python virtual environment in ~/.yules/venv
• Installs core dependencies + platform-specific packages
• Sets up the default config at ~/.yules/config.yaml
• Adds the yules CLI to your shell PATH

Post-install

Run yules setup to configure your LLM provider, set up messaging platforms, and run the first-time wizard. This creates your ~/.yules directory structure and validates the installation.

Per-user vs. system-wide

By default, Yules installs per-user (into ~/.yules). This avoids permission issues and makes uninstallation trivial: rm -rf ~/.yules. For system-wide installs, pass --system to the install script (requires root).

This tutorial gets you from zero to a working agent in five minutes. You will start a conversation, run your first tool, and see how Yules remembers context across messages.

1. Start the agent

This launches the Yules gateway in the background. Check status with yules status.

2. Open the CLI interface

You are now in an interactive session. Try your first message:

Yules will use web_search to find sources, browser.open to read papers, and execute_code to synthesize a summary.

3. Watch memory form

After the research task completes, ask: "What did we just research?" Yules recalls the topic, key findings, and sources — even though you never explicitly saved anything. This is the cross-session memory layer at work.

4. Try natural language scheduling

Yules parses the schedule, creates a cron entry, and confirms the delivery channel.

5. Check the Portal

Open http://localhost:8080 in your browser to see the Yules Portal dashboard. You can view active conversations, memory entries, scheduled tasks, and system health from here.

Not sure where to start? Pick the path that matches your experience level.

Yules is configured through a single YAML file at ~/.yules/config.yaml. Changes take effect on the next gateway restart (yules restart).

Config file structure

# ~/.yules/config.yaml

# LLM Provider configuration
provider:
  name: "openrouter"          # openrouter | openai | anthropic | local
  api_key: "${OPENROUTER_API_KEY}"
  model: "anthropic/claude-sonnet-4"
  max_tokens: 4096
  temperature: 0.7

# Gateway settings
gateway:
  host: "0.0.0.0"
  port: 8080
  auth:
    type: "token"
    secret: "${YULES_AUTH_TOKEN}"

# Memory configuration
memory:
  backend: "sqlite"           # sqlite | postgres | chroma
  path: "~/.yules/memory.db"
  compaction_interval: "24h"
  max_entries: 100000

# Messaging platforms
messaging:
  telegram:
    enabled: true
    bot_token: "${TELEGRAM_BOT_TOKEN}"
  discord:
    enabled: true
    bot_token: "${DISCORD_BOT_TOKEN}"
  slack:
    enabled: false
    app_token: "${SLACK_APP_TOKEN}"

# Tool settings
tools:
  enabled:
    - web_search
    - browser
    - execute_code
    - vision
    - image_generation
  execute_code:
    sandbox: "docker"         # none | docker | ssh | singularity | modal
    timeout: 30

# Skills hub
skills:
  auto_create: true
  hub_url: ""
  local_path: "~/.yules/skills"

# Scheduled tasks
scheduler:
  timezone: "UTC"
  max_concurrent: 5

Environment variables

Sensitive values should use the ${VAR_NAME} syntax. Yules loads .env from ~/.yules/.env automatically. Alternatively, export variables in your shell before starting the gateway.

Multiple provider fallback

You can configure multiple providers with priority ordering. If the primary fails (rate limit, outage), Yules automatically falls back to the secondary:

Config validation

Validates your config without starting the gateway. Catches syntax errors, missing required fields, and invalid provider credentials.

Yules connects to multiple messaging platforms through a unified gateway. Each platform is a transport — the agent itself is platform-agnostic. Start a conversation on Telegram, continue it on Discord, and finish in the CLI.

Supported platforms

Setting up Telegram

1. Message @BotFather on Telegram and create a new bot.
2. Copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).
3. Add it to your config.yaml under messaging.telegram.bot_token.
4. Run yules messaging test telegram to verify connectivity.
5. Send /start to your bot. Yules responds immediately.

Context preservation across platforms

Every conversation is tagged with a thread_id derived from the user's identity, not the platform. This means you can start debugging in the CLI, ask a follow-up in Telegram, and receive the final report via Email — all as one continuous thread.

Yules ships with built-in tools covering web search, browser automation, code execution, vision, image generation, text-to-speech, file operations, and more. Tools are organized into toolsets that can be enabled or disabled per-conversation or globally.

Core tool categories

Enabling and disabling tools

In config.yaml, list the tools you want available globally:

Per-conversation tool override

You can restrict tools for a single conversation. This is useful when delegating to a subagent or working with sensitive data:

Creating custom tools

Custom tools are Python functions placed in ~/.yules/tools/. Yules auto-discovers them on startup. A minimal custom tool looks like this:

The @tool decorator registers the function with Yules. The docstring becomes the tool description sent to the LLM. The ToolContext gives you access to config, memory, and the current conversation.

Programmatic Tool Calling

For complex multi-step pipelines, use execute_code with theyules.tools API to call tools directly from Python. This collapses multi-turn tool loops into a single inference call, saving tokens and latency.

Yules uses persistent memory that stores cross-session facts, skills, and conversation history. Memory is searchable and grows as you use the agent.

How memory is stored

By default, long-term memory uses SQLite with FTS5 for full-text search. For larger deployments, switch to PostgreSQL or ChromaDB:

Manual memory operations

Skills are reusable workflows that Yules creates automatically. When the agent notices it solving the same type of problem repeatedly, it proposes creating a skill. Once accepted, that skill becomes available as a callable tool in future conversations.

Skill format

Skills are stored as YAML + Python files in ~/.yules/skills/. They are portable and can be shared between compatible agents.

Sharing skills

Skills can be shared with other users or installed from a remote source:

Managing skills

Model Context Protocol (MCP) is an open standard for extending agent capabilities through external servers. Yules supports MCP out of the box — connect to any MCP server (filesystem, database, GitHub, Slack, browser, etc.) and its tools become available to the agent immediately.

What is MCP?

MCP servers expose a standardized JSON-RPC interface. They run as separate processes and communicate with Yules over stdio or HTTP/SSE. This isolation means a crashing MCP server never takes down the agent, and you can audit every tool call independently.

Adding an MCP server

Edit ~/.yules/config.yaml to register MCP servers:

Tool filtering

Not every tool from every MCP server should be available to the LLM. Yules lets you filter by name pattern, argument type, or risk level:

In this example, the filesystem MCP server can only read and list. Write operations are explicitly blocked, even if the server advertises them.

Audit and logging

Every MCP tool call is logged with full arguments, timing, and result summary. Access logs via the Portal or CLI:

Practical patterns for integrating MCP servers into your Yules workflows.

Pattern 1: Read-only knowledge base

Connect a filesystem MCP server to a directory of documentation, RFCs, and meeting notes. Yules can then answer questions like "What did we decide about the auth flow in March?"by searching the knowledge base directly — no manual uploads needed.

Pattern 2: Database querying

Connect the PostgreSQL MCP server and ask natural language questions about your data:

Yules generates the SQL via the MCP server, executes it, and presents the results. With filtering configured, destructive queries (DROP, DELETE) are blocked automatically.

Pattern 3: GitHub issue triage

Connect the GitHub MCP server to automate issue management. Yules can:

• List open issues with specific labels
• Draft responses based on issue content and project context
• Create PRs from branch comparisons
• Search code for references to a failing API

Pattern 4: Multi-MCP orchestration

Yules can use multiple MCP servers in a single workflow. For example, reading a GitHub issue, querying the database for affected users, and posting an update to Slack — all coordinated through natural language:

Debugging MCP connections

Yules supports voice interaction in CLI and messaging platforms. Speech recognition uses Whisper; text-to-speech supports multiple backends.

Setup

SOUL.md is Yules' personality definition file. It sits at ~/.yules/SOUL.md and shapes how the agent communicates, what tone it uses, and what values it prioritizes in ambiguous situations. It is loaded into the system prompt on every inference.

What goes in SOUL.md

A SOUL.md file is markdown with structured sections. The LLM reads it as part of its system instructions, so clarity and specificity matter:

Per-project personality overrides

You can place a SOUL.md in any project directory. When Yules detects one, it merges the project SOUL.md with the global one — project settings override globals for conflicts. This lets you define domain-specific personas:

• A data science project might prioritize statistical rigor and visualization
• A frontend project might prioritize UX accessibility and component reusability
• A security audit project might prioritize paranoid validation and explicit consent

Dynamic personality adaptation

Over time, Yules observes your reactions (corrections, approvals, follow-up depth) and suggests SOUL.md adjustments. These are presented as diffs — you approve or reject them.

Opens SOUL.md in your $EDITOR. Changes take effect on the next message — no restart required.

Context files inject structured project information into every conversation. They help Yules understand codebase conventions, architectural decisions, and active priorities without you repeating them.

.yules.md files

Place a .yules.md file at the root of any project directory. Yules automatically loads it when the conversation references files in that tree.

Context hierarchy

When multiple context files apply, Yules merges them with a well-defined precedence:

1. Global SOUL.md — Base personality and values
2. Project .yules.md — Tech stack, architecture, conventions
3. Directory .yules.md — Subdirectory-specific rules (e.g., app/api/.yules.md)
4. Conversation memory — Facts learned during this thread
5. Ephemeral context — Current file contents, selection, etc.

Lower numbers have higher precedence. A project file overrides the global SOUL.md; a directory file overrides the project file.

Dynamic context injection

Yules can also read context from other sources automatically:

• package.json, pyproject.toml — dependency info
• README.md — project overview
• CONTRIBUTING.md — contribution guidelines
• Git history — recent commits, active branch, merge conflicts

Yules is designed with security as a first-class concern. By default, it operates in a conservative mode that requires explicit approval for destructive operations. Every layer of the stack — from tool execution to container isolation to API authentication — is hardened against misuse.

Container isolation

The execute_code and execute_shell tools support multiple sandbox backends:

Choose the backend that matches your environment. Local runs without isolation. Docker provides container sandboxing. SSH, Singularity, and Modal let you run code on remote or serverless infrastructure.

Subagent isolation

When Yules spawns subagents for parallel work, each runs in its own isolated context with separate tool permissions and conversation history.

Quick wins to get the most out of Yules, gathered from the core team and power users.

1. Start with a strong SOUL.md

Spending 10 minutes writing a clear SOUL.md saves hours of correcting tone and behavior later. Be specific about your communication preferences, domain expertise, and boundary conditions.

2. Use natural language for scheduling

Yules' scheduler understands natural time expressions. Instead of memorizing cron syntax, say:

Yules converts these to cron internally and confirms the exact schedule before activating.

3. Compact memory before long sessions

If you're starting a deep research or coding marathon, run yules memory compact first. This ensures the semantic search index is fresh and maximizes recall quality for the session.

4. Delegate with subagents

For multi-step tasks with independent workstreams, spawn subagents instead of doing everything in one conversation:

Each subagent runs in parallel with isolated context. The parent agent consolidates results.

5. Version your config

Track ~/.yules/config.yaml and ~/.yules/SOUL.md in a private dotfiles repo. This makes setting up a new machine trivial and lets you roll back configuration changes.

6. Use the Portal for debugging

When a conversation behaves unexpectedly, open the Portal and inspect the raw tool calls, memory retrievals, and inference logs. Often the issue is a misconfigured tool filter or an oversized context window — both visible in the Portal's trace view.

7. Enable skill auto-creation selectively

Skill auto-creation is powerful but can generate noise. Start with it enabled, review proposed skills for a week, then disable auto-creation and manually create skills for patterns you actually repeat.

8. Set tool timeouts aggressively

Long-running tools (browser automation, code execution) can stall a conversation. Set short timeouts in config and let Yules retry with adjusted parameters:

Yules is built as a modular, event-driven system. Understanding the architecture helps you debug issues, extend functionality, and optimize performance for your workload.

High-level overview

The system has four major layers:

Terminal backends

The execute_code and execute_shell tools support five execution environments:

Scheduler

The built-in scheduler supports cron expressions and natural language scheduling. It runs inside the gateway process and can deliver to any configured messaging platform.

Common questions and solutions. If your issue isn't here, check the GitHub Issues or run yules doctor for automated diagnostics.