mirror of
https://github.com/eliasstepanik/core.git
synced 2026-01-11 17:18:28 +00:00
136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# 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](./github/README.md)
|
|
|
|
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](./linear/README.md)
|
|
|
|
Project management and issue tracking integration.
|
|
|
|
**Features:**
|
|
|
|
- Issue creation and updates
|
|
- Project milestone tracking
|
|
- Team assignments and workflows
|
|
|
|
### 💬 [Slack](./slack/README.md)
|
|
|
|
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:
|
|
|
|
```typescript
|
|
{
|
|
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**
|
|
|
|
```bash
|
|
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
|