juliaz-system — Architecture & Navigation

You are working on juliaz_agents — Raphael's multi-agent platform for his master's thesis on autonomous AI collaboration.

Mental Model

Raphael (human) → Antigravity (IDE agent / builder) → Julia (the product being built)

• •Antigravity = the AI in the IDE (Claude Code / Cowork) that builds Julia
• •Julia = the multi-agent system being built
• •OpenClaw = communication gateway (Telegram, WhatsApp, etc.)

The 7 Components

Supporting Directories

Message Flow (Telegram → Julia → Reply)

Telegram user sends message
  → OpenClaw gateway receives it (ws://127.0.0.1:18789)
    → OpenClaw POSTs to bridge: POST http://localhost:3001/incoming
      → Bridge stores in queue.json (state: pending)
        → Orchestrator polls via MCP: telegram_get_pending_messages (state → processing)
          → Orchestrator generates reply (Claude Haiku → GPT-4o fallback)
            → Orchestrator calls MCP: telegram_send_reply (state → replied)
              → OpenClaw polls GET /pending-reply/:chatId
                → OpenClaw delivers to Telegram

Key Patterns & Conventions

Agent Definition Files

Each agent directory follows this convention:

• •SOUL.md — Core identity, personality, values, boundaries
• •IDENTITY.md — Name, creature type, vibe, emoji
• •TOOLS.md — Available tools and environment config
• •AGENTS.md — Behavioral playbook, memory patterns, group chat rules
• •HEARTBEAT.md — Scheduling, health checks, reporting cadence
• •HEURISTICS.md — Learned rules from past incidents
• •MEMORY.md — Persistent context across sessions
• •USER.md — Info about the user (Raphael)

Tool Definition Patterns

• •Anthropic format (orchestrator, cowork-mcp): { name, description, input_schema } with JSON Schema
• •OpenAI format (frontend chat): { function: { name, description, parameters } }
• •MCP tools (bridge): Defined via server.tool(name, schema, handler)

Error Handling

• •Graceful fallback: Claude Haiku → GPT-4o (orchestrator)
• •Exponential backoff: Consecutive errors trigger increasing delays (capped 55s)
• •Rate limiting: Honors Retry-After header from Anthropic
• •Fire-and-forget: Memory capture and letter generation never crash main loop
• •Timeouts: 30s per API call with AbortController

Memory System

• •Short-term: In-memory conversation history (20 messages = 10 turns per chat)
• •Long-term: Backend PostgreSQL (memories, letters, logs, tasks)
• •Memory extraction: gpt-4o-mini categorizes moments as STORY, FEELING, MOMENT, WISH, REFLECTION
• •Letter generation: Daily physical letters via Lob.com using GPT-4o + seed file + recent memories

Configuration

• •Environment: .env.example (template), .env.secrets (live keys — NEVER commit)
• •Process manager: PM2 via ecosystem.config.js (prod) / ecosystem.dev.config.js (dev)
• •Docker: Only backend runs in Docker (PostgreSQL + Express API)
• •MCP config: .mcp.json for bridge connection

File Location Quick Reference

When Raphael asks "where is X", use this:

Known Pain Points

These are real issues in the codebase — reference them when relevant:

1. •Hardcoded Mac paths in orchestrator tools (email skill path: /Users/raphael/Documents/Devs/juliaz_agents/openclaw/skills/email-aberer)
2. •Tool definition duplication between orchestrator and frontend (both define similar tools separately)
3. •No pagination on any backend GET endpoint (returns entire table)
4. •Bridge queue grows unbounded — no pruning of old replied messages
5. •Memory lost on restart — in-memory conversation history clears before DB save
6. •Cowork MCP defaults to Haiku despite being intended for complex delegation
7. •No structured logging — sparse console.log, no log levels
8. •No tests visible — no test files or CI/CD pipeline (except backend has Vitest configured)
9. •No authentication on any endpoint (frontend chat, backend API, bridge)
10. •Silent content truncation — cowork-mcp silently drops content over 25K chars

Backend Database Tables

Bridge MCP Tools