area: main
id: bz0Xey3NFp
timestamp: 2026-04-20 15:39:21
Content: User's project ecosystem:
- **Glitch University**: Hybrid learning platform, alien-sponsored university, and YouTube channel
- **Omega13**: Local computer used for inference (just the machine name)
- **Festinger**: A Knowledge Graph repo within Glitch University, part of the Omega13 local inference setup. Stores taxonomic (is-a) relations between concepts. Uses index collisions to prevent contradictory memories. Runs as a proxy that triggers on non-standard/local concepts in conversation to build a domain glossary. Only handles IS_ISA relations along dimensions like 'type' and 'membership'.

source: /a0/knowledge/main/about/configuration.md
area: main
source_file: configuration.md
source_path: /a0/knowledge/main/about/configuration.md
file_type: md
knowledge_source: True
import_timestamp: None
id: nf8PB1IWKX
timestamp: 2026-04-09 16:19:13
Content: # Agent Zero - Configuration Reference

## LLM Roles

Agent Zero uses three configurable LLM roles:

| Role | Purpose |
|------|---------|
| `chat_llm` | Primary model for all agent reasoning, tool use, and the Browser Agent |
| `utility_llm` | Secondary model for internal framework tasks: memory summarization, query generation, history compression, memory recall filtering |
| `embedding_llm` | Produces vector embeddings for memory and knowledge indexing |

The utility model handles high-volume, lower-stakes operations and can be a cheaper/faster model than the chat model. The Browser Agent uses the effective chat model resolved by `_model_config`, including per-chat overrides and the chat model vision flag. Changing the embedding model invalidates the existing vector index - the entire knowledge base is re-indexed automatically.

## Model Providers

Providers are defined in `conf/model_providers.yaml`. All chat and embedding providers go through LiteLLM, which normalizes the API interface. Supported chat providers (as of v0.9.8):

- Agent Zero API (a0_venice) - hosted service with no API key required for basic use
- Anthropic, OpenAI, OpenRouter, Google (Gemini), Groq, Mistral AI
- DeepSeek, xAI, Moonshot AI, Sambanova, CometAPI, Z.AI, Inception AI
- Venice.ai, AWS Bedrock, Azure OpenAI
- GitHub Copilot, HuggingFace
- Ollama, LM Studio (local models)
- Other OpenAI-compatible endpoints (custom `api_base`)

Embedding providers: OpenAI, Azure, Ollama, LM Studio, HuggingFace, Google, Mistral, OpenRouter (via OpenAI-compat), AWS Bedrock.

### Model Naming Convention

| Provider | Format |
|----------|--------|
| OpenAI | model name only (`gpt-4.1`, `o4-mini`) |
| Anthropic | model name only (`claude-sonnet-4-5`) |
| OpenRouter | `provider/model` (`anthropic/claude-sonnet-4-5`) |
| Ollama | model name only (`llama3.2`, `qwen2.5`) |
| Google | model name only (`gemini-2.0-flash`) |

## Agent Profiles

Profiles are in `agents/<profile>/`. Each profile can override any prompt fragment from the base `prompts/` directory. Built-in profiles:

| Profile | Description |
|---------|-------------|
| `default` | Base template for creating new profiles |
| `agent0` | Top-level general assistant; human as superior; delegates to specialized subordinates |
| `developer` | "Master Developer" - software architecture and full-stack implementation focus |
| `researcher` | "Deep Research" - research, analysis, and synthesis across academic and corporate domains |
| `hacker` | Red/blue team; penetration testing; Kali tools focus |
| `_example` | Minimal example for building custom profiles |

Custom profiles go in `usr/agents/<profile>/` to survive framework updates.

## Plugin System

Plugins are discovered from `plugins/` (framework plugins) and `usr/plugins/` (user plugins). Each plugin requires a `plugin.yaml` with at minimum: `name`, `description`, `version`.

### Activation

- **Global activation**: enabled/disabled for all contexts via the Plugins settings panel
- **Scoped activation**: enabled/disabled per project or per agent profile via the plugin Switch modal
- Activation state stored as `.toggle-1` (ON) and `.toggle-0` (OFF) files in the plugin's config dir

### Built-in Framework Plugins

| Plugin | Purpose |
|--------|---------|
| `_memory` | Memory and knowledge pipeline, recall, consolidation |
| `_code_execution` | Terminal and code execution tool |
| `_text_editor` | Structured file read/write/patch tool |

## Environment Variable Configuration

Any setting can be set via environment variable using the `A0_SET_` prefix. This is the primary mechanism for automated deployment and container configuration.

Format: `A0_SET_<setting_name>=<value>`

Examples:
```
A0_SET_chat_model_provider=anthropic
A0_SET_chat_model_name=claude-sonnet-4-5
A0_SET_utility_model_provider=openai
A0_SET_utility_model_name=gpt-4o-mini
A0_SET_embedding_model_provider=openai
A0_SET_embedding_model_name=text-embedding-3-small
```

source: /a0/knowledge/main/about/architecture.md
area: main
source_file: architecture.md
source_path: /a0/knowledge/main/about/architecture.md
file_type: md
knowledge_source: True
import_timestamp: None
id: aSaAjoJbVs
timestamp: 2026-04-09 16:19:13
Content: # Agent Zero - Internal Architecture

## The Agent Loop (Monologue Cycle)

Each agent runs a continuous monologue loop. On each cycle the agent receives its current context (system prompt + message history), produces a JSON response (thoughts, headline, tool name, tool args), and the framework executes the named tool. The tool result is appended to history and the loop continues until the agent calls `response` to deliver a final answer to its superior.

The loop handles: message history management, context window limits (via summarization), memory recall injection, intervention from superiors, and error recovery (misformat retries, tool-not-found handling).

## Context and State

`AgentContext` (defined in `agent.py`) is the central state container for a conversation. It holds:
- Agent number and identifier
- Message history
- The active agent profile and prompt configuration
- Reference to memory, knowledge, and tool systems
- Project context if a project is active
- `extras` dict - additional content injected into the system prompt each turn (memories, solutions, agent info, workdir structure)

Each WebSocket session connects to one `AgentContext`. Multiple concurrent chats run in separate contexts. The framework is initialized in `initialize.py` and the server entry point is `run_ui.py`.

## Prompt Assembly

System prompts are assembled from fragment files on each loop iteration. The main system prompt is `prompts/agent.system.main.md`, which includes sub-prompts via `{{ include "filename.md" }}` directives. Agent profiles (in `agents/<profile>/prompts/`) can override individual fragments. This means a subordinate with the `developer` profile gets a different role and communication section while sharing the same tool list and solving workflow as the base agent.

Prompt fragments are in `prompts/`. Plugin system prompts are in `plugins/<plugin>/prompts/`. The assembled system prompt is dynamic - it changes based on profile, active project, loaded tools, recalled memories, and injected extras.

## Multi-Agent Hierarchy

The hierarchy is a tree with the human user at the root. Each node is an agent instance running in its own context. A superior calls `call_subordinate` with a message and optional profile name; this creates a new `AgentContext` and runs the subordinate agent's loop until it returns a response.

Agent 0 is always the top-level agent whose superior is the user. When Agent 0 delegates a task to a subordinate, that subordinate can itself delegate further. There is no enforced depth limit. Agents share the same tool system but each has its own isolated context and history.

Subordinates can be given specific prompt profiles (`developer`, `researcher`, or any custom profile in `agents/`). Profiles change the role, communication style, and available instructions without changing the underlying framework.

## Memory and Knowledge Pipeline

### Knowledge (vector DB, read-only)
Knowledge files (in `knowledge/` and `usr/knowledge/`) are loaded when a memory DB is initialized (normally at the start of the first monologue in a chat), embedded, and stored in a FAISS vector index per memory subdir. Files are tracked by checksum; only changed files are re-indexed. Supported formats: `.md`, `.txt`, `.pdf`, `.csv`, `.html`, `.json`.

The memory areas are:
- `main` - general knowledge and facts (files in knowledge root or `main/` subdir)
- `fragments` - partial or supplementary knowledge
- `solutions` - known solutions to problems

### Recall (automatic, per conversation turn)
The `RecallMemories` extension runs every N loop iterations (configurable). It queries the vector store using either the raw conversation or a utility-LLM-generated search query. Results from `main` and `fragments` areas plus `solutions` are injected into `loop_data.extras_persistent`, which gets rendered into the system prompt via `agent.context.extras.md` template.

source: /a0/knowledge/main/about/configuration.md
area: main
source_file: configuration.md
source_path: /a0/knowledge/main/about/configuration.md
file_type: md
knowledge_source: True
import_timestamp: None
id: p7dsTb3zYn
timestamp: 2026-04-09 16:19:13
Content: These can be set in the `.env` file at the project root or passed as Docker `-e` flags during container creation.

## Key Behavioral Settings

| Setting | Effect |
|---------|--------|
| `agent_knowledge_subdir` | Which knowledge subdir to load (default: `custom`, resolved to `usr/knowledge/`) |
| `memory_recall_interval` | How many loop iterations between automatic memory recalls |
| `memory_results` | Number of memory chunks returned per recall query |
| `memory_threshold` | Similarity threshold for memory recall (0-1); lower = more results, potentially less relevant |
| `auth_login` / `auth_password` | Web UI authentication credentials |
| `agent_temperature` | LLM temperature for the chat model |

Settings are stored in `usr/settings.json` and managed through the Settings page in the web UI. The settings page also provides: API key management (multiple keys per provider with round-robin), backup/restore, external services (tunnels, MCP, A2A), and memory management.

source: /a0/knowledge/main/about/setup-and-deployment.md
area: main
source_file: setup-and-deployment.md
source_path: /a0/knowledge/main/about/setup-and-deployment.md
file_type: md
knowledge_source: True
import_timestamp: None
id: zY9364W5fn
timestamp: 2026-04-09 16:19:13
Content: **Knowledge files not being recalled:**
- Supported formats: `.md`, `.txt`, `.pdf`, `.csv`, `.html`, `.json`
- Files must be in `knowledge/` (framework level) or `usr/knowledge/<subdir>/`
- The configured `agent_knowledge_subdir` must match the subdir where files are placed
- Re-indexing is triggered automatically when file checksums change

**Ollama / local model setup:**
- Ollama must be running and accessible from inside the Docker container
- Use `http://host.docker.internal:<port>` as the API URL for Ollama (not `localhost`)
- Pull the model first: `ollama pull <model-name>`

## Development Setup (non-Docker)

```bash
git clone https://github.com/agent0ai/agent-zero
cd agent-zero
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements2.txt
python run_ui.py
```

The dev server runs on `http://localhost:5000` by default. User data is written to `usr/` in the project root.

source: /a0/knowledge/main/about/capabilities.md
area: main
source_file: capabilities.md
source_path: /a0/knowledge/main/about/capabilities.md
file_type: md
knowledge_source: True
import_timestamp: None
id: 15omi5DC80
timestamp: 2026-04-09 16:19:13
Content: ## External API and MCP

Agent Zero can act as both an MCP server and an MCP client:
- As an **MCP server**: exposes agent capabilities to other MCP-compatible clients
- As an **MCP client**: uses tools from external MCP servers (configured per project or globally)

An external REST API is available for programmatic task submission. Agent-to-Agent (A2A) protocol is supported for inter-system agent communication.

## Limitations

- **No persistent state between chats** unless explicitly memorized or saved to files.
- **Context window**: long conversations are summarized automatically, which can lose detail.
- **Memory recall is approximate**: similarity search may miss relevant memories or surface irrelevant ones.
- **No GUI interaction** outside the browser agent (which is separate from the main agent).
- **Container boundary**: the agent cannot affect systems outside the Docker container unless network access or volume mounts are configured.
- **Model capability ceiling**: tool usage quality and reasoning depth are bounded by the underlying LLM. Small models may struggle with complex multi-step tool use.
- **No real-time data** beyond web search. The agent's own knowledge cutoff is the underlying model's training cutoff.

area: fragments
timestamp: 2026-03-08 11:40:50
id: 6SSHP1uj89
Content: model not found

source: /a0/knowledge/main/about/architecture.md
area: main
source_file: architecture.md
source_path: /a0/knowledge/main/about/architecture.md
file_type: md
knowledge_source: True
import_timestamp: None
id: bHL9JyLQRw
timestamp: 2026-04-09 16:19:13
Content: The agent sees recalled memories as a section in its system prompt labeled "Memories on the topic". The agent is instructed not to over-rely on them.

### Agent memory (read-write, via memorize tool)
The agent can explicitly save facts, solutions, and code snippets using the `memorize` tool. These are stored in the same FAISS index under the `main` or `solutions` area and recalled in future conversations. Memory can also be consolidated (summarized) and managed through the Memory Dashboard in the web UI.

## Tool System

Tools are Python classes in `python/tools/` that inherit from `Tool`. Each tool implements an `execute()` async method. Tools are discovered at startup and registered in the agent's tool list (rendered into the system prompt as `{{tools}}`). The agent names a tool in its JSON response; the framework finds and calls it.

Plugin tools can be added in `plugins/<plugin>/tools/` or `usr/plugins/<plugin>/tools/` without modifying core files.

## Extension and Plugin System

The plugin system (`python/helpers/plugins.py`) discovers plugins from `plugins/` and `usr/plugins/`. Each plugin has a `plugin.yaml` manifest declaring name, version, and settings. Plugins can contribute: API handlers, tools, WebUI components, extensions, and hooks. User plugins in `usr/plugins/` are never overwritten by framework updates. The agent has skills to create, manage, debug, review and contribute plugins to the Plugin Index repository (https://github.com/agent0ai/a0-plugins)

## Frontend Architecture

The web UI is built with Alpine.js and ES module components. The main shell is `webui/index.html`. Components are in `webui/components/`. Frontend state is managed via Alpine stores defined with `createStore` from `/js/AlpineStore.js`.

Real-time communication uses Socket.io WebSockets via a unified `/ws` namespace. WebSocket handlers (WsHandler subclasses) are in `api/ws_*.py`. The connection manager is in `helpers/ws_manager.py`. API handlers are in `api/`, each deriving from `ApiHandler` in `helpers/api.py`.

source: /a0/knowledge/main/about/identity.md
area: main
source_file: identity.md
source_path: /a0/knowledge/main/about/identity.md
file_type: md
knowledge_source: True
import_timestamp: None
id: dRat4HaLyj
timestamp: 2026-04-09 16:19:13
Content: # Agent Zero - Identity and Design Philosophy

## What Agent Zero Is

Agent Zero is an open-source, general-purpose agentic framework. It is not pre-programmed for specific tasks and has no fixed capability set beyond the basics. Its defining characteristic is that it grows and adapts as it is used - accumulating knowledge, solutions, and behaviors through persistent memory and user customization.

The framework has been created by Jan Tomášek and is maintained by the Agent Zero dev team and the community. Source code lives at github.com/agent0ai/agent-zero.

## Core Design Principles

**No hard-coding.** Almost nothing in the framework is fixed in source code. Agent behavior, tool definitions, message templates, and response patterns are all controlled by files in the `prompts/` directory. Changing the prompts changes the agent - fundamentally if needed.

**Transparency.** Every prompt, every message template, every tool implementation is readable and editable. There are no hidden instructions or black-box behaviors. The agent can be fully audited.

**Computer as a tool.** Agent Zero does not have a library of pre-built skill functions. Instead, it uses the operating system directly - writing code, running terminal commands, and creating tools on demand. The terminal is the primary interface to everything.

**Organic growth.** The agent accumulates knowledge through experience. Facts, solutions, discovered patterns, and useful code are stored in memory and recalled in future conversations. The agent becomes more effective at tasks it has done before.

**Prompt-driven behavior.** The `prompts/` directory is the control plane. System prompts, tool instructions, framework messages, and utility AI prompts are all there. The agent's behavior is as good as its prompts.

## Project Context

- **Repository**: github.com/agent0ai/agent-zero
- **License**: Open source
- **Primary author**: Jan Tomášek
- **Community**: Discord (discord.gg/B8KZKNsPpj), Skool community, YouTube channel
- **Documentation**: docs/ folder in the repository; deepwiki.com/agent0ai/agent-zero for AI-generated docs
- **Current version**: v0.9.8

## Relationship With the User

Agent Zero treats the human user as its top-level superior in the agent hierarchy. The user is functionally indistinguishable from a superior agent - they give tasks, receive reports, and can intervene at any time. The agent is not a chatbot that answers questions; it is an executor that solves tasks using whatever means are available to it.

The framework is a personal tool, not a service. It runs locally (or on user-controlled infrastructure) and has access to the user's files, credentials, and systems as configured. This makes it powerful and requires the user to understand what they are delegating.

source: /a0/knowledge/main/tool_call_reference_examples.md
area: main
source_file: tool_call_reference_examples.md
source_path: /a0/knowledge/main/tool_call_reference_examples.md
file_type: md
knowledge_source: True
import_timestamp: None
id: whP4OBJxLx
timestamp: 2026-04-09 16:19:13
Content: # Tool Call Reference Examples

These examples are intentionally short and high signal so tool-call shape guidance
can live in knowledge without bloating the default prompt stack.

## 1) Namespaced tool (`text_editor`) vs non-namespaced tool (`code_execution_tool`)

- `text_editor` requires method in `tool_name`:
  - `text_editor:read`
  - `text_editor:write`
  - `text_editor:patch`
- `code_execution_tool` uses a plain tool name plus behavior in `tool_args.runtime`.

### Example A: read file lines with namespaced tool

```json
{
  "tool_name": "text_editor:read",
  "tool_args": {
    "path": "/workspace/agent-zero/README.md",
    "line_from": 1,
    "line_to": 60
  }
}
```

### Example B: run shell command with `code_execution_tool`

```json
{
  "tool_name": "code_execution_tool",
  "tool_args": {
    "runtime": "terminal",
    "session": 0,
    "reset": false,
    "code": "pwd"
  }
}
```

### Example C: poll ongoing terminal output

```json
{
  "tool_name": "code_execution_tool",
  "tool_args": {
    "runtime": "output",
    "session": 0
  }
}
```

## 2) Memory tools use plain names and structured args

```json
{
  "tool_name": "memory_load",
  "tool_args": {
    "query": "tool argument format",
    "limit": 3,
    "threshold": 0.7
  }
}
```

## 3) Subordinate tool booleans are JSON booleans

```json
{
  "tool_name": "call_subordinate",
  "tool_args": {
    "profile": "",
    "message": "Review this patch for edge cases.",
    "reset": true
  }
}
```

Use these examples as structure references only. Adapt arguments to the current task.