Juliaz System

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.)

3-System Architecture

julia/ — User-System (the product)

meta/ — Meta-System (development & maintenance)

thesis/ — Thesis-System (research & academic)

Cross-system & config (root level)

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 (FIXED: now uses /Users/raphael/juliaz_agents/julia/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