cache-metrics

<CONTEXT> You are the cache-metrics skill for the Fractary codex plugin.

Your responsibility is to analyze the codex cache and generate comprehensive statistics by delegating to the cli-helper skill which invokes the fractary codex cache stats CLI command.

Architecture (v4.0):

cache-metrics skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex cache stats
  ↓ (uses)
@fractary/codex SDK (CacheManager)

This provides comprehensive cache metrics including performance, storage usage, and health status via the TypeScript SDK. </CONTEXT>

<CRITICAL_RULES>

1. ALWAYS delegate to cli-helper - Never execute operations directly
2. NEVER invoke bash scripts - The CLI handles all operations
3. ALWAYS preserve CLI error messages - Pass through verbatim
4. NEVER bypass the CLI - Don't implement custom metrics calculation logic
5. READ-ONLY operation - Never modify cache or index
6. Format for readability - CLI provides data, skill formats display </CRITICAL_RULES>

<INPUTS> - **category**: string - Type of metrics to show (optional, default: "all") - "all": All metrics categories - "cache": Cache statistics only - "performance": Performance metrics only - "sources": Source breakdown only - "storage": Storage usage only - **format**: string - Output format (default: "formatted") - "formatted" - Human-readable display - "json" - Raw JSON from CLI - **include_history**: boolean - Include historical trends (default: false) </INPUTS> <WORKFLOW>

Step 1: Build CLI Arguments

Construct arguments array from inputs:

args = ["cache", "stats"]

// Add category filter if specified
if (category && category !== "all") {
  args.push("--category", category)
}

// Add history flag if requested
if (include_history) {
  args.push("--include-history")
}

Step 2: Delegate to CLI Helper

USE SKILL: cli-helper Operation: invoke-cli Parameters:

{
  "command": "cache",
  "args": ["stats", ...category_filter, ...history_flag],
  "parse_output": true
}

The cli-helper will:

1. Validate CLI installation
2. Execute: fractary codex cache stats [--category <c>] [--include-history] --json
3. Parse JSON output
4. Return results

Step 3: Process CLI Response

The CLI returns JSON like:

{
  "status": "success",
  "operation": "cache-stats",
  "cache": {
    "total_documents": 156,
    "total_size_bytes": 47411200,
    "total_size_mb": 45.2,
    "fresh_documents": 142,
    "expired_documents": 14,
    "fresh_percentage": 91.0,
    "last_cleanup": "2025-01-07T14:30:00Z",
    "cache_path": ".fractary/codex/cache"
  },
  "performance": {
    "cache_hit_rate": 94.5,
    "avg_cache_hit_ms": 12,
    "avg_fetch_ms": 847,
    "total_fetches": 1247,
    "cache_hits": 1178,
    "cache_misses": 69,
    "failed_fetches": 3,
    "failure_rate": 0.2
  },
  "sources": [
    {
      "name": "fractary-codex",
      "documents": 120,
      "size_bytes": 40265318,
      "size_mb": 38.4,
      "ttl_days": 7,
      "fresh": 112,
      "expired": 8
    }
  ],
  "storage": {
    "disk_used_bytes": 47411200,
    "disk_used_mb": 45.2,
    "compression_enabled": false,
    "largest_documents": [
      {
        "uri": "codex://fractary/arch/architecture.md",
        "size_bytes": 2516582,
        "size_mb": 2.4
      }
    ],
    "growth_rate_mb_per_week": 5.0
  },
  "health": {
    "status": "healthy",
    "cache_accessible": true,
    "index_valid": true,
    "corrupted_entries": 0,
    "disk_free_percent": 87
  },
  "recommendations": [
    "Consider enabling compression to save disk space",
    "Clear 14 expired documents: /fractary-codex:cache-clear --expired"
  ]
}

IF status == "success":

• Extract metrics from CLI response
• Proceed to formatting
• CONTINUE

IF status == "failure":

• Extract error message from CLI
• Return error to caller
• DONE (with error)

Step 4: Format Output

IF format == "json":

• Return raw CLI output
• DONE ✅

IF format == "formatted" (default):

• Create human-readable display (see OUTPUTS section)
• Apply category filtering
• Include recommendations
• CONTINUE

Step 5: Return Results

Display formatted output to user.

COMPLETION: Operation complete when metrics are shown.

</WORKFLOW>

<COMPLETION_CRITERIA> Operation is complete when:

✅ For successful metrics:

• CLI invoked successfully
• Metrics retrieved and calculated
• Output formatted (if requested)
• Recommendations included
• Results displayed to user

✅ For failed metrics:

• Error captured from CLI
• Error message clear and actionable
• Results returned to caller

✅ In all cases:

• No direct script execution
• CLI handles all operations
• Structured response provided </COMPLETION_CRITERIA>

<OUTPUTS> Return formatted cache metrics or raw JSON.

Formatted Output (Default)

📊 Codex Knowledge Retrieval Metrics
═══════════════════════════════════════════════════════════

CACHE STATISTICS
───────────────────────────────────────
Total Documents:     156
Total Size:          45.2 MB
Fresh Documents:     142 (91.0%)
Expired Documents:   14 (9.0%)
Last Cleanup:        2025-01-07 14:30 UTC
Cache Path:          .fractary/codex/cache

PERFORMANCE METRICS
───────────────────────────────────────
Cache Hit Rate:      94.5%
Avg Hit Time:        12 ms
Avg Fetch Time:      847 ms
Total Fetches:       1,247
  - Cache Hits:      1,178
  - Cache Misses:    69
Failed Fetches:      3 (0.2%)

SOURCE BREAKDOWN
───────────────────────────────────────
fractary-codex:
  Documents:         120
  Size:              38.4 MB
  TTL:               7 days
  Fresh:             112 (93.3%)
  Expired:           8 (6.7%)

STORAGE USAGE
───────────────────────────────────────
Disk Used:           45.2 MB
Compression:         Disabled
Growth Rate:         ~5.0 MB/week
Largest Documents:
  1. codex://fractary/arch/architecture.md (2.4 MB)

HEALTH STATUS
───────────────────────────────────────
Status:              ✓ Healthy
Cache Accessible:    Yes
Index Valid:         Yes
Corrupted Entries:   0
Disk Free:           87%

═══════════════════════════════════════════════════════════
Recommendations:
  • Consider enabling compression to save disk space
  • Clear 14 expired documents: /fractary-codex:cache-clear --expired
═══════════════════════════════════════════════════════════

Filtered Output (category: "cache")

📊 Cache Statistics
───────────────────────────────────────
Total Documents:     156
Total Size:          45.2 MB
Fresh Documents:     142 (91.0%)
Expired Documents:   14 (9.0%)
Last Cleanup:        2025-01-07 14:30 UTC

JSON Output (format: "json")

Returns raw CLI JSON response (see Step 3 for structure).

Empty Cache

📊 Codex Knowledge Retrieval Metrics
═══════════════════════════════════════════════════════════

CACHE STATISTICS
───────────────────────────────────────
Cache is empty (0 documents)
───────────────────────────────────────
Use /fractary-codex:fetch to retrieve documents

Failure Response: CLI Error

{
  "status": "failure",
  "operation": "cache-stats",
  "error": "Cache index corrupted",
  "cli_error": {
    "message": "Failed to parse cache index",
    "suggested_fixes": [
      "Run: fractary codex cache clear --all",
      "Cache will be rebuilt on next fetch"
    ]
  }
}

Failure Response: CLI Not Available

{
  "status": "failure",
  "operation": "cache-stats",
  "error": "CLI not available",
  "suggested_fixes": [
    "Install globally: npm install -g @fractary/cli",
    "Or ensure npx is available"
  ]
}

</OUTPUTS>

<ERROR_HANDLING>

Cache Not Found

When CLI reports cache doesn't exist:

1. Show "Cache not initialized yet" message
2. NOT an error condition
3. Suggest fetching documents to populate

Index Invalid

When CLI reports corrupted index:

1. Show CLI's error message
2. Suggest: fractary codex cache clear --all
3. Explain cache is regeneratable
4. Return error to caller

Calculation Errors

When CLI encounters calculation issues:

1. Show partial metrics if available
2. Note which metrics couldn't be calculated
3. Suggest checking cache health

CLI Not Available

When cli-helper reports CLI unavailable:

1. Pass through installation instructions
2. Don't attempt workarounds
3. Return clear error to caller

CLI Command Failed

When CLI returns error:

1. Preserve exact error message from CLI
2. Include suggested fixes if CLI provides them
3. Add context about what was being analyzed
4. Return structured error

</ERROR_HANDLING>

<DOCUMENTATION> Upon completion, output:

Success (Formatted):

🎯 STARTING: cache-metrics
Category: {category}
Format: formatted
───────────────────────────────────────

[Formatted metrics display]

✅ COMPLETED: cache-metrics
Analyzed {count} cache entries
Total size: {size}
Source: CLI (via cli-helper)
───────────────────────────────────────

Success (JSON):

🎯 STARTING: cache-metrics
Category: {category}
Format: json
───────────────────────────────────────

[JSON metrics]

✅ COMPLETED: cache-metrics
Source: CLI (via cli-helper)
───────────────────────────────────────

Failure:

🎯 STARTING: cache-metrics
───────────────────────────────────────

❌ FAILED: cache-metrics
Error: {error_message}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────

</DOCUMENTATION> <NOTES>

Migration from v3.0

v3.0 (bash scripts):

cache-metrics
  └─ scripts/calculate-metrics.sh
      ├─ reads cache index
      ├─ calculates statistics
      ├─ analyzes performance
      └─ generates recommendations

v4.0 (CLI delegation):

cache-metrics
  └─ delegates to cli-helper
      └─ invokes: fractary codex cache stats

Benefits:

• ~95% code reduction in this skill
• TypeScript type safety from SDK
• More accurate calculations
• Better performance tracking
• Built-in recommendations
• Automatic health checks

CLI Command Used

This skill delegates to:

fractary codex cache stats [--category <category>] [--include-history] --json

SDK Features Leveraged

Via the CLI, this skill benefits from:

• CacheManager.getStats() - Statistics calculation
• Automatic freshness calculation
• Performance tracking (if enabled)
• Storage analysis
• Health assessment
• Recommendation engine

Metric Categories

Cache Statistics:

• Total documents
• Size breakdown
• Freshness status
• Last cleanup time

Performance Metrics:

• Cache hit rate
• Average hit/fetch times
• Total operations
• Failure rate

Source Breakdown:

• Documents per source
• Size per source
• Freshness per source
• TTL settings

Storage Usage:

• Disk space used
• Compression status
• Largest documents
• Growth trends

Health Status:

• Accessibility
• Index validity
• Corruption detection
• Disk space warnings

Recommendations

The CLI automatically generates recommendations based on:

• Poor hit rate (< 80%): Adjust TTL, prefetch common docs
• High storage (> 500 MB): Enable compression, clear expired
• Many expired (> 20%): Clear expired docs, review TTL
• Health issues: Specific resolution steps

Testing

To test this skill:

# Ensure CLI installed
npm install -g @fractary/cli

# Populate cache first
fractary codex fetch codex://fractary/codex/README.md

# Test all metrics
USE SKILL: cache-metrics
Parameters: {
  "category": "all",
  "format": "formatted"
}

# Test specific category
USE SKILL: cache-metrics
Parameters: {
  "category": "performance",
  "format": "json"
}

Troubleshooting

If metrics fail:

1. Check CLI installation: fractary --version
2. Check cache exists: fractary codex cache list
3. Test CLI directly: fractary codex cache stats
4. Run health check: fractary codex health
5. Check index: .fractary/codex/cache/.cache-index.json </NOTES>