Multi-Agent Ralph Loop

Autonomous orchestration framework for Claude Code with MemPalace-inspired memory, Agent Teams, and quality gates.

What It Does

Ralph extends Claude Code into a multi-agent development framework with a structured memory system inspired by the Memory Palace technique. Every task is analyzed from first principles, decomposed into focused subtasks, assigned to specialized teammates, and validated through quality gates before completion.

MemPalace Memory System

Inspired by the MemPalace repository (Memory Palace technique for LLM agents), Ralph implements a layered memory architecture with key differences based on our implementation findings.

Layer Stack (Session Wake-up)

Key Implementation Findings

These findings emerged during our MemPalace implementation and may be relevant to others building LLM memory systems:

Full analysis: AAAK_LIMITATIONS_ADR

Learning Pipeline (Automatic)

SESSION (any repo)
  |
  +-- Stop      --> (automatic learning removed by #69 Slice D; writes are explicit)
  +-- PostToolUse --> semantic extractors  --> vault facts & decisions
  +-- SessionStart --> (automatic graduation removed by #69 Slice D)
  +-- SessionEnd   --> (automatic indexing removed by #69 Slice D)

All learning flows project -> global -> vault. Only universal patterns graduate to global scope.

Quick Start

git clone https://github.com/alfredolopez80/multi-agent-ralph-loop.git
cd multi-agent-ralph-loop

# Validate global infrastructure
bash scripts/validate-global-infrastructure.sh

# Run tests
python3 -m pytest tests/ -q

# Use
/orchestrator "Create a REST API endpoint"
/iterate "Fix all lint errors"
/security src/

Agent Teams

6 specialized teammates for parallel execution:

Agent Teams is enabled via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json. Teammates can be spawned by the orchestrator, iterate, parallel, security, and task-batch skills when a task benefits from it.

Core Skills

Orchestration Workflow

/orchestrator runs steps 0 through 8. Step 0 classifies the task on three dimensions and routes it; step 6 is a nested loop that runs once per plan step.

0. EVALUATE   -> Aristotle first principles + 3-dimension classification
1. CLARIFY    -> AskUserQuestion (MUST_HAVE blocking, NICE_TO_HAVE optional)
2. CLASSIFY   -> task-classifier (complexity 1-10)
3. PLAN       -> Detailed design
4. PLAN MODE  -> EnterPlanMode, user approves
5. DELEGATE   -> Assign to teammates (isolation and parallelism, never model routing)
6. EXECUTE-WITH-SYNC, per plan step:
   6a. LSA-VERIFY  -> architecture pre-check
   6b. IMPLEMENT   -> run the step
   6c. PLAN-SYNC   -> detect drift from the plan
   6d. MICRO-GATE  -> per-step quality (3-fix rule)
7. VALIDATE   -> quality-auditor, /gates, adversarial spec and plan cross-validation
8. RETROSPECT -> self-improvement

3-Dimension Classification

Step 0 classifies before it plans, and the three values together choose the route:

CONSTANT + FITS + complexity 1-3 takes a 3-step fast path; QUADRATIC recursively decomposes; LINEAR + CHUNKED runs as parallel chunks.

The Ralph Loop

/iterate repeats execute -> validate -> iterate until the quality gates pass (VERIFIED_DONE) or the bounded iteration budget is exhausted (max_iterations, 15 by default). An unbounded loop has no failure signal, so every loop sets one.

Essential Commands

# Orchestration
/orchestrator "Implement OAuth2 with Google"
ralph orch "task"                # Full orchestration
ralph loop "fix the lint errors" # Loop until VERIFIED_DONE
/clarify                         # Intensive requirement clarification

# Quality
/gates                           # Quality gates
/adversarial                     # Spec refinement

# Memory
ralph memory-search "query"      # Parallel memory search
ralph fork-suggest "task"        # Suggest fork sessions

# Security
ralph security src/              # Security audit
ralph security-loop src/         # Iterative audit until clean

# Git worktree
ralph worktree "feature"         # Create an isolated worktree
ralph worktree-pr <branch>       # PR with review

# Context
ralph ledger save                # Save session state
ralph handoff create             # Create a handoff

Local Observability

Observability with no external dependencies, backed by local files:

ralph plan status     # Current plan state (reads .claude/plan-state.json)
ralph trace show      # Recent events
ralph trace search    # Search events
ralph trace timeline  # Visual timeline
ralph trace export    # Export to JSON/CSV

Quality Gates

4-stage validation, all blocking except consistency:

1. CORRECTNESS -- Syntax valid, logic sound
2. QUALITY -- Types, no debug artifacts
3. SECURITY -- semgrep + gitleaks + OWASP validation
4. CONSISTENCY -- Linting and style (advisory)

Hook enforcement on the TaskCompleted event ensures no agent completes without passing gates.

Architecture (post-M2)

The repo has 84 hooks in .claude/hooks/. After the M2 retirement (T106), they fall into four categories by default registration, not by file existence: always-on security, active canonical #47, retired-to-opt-in hooks, and cold-path session/scheduler hooks.

Source of truth: results/T107-inventario.md. Every row in the inventory traces to a real file in the repo; if a source link breaks, delete the row.

Categories at a glance