Advanced Projects

Advanced GitHub Projects Integration

Overview

Advanced GitHub Projects features include analytics, status tracking, and intelligent caching - enabling AI to understand cross-project patterns and productivity trends.

Why This Matters for AI Context: When working on multiple projects simultaneously, AI needs to understand not just individual project state, but how your time and attention is distributed across projects. These advanced analytics provide this meta-context.

✨ Key Features

1. Cross-Project Insights

Analyze patterns across all tracked GitHub Projects in your journal.

Tool: get_cross_project_insights

Parameters:

• start_date (optional): Start date filter (YYYY-MM-DD)
• end_date (optional): End date filter (YYYY-MM-DD)
• min_entries (optional): Minimum entries to include project (default: 3)

Returns:

• Active projects ranked by entry count
• Time distribution percentages
• Most productive day per project
• Top tags per project
• Inactive projects (>7 days since last entry)

Example:

get_cross_project_insights({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  min_entries: 3,
});

2. Project Breakdown in Statistics

Enhanced get_statistics tool with project-level analytics.

New Parameter:

• project_breakdown (boolean): Include per-project statistics (default: false)

Additional Data:

• Entries per project
• Active days per project

Enhanced Analytics:

• decisionDensity: Significant entries per period
• relationshipComplexity: Avg relationships per entry
• activityTrend: Period-over-period growth %
• causalMetrics: blocked_by / resolved / caused counts

Example:

get_statistics({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  group_by: "week",
  project_breakdown: true,
});

3. Project Status Summary (Prompt)

Generate comprehensive status reports for specific GitHub Projects.

Prompt: project-status-summary

Parameters:

• project_number (required): GitHub Project number

Output Includes:

• Project overview (name, description, status, URL)
• Journal activity statistics
• Recent journal entries (up to 20)
• Key insights and next steps

Example:

project-status-summary({
  project_number: 1
})

4. Milestone Tracking (Prompt)

Track GitHub milestones with velocity analysis.

Prompt: project-milestone-tracker

Parameters:

• project_number (required): GitHub Project number

Output Includes:

• Significant milestone entries for the project
• Progress summary and timeline
• Upcoming milestones

Example:

project-milestone-tracker({
  project_number: 1
})

5. Project Timeline Resource

Live activity feed combining journal entries and GitHub Project events.

Resource URI: memory://projects/{identifier}/timeline

Discovering Resources: Call ListMcpResources() to discover available resources. Cursor prefixes server names with user- (e.g., user-memory-journal-mcp).

Three access formats:

// After listing resources and getting exact server identifier:
memory://projects/1/timeline                    // By project number
memory://projects/memory-journal-mcp/timeline   // By project name (current name from GitHub)
memory://projects/neverinfamous/user/1/timeline // By owner/type/number

Note: Project names are looked up from the current GitHub context. Old journal entries may contain historical project names in their stored context, but the resource always uses the current project name.

Returns:

• Chronological Markdown timeline
• Last 30 days of activity
• Journal entries with timestamps
• GitHub Project item updates
• Grouped by date with event type indicators

🚀 Smart Caching System

Advanced GitHub Projects integration includes intelligent caching to reduce GitHub API calls by 80%+.

Cache TTLs

• Project metadata: 1 hour (3600 seconds)
• Project items: 15 minutes (900 seconds)
• Milestones: 1 hour (3600 seconds)

Cache Storage

Cached data is stored in an in-memory Map<string, CacheEntry> with TTL-based expiration inside GitHubIntegration.ts. The cache is cleared automatically when the server restarts or when mutation methods invalidate related keys.

Cache Keys

• project_details:{username}:{project_number}
• milestones:{owner}:{repo}
• project_items_full:{username}:{project_number}:{limit}

📊 Use Cases

Weekly Project Review

// Get cross-project insights
get_cross_project_insights({
  start_date: "2025-10-20",
  end_date: "2025-10-27",
  min_entries: 2,
});

// Deep dive into active project
// Use prompt: /project-status-summary
// project_number: 1

Sprint Retrospective

// Analyze sprint velocity
// Use prompt: /project-milestone-tracker
// project_number: 1

// Review project statistics
get_statistics({
  start_date: "2025-10-14",
  end_date: "2025-10-27",
  group_by: "week",
  project_breakdown: true,
});

Quarterly Review

// Quarter-long insights
get_cross_project_insights({
  start_date: "2025-07-01",
  end_date: "2025-09-30",
  min_entries: 5
})

// Access project timelines (by number or name)
memory://projects/1/timeline
memory://projects/memory-journal-mcp/timeline

🔧 Configuration

GitHub Token Setup

For full advanced projects functionality, set the GITHUB_TOKEN environment variable:

# Linux/macOS
export GITHUB_TOKEN="your_github_personal_access_token"

# Windows PowerShell
$env:GITHUB_TOKEN="your_github_personal_access_token"

Required Scopes:

• repo - Repository access
• project - GitHub Projects access

Fallback Options

• Works with GitHub CLI (gh) if token not available
• Graceful degradation without token (limited features)

📈 Performance

API Call Reduction

• Before caching: ~10-15 API calls per status summary
• After caching: ~2-3 API calls per status summary
• Cache hit rate: Typically 75-85% in active use

Startup Time

• No impact on startup (lazy loading)
• Caching infrastructure adds <50ms to first query

🔗 Related Documentation

• GitHub Projects Integration
• Tools Reference
• Prompts Guide
• Architecture

📝 Changelog

See the canonical CHANGELOG for version history.