Skip to content

jtshow/Medusa

Repository files navigation

Medusa Skill Framework (MSF) v0.12.1

medusa.jpg W6EJw.jpg

Ultra-fast skill scanner with audit-based ranking, automatic promotion, and 9-tier leveling system.

⚑ One-Line Install

Windows (PowerShell)

irm https://raw.githubusercontent.com/your-repo/medusa/main/install.ps1 | iex

Windows (Command Prompt)

curl -SL https://raw.githubusercontent.com/your-repo/medusa/main/install.bat -o install.bat && install.bat

macOS / Linux

curl -sSL https://raw.githubusercontent.com/your-repo/medusa/main/install.sh | bash

Build from Source (Any Platform)

Step 1: Install Rust

  • Windows: irm https://win.rustup.rs/x86_64 | iex (or download from https://rustup.rs)
  • macOS/Linux: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Step 2: Clone & Build

# All platforms (Windows CMD/PowerShell, macOS, Linux):
git clone https://github.com/your-repo/medusa.git
cd medusa
cargo build --release

Binary Location:

Platform Binary Path
Windows target\release\medusa.exe
macOS/Linux target/release/medusa

Step 3: Run

# Windows (CMD)
.\target\release\medusa.exe --help

# Windows (PowerShell)
.\target\release\medusa.exe --help

# macOS/Linux
./target/release/medusa --help
Feature Description Performance
Audit-Based Ranking Measures complexity, value, technical depth 9-tier system
Automatic Promotion Skills rank up as they improve No manual needed
Parallel Scanning Rayon-powered concurrent processing 46% faster (A/B tested)
Fusion Detection Finds similar skills (name + content) FxHash-powered
HTML Visualization Dark-themed reports with progress bars Interactive
A/B Test Framework Validate performance claims scientifically Statistical rigor
Dreaming Process Cross-session pattern detection, recurring gaps, trends Auto-records every scan
Memory Consolidation Merges duplicates, prunes low-severity, caps at 200 Runs after every dream
Outcomes Framework Weighted rubric-based skill assessment 4 default criteria
Learning Paths Built-in fix suggestions mapped to gap patterns Per-skill recommendations
Multi-Agent Orchestration 4 specialized sub-audits (doc quality, code quality, dependencies, learning value) Synthesized weighted scoring
Dream Diary Narrative timeline of skill evolution with gap history Console + Markdown export
Configurable Dreaming Tune frequency, retention, auto-apply, max insights Via medusa.toml
Procedural Memory Auto-detects step-by-step workflows from skill content 38 workflows from 36 skills
Cross-Agent Memory Export/import dream + procedural + outcome bundles Merge with source tracking

Usage

Scan Skills (JSON Output)

# Windows (CMD)
.\target\release\medusa.exe scan C:\path\to\skills

# Windows (PowerShell)
.\target\release\medusa.exe scan C:\path\to\skills

# macOS/Linux
./target/release/medusa scan /path/to/skills

Audit a Skill (See WHY it's at its tier)

# Windows
.\target\release\medusa.exe audit C:\path\to\skills

# macOS/Linux
./target/release/medusa audit /path/to/skills

Example Output:

=== Medusa Skill Audit Report ===

Skill: ai-ml (ai-ml), level: Godlike
  Experience: 100.0/100
  Confidence: 75%
  Metrics:
    - Content Length: 5966 chars
    - Code Blocks: 15
    - Step Instructions: 0
    - Technical Terms: 26
    - Complexity Score: 80.0/100
    - Value Score: 90.0/100

Generate HTML Report

# Windows (CMD)
.\target\release\medusa.exe html C:\path\to\skills C:\path\to\report.html

# Windows (PowerShell)
.\target\release\medusa.exe html C:\path\to\skills C:\path\to\report.html

# macOS/Linux
./target/release/medusa html /path/to/skills /path/to/report.html

Opens a beautiful dark-themed visualization with:

  • Skill bars showing experience levels
  • Color-coded tiers (Godlike = Purple gradient, Unique = Orange gradient, etc.)
  • Detailed metrics for each skill
  • Fusion detection (similar skills)

Run A/B Test (Validate Performance)

# Windows (CMD)
.\target\release\medusa.exe ab-test C:\path\to\skills --iterations 20

# Windows (PowerShell)
.\target\release\medusa.exe ab-test C:\path\to\skills --iterations 20

# macOS/Linux
./target/release/medusa ab-test /path/to/skills --iterations 20

Example Output:

Running A/B Test: Parallel vs Sequential Scan
Path: /path/to/skills
Iterations: 20

Hypothesis: Parallel scanning is faster than sequential
Primary metric: scan_time_ms

Iteration 1: Parallel=178ms, Sequential=362ms
Iteration 2: Parallel=187ms, Sequential=325ms
...
Iteration 20: Parallel=204ms, Sequential=391ms

=== A/B Test Results ===
Parallel avg: 190.00ms
Sequential avg: 352.00ms
βœ… Parallel is 46.0% faster

9-Tier Leveling System

Tier Range Color Background
Godlike 95+ πŸ”΄ Red-Orange-Green Gradient
Unique 90+ πŸ”΄ Red Solid
Legendary 85+ πŸ’œ Pink-Purple Solid
Mythic 80+ 🟣 Purple Solid
Epic 75+ 🟑 Yellow Solid
Ultra Rare 65+ 🟒 Teal Solid
Rare 55+ πŸ”΅ Blue Solid
Uncommon 45+ 🟒 Green Solid
Common 25+ βšͺ Light Gray Solid
Poor <25 ⚫ Dark Gray Solid

Commands

medusa --help

Output:

Medusa Skill Framework (MSF) v0.12 - Audit-Based Ranking with Context
Usage: medusa <command> [options]

Commands:
  scan <path>              Scan skills with FULL audit (60/30/10 scoring)
    --sequential           Use sequential scanning (no Rayon)
    --no-cache             Disable incremental scan cache

  audit <path>             Show detailed skill audit with cross-session context
    --no-cache             Disable cache

  html <path> <output>     Generate HTML visualization
    --sequential           Use sequential scanning
    --no-cache             Disable cache

  export-csv <path> <f>    Export skills to CSV format
  export-md <path> <f>     Export skills to Markdown
  export-svg <path> <f>    Export skills to SVG visualization

  ab-test <path>           Run A/B test (parallel vs sequential)
    --iterations N         Number of test iterations (default: 10)

  dream <path>             Run dreaming process (cross-session pattern detection)
  dream-status <path>      Show dream knowledge base and patterns
  dream-reset <path>       Reset dream state and history
  dream-consolidate <path> Manually consolidate dream knowledge base
  dream-diary <path>       Show dream diary (narrative skill evolution timeline)
    --output <file.md>     Export diary as Markdown
  dream-params <path>      Show dreaming configuration parameters

  orchestrate <path>       Run multi-agent orchestrated audit (4 specialized sub-audits)
    --sequential           Use sequential scanning
    --no-cache             Disable cache

  outcome-add <path> <id>  Add default outcome rubric for a skill
  outcome-list <path>      List outcome rubrics
  outcome-remove <path> <id> Remove an outcome rubric
  learning-path <path> <id> Show learning path and suggestions for a skill

  procedural-list <path>   List all learned procedural workflows
  procedural-show <p> <id> Show workflows associated with a skill

  memory-export <p> <f>    Export all memory (dream, procedural, outcomes) to JSON bundle
  memory-import <p> <f>    Import and merge a memory bundle from another Medusa instance
    --source <name>        Tag imported data with a source identifier

  update                  Update Medusa from GitHub (git pull + rebuild)

Options:
  --help, -h              Show this help message
  --version, -v           Show version

How It Works

SKILL.md files
    ↓
[WalkDir] Scan filesystem (max depth 4)
    ↓
[Rayon] Parallel processing (46% faster, optional)
    ↓
[Regex] Extract YAML frontmatter
    ↓
[Audit] Measure complexity (length, code, steps, terms)
    ↓
[Score] Calculate experience (60% + 30% + 10%)
    ↓
[Rank] Assign tier (Godlike β†’ Poor)
    ↓
[Fusion] Detect similar skills (FxHash)
    ↓
[Session] Record snapshot for dreaming
    ↓
[Dream] Cross-session pattern detection + consolidation
    ↓
[Diary] Generate skill evolution timeline
    ↓
[Agents] Multi-agent orchestrated sub-audits
    ↓
[Outcomes] Rubric-based quality assessment
    ↓
[Procedural] Extract step-by-step workflows
    ↓
[Output] JSON / HTML / CSV / MD / SVG

Cross-Platform Support βœ…

Platform Binary Build Command
Windows medusa.exe cargo build --release
macOS (Intel) medusa cargo build --release
macOS (Apple Silicon) medusa cargo build --release
Linux (x86_64) medusa cargo build --release
Linux (ARM64) medusa cargo build --release

No WSL required! Runs natively on all platforms.

medusa/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ main.rs          # CLI entry, scoring, reports (~1350 lines)
β”‚   β”œβ”€β”€ dream.rs         # Dreaming, consolidation, diary, learning paths
β”‚   β”œβ”€β”€ outcomes.rs      # Rubric CRUD, skill assessment
β”‚   β”œβ”€β”€ agents.rs        # Multi-agent orchestrated audit (4 agents)
β”‚   └── procedural.rs    # Procedural workflow detection & memory
β”œβ”€β”€ target/
β”‚   └── release/
β”‚       └── medusa       # Compiled binary
β”œβ”€β”€ Cargo.toml          # Dependencies (minimal: 9 deps)
β”œβ”€β”€ medusa.toml         # Configurable scoring + dreaming params
β”œβ”€β”€ README.md           # This file
β”œβ”€β”€ TECHNICAL.md        # Architecture deep-dive
└── .medusa_state.json  # Promotion state (auto-created)

Dependencies (Minimal)

serde       β€” Struct serialization
serde_json  β€” JSON output
toml        β€” Config parsing
fxhash      β€” Fusion hash computation
walkdir     β€” Directory traversal
rayon       β€” Parallel processing
regex       β€” Pattern extraction
lazy_static β€” Regex compilation
chrono      β€” Timestamps for dream sessions

Compile time: ~5 seconds (release, stripped) Binary size: ~2MB (Windows/Linux/macOS) No runtime dependencies! Single binary, just download and run.

Examples

Example 1: Scan Your Skills

# Windows
.\target\release\medusa.exe scan C:\Project\.opencode\skills

# macOS/Linux
./target/release/medusa scan ~/.hermes/skills

Example 2: Audit a Specific Skill

# Windows
.\target\release\medusa.exe audit C:\Project\.opencode\skills\ai-ml

# macOS/Linux
./target/release/medusa audit ~/.hermes/skills/ai-ml

Shows detailed breakdown:

  • Why it's ranked "Godlike"
  • Content length, code blocks, step count
  • Technical term density
  • Complexity and value scores

Example 3: Generate Beautiful Report

# Windows
.\target\release\medusa.exe html C:\Project\.opencode\skills C:\Project\medusa\report.html

# macOS/Linux
./target/release/medusa html ~/.hermes/skills ~/report.html

Example 2: Audit a Specific Skill

# Shows WHY it's at its tier
medusa audit /path/to/skills/ai-ml

Example Output:

=== Medusa Skill Audit Report ===

Skill: ai-ml (ai-ml), level: Godlike
  Experience: 100.0/100
  Confidence: 75%
  Metrics:
    - Content Length: 5966 chars
    - Code Blocks: 15
    - Step Instructions: 0
    - Technical Terms: 26
    - Complexity Score: 80.0/100
    - Value Score: 90.0/100

Example 3: Generate Beautiful Report

# Windows
.\target\release\medusa.exe html C:\path\to\skills report.html

# Mac/Linux
./target/release/medusa html /path/to/skills report.html

Opens in browser with:

  • Dark theme (hacker style)
  • Color-coded skill cards
  • Experience progress bars
  • Fusion detection section

Performance

A/B Test Results (36 skills, 20 iterations):

  • Parallel (Rayon): 190ms average
  • Sequential: 352ms average
  • Speedup: 46% faster

Scalability:

  • 36 skills scanned in ~150ms
  • Linear scaling with Rayon parallelization
  • Memory-efficient (no unnecessary copies)

Update Medusa

# One-line update (pull latest + rebuild)
cd /path/to/medusa && git pull && cargo build --release

Or use the built-in update command:

medusa update

Quick Test (Verify Installation)

After installation, verify it works:

# Windows (CMD)
.\target\release\medusa.exe --version

# Windows (PowerShell)
.\target\release\medusa.exe --version

# macOS/Linux
./target/release/medusa --version

Expected output:

Medusa Skill Framework (MSF) v0.12.1

Test Scan

# Windows: medusa scan C:\Project\.opencode\skills

# macOS/Linux:
./target/release/medusa scan ~/.hermes/skills

Should output JSON with skills audit.

Traditional skill systems use static rankings (you manually set the level).

Medusa uses audit-based ranking:

  1. Measures actual skill complexity (content, code, steps, terms)
  2. Calculates objective experience score (60% complexity + 30% value)
  3. Assigns tier automatically (Godlike β†’ Poor)
  4. Promotes as you improve (just edit SKILL.md, next scan updates!)

No manual promotion commands needed!

License

MIT License (or your choice)

Version History

  • v0.12 (Current): Multi-agent orchestration, dream diary, configurable dreaming, procedural memory, cross-agent memory sharing + all Phase 1 features
  • v0.11: 9-tier leveling system (Godlike β†’ Poor), rank promotion system
  • v0.5.0: Rank promotion system
  • v0.4.0: CLI improvements, A/B test framework
  • v0.3.0: Fusion detection, HTML visualization
  • v0.2.0: Parallel scanning with Rayon
  • v0.1.0: Initial release

Built with Rust πŸ¦€ + Rayon ⚑ + Regex πŸ”

About

Medusa Skill Framework for AI Agents.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages