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

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

Parameters

provider

select

required

AI provider: openai, anthropic, gemini, openrouter, groq, cerebras, deepseek, kimi, mistral, ollama, lmstudio

model

select

required

Model to use (options based on provider)

system_message

string

Instructions that define the agent’s behavior and personality

prompt

string

required

The user message. Supports template variables like {{nodeName.field}}

max_iterations

number

Optional per-node cap on agent loop steps. When unset, falls back to your Settings recursion limit (default 200).

Output

{
  "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

provider

select

required

AI provider: openai, anthropic, gemini, openrouter, groq, cerebras, deepseek, kimi, mistral, ollama, lmstudio

model

select

required

Model to use (options based on provider)

system_message

string

Base system instructions (extended by connected skills)

prompt

string

User message. If empty, reads from connected input node’s message, text, or content field.

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

Template Variable (Explicit):
```
Prompt: {{chatTrigger.message}}
```
Auto-Fallback (Implicit): Leave Prompt empty - the agent reads from the connected input node automatically.

Output

{
  "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]

Connect to the diamond handle, not the main input. The main input is for data flow.

Parameters

sessionId

string

default:"default"

Unique identifier for the conversation session. Use dynamic values for multi-user scenarios.

windowSize

number

default:"10"

Number of message pairs to keep in short-term memory

memoryContent

string

Editable conversation history in markdown format. View and edit directly in the parameter panel.

longTermEnabled

boolean

default:"false"

Archive old messages to vector DB for semantic retrieval

retrievalCount

number

default:"3"

Number of relevant memories to retrieve from long-term storage (shown when longTermEnabled is true)

Memory Format

Conversation history is stored in markdown:

# 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

Agent reads memoryContent markdown from connected Simple Memory node
Parses markdown into message history
(If enabled) Retrieves relevant context from vector store
Executes with conversation history
Appends new messages to markdown
Trims to keep last N pairs (windowSize)
Archives removed messages to vector store (if longTermEnabled)
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

Add AI Agent or Chat Agent from AI Agents category
Add Simple Memory and connect to memory handle (diamond)
Add Tools/Skills and connect to respective handles
Add Trigger (Webhook, Chat, WhatsApp) connected to main input
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

Connect a specialized agent to a parent agent’s input-tools handle
Parent agent calls delegate_to_<agent_type>(task="...", context="...")
Child agent spawns as background task
Parent receives {"status": "delegated", "task_id": "..."} immediately
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

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

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

Use descriptive system prompts to define agent behavior clearly.

Set Max Iterations based on task complexity. Simple Q&A: 1-2, Complex reasoning: 3-5.

Use unique Session IDs per user/conversation for proper isolation.

Connect Skills to Chat Agent for domain-specific behavior (WhatsApp, Maps, HTTP, etc.).

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

Troubleshooting

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)

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

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

Memory grows too large

Reduce windowSize setting (10-20 messages recommended)
Enable long-term memory to archive old messages
Consider clearing sessions periodically

AI Models

11 chat model providers with thinking modes

AI Skills

Skill nodes for AI and Chat Agents

AI Tools

Tool nodes for AI agents

AI Tutorial

Step-by-step agent tutorial

​AI Agents & Memory

​Agent Types

​Specialized Agents

​Agent Teams Pattern

​AI Agent Node

​Input Handles

​Parameters

​Output

​Tool Calling

​Chat Agent Node (Zeenie)

​Input Handles

​Parameters

​Skill Support

​Input Methods

​Output

​Simple Memory Node

​Connection

​Parameters

​Memory Format

​Memory Flow

​Dynamic Session IDs

​Building Agent Workflows

​Basic AI Agent with Tools

​Chat Agent with Skills

​Step-by-Step Setup

​AI Agent vs Chat Agent

​Async Agent Delegation

​How It Works

​Example

​Multi-Turn Conversation Example

​First Request

​Second Request

​Tips

​Troubleshooting

​Related

AI Models

AI Skills

AI Tools

AI Tutorial

AI Agents & Memory

Agent Types

Specialized Agents

Agent Teams Pattern

AI Agent Node

Input Handles

Parameters

Output

Tool Calling

Chat Agent Node (Zeenie)

Input Handles

Parameters

Skill Support

Input Methods

Output

Simple Memory Node

Connection

Parameters

Memory Format

Memory Flow

Dynamic Session IDs

Building Agent Workflows

Basic AI Agent with Tools

Chat Agent with Skills

Step-by-Step Setup

AI Agent vs Chat Agent

Async Agent Delegation

How It Works

Example

Multi-Turn Conversation Example

First Request

Second Request

Tips

Troubleshooting

Related