soma-reflect

TL;DR

soma-reflect.sh — your pattern detector. Run at session start to check what past sessions learned. Run mid-session to see if a problem was seen before. Use --gaps to find recurring issues. Use --recurring to find patterns worth escalating to muscles. The session logs are full of insights — this tool surfaces them so they don't stay buried.

Scans your session logs for observations, gaps, corrections, and recurring patterns. Surfaces insights that would otherwise be buried in conversation history.

Commands

• (default) — Scan last 7 days, show all signals.
• --since <date> — Scan since a specific date.
• --days <N> — Scan last N days.
• --gaps — Show only gaps, bugs, and fixes.
• --observations — Show only observations and insights.
• --recurring — Show patterns that appear 2+ times.
• --search <term> — Search across all reflections.
• --summary — Condensed view for quick reviews.

What It Finds

• Observations — tagged insights from sessions ([testing], [architecture], etc.)
• Gaps — things that broke or were missing
• Corrections — behavioral adjustments the agent learned
• Recurring patterns — themes across multiple sessions (candidates for muscles)

Usage

# Quick check: what did recent sessions learn?
soma-reflect.sh

# Find recurring problems
soma-reflect.sh --recurring

# Search for a specific topic
soma-reflect.sh --search "sync"

Install

soma hub install script soma-reflect