Experimental build

Ralph Plus

Ralph with a self-improving memory system. Every session teaches it something. Every completed task makes the next one faster.

Download How Brain works

By downloading you agree to the Ralph License and Terms of Use.

⚠️ Experimental: The core agent loop in Ralph Plus is identical to stable Ralph — same tools, same providers, same behaviour. The Brain memory features are new, still evolving, and may have rough edges. Feedback and bug reports are welcome. When in doubt, use stable Ralph.

The Brain Memory System

Ralph normally starts every session with no memory of past work. Ralph Plus adds a memory layer that runs quietly in the background, building up knowledge across sessions — automatically, with no configuration needed.

What it remembers

Brain remembers what the agent did, not about you personally. Specifically: which errors occurred, what edits fixed them, how many turns a task took, and whether tests passed. Over time it learns patterns like “this class of compile error in Rust is usually fixed by doing X” — and that knowledge is silently available the next time a similar error appears.

All data is stored locally on your machine in ~/.ralph/. Nothing is sent anywhere.

Three active phases

Phase 1 — Per-session
Context Graph
Tracks every file read, edit, error, and test outcome during a session. Stored alongside the message history so it survives context compaction. When you resume a session, Ralph Plus already knows which files were touched and what errors were open.
Phase 2 — Cross-session
Knowledge Store
After every completed task, error→fix patterns are extracted and stored in a local SQLite database at ~/.ralph/knowledge.db. At the start of future sessions, relevant past patterns are retrieved (FTS keyword search) and quietly injected into context. Patterns confirmed across 3+ projects are promoted to global scope.
Phase 3 — Synthesis
Learned Rules
After each successful task, Ralph Plus sends the session’s patterns to the LLM and asks it to distill generalizable rules. These are written to ~/.ralph/RALPH.md.learned and injected at the top of the system prompt for every future session — the highest-priority context Ralph Plus sees.

What it looks like in practice

After a session where Ralph Plus fixed a compile error, you’ll see:

ralph-plus output
✓ Done: fixed the lifetime error in session.rs
[brain] 2 new rules learned → ~/.ralph/RALPH.md.learned
[checkpoint] Task state saved on ralph/checkpoints branch (a3f8c12)

On the next session in any Rust project, those rules are already in context — Ralph Plus may resolve the same class of error in fewer turns.

Zero configuration

Brain starts working automatically. No flags, no setup, no API. The knowledge database and learned rules file are created on first use. To inspect what Ralph Plus has learned:

bash
# View learned rules
cat ~/.ralph/RALPH.md.learned

# View session context graph
cat /path/to/project/.ralph/sessions/<id>/context_graph.json

Download loading...

One binary, no dependencies. The ralph-plus binary is a superset of stable Ralph — every Ralph feature works exactly as before.

For Macs with M1, M2, M3, or M4 chips.

Option A — Homebrew (recommended)

bash
brew install akkeshavan/ralph/ralph-plus

Upgrade: brew upgrade ralph-plus

Option B — Manual install

  1. Download the binary
bash
# Download
curl -L -o ralph-plus.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-plus-LATEST-aarch64-apple-darwin.tar.gz
  1. Extract and install
bash
tar xzf ralph-plus.tar.gz
sudo mv ralph-plus-*/ralph-plus /usr/local/bin/ralph-plus
rm -rf ralph-plus.tar.gz ralph-plus-*/
  1. Verify
bash
ralph-plus --version
ralph-plus --help

For Macs with Intel processors (2020 and earlier).

Option A — Homebrew (recommended)

bash
brew install akkeshavan/ralph/ralph-plus

Upgrade: brew upgrade ralph-plus

Option B — Manual install

  1. Download the binary
bash
# Download
curl -L -o ralph-plus.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-plus-LATEST-x86_64-apple-darwin.tar.gz
  1. Extract and install
bash
tar xzf ralph-plus.tar.gz
sudo mv ralph-plus-*/ralph-plus /usr/local/bin/ralph-plus
rm -rf ralph-plus.tar.gz ralph-plus-*/
  1. Verify
bash
ralph-plus --version
ralph-plus --help

For standard 64-bit Linux (Ubuntu, Debian, Fedora, Arch, Alpine, etc.).

  1. Download the binary
bash
# Download (statically linked musl build)
curl -L -o ralph-plus.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-plus-LATEST-x86_64-unknown-linux-musl.tar.gz
  1. Extract and install
bash
tar xzf ralph-plus.tar.gz
sudo mv ralph-plus-*/ralph-plus /usr/local/bin/ralph-plus
rm -rf ralph-plus.tar.gz ralph-plus-*/
  1. Verify
bash
ralph-plus --version
ralph-plus --help

For ARM64 Linux — AWS Graviton, Raspberry Pi 5, Oracle Ampere, etc.

  1. Download the binary
bash
# Download (statically linked musl build)
curl -L -o ralph-plus.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-plus-LATEST-aarch64-unknown-linux-musl.tar.gz
  1. Extract and install
bash
tar xzf ralph-plus.tar.gz
sudo mv ralph-plus-*/ralph-plus /usr/local/bin/ralph-plus
rm -rf ralph-plus.tar.gz ralph-plus-*/
  1. Verify
bash
ralph-plus --version
ralph-plus --help

For Windows 10/11 x86-64. Run commands in PowerShell.

  1. Download — click here to download the .zip for Windows x86-64.
  2. Extract — right-click and select Extract All.
  3. Install
powershell (as Administrator)
New-Item -ItemType Directory -Force -Path "C:\tools\ralph-plus"
Copy-Item ralph-plus.exe "C:\tools\ralph-plus\"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\tools\ralph-plus", "Machine")
  1. Restart PowerShell, then verify:
powershell
ralph-plus --version
ralph-plus --help

Setup

Setup is identical to stable Ralph. The binary is named ralph-plus — everything else (API keys, providers, .env files, RALPH.md) works the same way.

API key

Ralph Plus uses DeepSeek by default. Set your key in your shell profile or in a .env file in your project directory. Get a key at platform.deepseek.com.

bash — ~/.zshrc or ~/.bashrc
export DEEPSEEK_API_KEY="sk-..."
.env — project root (add to .gitignore)
DEEPSEEK_API_KEY=sk-...

Ralph Plus supports all the same providers as stable Ralph: DeepSeek, Sarvam AI, Ollama, Groq, OpenAI, Together AI. See the providers guide for setup details — just replace ralph with ralph-plus in the commands.

Running Ralph Plus

Use exactly like stable Ralph, just with the ralph-plus command:

bash
# Start in your project directory
cd /path/to/your/project
ralph-plus

# Resume last session
ralph-plus --resume

# With a specific provider
ralph-plus --provider groq "fix the failing tests"

Brain starts automatically. No flags needed. After each completed task you’ll see a [brain] line in the output confirming any new rules were learned.

Brain data files

All Brain data is stored locally:

bash
# Synthesised rules — injected into every future session
~/.ralph/RALPH.md.learned

# Cross-session knowledge store (SQLite + FTS5)
~/.ralph/knowledge.db

# Per-session context graph (alongside message history)
.ralph/sessions/<id>/context_graph.json

You can read and edit RALPH.md.learned directly. Ralph Plus will never overwrite content outside its delimited block. To reset Brain’s memory, delete ~/.ralph/knowledge.db and ~/.ralph/RALPH.md.learned.

Release Notes

plus-v0.2.1 — June 2026

Session integrity on stall exit — typing a follow-up prompt after Ralph Plus stalled no longer produces an immediate HTTP 400 error. The orphaned assistant tool_calls message is now stripped before the stall exit so the session remains valid for the next prompt.

plus-v0.2.0 — June 2026

Parallel subagent orchestration — delegate independent subtasks to background workers running concurrently with file-locking. Use --agents to enable, /tasks to monitor, /kill <id> to stop.

Anti-stall & large-codebase handling — context-aware stall nudges, repo map injected into the system prompt, reasoning provider fallback triggered automatically after consecutive failures.

Security hardening — compound shell commands always require confirmation, secret file guard applied consistently across all read paths including load_files, GitHub token patterns added to secret detection.

Brain context graph fix — the context graph tool now uses the correct argument key, ensuring file-read events are properly recorded across sessions.

Version check fix — Ralph Plus now tracks only plus-v* release tags for its upgrade notifications.

plus-v0.1.x — 2026

Brain memory system — Phase 1 (per-session context graph), Phase 2 (cross-session knowledge store), and Phase 3 (synthesised rules injected into future sessions).

All stable Ralph features — every improvement in Ralph v0.5–v0.7 ships in Ralph Plus simultaneously.

Uninstall

bash
brew uninstall ralph-plus
# Optionally remove the tap entirely (also removes stable ralph if installed via brew):
brew untap akkeshavan/ralph
bash
sudo rm /usr/local/bin/ralph-plus
# Optionally remove Brain data:
rm -rf ~/.ralph/knowledge.db ~/.ralph/RALPH.md.learned
powershell (as Administrator)
Remove-Item "C:\tools\ralph-plus\ralph-plus.exe"
# Then remove C:\tools\ralph-plus from your PATH in System Environment Variables