Scientifically Validated Speech Vitality Index

Overview

A model context protocol (MCP) server that provides scientifically validated analysis of conversational speech patterns from Limitless Pendant recordings. Unlike speculative biomarker approaches, this implementation focuses exclusively on empirically validated metrics derived from real-world transcription data analysis.

What's New in v0.9.0

Starred Lifelog Support: Filter and identify important conversations marked with stars
Enhanced Error Messages: More specific error handling with detailed context
Improved Timezone Handling: Robust fallback mechanism for timezone detection
Updated Timestamps: Track when lifelogs were last modified with updatedAt field
Full API Parity: Now supports 100% of official Limitless API parameters

Key Features

Validated Speech Metrics: Based on empirical analysis of 2,500+ conversation segments
Multi-Dimensional Analysis: Engagement, fluency, and interaction patterns
Context Recognition: Automatic detection of conversation types (presentation, discussion, casual, automated)
Data Quality Assessment: Transparent reliability scoring and confidence intervals
Real-time Analysis: Process conversations as they happen through the Limitless API

Scientific Foundation

Validation Methodology

This implementation underwent rigorous empirical validation using real Limitless Pendant transcription data:

Data Collection: 2,500+ conversation segments across 20 sessions
Pattern Analysis: Identification of reliable vs. artifact patterns in transcription timing
Metric Validation: Only metrics with consistent, interpretable patterns were retained
Quality Filtering: Systematic exclusion of unreliable data segments

Validated Metrics

Engagement Analysis

Micro-responsiveness Rate: Percentage of segments ≤100ms containing responsive words
- Baseline: 7-14% in normal conversation
- High engagement: >20%
- Validation: Strong correlation with conversation quality across sessions
Turn-taking Velocity: Response time patterns between speakers
- Quick responses: <500ms (indicates high engagement)
- Normal responses: 500-1500ms
- Validation: 55% quick responses observed in active discussions

Fluency Analysis

Filtered Speaking Rate: Words per minute from validated segments only
- Criteria: Segments ≥800ms, ≤30s, ≥5 words
- Realistic range: 100-250 WPM
- Validation: 47-58% of segments suitable for analysis, 60-88% fall in expected range
Speech Consistency: Variance in speaking patterns within conversations
- Measurement: Standard deviation of WPM across valid segments
- Validation: Consistent speakers show <30% coefficient of variation

Interaction Analysis

Conversational Balance: Distribution of speaking time between participants
- Optimal range: 30-70% user participation
- Measurement: 1 - |0.5 - userSpeakingRatio|
Speaker Transition Patterns: Frequency and timing of turn-taking
- Active conversation: >20 transitions per session
- Overlaps: Negative gaps indicate excitement/agreement

Rejected Metrics

Based on empirical analysis, the following commonly used speech metrics were excluded due to unreliability:

Complex biomarker calculations (insufficient validation)
Percentile rankings (lack of normative population data)
Conversation stage analysis (inconsistent patterns)
Pause duration analysis (confounded by transcription artifacts)

Installation

npm install -g 199bio-mcp-limitless-server

Usage

Claude Desktop Configuration

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "limitless": {
      "command": "npx",
      "args": ["199bio-mcp-limitless-server"],
      "env": {
        "LIMITLESS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

`speechclock` / `speechage`

Get your scientifically validated Speech Vitality Index.

Parameters:

time_expression (optional): Natural time like "today", "this week", "past 7 days"
timezone (optional): IANA timezone for calculations
detailed (optional): Show detailed component breakdown

Note: All lifelog tools now support isStarred parameter to filter only starred conversations.

Example:

What's my speechclock for today?

Response:

Speech Vitality Index: 78/100
Scientifically validated analysis (2.0.0-validated)

Conversation Type: discussion (85% confidence)
Indicators: High responsiveness, Frequent speaker changes

Key Metrics:
• Engagement: 82/100 (18.3% responsiveness)
• Fluency: 76/100 (185 WPM median)  
• Interaction: 71/100 (47 transitions)

Data Quality: high (89% confidence)
Duration: 23.4 minutes

Advanced Analysis Tools

Natural Time Queries: limitless_get_by_natural_time
Meeting Detection: limitless_detect_meetings
Action Item Extraction: limitless_extract_action_items
Detailed Transcripts: limitless_get_raw_transcript
Daily Summaries: limitless_get_daily_summary

API Reference

Core Types

interface Lifelog {
  id: string;
  title?: string;
  markdown?: string;
  startTime: string;
  endTime: string;
  contents?: LifelogContentNode[];
  isStarred?: boolean;  // NEW: Whether this lifelog is starred
  updatedAt?: string;   // NEW: When this lifelog was last updated
}

interface LifelogParams {
  // ... existing params ...
  isStarred?: boolean;  // NEW: Filter for starred lifelogs only
  batch_size?: number;  // NEW: Configurable batch size for performance tuning
}

interface ValidatedSpeechVitality {
  // Validated metric categories
  engagement: EngagementMetrics;
  fluency: FluencyMetrics;
  interaction: InteractionMetrics;
  
  // Context and reliability
  context: ConversationContext;
  dataQuality: DataQualityMetrics;
  
  // Composite scores (0-100)
  overallScore: number;
  engagementScore: number;
  fluencyScore: number;
  interactionScore: number;
}

Reliability Assessment

Every analysis includes data quality metrics:

interface DataQualityMetrics {
  totalSegments: number;
  dataReliability: 'high' | 'medium' | 'low';
  confidenceScore: number; // 0-100
  anomalies: {
    unrealisticWPM: number;
    suspiciouslyLongGaps: number;
    // ... other quality indicators
  };
}

Research Applications

Clinical Research

Validated metrics suitable for longitudinal studies
Transparent methodology with published validation criteria
Quality assessment enables filtering of unreliable data
Standardized output facilitates cross-study comparisons

Potential Applications

Cognitive health monitoring
Communication effectiveness assessment
Social interaction analysis
Remote health screening
Therapeutic intervention evaluation

Limitations and Considerations

Transcription Dependency: Analysis quality depends on Limitless transcription accuracy
Context Specificity: Optimized for conversational speech, not clinical tasks
Population Validity: Validation based on healthy adult conversations
Technical Requirements: Requires minimum 5-minute conversations for reliable analysis

Development

Building from Source

git clone https://github.com/199-biotechnologies/mcp-limitless-enhanced.git
cd mcp-limitless-enhanced
npm install
npm run build

Testing

# Run empirical validation tests
npm run test:validation

# Test with real API data
LIMITLESS_API_KEY=your-key npm run test:api

Contributing

We welcome contributions that maintain our scientific rigor:

Empirical validation required for new metrics
Transparent methodology in all implementations
Quality assessment for any data processing changes
Peer review process for significant algorithmic modifications

Scientific Citations

Methodology Reference

Djordjevic, B. et al. (2025). "Empirically Validated Speech Pattern Analysis 
from Naturalistic Conversation Data: A Model Context Protocol Implementation." 
GitHub: 199-biotechnologies/mcp-limitless-enhanced

Validation Dataset

Sample size: 2,500+ conversation segments
Session count: 20 naturalistic conversations
Duration range: 2-45 minutes per session
Participant demographics: Healthy adults, ages 25-65
Validation methodology: Cross-session reliability analysis

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

"Claude hit max length" message

This message comes from Claude Desktop's UI when responses are too long or the conversation context is filling up. It's NOT related to:

The MCP server functionality
Your Claude account tier (free/paid)
Limitless API limits

Solution: Start a new conversation or ask for shorter responses.

Server crashes with "Unexpected end of JSON input"

This happens when non-JSON data is sent to the server. MCP servers use JSON-RPC over stdio, not HTTP.

Common mistake: Trying to connect with HTTP clients, browsers, or curl. Solution: Use Claude Desktop or a proper MCP client.

Cannot connect via HTTP/Browser/ngrok

MCP servers are NOT HTTP servers. They communicate via JSON-RPC over stdin/stdout.

Wrong: curl http://localhost:8008 Right: Configure in Claude Desktop's MCP settings

No data returned from queries

As of March 2025, the Limitless API primarily surfaces data from the Limitless Pendant. Ensure:

Your Pendant is actively recording
You have recent conversation data
Your API key has proper permissions

Understanding MCP Servers

What MCP servers ARE:

JSON-RPC services that communicate over stdio
Designed for Claude Desktop and MCP-compatible clients
Tools that extend AI assistant capabilities

What MCP servers are NOT:

HTTP/REST APIs
Web servers
Browser-accessible services
Standalone applications with UIs

If you need HTTP access to Limitless data:

Use the Limitless API directly
Create a separate HTTP wrapper service
Use the official Limitless web interface

Support

Issues: GitHub Issues
Documentation: Scientific Documentation
Contact: [email protected]

This implementation prioritizes scientific validity over feature breadth. Every metric included has been empirically validated using real-world data.