GitHub Projects Integration

GitHub Projects Integration Guide

Added in v1.2.0 (Phase 1)

Overview

Memory Journal MCP now seamlessly integrates with GitHub Projects, automatically detecting and linking your journal entries to your active GitHub Projects. This enhances context awareness and helps you track work across projects more effectively.

Features

🔍 Automatic Project Detection

When you create a journal entry with auto_context enabled (default), Memory Journal automatically:

Extracts the repository owner from your Git remote URL
Queries GitHub Projects API for projects associated with that owner
Includes project information in the context bundle

📋 Active Work Items

The context bundle includes active items from your GitHub Projects:

Item titles and types (issue/PR)
Status fields
Priority information
Direct links to items

🔗 Entry-Project Linking

Associate journal entries with specific GitHub Projects and project items:

Manual linking - Explicitly specify project number and item ID
Automatic linking - Auto-populate from context if available
Backward compatible - All project fields are optional and nullable

🔎 Project-Based Search

Filter journal entries by project:

search_entries - Full-text search with project filtering
search_by_date_range - Date range queries with project filter
get_entry_by_id - Retrieve entries with full project information

Configuration

Authentication

GitHub Projects integration supports multiple authentication methods:

Option 1: GitHub Personal Access Token (Recommended)

Set the GITHUB_TOKEN environment variable:

Linux/macOS:

export GITHUB_TOKEN="ghp_your_token_here"

Windows PowerShell:

$env:GITHUB_TOKEN="ghp_your_token_here"

Windows Command Prompt:

set GITHUB_TOKEN=ghp_your_token_here

Required Scopes:

repo - Access to repositories
project - Access to GitHub Projects (read)

Create a Token:

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Click "Generate new token (classic)"
Select scopes: repo and project
Generate and copy the token
Set as environment variable

Option 2: GitHub CLI Fallback

If GITHUB_TOKEN is not available, Memory Journal will attempt to use GitHub CLI (gh):

# Authenticate with gh CLI
gh auth login

# Verify authentication
gh auth status

Option 3: No Authentication (Graceful Degradation)

Memory Journal works perfectly without GitHub authentication:

Project detection features are disabled
All other functionality remains available
No errors or warnings

Usage

Creating Entries with Project Links

Automatic Project Detection

Create an entry with automatic context capture:

create_entry({
  content: "Completed Phase 1 implementation of GitHub Projects integration",
  entry_type: "technical_achievement",
  tags: ["github-projects", "integration"],
  auto_context: true  // Default - includes GitHub Projects info
})

Result: Entry automatically linked to the first (most recent) GitHub Project found in context.

Manual Project Linking

Explicitly specify project information:

create_entry({
  content: "Working on issue #42 in memory-journal-mcp project",
  entry_type: "development_note",
  tags: ["bug-fix"],
  project_number: 1,
  project_item_id: 12345,
  github_project_url: "https://github.com/users/username/projects/1"
})

Minimal Entry with Project

create_entry_minimal({
  content: "Quick note about project progress",
  project_number: 1
})

Searching by Project

Full-Text Search with Project Filter

search_entries({
  query: "authentication",
  project_number: 1,
  limit: 10
})

Date Range with Project Filter

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  project_number: 1,
  tags: ["milestone"]
})

Retrieve Entry with Project Info

get_entry_by_id({
  entry_id: 42,
  include_relationships: true
})

Response includes:

{
  "id": 42,
  "content": "...",
  "project_number": 1,
  "project_item_id": 12345,
  "github_project_url": "https://github.com/users/username/projects/1",
  "project_context": {
    "github_projects": {
      "github_projects": [
        {
          "number": 1,
          "name": "memory-journal-mcp",
          "url": "https://github.com/users/username/projects/1"
        }
      ]
    }
  }
}

Context Bundle Structure

When auto_context is enabled, the context bundle includes GitHub Projects information:

{
  "repo_name": "memory-journal-mcp",
  "repo_path": "/path/to/repo",
  "branch": "main",
  "last_commit": {
    "hash": "abc12345",
    "message": "Add GitHub Projects integration"
  },
  "github_projects": {
    "github_projects": [
      {
        "number": 1,
        "name": "memory-journal-mcp",
        "description": "Development roadmap for memory journal",
        "url": "https://github.com/users/neverinfamous/projects/1",
        "state": "OPEN",
        "created_at": "2025-09-15T10:30:00Z",
        "updated_at": "2025-10-25T14:20:00Z"
      }
    ],
    "active_items": [
      {
        "id": 12345,
        "content_type": "Issue",
        "title": "GitHub Projects Integration",
        "status": "In Progress",
        "created_at": "2025-10-01T09:00:00Z",
        "updated_at": "2025-10-25T15:00:00Z"
      }
    ]
  },
  "cwd": "/path/to/repo",
  "timestamp": "2025-10-26T12:00:00Z"
}

Database Schema

GitHub Projects integration adds three new columns to the memory_journal table:

-- GitHub Projects integration (Phase 1)
project_number INTEGER,        -- GitHub Project number
project_item_id INTEGER,       -- GitHub Project item ID  
github_project_url TEXT,       -- Full URL to GitHub Project

Indexes:

CREATE INDEX idx_memory_journal_project_number ON memory_journal(project_number);
CREATE INDEX idx_memory_journal_project_item_id ON memory_journal(project_item_id);

Migration:

Automatic migration on server startup
Backward compatible with existing databases
All fields are nullable (no breaking changes)

API Integration

GitHub REST API

Memory Journal uses the GitHub REST API v3 with these endpoints:

User Projects:

GET /users/{username}/projects

Project Details:

GET /users/{username}/projects/{project_number}

Project Items:

GET /users/{username}/projects/{project_number}/items

Headers:

{
  "Accept": "application/vnd.github+json",
  "X-GitHub-Api-Version": "2022-11-28",
  "Authorization": "token YOUR_TOKEN"
}

GitHub CLI Fallback

When GitHub API is unavailable, Memory Journal uses gh CLI commands:

# List projects
gh project list --owner username --format json

# List project items
gh project item-list PROJECT_NUMBER --owner username --format json --limit 5

Error Handling

Timeout Protection

All GitHub API calls have aggressive timeouts:

API requests: 5 seconds
CLI commands: 5 seconds
Git operations: 2 seconds

Timeouts prevent blocking and ensure fast response times.

Rate Limiting

Memory Journal respects GitHub API rate limits:

Authenticated: 5,000 requests/hour
Unauthenticated: 60 requests/hour

Graceful Degradation

If GitHub Projects features fail:

Error is logged to stderr
Context includes error message
Entry creation continues normally
No data loss or corruption

Example error in context:

{
  "github_projects_error": "GitHub Projects error: Authentication required"
}

Troubleshooting

No Projects Detected

Symptom: Context doesn't include GitHub Projects information

Possible causes:

Not in a Git repository
Remote URL doesn't point to GitHub
User has no GitHub Projects
Authentication failed

Solutions:

# Verify Git remote
git remote -v

# Check authentication
gh auth status

# Verify GITHUB_TOKEN
echo $GITHUB_TOKEN  # Linux/macOS
echo $env:GITHUB_TOKEN  # Windows PowerShell

API Rate Limiting

Symptom: github_projects_error mentions rate limiting

Solutions:

Use Personal Access Token (higher rate limit)
Wait for rate limit reset
Reduce frequency of operations

Permission Errors

Symptom: API returns 403 or 404 errors

Solutions:

Verify token has repo and project scopes
Check if projects are public/private
Ensure correct repository owner

Slow Performance

Symptom: Entry creation takes longer than expected

Solutions:

GitHub API calls timeout after 5 seconds (no indefinite waiting)
Disable auto_context if not needed: auto_context: false
Use create_entry_minimal for faster entries

Best Practices

1. Use Auto-Context for Development Work

Enable automatic project detection for development-related entries:

create_entry({
  content: "Implemented feature X",
  entry_type: "development_note",
  tags: ["feature-x"],
  auto_context: true  // Captures GitHub Projects info
})

2. Manual Linking for Specific Items

Explicitly link entries to specific project items:

create_entry({
  content: "Closed issue #42",
  tags: ["bug-fix"],
  project_number: 1,
  project_item_id: 42
})

3. Project-Based Retrospectives

Filter entries by project for sprint retrospectives:

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  project_number: 1
})

4. Organize Multi-Project Work

Use project filtering to track work across multiple projects:

// Project 1 entries
search_entries({ project_number: 1, limit: 5 })

// Project 2 entries  
search_entries({ project_number: 2, limit: 5 })

5. Graceful Degradation

Don't rely on GitHub Projects features exclusively:

Use tags for backup categorization
Include project names in content
Leverage entry_type for classification

Security Considerations

Token Storage

✅ DO:

Store token in environment variable
Use .env files (add to .gitignore)
Rotate tokens regularly
Use minimum required scopes

❌ DON'T:

Hard-code tokens in code
Commit tokens to repositories
Share tokens between users
Use tokens with excessive permissions

Token Scopes

Minimum required scopes for GitHub Projects integration:

repo - Repository access (read-only sufficient)
project - Project access (read-only sufficient)

Network Security

All API calls use HTTPS
Timeout protection prevents hanging connections
No sensitive data in API requests
Error messages sanitized

Roadmap

Phase 2 (Planned)

Organization Projects - Support for org-level projects
Advanced Filtering - Filter by project status, priority, assignee
Bidirectional Sync - Update project items from journal entries
Project Webhooks - Real-time updates from GitHub
Custom Fields - Support for project custom fields

GitHub Projects Integration

GitHub Projects Integration Guide

Overview

Features

🔍 Automatic Project Detection

📋 Active Work Items

🔗 Entry-Project Linking

🔎 Project-Based Search

Configuration

Authentication

Option 1: GitHub Personal Access Token (Recommended)

Option 2: GitHub CLI Fallback

Option 3: No Authentication (Graceful Degradation)

Usage

Creating Entries with Project Links

Automatic Project Detection

Manual Project Linking

Minimal Entry with Project

Searching by Project

Full-Text Search with Project Filter

Date Range with Project Filter

Retrieve Entry with Project Info

Context Bundle Structure

Database Schema

API Integration

GitHub REST API

GitHub CLI Fallback

Error Handling

Timeout Protection

Rate Limiting

Graceful Degradation

Troubleshooting

No Projects Detected

API Rate Limiting

Permission Errors

Slow Performance

Best Practices

1. Use Auto-Context for Development Work

2. Manual Linking for Specific Items

3. Project-Based Retrospectives

4. Organize Multi-Project Work

5. Graceful Degradation

Security Considerations

Token Storage

Token Scopes

Network Security

Roadmap

Phase 2 (Planned)

Phase 3 (Planned)

Related Documentation

References

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!