Autonomous orchestration framework for Claude Code with MemPalace-inspired memory, parallel-first Agent Teams, Aristotle First Principles methodology, and quality gates.

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.

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.

Rules organized in 3 dimensions for flexible retrieval:

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

Full analysis: AAAK_LIMITATIONS_ADR

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.

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/

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.

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.

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

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)

The framework includes multiple layers of security enforcement:

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

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

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.

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

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

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

MIT License - see LICENSE file.

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