Agent Zero Ecosystem

Current product direction

Agent Zero is becoming a personal agent workspace backed by a gateway-routed fleet of specialist agents.

Recent decisions:

• Use Hermes Desktop as a visual/product reference for the web and desktop clients.
• Redesign agent-zero-ui around a dark workspace shell, persistent sidebar, bottom status bar, structured tool-call rendering, Memory, Agents, Skills/Tools, and Artifacts areas.
• Create agent-zero-desktop as an Electron + React client that speaks to the same gateway API as the web UI.
• Introduce a user-specific personal agent concept: a default agent for each user/workspace that can use approved tools/memory and delegate to authorized specialist agents through the gateway.

Docs:

• Hermes-inspired UI direction
• Personal agents and delegation

This repository documents the Agent Zero project family and the boundaries between each project.

Projects

agent-zero
  Profile-driven runnable agent runtime built on Pi.

agent-zero-gateway
  Multi-agent routing, registry, session mapping, auth boundary, and gateway API.

agent-zero-ui
  ChatGPT-style web interface for talking to agents and discovering available agents.

agent-zero-memory
  Shared memory service for user memory and agent operational memory.

Architecture

Browser / clients
  -> agent-zero-ui
    -> agent-zero-gateway
      -> agent-zero runtime instances
        -> optional memory tools
          -> agent-zero-memory

Direct local development can also connect the UI directly to one Agent Zero runtime:

agent-zero-ui -> agent-zero

Ownership boundaries

Agent Zero

Owns:

• profile-driven runtime shape
• Pi SDK/runtime integration
• HTTP/SSE single-agent API
• runtime sessions
• messages/events/turn summaries
• optional gateway self-registration client
• optional extension tools, including future memory tools

Does not own:

• multi-user OIDC auth
• fleet routing
• long-term cross-agent memory service
• browser UI

Agent Zero Gateway

Owns:

• public multi-agent API
• agent registry
• configured and self-registered agents
• registration leases/heartbeats/expiry
• gateway session IDs
• routing by agent/profile/capability
• OIDC/multi-user auth boundary in the future
• user/workspace/session ownership in the future

Does not own:

• model execution
• Pi runtime sessions directly
• primary browser UX
• memory storage

Agent Zero UI

Owns:

• chat interface
• session list UX
• Agents page/discovery UX
• settings/connections
• Agent Work display
• future login/logout UX
• future memory approval/edit UX

Does not own:

• gateway administration as primary UX
• auth enforcement
• agent runtime execution
• memory derivation/storage

Agent Zero Memory

Owns:

• manual memory storage/search/context
• user memory
• agent operational memory
• future memory suggestions/derivation
• future embeddings/vector search
• future Postgres memory backend

Does not own:

• agent runtime execution
• gateway routing
• OIDC validation as primary auth boundary

Key decisions

Runtime and sessions

Agent Zero currently uses Pi JSONL for runtime compatibility, but the long-term direction is:

relational Agent Zero session store = canonical API store
Pi JSONL = runtime adapter / compatibility substrate

SQLite is acceptable for local alpha. Postgres is the long-term production target.

Memory

Memory is separate infrastructure:

agent-zero-memory

Agents access memory through optional profile-selected tools, not global injection.

Memory domains remain separate:

agent operational memory
user memory

Multi-user auth

Gateway is the future multi-user/OIDC boundary.

UI obtains OIDC token
Gateway validates token and authorizes access
Agent Zero receives safe identity metadata
Memory is scoped by workspace/user/peer

Agent Zero runtimes should not become OIDC clients.

Ephemeral agents

Agent runtimes can self-register with the gateway:

POST /agents/register
POST /agents/:id/heartbeat
DELETE /agents/:id/registration

If an agent dies without unregistering, the gateway expires its lease.

Local development ports

agent-zero research  http://127.0.0.1:7331
agent-zero base      http://127.0.0.1:7332
agent-zero-gateway   http://127.0.0.1:7400
agent-zero-ui        http://127.0.0.1:5173
agent-zero-memory    http://127.0.0.1:7500

Current alpha status

Current released alpha for runtime/gateway/UI:

v0.2.1-alpha

Current memory service status:

0.1.0-alpha MVP on main, not yet integrated with Agent Zero tools

Suggested implementation order

1. Keep core repos clean and tagged.
2. Build memory tools in Agent Zero as optional profile capabilities.
3. Add memory UX later after tool flow is stable.
4. Add gateway user/workspace schema before remote multi-user deployment.
5. Add OIDC JWT validation in gateway.
6. Add UI login/logout/current-user flow.
7. Continue improving session management and run inspection.