Agents

Agents are the core building blocks of Moxxy. Each agent is an independent AI entity with its own workspace, memory, persona, and access controls.

What is an Agent?

An agent is a self-contained AI unit managed by the moxxy-gateway. Each agent has:

• Identity - A unique ID, name, optional parent (for sub-agents), and depth level
• Persona - Stored in the database and config.yaml, defining behavior and personality
• Memory - Markdown journals and vector embeddings in the central moxxy.db
• Primitives - Access to 85 built-in tool calls (subject to allowlists)
• Skills - Markdown-based higher-level capabilities that compose primitives
• Vault - Grant-based access to encrypted secrets
• Workspace - Isolated directory with PathPolicy enforcement

Agent Architecture

+---------------------------------------------------+
|                      Agent                         |
+---------------------------------------------------+
|  +-----------+  +----------+  +----------------+  |
|  |  Persona  |  |  Memory  |  |  Primitives    |  |
|  |  (config) |  | (journals|  |  (85 built-in) |  |
|  |           |  |  + vecs) |  |                |  |
|  +-----------+  +----------+  +----------------+  |
|                                                    |
|  +-----------+  +----------+  +----------------+  |
|  |   Vault   |  |  Skills  |  |   Allowlist    |  |
|  |  (grants) |  | (Markdown|  |  (allow/deny)  |  |
|  |           |  |  + YAML) |  |                |  |
|  +-----------+  +----------+  +----------------+  |
+---------------------------------------------------+
|              Agent Loop (Executor)                  |
|         LLM -> Tool Calls -> Primitives            |
+---------------------------------------------------+

Agent Components

Persona

The persona defines the agent's identity, behavior, and constraints. It is stored in the agent's config.yaml and in the database, not as a separate persona.md file.

The persona is injected into the system prompt when the agent processes requests.

Memory

Each agent has two memory mechanisms:

Type	Storage	Description
Long-Term Memory (LTM)	moxxy.db (memory_index + memory_vec tables)	Persistent knowledge with vector embeddings for semantic search
Short-Term Memory (STM)	In-memory + moxxy.db	Current session context
Journals	~/.moxxy/agents/{id}/memory/	Append-only Markdown logs

All memory operations use primitives: memory.store, memory.recall, memory.stm_read, memory.stm_write.

See Memory System for details.

Primitives

Agents have access to 85 built-in primitives organized by category:

Category	Examples
Filesystem	fs.read, fs.write, fs.list, fs.remove, fs.cd
Git	git.init, git.clone, git.status, git.commit, git.push, git.checkout, git.pr_create, git.fork, git.worktree_add
Web	browse.fetch, browse.extract
Shell	shell.exec (allowlist enforced)
HTTP	http.request (domain-gated)
Memory	memory.store, memory.recall, memory.stm_read, memory.stm_write
Agent	agent.spawn, agent.status, agent.list, agent.stop, agent.dismiss
Vault	vault.set, vault.get, vault.delete, vault.list
Hive	hive.create, hive.recruit, hive.task_create, hive.signal, etc.
MCP	mcp.list, mcp.connect, mcp.disconnect, mcp.tool

Primitives are subject to per-agent allowlists and denylists defined in allowlist.yaml.

See Skills & Primitives for the full list.

Skills

Skills are Markdown files with YAML frontmatter that define higher-level agent capabilities. Skills compose primitives and provide instructions for complex workflows. All skills start in a quarantined state and require approval before use.

See Skills & Primitives for details.

Vault

Agents access secrets through the centralized vault using grant-based permissions. An agent can only read secrets it has been explicitly granted access to via vault.get. Secrets are encrypted with AES-GCM and backed by the OS keychain.

Workspace Isolation

Each agent operates within a sandboxed workspace directory:

~/.moxxy/agents/{id}/workspace/

PathPolicy enforcement ensures agents cannot read or write files outside their workspace. The sandbox uses OS-level mechanisms: sandbox-exec on macOS and bwrap on Linux. Three profiles are available: strict, standard, and none.

Agent Lifecycle

  +----------+
  | created  |
  +----+-----+
       |
       v
  +----------+     +----------+
  | running  | --> |  stopped |
  +----------+     +----------+
       |
       v
  +----------+
  |  error   |
  +----------+

Status Values

Status	Description
created	Agent record exists but no run has started
running	Agent is actively processing in the Executor loop
stopped	Agent was explicitly stopped or finished its run
error	Agent encountered an unrecoverable error

The Agent Loop (Executor)

When an agent receives a prompt, the Executor runs this loop:

1. Build message history - Assemble system prompt (persona + primitive catalog) and conversation history
2. Call LLM - Send to the configured provider (Anthropic, OpenAI, Ollama, or OpenAI-compatible)
3. Parse tool calls - Extract tool_use/function calling responses from the LLM
4. Invoke primitives - Execute the requested primitives and collect results
5. Emit events - Publish SSE events for each step (60 event types)
6. Loop or respond - If the LLM made tool calls, feed results back and repeat; if not, return the final response

The Executor includes stuck detection with automatic recovery to handle cases where the agent gets into a loop.

See Agent Loop for details.

Sub-Agent Spawning

Agents can spawn sub-agents using the agent.spawn primitive. Sub-agents inherit constraints from their parent:

• Depth limit - Prevents deeply nested agent chains
• Fan-out limit - Prevents spawning too many concurrent sub-agents
• Parent tracking - Each sub-agent records its parent for the hierarchy

Parent Agent (depth 0)
  |-- Sub-Agent A (depth 1)
  |     |-- Sub-Agent C (depth 2)
  |-- Sub-Agent B (depth 1)

Agent Directory Structure

~/.moxxy/agents/{id}/
  workspace/       # Sandboxed working directory
  memory/          # Append-only Markdown journals
  config.yaml      # Agent configuration
  allowlist.yaml   # Primitive allow/deny lists

All persistent data (memory embeddings, agent metadata, run history) is stored in the central ~/.moxxy/moxxy.db SQLite database.

Creating and Managing Agents

Agents are managed through the REST API:

# Create
curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Authorization: Bearer mox_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "researcher", "persona": "You are a research assistant."}'

# List
curl http://127.0.0.1:3000/v1/agents \
  -H "Authorization: Bearer mox_your_token"

# Start a run
curl -X POST http://127.0.0.1:3000/v1/agents/researcher/runs \
  -H "Authorization: Bearer mox_your_token" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Research the latest developments in AI safety"}'

# Stop
curl -X POST http://127.0.0.1:3000/v1/agents/researcher/stop \
  -H "Authorization: Bearer mox_your_token"

# Delete
curl -X DELETE http://127.0.0.1:3000/v1/agents/researcher \
  -H "Authorization: Bearer mox_your_token"

See Agent Management CLI for the full API reference.

Hive Orchestration

For multi-agent collaboration, Moxxy uses the Hive system with Queen/Worker hierarchy, task boards, and voting consensus. This replaces simple agent delegation.

See Hive Orchestration for details.