Multi-Agent Ralph Loop

Autonomous orchestration framework for Claude Code with MemPalace-inspired memory, parallel-first Agent Teams, Aristotle First Principles methodology, 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 parallel 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)

Learned Rules Taxonomy

Rules organized in 3 dimensions for flexible retrieval:

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      --> continuous-learning.sh --> vault + procedural memory
  +-- PostToolUse --> semantic extractors  --> vault facts & decisions
  +-- SessionStart --> vault-graduation.sh --> promote to local rules
  +-- SessionEnd   --> vault-index-updater  --> update indices

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 are spawned in parallel by the orchestrator, iterate, parallel, security, and task-batch skills.

Core Skills

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 via TeammateIdle and TaskCompleted events ensures no agent completes without passing gates.

Parallel-First Rule

All independent tasks MUST execute in parallel. Sequential execution requires documented dependency.

Complexity 1-2: Direct execution (no team required)
Complexity 3+:  Agent Teams with parallel teammates (MANDATORY)

See: .claude/rules/parallel-first.md

Architecture

User Request --> Claude Code
                    |
            Aristotle Analysis (5 phases)
                    |
            Task Classification (1-10)
                    |
        +-----------+-----------+
        |                       |
    Agent Teams            Quality Gates
    (parallel)             (blocking)
        |                       |
    ralph-coder ---+     CORRECTNESS ok
    ralph-tester --+     QUALITY ok
    ralph-reviewer-+     SECURITY ok
    ralph-security-+     CONSISTENCY ok
        |                       |
        +-----------+-----------+
                    |
              VERIFIED_DONE
                    |
            MemPalace Learning
            (session -> vault -> global)

Security

The framework includes multiple layers of security enforcement:

Context Optimization

Ralph uses symlinks (not copies) for all global rules, skills, and agents. This eliminates content duplication and reduces context overhead by ~29% (~10K tokens saved per session).

# Sync rules from repo to global (creates symlinks)
bash scripts/sync-rules.sh

# Preview changes without executing
bash scripts/sync-rules.sh --dry-run

Distribution policy: See docs/architecture/DISTRIBUTION_POLICY.md for the symlink vs copy strategy per component type (Rules=COPY, Hooks=COPY, Agents=SYMLINK, Skills=MIXED).

Requirements

Testing

python3 -m pytest tests/ -q                    # Full test suite
bash scripts/validate-global-infrastructure.sh  # Infrastructure checks

Configuration

The system is model-agnostic -- all skills and agents inherit the configured model from settings, no per-command flags required.

{
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "your-model",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Skills are symlinked to multiple platform directories. Source of truth: .claude/skills/ in this repo.

Global Infrastructure

All Ralph advantages (Plan Mode, Aristotle, Parallel-First, Agent Teams) work in any project -- rules, skills, and agents are symlinked globally.

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

# Auto-fix broken symlinks
bash scripts/validate-global-infrastructure.sh --fix

Autoresearch

Autonomous experimentation loop inspired by karpathy/autoresearch. Continuously modifies code, measures metrics, and keeps only improvements.

Smart Setup reduces configuration from 14+ manual parameters to 2-3 guided questions:

9 domain templates: ML Training, Node.js Tests, Bundle Size, Python Tests, Prompt Engineering, SQL, Rust, Lighthouse, Custom.

/autoresearch "optimize my tests"     # Smart mode (auto-detect)
/autoresearch --manual                # Classic setup

Documentation

Acknowledgments

• MemPalace -- Original Memory Palace technique research for LLM agents that inspired our layered memory architecture. Our implementation diverges in key areas documented in AAAK_LIMITATIONS_ADR.
• Claude Code -- Base orchestration platform with hooks, skills, and Agent Teams APIs.
• karpathy/autoresearch -- Inspiration for the autonomous experimentation loop.

License

MIT License - see LICENSE file.

References

• Claude Code Agent Teams
• Claude Code Hooks Guide
• Claude Code Skills