> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencompany.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents & Memory

> Build intelligent agents with conversation memory, skills, and tool calling

# AI Agents & Memory

MachinaOs provides two general-purpose AI agents plus a set of specialized, pre-configured agents, all sharing a memory node for conversation context.

## Agent Types

| Agent               | Purpose                             | Special Features                               |
| ------------------- | ----------------------------------- | ---------------------------------------------- |
| AI Agent            | Complex reasoning with tool calling | Iterative agent loop, tool calling, delegation |
| Chat Agent (Zeenie) | Conversational AI with skills       | Skill-driven behavior, multi-turn chat         |
| Simple Memory       | Conversation history storage        | Markdown format, long-term vector storage      |

### Specialized Agents

Pre-configured agents for specific domains. Each is a self-contained plugin that inherits full AI Agent behavior (provider, model, prompt, system message, thinking) while being tailored for a domain. Most run the shared agent loop; `rlm_agent`, `claude_code_agent`, and `codex_agent` have dedicated engines.

| Agent                 | Description                                                           | Theme  |
| --------------------- | --------------------------------------------------------------------- | ------ |
| Android Control Agent | Android device control via ADB                                        | Green  |
| Coding Agent          | Python / JavaScript / TypeScript code execution                       | Cyan   |
| Web Control Agent     | Web automation and scraping                                           | Pink   |
| Task Management Agent | Task automation and scheduling                                        | Purple |
| Social Media Agent    | WhatsApp, Telegram, Twitter messaging                                 | Green  |
| Travel Agent          | Location and maps services                                            | Orange |
| Tool Agent            | Flexible tool orchestration                                           | Yellow |
| Productivity Agent    | Google Workspace workflows                                            | Cyan   |
| Payments Agent        | Payment processing                                                    | Green  |
| Consumer Agent        | Customer support interactions                                         | Purple |
| Autonomous Agent      | Code Mode with agentic loops (81-98% token savings)                   | Purple |
| Orchestrator Agent    | Team lead for multi-agent coordination                                | Cyan   |
| AI Employee           | Team lead (alternate branding)                                        | Purple |
| RLM Agent             | Recursive Language Model via REPL (`llm_query`, `rlm_query`, `FINAL`) | Orange |
| Claude Code Agent     | Claude Code CLI integration (interactive mode)                        | Purple |
| Codex Agent           | Codex CLI integration                                                 | Purple |

### Agent Teams Pattern

`orchestrator_agent` and `ai_employee` have an extra `input-teammates` handle. Connected agents become `delegate_to_<type>` tools automatically:

```
                 Team Lead (AI Employee / Orchestrator)
                          |
                          | input-teammates
         +----------------+----------------+
         |                |                |
   Coding Agent      Web Agent       Task Agent
   (delegate_to_     (delegate_to_   (delegate_to_
    coding_agent)     web_agent)      task_agent)
```

Delegation is fire-and-forget: the child agent spawns as a background task, the parent continues working, and the child broadcasts its status independently. Completion results can be consumed by a `taskTrigger` node connected to the parent's Task handle.

***

## AI Agent Node

The AI Agent runs an iterative agent loop with tool calling and delegation.

### Input Handles

| Handle                    | Position         | Purpose                                     |
| ------------------------- | ---------------- | ------------------------------------------- |
| Main Input (`input-main`) | Left             | User prompt/data from upstream nodes        |
| Memory (`input-memory`)   | Left (diamond)   | Connect Simple Memory                       |
| Task (`input-task`)       | Left (diamond)   | Connect taskTrigger for delegation feedback |
| Skill (`input-skill`)     | Bottom (diamond) | Connect Master Skill                        |
| Tools (`input-tools`)     | Bottom (diamond) | Connect Tool nodes or dual-purpose nodes    |

<Info>
  Team lead agents (Orchestrator Agent, AI Employee) add an extra `input-teammates` handle for delegation.
</Info>

### Parameters

<ParamField path="provider" type="select" required>
  AI provider: openai, anthropic, gemini, openrouter, groq, cerebras, deepseek, kimi, mistral, ollama, lmstudio
</ParamField>

<ParamField path="model" type="select" required>
  Model to use (options based on provider)
</ParamField>

<ParamField path="system_message" type="string">
  Instructions that define the agent's behavior and personality
</ParamField>

<ParamField path="prompt" type="string" required>
  The user message. Supports template variables like `{{nodeName.field}}`
</ParamField>

<ParamField path="max_iterations" type="number">
  Optional per-node cap on agent loop steps. When unset, falls back to your Settings recursion limit (default 200).
</ParamField>

### Output

```json theme={null}
{
  "response": "The agent's final response",
  "thinking": "Reasoning process (if thinking enabled)",
  "iterations": 2,
  "tool_calls": [
    {"tool": "calculator", "input": {"operation": "add", "a": 5, "b": 3}, "output": 8}
  ]
}
```

### Tool Calling

Connect Tool nodes to the **input-tools** handle (bottom diamond) to give the agent capabilities:

```
[Calculator Tool] --+
                    +--> [AI Agent] --> [Output]
[Web Search Tool] --+
```

The agent will automatically use tools when needed based on the user's request.

***

## Chat Agent Node (Zeenie)

The Chat Agent is designed for conversational interactions with skill-based behavior extension.

### Input Handles

| Handle                    | Position         | Purpose                                     |
| ------------------------- | ---------------- | ------------------------------------------- |
| Main Input (`input-main`) | Left             | User message (e.g., from Chat Trigger)      |
| Memory (`input-memory`)   | Left (diamond)   | Connect Simple Memory                       |
| Task (`input-task`)       | Left (diamond)   | Connect taskTrigger for delegation feedback |
| Skills (`input-skill`)    | Bottom (diamond) | Connect Skill nodes                         |
| Tools (`input-tools`)     | Bottom (diamond) | Connect Tool nodes                          |

### Parameters

<ParamField path="provider" type="select" required>
  AI provider: openai, anthropic, gemini, openrouter, groq, cerebras, deepseek, kimi, mistral, ollama, lmstudio
</ParamField>

<ParamField path="model" type="select" required>
  Model to use (options based on provider)
</ParamField>

<ParamField path="system_message" type="string">
  Base system instructions (extended by connected skills)
</ParamField>

<ParamField path="prompt" type="string">
  User message. If empty, reads from connected input node's `message`, `text`, or `content` field.
</ParamField>

### Skill Support

Connect Skill nodes to the **input-skill** handle to extend the Chat Agent's capabilities:

```
[WhatsApp Skill] --+
                   +--> [Chat Agent] --> [Response]
[Maps Skill] ------+
```

Skills provide domain-specific instructions and allowed tools to the Chat Agent.

### Input Methods

1. **Template Variable (Explicit)**:
   ```
   Prompt: {{chatTrigger.message}}
   ```

2. **Auto-Fallback (Implicit)**: Leave Prompt empty - the agent reads from the connected input node automatically.

### Output

```json theme={null}
{
  "response": "Chat Agent's response",
  "thinking": "Reasoning (if enabled)",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic"
}
```

***

## Simple Memory Node

Stores conversation history in markdown format for AI agents.

### Connection

Simple Memory connects to the **memory handle** (diamond shape on bottom-left):

```
[Simple Memory] ---(diamond)---> [AI Agent or Chat Agent]
```

<Warning>
  Connect to the diamond handle, not the main input. The main input is for data flow.
</Warning>

### Parameters

<ParamField path="sessionId" type="string" default="default">
  Unique identifier for the conversation session. Use dynamic values for multi-user scenarios.
</ParamField>

<ParamField path="windowSize" type="number" default="10">
  Number of message pairs to keep in short-term memory
</ParamField>

<ParamField path="memoryContent" type="string">
  Editable conversation history in markdown format. View and edit directly in the parameter panel.
</ParamField>

<ParamField path="longTermEnabled" type="boolean" default="false">
  Archive old messages to vector DB for semantic retrieval
</ParamField>

<ParamField path="retrievalCount" type="number" default="3">
  Number of relevant memories to retrieve from long-term storage (shown when longTermEnabled is true)
</ParamField>

### Memory Format

Conversation history is stored in markdown:

```markdown theme={null}
# Conversation History

### **Human** (2025-01-30 14:23:45)
What is the weather like today?

### **Assistant** (2025-01-30 14:23:48)
I don't have access to real-time weather data...
```

### Memory Flow

1. Agent reads `memoryContent` markdown from connected Simple Memory node
2. Parses markdown into message history
3. (If enabled) Retrieves relevant context from vector store
4. Executes with conversation history
5. Appends new messages to markdown
6. Trims to keep last N pairs (windowSize)
7. Archives removed messages to vector store (if longTermEnabled)
8. Saves updated markdown back to node parameters

### Dynamic Session IDs

For multi-user scenarios, use template variables:

```
Session ID: {{webhookTrigger.body.user_id}}
```

This creates separate memory for each user.

***

## Building Agent Workflows

### Basic AI Agent with Tools

```
[Webhook Trigger] --> [AI Agent] --> [Webhook Response]
                          ^
                          |
                   [Simple Memory]

                   [Calculator Tool]
                          |
                          v
                     [AI Agent]
```

### Chat Agent with Skills

```
[Chat Trigger] --> [Chat Agent] --> [Console]
                        ^
                        |
                 [Simple Memory]

                 [WhatsApp Skill]
                        |
                        v
                   [Chat Agent]
```

### Step-by-Step Setup

1. **Add AI Agent or Chat Agent** from AI Agents category
2. **Add Simple Memory** and connect to memory handle (diamond)
3. **Add Tools/Skills** and connect to respective handles
4. **Add Trigger** (Webhook, Chat, WhatsApp) connected to main input
5. **Add Response** node connected to agent output

***

## AI Agent vs Chat Agent

| Feature        | AI Agent                   | Chat Agent (Zeenie)                |
| -------------- | -------------------------- | ---------------------------------- |
| Primary Use    | Complex reasoning tasks    | Conversational interactions        |
| Tool Calling   | Yes (agent loop)           | Yes (agent loop)                   |
| Memory Support | Yes                        | Yes                                |
| Skill Support  | Yes                        | Yes                                |
| Bottom Handles | Skill, Tools               | Skill, Tools                       |
| Left Handles   | Input, Memory, Task        | Input, Memory, Task                |
| Best For       | Task automation, reasoning | Chat interfaces, multi-turn dialog |

***

## Async Agent Delegation

Agents can delegate tasks to other agents connected via the `input-tools` handle. The parent agent continues immediately while the child works in the background.

### How It Works

1. Connect a specialized agent to a parent agent's `input-tools` handle
2. Parent agent calls `delegate_to_<agent_type>(task="...", context="...")`
3. Child agent spawns as background task
4. Parent receives `{"status": "delegated", "task_id": "..."}` immediately
5. Child executes independently with its own tools

### Example

```
[AI Agent] <--tools-- [Android Control Agent] <--tools-- [Battery Monitor]
                                              <--tools-- [WiFi Automation]
```

When the AI Agent needs Android control:

* Calls `delegate_to_android_agent(task="Check battery and enable WiFi if low")`
* Android Agent spawns in background with its own connected tools
* AI Agent continues with other work

***

## Multi-Turn Conversation Example

### First Request

```bash theme={null}
curl -X POST http://localhost:3010/webhook/chat \
  -d '{"user_id": "user123", "message": "My name is Alex"}'
```

Response: "Nice to meet you, Alex! How can I help you today?"

### Second Request

```bash theme={null}
curl -X POST http://localhost:3010/webhook/chat \
  -d '{"user_id": "user123", "message": "What is my name?"}'
```

Response: "Your name is Alex, as you told me earlier."

***

## Tips

<Tip>
  Use descriptive **system prompts** to define agent behavior clearly.
</Tip>

<Tip>
  Set **Max Iterations** based on task complexity. Simple Q\&A: 1-2, Complex reasoning: 3-5.
</Tip>

<Tip>
  Use unique **Session IDs** per user/conversation for proper isolation.
</Tip>

<Tip>
  Connect **Skills** to Chat Agent for domain-specific behavior (WhatsApp, Maps, HTTP, etc.).
</Tip>

<Warning>
  Long conversations with large window sizes can exceed model context limits. Use appropriate windowSize for your use case.
</Warning>

***

## Troubleshooting

<Accordion title="Agent doesn't remember previous messages">
  * Verify Simple Memory is connected to diamond handle (not main input)
  * Check Session ID is consistent across requests
  * Ensure workflow is deployed (not just saved)
</Accordion>

<Accordion title="Agent doesn't use connected tools">
  * Verify Tool nodes are connected to the input-tools diamond handle
  * Check tool node has proper schema/description
  * Ensure the prompt requires tool usage
</Accordion>

<Accordion title="Skills not affecting Chat Agent behavior">
  * Verify Skill nodes are connected to input-skill handle
  * Check skill SKILL.md content is valid
  * Ensure skill's allowed-tools match connected tool nodes
</Accordion>

<Accordion title="Memory grows too large">
  * Reduce windowSize setting (10-20 messages recommended)
  * Enable long-term memory to archive old messages
  * Consider clearing sessions periodically
</Accordion>

***

## Related

<CardGroup cols={2}>
  <Card title="AI Models" icon="brain" href="/nodes/ai-models">
    11 chat model providers with thinking modes
  </Card>

  <Card title="AI Skills" icon="wand-magic-sparkles" href="/nodes/skills">
    Skill nodes for AI and Chat Agents
  </Card>

  <Card title="AI Tools" icon="screwdriver-wrench" href="/nodes/tools">
    Tool nodes for AI agents
  </Card>

  <Card title="AI Tutorial" icon="graduation-cap" href="/tutorials/ai-agent-workflow">
    Step-by-step agent tutorial
  </Card>
</CardGroup>