core/integrations/README.md

CORE Integrations

Integrations connect external services to CORE's knowledge graph, automatically capturing activities and context to build your persistent memory layer.

Available Integrations

🐙 GitHub

Tracks your GitHub activities and notifications, including PRs, issues, comments, and repository events.

Features:

• Pull request creation, comments, and reviews
• Issue tracking and assignments
• Notification processing (mentions, reviews, assignments)
• Repository watching and subscriptions
• Team mentions and state changes

📐 Linear

Project management and issue tracking integration.

Features:

• Issue creation and updates
• Project milestone tracking
• Team assignments and workflows

💬 Slack

Workspace communication and activity tracking.

Features:

• Channel message monitoring
• Direct message tracking
• Thread participation

How Integrations Work

1. Authentication: OAuth2 setup with service-specific scopes
2. Data Collection: Either scheduled sync (every 5 minutes) or real-time webhooks when supported
3. Event Processing: Converting activities into structured events
4. Entity Extraction: Identifying users, projects, repositories, etc.
5. Knowledge Graph Ingestion: Creating episodes and relationships in CORE

Common Features

🔄 Data Collection Methods

• Scheduled Sync: Periodic API polling (every 5 minutes) for services like GitHub and Linear
• Real-time Webhooks: Instant event delivery for services that support personal webhooks (like Slack)
• Incremental Updates: Only fetch new activities since last sync
• Deduplication: Prevent duplicate events from being processed
• Rate Limiting: Respect API limits with intelligent backoff
• Error Handling: Graceful degradation on service outages

📊 Activity Tracking

• User Actions: What you created, commented, or modified
• Mentions: When others reference you in discussions
• Assignments: Tasks or issues assigned to you
• State Changes: Status updates on projects you follow

🧠 Knowledge Graph Integration

• Entities: People, projects, repositories, issues, organizations
• Relationships: Created, commented, assigned, mentioned, collaborated
• Temporal Context: When events occurred and their sequence
• Cross-Integration Links: Connections between different services

Event Format

All integrations generate events in a consistent format for knowledge graph ingestion:

{
  text: "{actor} {action} {object} in {context}: {details}",
  sourceURL: "https://service.com/link/to/event",
  timestamp: "2025-01-20T10:30:00Z",
  integration: "github" | "linear" | "slack"
}

Example Events

john_doe created PR #123 in facebook/react: Fix memory leak in hooks
alice_smith mentioned manoj_k in linear/project issue #456: Can you review?
team mentioned manoj_k's team in slack/engineering: Weekly standup reminder

Configuration

Each integration requires:

1. OAuth Setup: Service-specific authentication
2. Scope Configuration: Permissions for data access
3. Sync Schedule: How frequently to check for updates
4. Filtering Rules: What events to include/exclude

Development Guide

Adding New Integrations

1. Create Integration Directory

   mkdir integrations/{service-name}
   cd integrations/{service-name}
   

2. Required Files

   src/
   ├── index.ts          # Main entry point
   ├── schedule.ts       # Sync logic and event processing
   ├── utils.ts          # API utilities
   ├── account-create.ts # Authentication setup
   └── README.md         # Integration documentation
   

3. Core Implementation

   • Extend IntegrationCLI class
   • Implement OAuth2 authentication
   • Define sync schedule and event processing
   • Handle API rate limits and errors

4. Event Processing

   • Convert service events to standard format
   • Extract entities and relationships
   • Ensure consistent naming and structure
   • Add deduplication logic