Skip to content

GitHub Projects Integration

Jump to bottom
Chris & Mike edited this page Mar 27, 2026 · 17 revisions

GitHub Projects Integration Guide

Added in v1.2.0

Overview

Memory Journal integrates with GitHub Projects to provide AI with project-level context beyond individual repository state. This enables AI to understand:

  • What projects you're working on across multiple repositories
  • What project items (issues, PRs) are currently active
  • Project milestones and sprint goals
  • Team coordination through organization-level projects

Why This Matters for AI: GitHub Projects represent high-level work organization. By connecting journal entries to projects, AI understands not just what code you're writing, but what business goals you're working toward.

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

📋 Kanban Board Integration (v3.0.0+)

View and manage GitHub Projects v2 as Kanban boards:

  • get_kanban_board - View project items grouped by Status columns
  • move_kanban_item - Move items between Status columns
  • memory://kanban/{n} - Access Kanban data as MCP resource
  • memory://kanban/{n}/diagram - Mermaid visualization of the board

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"
export PROJECT_REGISTRY='{"my-repo":{"path":"/app/repo","project_number":1}}'  # Optional: Auto-routes issues and Kanban boards

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
  • read:project or project - Access to GitHub Projects v2 (GraphQL API)

Create a Token:

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click "Generate new token (classic)"
  3. Select scopes: repo and project (includes read:project)
  4. Generate and copy the token
  5. Set as environment variable

Important: GitHub Projects v2 uses GraphQL API. The old REST API endpoints have been deprecated (return HTTP 410). Ensure your token has read:project or project scope.

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 initial implementation of GitHub Projects integration (v1.2.0)",
  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: "bug_fix",
  tags: ["bug-fix"],
  project_number: 1,
});

Quick Entry with Project

Note: create_entry_minimal only accepts content. To link an entry to a project, use create_entry:

create_entry({
  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_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 (v1.2.0)
project_number INTEGER,        -- GitHub Project number
project_owner TEXT,            -- GitHub Project owner (user or org)

Indexes:

CREATE INDEX idx_memory_journal_project ON memory_journal(project_number);

Migration:

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

API Integration

GitHub GraphQL API (Projects v2)

Memory Journal uses the GitHub GraphQL API for all Projects v2 operations. The legacy REST API v3 endpoints for GitHub Projects have been deprecated by GitHub (return HTTP 410).

Authentication:

{
  "Accept": "application/vnd.github+json",
  "Authorization": "Bearer YOUR_TOKEN"
}

Required Token Scopes:

  • repo - Repository access
  • read:project or project - GitHub Projects v2 access

Note

All GitHub Projects v2 queries use GraphQL. See GitHub's Projects v2 API documentation for details.

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:

  1. Error is logged to stderr
  2. Context includes error message
  3. Entry creation continues normally
  4. 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:

  1. Not in a Git repository
  2. Remote URL doesn't point to GitHub
  3. User has no GitHub Projects
  4. 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:

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

Permission Errors

Symptom: API returns 403 or 404 errors

Solutions:

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

Slow Performance

Symptom: Entry creation takes longer than expected

Solutions:

  1. GitHub API calls timeout after 5 seconds (no indefinite waiting)
  2. Disable auto_context if not needed: auto_context: false
  3. 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: "feature_implementation",
  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,
});

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

Kanban Board Usage (v3.0.0+)

GitHub Projects v2 can be accessed as Kanban boards using dedicated tools and resources.

View a Kanban Board

Using the Tool:

get_kanban_board({ project_number: 5 });

Using the Resource:

memory://kanban/5

Using the Diagram Resource:

memory://kanban/5/diagram

Returns a Mermaid diagram for visualization:

flowchart LR
    subgraph Backlog["📋 Backlog (3)"]
        B1["Research OAuth flows"]
        B2["Update dependencies"]
    end
    subgraph InProgress["🔄 In Progress (2)"]
        I1["Implement Kanban support"]
    end
    subgraph Done["✅ Done (5)"]
        D1["Add backup tools"]
    end
Loading

Move Items on the Board

// Move an item to "Done"
move_kanban_item({
  project_number: 5,
  item_id: "PVTI_lADOA...", // From get_kanban_board response
  target_status: "Done",
});

Token Scope Requirements

Kanban tools require the project scope:

  • project - Required for reading and modifying Projects v2

Multi-Level Project Discovery

The Kanban tools automatically search for projects at multiple levels:

  1. User-level projects - Personal projects
  2. Repository-level projects - Projects linked to a specific repo
  3. Organization-level projects - Organization-wide projects

This ensures the tool finds your project regardless of how it's configured.

Advanced Features

All advanced GitHub Projects features are available. See:

Future Roadmap

  • 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
  • Smart Recommendations - Suggest project links based on content
  • Multi-Repository - Track work across multiple repos in same project

Already Shipped:

  • ✅ GitHub Actions Integration - Workflow run tracking and CI status (shipped in v2.1.0)
  • ✅ GraphQL API - Used for all Projects v2 operations

Related Documentation

References

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally