Skip to content

Organization Support

Jump to bottom
Chris & Mike edited this page Mar 6, 2026 · 12 revisions

Organization Support

Status: ✅ Production/Stable

Overview

Organization support extends Memory Journal with organization-level GitHub Projects, enabling AI context management for team collaboration and enterprise development.

Why This Matters for Teams: In team environments, project context is often fragmented across multiple developers' work. Organization-level integration enables:

  • Shared project memory across team members
  • Cross-developer context understanding what teammates are working on
  • Enterprise visibility for project managers overseeing multiple teams

All advanced GitHub Projects features work seamlessly with both user and organization projects.

🏢 Key Features

Automatic Owner Detection

  • Detects whether repository belongs to a user or organization
  • Uses GitHub API GET /users/{owner} to determine owner type
  • Caches owner type for 24 hours (rarely changes)
  • Gracefully falls back to 'user' if detection fails

Dual Project Lookup

  • Queries both user AND organization projects automatically
  • Prioritizes org projects for org repos, user projects for personal repos
  • Returns structured context with separate user_projects and org_projects arrays
  • Leverages advanced smart caching (1hr TTL for projects)

Organization Project Analytics

  • All advanced features work identically for org projects:
    • Cross-Project Insights - Analyze patterns across user + org projects
    • Status Summaries - Comprehensive reports for org project teams
    • Milestone Tracking - Track org-level milestones and team velocity
    • Project Timelines - Combined journal + GitHub activity feeds
  • Smart caching reduces API calls by 80%+ (same as user projects)

Single Token, Automatic Detection

  • Uses your standard GITHUB_TOKEN for both user and org project access
  • Automatically detects owner type (user vs organization) via the GitHub API
  • No separate token needed — just ensure your token has org-level scopes if accessing org projects

🔧 Configuration

Environment Variables

# Linux/macOS
export GITHUB_TOKEN="your_personal_token"           # Required for all GitHub features

# Windows PowerShell
$env:GITHUB_TOKEN="your_personal_token"

Required GitHub Token Scopes

Scope Purpose
repo Repository access
project User and organization project access
read:org Organization membership and org project access
admin:org Team information and advanced org features

MCP Configuration Example

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Docker Configuration Example

docker run --rm -i \
  -v ./data:/app/data \
  -e GITHUB_TOKEN=ghp_your_token \
  writenotenow/memory-journal-mcp:latest

📖 Usage Examples

Create Entry with Explicit Org Project

create_entry({
  content:
    "Sprint planning meeting - discussed Q4 roadmap and feature priorities",
  entry_type: "planning",
  tags: ["sprint-planning", "Q4", "team-meeting"],
  project_number: 5,
  project_owner: "my-company",
});

Auto-Detect Works for Org Repos

// Owner type is automatically detected from repo context
create_entry({
  content: "Fixed critical authentication bug in user service",
  entry_type: "bug_fix",
  tags: ["auth", "security", "critical"],
  project_number: 5, // Owner and type auto-detected
});
// Context automatically includes org project info

Org Project Status Summary

// Explicit org specification
// Use prompt: /project-status-summary
// project_number: 5
// Returns: Org project overview, team activity, GitHub items, insights

// Auto-detect from context (recommended)
// Use prompt: /project-status-summary
// project_number: 5
// Automatically detects owner is "my-company" and type is "org"

Org Milestone Tracking

// Use prompt: /project-milestone-tracker
// project_number: 5
// Returns: Org milestone progress, team velocity, activity summary

Access Org Project Timeline

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

// Three access formats supported (after getting exact server identifier):

// 1. By project number (auto-detects user vs org)
memory://projects/5/timeline
// Auto-detects if project belongs to org and fetches accordingly

// 2. By project name (auto-detects user vs org)
memory://projects/my-org-project/timeline
// Looks up current project name from GitHub context

// 3. Explicit format (full control)
memory://projects/my-company/org/5/timeline
// Specify owner, type, and number explicitly

// Note: Project names use the current name from GitHub.
// Historical entries may have old names, but lookups use current names.

Cross-Project Insights (User + Org)

get_cross_project_insights({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  min_entries: 3,
});
// Returns: Insights across BOTH user and org projects
// - Active projects ranked by activity (user + org)
// - Time distribution across all projects
// - Productivity patterns
// - Inactive projects needing attention

Search Entries by Org Project

// Works identically to user projects
search_entries({
  query: "authentication",
  project_number: 5, // Org project
  limit: 10,
});

// Filter by date range + org project
search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  project_number: 5,
  tags: ["security"],
});

🔄 Auto-Detection Workflow

Step 1: Extract Repo Owner

Git remote URL → Extract owner name (e.g., "my-company")

Step 2: Detect Owner Type

GitHub API: GET /users/my-company
Response: {"type": "Organization"}
Result: owner_type = "org"
Cache for 24 hours

Step 3: Dual Project Lookup

Query user projects: GET /users/my-company/projects
Query org projects:  GET /orgs/my-company/projects
Combine and prioritize based on owner type

Step 4: Context Bundle

{
  "github_projects": {
    "user_projects": [...],
    "org_projects": [
      {
        "number": 5,
        "name": "Q4 Sprint Planning",
        "source": "org",
        "owner": "my-company"
      }
    ]
  }
}

📊 Context Structure (Organization Support)

Before Organization Support

{
  "github_projects": [{ "number": 1, "name": "Project A" }]
}

With Organization Support (Backward Compatible)

{
  "github_projects": {
    "user_projects": [
      {
        "number": 1,
        "name": "Personal Project",
        "source": "user",
        "owner": "username"
      }
    ],
    "org_projects": [
      {
        "number": 5,
        "name": "Team Sprint",
        "source": "org",
        "owner": "my-company"
      }
    ]
  }
}

Note: The basic format is still supported for backward compatibility. Auto-population logic handles both formats seamlessly.

🚀 Performance & Caching

Cache Strategy

Cache Key Pattern TTL Purpose
owner_type:{owner} 24 hours Owner type detection (new)
projects:org:{org} 1 hour Org project list (new)
projects:user:{user} 1 hour User project list (v1.2.0)
project_details:{org}:{number} 1 hour Project metadata
project_items_full:{org}:{number}:{limit} 15 minutes Project items
milestones:{owner}:{repo} 1 hour Repository milestones

Performance Impact

  • Owner type detection: 1 API call per owner (cached 24hr)
  • Org project lookup: 1 API call per org (cached 1hr)
  • 80%+ API reduction via smart caching
  • Zero performance degradation vs non-org workflows

Cache Hit Rates

  • Owner type: 95%+ (rarely changes)
  • Org projects: 75-85% (same as user projects)
  • Project details: 80-90%
  • Project items: 70-80%

🔒 Security & Permissions

Permission Handling

403 Forbidden Responses:

  • Gracefully degrade to public project data
  • Clear error messages in logs
  • Continue operation without breaking

Required Permissions:

  • Minimum: repo, project, read:org
  • Recommended: Add admin:org for team info

Best Practices:

  • Use separate org token with minimal required scopes
  • Rotate tokens regularly
  • Use environment variables, never hardcode tokens
  • Monitor token usage in GitHub settings

🧪 Testing Org Support

Verify Owner Detection

// Check logs for owner type detection
// Look for: "Detecting owner type for: my-company"
// Expected: "Owner type: org"

Test Dual Lookup

// Create entry in org repo
create_entry({
  content: "Testing org support",
  entry_type: "other",
});
// Check context includes both user_projects and org_projects

Verify Caching

// First call: API hit
get_cross_project_insights({...})

// Second call within 1 hour: Cache hit
get_cross_project_insights({...})
// Should be significantly faster

✅ Backward Compatibility

✅ All existing entries work unchanged
✅ Old context format still supported
✅ No database migration required
✅ No breaking API changes
✅ User-only workflows unaffected

Migration Path

No action required for existing users!

Organization support is 100% backward compatible. If you don't use organization projects:

  • Everything continues working exactly as before
  • No configuration changes needed
  • No performance impact
  • Optional features only activate when org repos detected

🐛 Troubleshooting

Org Projects Not Detected

Problem: Auto-detection not finding org projects

Solutions:

  1. Verify GITHUB_TOKEN has correct scopes (repo, project, read:org)
  2. Check repo remote URL points to org: git remote -v
  3. Confirm owner is actually an organization on GitHub
  4. Check logs for owner type detection: "Owner type: org"
  5. Try explicit owner parameters in prompts

403 Permission Errors

Problem: Getting 403 Forbidden when accessing org projects

Solutions:

  1. Add read:org scope to token
  2. Verify you're a member of the organization
  3. Check org project visibility settings
  4. Ensure your GITHUB_TOKEN has read:org scope for organization access
  5. Contact org admin to verify project access

Cache Not Working

Problem: Seeing too many API calls

Solutions:

  1. Verify database connection (caching requires database)
  2. Cache is stored in-memory (restart server to clear)
  3. Review TTL settings in GitHubIntegration
  4. Monitor cache hit rates in logs (if debug enabled)

Old Format Breaking

Problem: Legacy entries not working with organization support

Solutions:

  1. This shouldn't happen! Organization support maintains full backward compatibility
  2. If you encounter issues, please report at: https://github.com/neverinfamous/memory-journal-mcp/issues
  3. Include entry ID and error message in report

📚 Related Documentation

🔗 API Reference

MCP Tool Parameters (Organization Support)

create_entry

  • project_owner (optional) - Explicit owner name

Advanced Prompts:

  • project-status-summary - Accepts project_number; org detection is automatic
  • project-milestone-tracker - Accepts project_number; org detection is automatic

Note

Organization support is handled internally by the server. Owner type detection, project lookup, and caching are automatic — you only need to specify project_owner when auto-detection is insufficient.

🎯 Success Criteria

✅ Auto-detect org repos and query org projects
✅ Show both user and org projects in context
✅ Create entries linked to org projects
✅ Generate org project status summaries
✅ Graceful degradation with insufficient permissions
✅ Zero breaking changes for user-only workflows
✅ All advanced features work with org projects
✅ Cache performance maintained (80%+ API reduction)
✅ Full-text search works with org names (hyphens, special chars)
✅ Complete documentation for org setup

Organization Support Status: ✅ Production/Stable - Ready for enterprise use

Estimated Setup Time: 2 minutes (add org token to env)

Compatibility: 100% backward compatible with all existing features

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally