Ralph Tools

Quick reference for shared ralph tools commands used during orchestration.

Interact Commands

ralph tools interact progress "message"

Send a non-blocking progress update via the configured RObot (Telegram).

Skill Commands

ralph tools skill list
ralph tools skill load <name>

List available skills or load a specific skill by name.

Wave Commands

Dispatch multiple events as a wave for parallel hat execution:

ralph wave emit <topic> --payloads "item1" "item2" "item3"

Each payload becomes a separate event tagged with a shared wave_id. The loop runner detects wave events and spawns parallel backend instances (up to the hat's concurrency limit).

When to use: When a hat's configuration has concurrency > 1, use wave dispatch to send N items for parallel processing instead of N sequential iterations.

Constraints:

• Cannot be used inside a wave worker (RALPH_WAVE_WORKER=1 blocks it)
• Wave workers emit results via ralph emit, not ralph wave emit

Memory Commands

ralph tools memory add "content" -t pattern --tags tag1,tag2
ralph tools memory list [-t type] [--tags tags]
ralph tools memory search "query" [-t type] [--tags tags]
ralph tools memory prime --budget 2000    # Output for context injection
ralph tools memory show <mem-id>
ralph tools memory delete <mem-id>

Memory types:

Memory ID format: mem-{timestamp}-{4hex} (e.g., mem-1737372000-a1b2)

NEVER use echo/cat to write tasks or memories — always use CLI tools.

When to Search Memories

Search BEFORE starting work when:

• Entering unfamiliar code area → ralph tools memory search "area-name"
• Encountering an error → ralph tools memory search -t fix "error message"
• Making architectural decisions → ralph tools memory search -t decision "topic"
• Something feels familiar → there might be a memory about it

Search strategies:

• Start broad, narrow with filters: search "api" → search -t pattern --tags api
• Check fixes first for errors: search -t fix "ECONNREFUSED"
• Review decisions before changing architecture: search -t decision

When to Create Memories

Create a memory when:

• You discover how this codebase does things (pattern)
• You make or learn why an architectural choice was made (decision)
• You solve a problem that might recur (fix)
• You learn project-specific knowledge others need (context)
• Any non-zero command, missing dependency/skill, or blocked step (fix + task if unresolved)

Do NOT create memories for:

• Session-specific state (use tasks instead)
• Obvious/universal practices
• Temporary workarounds

Failure Capture (Generic Rule)

If any command fails (non-zero exit), or you hit a missing dependency/skill, or you are blocked:

1. Record a fix memory with the exact command, error, and intended fix.
2. Open or reopen a task if it won't be resolved in the same iteration.

ralph tools memory add \\
  "failure: cmd=<command>, exit=<code>, error=<message>, next=<intended fix>" \\
  -t fix --tags tooling,error-handling

ralph tools task ensure "Fix: <short description>" --key fix:<short-key> -p 2

Discover Available Tags

Before searching or adding, check what tags already exist:

ralph tools memory list
grep -o 'tags: [^|]*' .agent/memories.md | sort -u

Reuse existing tags for consistency. Common tag patterns:

• Component names: api, auth, database, cli
• Concerns: testing, performance, error-handling
• Tools: docker, postgres, redis

Memory Best Practices

1. Be specific: "Uses barrel exports in each module" not "Has good patterns"
2. Include why: "Chose X because Y" not just "Uses X"
3. One concept per memory: Split complex learnings
4. Tag consistently: Reuse existing tags when possible

Decision Journal

Use .ralph/agent/decisions.md to capture consequential decisions and their confidence scores. Follow the template at the top of the file and keep IDs sequential (DEC-001, DEC-002, ...).

Confidence thresholds:

• >80: Proceed autonomously.
• 50-80: Proceed, but document the decision in .ralph/agent/decisions.md.
• <50: Choose the safest default and document the decision in .ralph/agent/decisions.md.

Template fields:

• Decision
• Chosen Option
• Confidence (0-100)
• Alternatives Considered
• Reasoning
• Reversibility
• Timestamp (UTC ISO 8601)

Output Formats

All commands support --format:

• table (default) - Human-readable
• json - Machine-parseable
• quiet - IDs only (for scripting)
• markdown - Memory prime only

NEVER use echo/cat to write tasks or memories — always use CLI tools.