SpecMem Stats - Memory & Codebase Statistics

Show memory system statistics and distributions.

IMMEDIATE ACTION REQUIRED

Step 1: Parse input

• Args: $ARGUMENTS (may be empty, undefined, or a keyword)
• Normalize: treat empty/undefined/null as "default"

Step 2: Validate input

• Valid subcommands: help, -h, --help, memory, memories, tags, cache, instances, relationships, timeseries, full, detailed, all, default, (empty)
• If input is not in this list, show error message and HELP section, then STOP
• If input is valid, proceed to Step 3

Step 3: Route by keyword

Input	Action
help, -h, --help	Show HELP section below, then STOP
empty, undefined, all, default	EXECUTE with default params
memory, memories	EXECUTE with memory params
tags	EXECUTE with tags params
cache	EXECUTE with cache params
instances	EXECUTE with instances params
relationships, relations	EXECUTE with relationships params
timeseries, time	EXECUTE with timeseries params
full, detailed	EXECUTE with full params
other	Show error message with valid options, show HELP, then STOP

Step 4: EXECUTE - Call the MCP tool NOW

For default (empty/undefined/all/default):

mcp__specmem__show_me_the_stats({
  "includeTypeDistribution": true,
  "includeImportanceDistribution": true,
  "includeCacheStats": true,
  "includeInstanceStats": true
})

For memory/memories:

mcp__specmem__show_me_the_stats({
  "includeTypeDistribution": true,
  "includeImportanceDistribution": true,
  "includeCacheStats": false,
  "includeInstanceStats": false,
  "includeTagDistribution": true
})

For tags:

mcp__specmem__show_me_the_stats({
  "includeTagDistribution": true,
  "includeTypeDistribution": false,
  "includeImportanceDistribution": false,
  "includeCacheStats": false,
  "includeInstanceStats": false
})

For cache:

mcp__specmem__show_me_the_stats({
  "includeCacheStats": true,
  "includeTypeDistribution": false,
  "includeImportanceDistribution": false,
  "includeInstanceStats": false
})

For instances:

mcp__specmem__show_me_the_stats({
  "includeInstanceStats": true,
  "includeAllInstances": true,
  "includeTypeDistribution": false,
  "includeImportanceDistribution": false,
  "includeCacheStats": false
})

For relationships/relations:

mcp__specmem__show_me_the_stats({
  "includeRelationshipStats": true,
  "includeTypeDistribution": false,
  "includeImportanceDistribution": false,
  "includeCacheStats": false,
  "includeInstanceStats": false
})

For timeseries/time:

mcp__specmem__show_me_the_stats({
  "includeTimeSeriesData": true,
  "timeSeriesGranularity": "day",
  "includeTypeDistribution": false,
  "includeImportanceDistribution": false,
  "includeCacheStats": false,
  "includeInstanceStats": false
})

For full/detailed:

mcp__specmem__show_me_the_stats({
  "includeTypeDistribution": true,
  "includeImportanceDistribution": true,
  "includeCacheStats": true,
  "includeInstanceStats": true,
  "includeAllInstances": true,
  "includeTagDistribution": true,
  "includeRelationshipStats": true,
  "includeTimeSeriesData": true,
  "timeSeriesGranularity": "day"
})

---

HELP

SPECMEM STATS - View Memory System Statistics

USAGE:
  /specmem-stats              Show default stats (types, importance, cache, instances)
  /specmem-stats memory       Memory type and importance breakdown
  /specmem-stats tags         Tag distribution only
  /specmem-stats cache        Cache performance metrics
  /specmem-stats instances    Per-instance RAM usage (all processes)
  /specmem-stats relationships Memory relationship statistics
  /specmem-stats timeseries   Time series data (memory creation over time)
  /specmem-stats full         Complete stats including all metrics

AVAILABLE SUBCOMMANDS:
  (empty)                     Default stats (types, importance, cache, instances)
  memory, memories            Memory type and importance distribution
  tags                        Tag usage distribution (top 50 tags)
  cache                       Cache performance (embedding cache, server cache, DB pool)
  instances                   Per-instance RAM usage across all processes
  relationships, relations    Memory relationship statistics
  timeseries, time            Time series data for memory creation
  full, detailed              All statistics with all metrics enabled

OPTIONS:
  help, -h, --help            Show this help

PARAMETERS EXPLAINED:
  includeTypeDistribution     Memory type breakdown (episodic, semantic, etc.)
  includeImportanceDistribution  Importance level breakdown (critical, high, etc.)
  includeCacheStats           Embedding cache, server cache, DB connection pool stats
  includeInstanceStats        Current instance RAM usage tracking
  includeAllInstances         Include stats from ALL running SpecMem instances
  includeTagDistribution      Tag usage distribution (top 50 tags)
  includeRelationshipStats    Memory relationship and connection statistics
  includeTimeSeriesData       Memory creation time series (requires timeSeriesGranularity)
  timeSeriesGranularity       Granularity for time series: "hour", "day", "week", "month"

EXAMPLES:
  /specmem-stats              Get overview of memory system
  /specmem-stats full         Detailed report with all metrics
  /specmem-stats cache        Check embedding cache performance
  /specmem-stats instances    Check RAM usage across all instances
  /specmem-stats tags         See most commonly used tags
  /specmem-stats relationships  See how memories are connected

TOOL SCHEMA REFERENCE:
  The mcp__specmem__show_me_the_stats tool accepts these boolean parameters:
  - includeTypeDistribution (default: true)
  - includeImportanceDistribution (default: true)
  - includeCacheStats (default: true)
  - includeInstanceStats (default: true)
  - includeAllInstances (default: false)
  - includeTagDistribution (default: false)
  - includeRelationshipStats (default: false)
  - includeTimeSeriesData (default: false)
  - timeSeriesGranularity (enum: "hour"|"day"|"week"|"month", default: "day")

RELATED COMMANDS:
  /specmem-find               Search memories
  /specmem-remember           Store new memories
  /specmem-pointers           Search code with tracebacks