Architecture

Steward is designed as a modular, layered system optimized for AI agent coordination.

System Layers

1. MCP Tool Gateway

The outermost layer. All agent interactions flow through the MCP Gateway. Tool definitions are stored as YAML files and can be hot-reloaded without restarting the server. The gateway supports two handler types: internal Elixir modules (compiled) and external REST endpoints (HTTP bridge).

2. Core Engine

The central coordination logic, built with Elixir OTP. Key subsystems:

• Task Manager — GenServer-based lifecycle management. Creates, claims, and releases work units. 10-minute auto-release timer prevents stuck tasks. Similar-task detection uses fuzzy matching on task titles.
• Lock Manager — Distributed file locking via ETS. Prevents multi-agent edit conflicts. Locks auto-release after inactivity (tied to task lifecycle).
• Memory Store — Vector database for semantic search. Stores "eternal truths" — patterns, decisions, warnings. Uses LLM-generated embeddings for similarity search.
• Presence System — Real-time agent tracking. Reports current task, purpose, application, and component for every connected agent.
• Error Registry — Persistent error traces with acknowledgment and resolution workflow. Create investigation tasks directly from error traces.

3. Persistence Layer

Three-tier storage strategy:

• ETS (in-memory) — Fast access for locks, presence, and active tasks. Sub-millisecond reads.
• PostgreSQL (production) — Full persistence for tasks, memories, errors, and configuration.
• SQLite3 (development) — Zero-config database for local development.

4. Background Processes

• Sweeper — Periodically scans for stale tasks and locks. Auto-releases after 10 minutes of inactivity.
• Memory Auditor — Validates memory quality and flags low-quality entries.
• Synthesis Engine — Clusters related claims into synthesized insights.

Data Flow

The full lifecycle of an agent interaction:

## Agent → ACS tool call flow ##

Agent──acs_create_work──▶MCP Gateway
                               │
                               ▼
                          Router (YAML-defined)
                               │
                    ┌──────────┼──────────┐
                    ▼          ▼          ▼
              TaskMgr   LockMgr   Memory
                    │          │          │
                    ▼          ▼          ▼
              ┌─────────────────────────────┐
              │      ETS Cache Layer        │
              └──────────┬──────────────────┘
                         ▼
              ┌──────────────────────┐
              │  PostgreSQL / SQLite  │
              └──────────────────────┘

Full Agent Workflow Data Flow

1. Agent → acs_create_work(agent_id, title, file_paths)
       → Task created with status "todo"
       → Similarity check against existing tasks
       → Returns task_id

2. Agent → acs_claim_work(agent_id, task_id)
       → Task status → "in_progress"
       → locked_by → agent_id
       → auto_release_at → now + 10min
       → Returns task + guidance packet

3. Agent → acs_lock_file(agent_id, task_id, "lib/foo.ex")
       → File lock created (unique constraint)
       → Safe to edit

4. Agent → acs_save_memory(kind, title, content, scope_path)
       → Memory created with status "proposed"
       → Searchable by other agents

5. Agent → acs_release_work(agent_id, task_id)
       → Task status → "done"
       → Locks released for this task
       → Returns feedback prompt

6. Agent → acs_submit_task_feedback(task_id, learned_for_agents)
       → Knowledge memories auto-generated
       → Task lifecycle complete

Technology Stack

Multi-Cluster Architecture

Steward supports multiple independent clusters. Each cluster is identified by ACS_CLUSTER_NAME and maintains its own isolated task, lock, and memory namespace. This enables separate environments for development, staging, and production — or independent clusters per team within the same organization.

Project Structure

steward_acs/
├── config/                 # Environment configs (dev, prod, test, runtime)
├── lib/
│   ├── acs.ex              # Public API module
│   ├── acs/                # Core logic: tasks, locks, memory, MCP, cognition
│   ├── acs_web/            # Phoenix web layer + LiveView dashboard
│   └── mix/tasks/          # Mix tasks (keys, cognition, meta-harness)
├── priv/
│   ├── acs_memory/         # Canonical YAML memory files
│   └── repo/migrations/
├── test/
├── assets/
├── Dockerfile
├── docker-compose.yml              # Local dev (SQLite, port 4001)
├── docker-compose.remote.yml       # Remote prod (PostgreSQL, Caddy TLS)
├── docker-compose.cloudflare.yml   # Cloudflare deployment variant
├── .env.example                    # Dev env template
├── .env.remote                     # Remote env template
├── Caddyfile                       # TLS config for remote
├── AGENTS.md                       # Agent coordination rules
├── AGENTS_STEWARD.md               # Agent steward instructions
└── mix.exs