GitHub Projects Integration

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 DEFAULT_PROJECT_NUMBER="1"  # Optional: Auto-add created issues to this project

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:

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Click "Generate new token (classic)"
Select scopes: repo and project (includes read:project)
Generate and copy the token
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: "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 (v1.2.0)
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

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

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:

User-level projects - Personal projects
Repository-level projects - Projects linked to a specific repo
Organization-level projects - Organization-wide projects

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

Advanced Features (Available Now in v1.2.0)

All advanced GitHub Projects features are already available! See:

Advanced GitHub Projects - Cross-project analytics, milestone tracking, status summaries
Organization Support - Full org-level project integration

Future Roadmap

GitHub Actions Integration - Workflow run tracking and CI status in context (in development)
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
GraphQL API - More efficient project queries
Smart Recommendations - Suggest project links based on content
Multi-Repository - Track work across multiple repos in same project

GitHub Projects Integration

GitHub Projects Integration Guide

Overview

Features

🔍 Automatic Project Detection

📋 Active Work Items

🔗 Entry-Project Linking

🔎 Project-Based Search

📋 Kanban Board Integration (v3.0.0+)

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

Kanban Board Usage (v3.0.0+)

View a Kanban Board

Move Items on the Board

Token Scope Requirements

Multi-Level Project Discovery

Advanced Features (Available Now in v1.2.0)

Future Roadmap

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!