ralph-mem

A persistent context management plugin for Claude Code based on Ralph Loop

한국어 문서 (Korean)

Overview

ralph-mem is a project inspired by Geoffrey Huntley's Ralph Loop and thedotmack's claude-mem.

It combines Ralph Loop's "repeat until success" philosophy with claude-mem's "intelligent context management" to implement a persistent memory management plugin for Claude Code.

Problems Solved

Problem	Description
Context Rot	Model performance degradation due to accumulated irrelevant info
Compaction	Output quality drops sharply when context window exceeds 60-70%
Forgetfulness	Loss of work context between sessions
One-shot Failure	Low success rate for complex tasks in single attempts

Key Features

1. Ralph Loop Engine

Automatically repeats execution until success criteria are met.

/ralph start "Add user authentication with JWT"

flowchart LR
    A[Prompt + Context] --> B[Agent Execute]
    B --> C{Success?}
    C -->|YES| D[Done]
    C -->|NO| E[Append Result]
    E --> A

Loading

Supported Success Criteria:

• test_pass - Tests pass (npm test, pytest)
• build_success - Build succeeds
• lint_clean - No lint errors
• type_check - Type check passes
• custom - User-defined command

2. Persistent Memory

Automatically saves and restores context between sessions.

flowchart TB
    A[New Session Start] --> B[Search Related Memory]
    B --> C[Inject Previous Context]
    C --> D[Session Progress]
    D --> E[Record Observations]
    E --> F[Session End]
    F --> G[Generate & Save Summary]

Loading

Lifecycle Hooks:

• SessionStart - Automatically inject related memory
• PostToolUse - Record tool usage results
• Stop - Cleanup on forced session termination
• SessionEnd - Generate and save session summary

3. Progressive Disclosure

Token-efficient 3-layer search saves ~10x tokens:

Layer	Content	Tokens
Layer 1	Index (ID + score)	50-100/result
Layer 2	Timeline (chronological)	200-300/result
Layer 3	Full Details	500-1000/result

/mem-search "authentication error"           # Layer 1
/mem-search --layer 3 obs-a1b2               # Layer 3

Installation

npm

npm install ralph-mem

yarn

yarn add ralph-mem

pnpm

pnpm add ralph-mem

bun

bun add ralph-mem

Claude Code Plugin

To use as a Claude Code plugin, install via the roboco-io/plugins marketplace:

1. Add marketplace

/plugin marketplace add roboco-io/plugins

2. Install plugin

/plugin install ralph-mem@roboco-plugins

Or open the plugin manager with /plugin command to install via UI.

Plugin Update

1. Update marketplace

claude plugin marketplace update roboco-plugins

2. Update plugin

claude plugin update ralph-mem@roboco-plugins

Restart Claude Code after update to apply changes.

Usage

Ralph Loop

# Start loop (default: until tests pass)
/ralph start "Implement feature X"

# Start with custom success criteria
/ralph start "Fix lint errors" --criteria lint_clean

# Check loop status
/ralph status

# Stop loop
/ralph stop

Memory Search

# Keyword search
/mem-search "JWT authentication"

# Get specific observation details
/mem-search --layer 3 <observation-id>

# Search with time range
/mem-search "database" --since 7d

Memory Management

# Check memory status
/mem-status

# Manual context injection
/mem-inject "This project uses Express + Prisma"

# Remove specific memory
/mem-forget <observation-id>

4. Privacy Features

Excludes sensitive information from memory.

<private> tag:

# Content wrapped in tags is not stored
My API key is <private>sk-1234567890</private>
# Stored as: My API key is [PRIVATE]

Configuration-based exclusion:

privacy:
  exclude_patterns:
    - "*.env"
    - "*password*"
    - "*secret*"

5. MCP Tools

In addition to skills, memory can be accessed via MCP (Model Context Protocol) tools.

Tool	Description
ralph_mem_search	Progressive Disclosure-based search
ralph_mem_timeline	Chronological context around specific observation
ralph_mem_get	Full details by observation ID

Configuration

~/.config/ralph-mem/config.yaml:

ralph:
  max_iterations: 10          # Maximum iterations
  context_budget: 0.6         # Context window usage limit
  cooldown_ms: 1000           # Wait time between iterations
  success_criteria:
    - type: test_pass
      command: "npm test"

memory:
  auto_inject: true           # Auto-inject at session start
  max_inject_tokens: 2000     # Maximum injection tokens
  retention_days: 30          # Memory retention period

privacy:
  exclude_patterns:           # Patterns to exclude from storage
    - "*.env"
    - "*password*"
    - "*secret*"

How It Works

ralph-mem operates in two modes:

1. Automatic Mode (Lifecycle Hooks): Runs in background without user intervention
2. Explicit Mode (Skills/Commands): User controls directly via slash commands

Lifecycle Hooks

Once the plugin is installed, it automatically connects to Claude Code's lifecycle.

sequenceDiagram
    participant CC as Claude Code
    participant Hook as Hook Layer
    participant Core as Core Layer
    participant DB as SQLite

    CC->>Hook: SessionStart
    Hook->>Core: Search related memory
    Core->>DB: FTS5 + Embedding search
    DB-->>Core: Previous context
    Core-->>Hook: Search results
    Hook-->>CC: Auto-inject context

    CC->>Hook: UserPromptSubmit
    Hook->>Core: Query-related search
    Core-->>Hook: Related memory notification
    Hook-->>CC: Show notification (no injection)

    CC->>Hook: PostToolUse
    Hook->>Core: Record tool usage result
    Core->>DB: Save Observation

    CC->>Hook: SessionEnd
    Hook->>Core: Generate session summary
    Core->>DB: Save summary

Loading

Hook	Timing	Action
SessionStart	Session start	Auto-inject project-related previous context
UserPromptSubmit	Prompt submission	Related memory notification (no injection to save tokens)
PostToolUse	After tool use	Record write tools, Bash command results as Observations
SessionEnd	Session end	Generate and save session summary

Ralph Loop Operation

Activated with /ralph start command, automatically repeats until success criteria are met.

flowchart LR
    A[Task + Context] --> B[Claude Execute]
    B --> C{Success?}
    C -->|YES| D[Complete]
    C -->|NO| E[Append Result]
    E --> F{Stop Condition?}
    F -->|NO| A
    F -->|YES| G[Failure + Rollback Guide]

Loading

Success Determination: Claude analyzes test/build output to determine success.

Overbaking Prevention: Stop conditions to prevent infinite loops:

Condition	Default	Description
maxIterations	10	Maximum iterations
maxDurationMs	30 min	Maximum execution time
noProgressThreshold	3	Allowed no-progress iterations

Snapshots: Changed files are snapshotted at loop start for rollback on failure.

Search Engine

Returns optimal results with 2-stage search:

1. FTS5 Full-text Search (primary): Fast text search using SQLite FTS5
2. Embedding Similarity (fallback): Semantic search when FTS5 results are insufficient

Embedding Model: paraphrase-multilingual-MiniLM-L12-v2

• Local execution (no API calls)
• 50+ languages supported (Korean, English included)
• 384 dimensions, ~278MB

Data Flow

flowchart TB
    subgraph Input["Input"]
        Tool[Tool Usage Result]
        Prompt[User Prompt]
    end

    subgraph Process["Processing"]
        Privacy[Privacy Filter]
        Compress[Compressor]
        Embed[Embedding Generation]
    end

    subgraph Storage["Storage"]
        Obs[(Observations)]
        Session[(Sessions)]
        FTS[(FTS5 Index)]
        Vec[(Embedding)]
    end

    Tool --> Privacy
    Privacy --> Compress
    Compress --> Obs
    Obs --> FTS
    Obs --> Embed
    Embed --> Vec

    Prompt --> FTS
    Prompt --> Vec
    FTS --> Result[Search Results]
    Vec --> Result

Loading

Observation Types

Tool usage results are categorized by type:

Type	Description	Target
tool_use	Tool usage result	Edit, Write, and other write tools
bash	Command execution result	Bash commands
error	Error occurrence	All errors (high importance)
success	Success record	Test pass, build success
note	Manual memo	Content injected via /mem-inject

Automatic Importance Scoring:

• Error occurrence: 1.0 (highest)
• Test pass/fail: 0.9
• File create/modify: 0.7
• General commands: 0.5

Architecture

flowchart TB
    subgraph Plugin["ralph-mem Plugin"]
        subgraph Interface["Interface Layer"]
            Hooks[Hooks]
            Skills[Skills]
            Loop[Loop Engine]
        end

        subgraph Core["Core Service"]
            Store[Memory Store]
            Search[Search Engine]
            Compress[Compressor]
        end

        subgraph Storage["Storage"]
            DB[(SQLite + FTS5)]
        end

        Hooks --> Core
        Skills --> Core
        Loop --> Core
        Core --> DB
    end

Loading

Project Structure

ralph-mem/
├── src/
│   ├── hooks/           # Lifecycle hooks
│   ├── skills/          # Slash commands
│   ├── loop/            # Ralph Loop engine
│   ├── memory/          # Memory store & search
│   └── db/              # SQLite + FTS5
├── prompts/             # AI prompts
├── docs/
│   └── PRD.md           # Product Requirements
└── tests/

Tech Stack

• Runtime: Bun
• Language: TypeScript
• Database: SQLite + FTS5
• Testing: Bun Test

Development

# Install dependencies
bun install

# Development mode
bun run dev

# Test
bun test

# Build
bun run build

Documentation

• Architecture - System architecture overview
• PRD - Product requirements document
• Design Docs - Detailed design documents

Korean versions available:

• README (Korean)
• Architecture (Korean)
• PRD (Korean)
• Design Docs (Korean)

References

• Ralph Loop - Geoffrey Huntley
• claude-mem
• Inventing the Ralph Wiggum Loop (Podcast)
• The Brief History of Ralph

License

MIT