/smart-fork - Smart Memory-Driven Session Forking

Based on @PerceptualPeak's Smart Forking concept:

v2.88 Key Changes (MODEL-AGNOSTIC)

• Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
• No flags required: Works with the configured default model
• Flexible: Model-agnostic — runs on whatever model the session runs
• Settings-driven: Model selection via ANTHROPICDEFAULT*_MODEL env vars

"Why not utilize the knowledge gained from your hundreds/thousands of other Claude code sessions? Don't let that valuable context go to waste!!"

Quick Start

# Find relevant sessions to fork from
/smart-fork "Implement OAuth authentication"

# Show fork suggestions for current task
/smart-fork --suggest

# Generate fork command for specific session
/smart-fork --fork <session_id>

# Show memory statistics
/smart-fork --stats

How It Works

1. PARALLEL Memory Search

When you invoke /smart-fork, we search across ALL memory sources in parallel:

┌──────────────────────────────────────────────────────────────┐
│                    PARALLEL MEMORY SEARCH                     │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│      ┌────────────┐  ┌────────────┐  ┌────────────┐          │
│      │   vault    │  │  handoffs  │  │  ledgers   │          │
│      │    MCP     │  │   scan     │  │   scan     │          │
│      └─────┬──────┘  └─────┬──────┘  └─────┬──────┘          │
│            │ PARALLEL      │ PARALLEL      │                 │
│            └───────────────┴───────────────┘                 │
│                            ↓                                  │
│                    AGGREGATOR (top 5)                        │
│                            ↓                                  │
│              .claude/memory-context.json                     │
└──────────────────────────────────────────────────────────────┘

2. Relevance Scoring

Results are scored by:

• Keyword Match: How many search terms appear in the session
• Recency: More recent sessions score higher
• Outcome: Sessions with successful completion score higher
• Similarity: Semantic similarity to current task

3. Fork Suggestions

Top 5 most relevant sessions are suggested with:

• Session ID
• Timestamp
• Brief summary
• Fork command

Commands

/smart-fork "task description"

Search for relevant sessions based on task description.

Example:

/smart-fork "Implement JWT authentication with refresh tokens"

Output:

SMART FORK RESULTS v2.47
========================

Search: "Implement JWT authentication with refresh tokens"

TOP 5 RELEVANT SESSIONS:
------------------------
1. [HIGH] Session: abc123-def456 (2026-01-15)
   Summary: Implemented OAuth2 with JWT, similar auth patterns
   Fork: claude --continue abc123-def456

2. [HIGH] Session: xyz789-uvw012 (2026-01-10)
   Summary: Token refresh implementation in Node.js
   Fork: claude --continue xyz789-uvw012

3. [MEDIUM] Session: pqr345-stu678 (2026-01-05)
   Summary: Authentication middleware setup
   Fork: claude --continue pqr345-stu678

Memory sources searched: vault (5), handoffs (8), ledgers (2)
Total results: 15

/smart-fork --suggest

Show fork suggestions based on current project context.

/smart-fork --fork <session_id>

Generate fork command for a specific session.

/smart-fork --stats

Show memory statistics across all sources.

Integration with Orchestrator

The Smart Fork system integrates with the orchestrator at Step 0b:

Step 0: EVALUATE
├── 0a: 3-Dimension Classification (v2.46)
└── 0b: SMART MEMORY SEARCH (v2.47) ◄── NEW
        │
        ├── Search vault for relevant observations
        ├── Search handoffs for recent context
        └── Search ledgers for session continuity
        │
        ▼
    .claude/memory-context.json
    │
    ├── past_successes: Implementation patterns that worked
    ├── past_errors: Mistakes to avoid
    ├── recommended_patterns: Best practices
    └── fork_suggestions: Top 5 sessions to fork from

Memory Sources

Benefits

1. Avoid Repeating Mistakes

Past errors are surfaced to prevent the same issues.

2. Reuse Successful Patterns

Implementation patterns that worked before are recommended.

3. Faster Context Loading

Fork from a relevant session instead of re-explaining everything.

4. Cross-Project Learning

Patterns from other projects inform current implementation.

Configuration

Smart Fork is configured via ~/.ralph/config/smart-fork.json:

{
    "version": "2.47",
    "cache_duration_seconds": 1800,
    "max_results_per_source": 10,
    "top_k_suggestions": 5,
    "search_recency_days": 30,
    "parallel_timeout_seconds": 30
}

CLI Commands

# Via ralph CLI
ralph fork-suggest "task description"
ralph memory-search "query"
ralph memory-stats

# Via skill
/smart-fork "task description"

Technical Notes

• PARALLEL by Default: All memory searches run concurrently
• 30-minute Cache: Results are cached to avoid repeated searches
• Graceful Degradation: Missing memory sources are skipped
• JSON Output: Results stored in .claude/memory-context.json

Files

Troubleshooting (v2.52.0)

"No memory sources available"

Cause: None of the 3 memory sources (vault, handoffs, ledgers) are initialized.

Fix:

# Initialize handoffs
ralph handoff create

# Initialize ledgers
ralph ledger save

# Verify Obsidian vault directory
ls ~/Documents/Obsidian/MiVault/ 2>/dev/null && echo "vault OK"

"Search timeout after 30s"

Cause: Memory sources are too large or slow to search within timeout.

Fix:

1. Increase timeout in config: ~/.ralph/config/smart-fork.json

``json {"paralleltimeoutseconds": 60} ``

1. Reduce search scope: {"searchrecencydays": 14}
2. Limit results: {"maxresultsper_source": 5}

"PreToolUse:Task hook error"

Cause: Hook execution failed (but usually non-critical).

Fix:

1. Check logs: tail -f ~/.ralph/logs/smart-memory-search-*.log
2. Verify hook is executable: chmod +x ~/.claude/hooks/smart-memory-search.sh
3. Test manually: echo '{"tool_name":"Read"}' | bash ~/.claude/hooks/smart-memory-search.sh

"Empty fork_suggestions"

Cause: No matching sessions found for your keywords.

Fix:

1. Try broader keywords
2. Ensure handoffs exist: ls ~/.ralph/handoffs/
3. Verify recent activity: ls -la ~/.ralph/ledgers/

"Cache not invalidating"

Cause: Cache file still valid within 30-minute window.

Fix:

# Force fresh search by removing cache
rm .claude/memory-context.json

Performance Tuning (v2.52.0)

Configuration Options

Edit ~/.ralph/config/smart-fork.json:

Optimal Configurations

Fast Startup (minimal latency):

{
    "cache_duration_seconds": 3600,
    "parallel_timeout_seconds": 10,
    "max_results_per_source": 3,
    "search_recency_days": 7
}

Comprehensive Search (maximum context):

{
    "cache_duration_seconds": 900,
    "parallel_timeout_seconds": 60,
    "max_results_per_source": 20,
    "search_recency_days": 90
}

Balanced (recommended):

{
    "cache_duration_seconds": 1800,
    "parallel_timeout_seconds": 30,
    "max_results_per_source": 10,
    "search_recency_days": 30
}

Performance Benchmarks

Monitoring Performance

# Check last search duration
tail -1 ~/.ralph/logs/smart-memory-search-*.log | grep "completed in"

# Monitor memory source health
ralph memory-stats

# Profile individual sources
time grep -r "test query" ~/Documents/Obsidian/MiVault/ | head -5

Security Notes (v2.52.0)

The smart-memory-search hook includes these security hardening measures:

All security tests pass: pytest tests/testv247_security.py -v