mirror of
https://github.com/eliasstepanik/core.git
synced 2026-01-11 21:38:27 +00:00
docs: add readme to integrations
This commit is contained in:
Manoj
Harshith Mullapudi
parent
6049332223
commit
92182f1428
@ -115,10 +115,12 @@ Ask questions like "What are my writing preferences?" with instant insights from
|
||||
|
||||
|
||||
|
||||
### ⚡ **Auto-Sync from Apps**:
|
||||
### ⚡ **Auto-Sync from Apps**:
|
||||
|
||||
Automatically capture relevant context from Linear, Slack, Notion, GitHub and other connected apps into your CORE memory
|
||||
|
||||
📖 **[View All Integrations](./integrations/README.md)** - Complete list of supported services and their features
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
122
integrations/README.md
Normal file
122
integrations/README.md
Normal file
@ -0,0 +1,122 @@
|
||||
# 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
|
||||
72
integrations/github/README.md
Normal file
72
integrations/github/README.md
Normal file
@ -0,0 +1,72 @@
|
||||
# GitHub Integration
|
||||
|
||||
Automatic GitHub activity tracking and notification processing for CORE memory system.
|
||||
|
||||
## Overview
|
||||
|
||||
The GitHub integration captures your GitHub activities and notifications, processes them into structured events, and ingests them into CORE's knowledge graph for intelligent memory and context building.
|
||||
|
||||
## Features
|
||||
|
||||
### 📊 Activity Tracking
|
||||
- **Pull Requests**: Created, commented, reviewed
|
||||
- **Issues**: Created, assigned, commented, self-assigned
|
||||
- **Comments**: PR comments, issue comments
|
||||
- **Repository Events**: Watching, subscribing, state changes
|
||||
|
||||
### 🔔 Notification Processing
|
||||
- **Assignments**: Issues and PRs assigned to you
|
||||
- **Reviews**: PR review requests
|
||||
- **Mentions**: @mentions in discussions
|
||||
- **Comments**: New comments on your content
|
||||
- **State Changes**: PR/issue open/close/merge events
|
||||
- **Subscriptions**: Updates on watched repositories
|
||||
- **Team Mentions**: Team @mentions
|
||||
|
||||
### 🔗 MCP Integration
|
||||
- Uses GitHub Copilot MCP server for extended functionality
|
||||
- Provides seamless integration with GitHub's AI tools
|
||||
|
||||
## Authentication
|
||||
|
||||
Uses OAuth2 with the following scopes:
|
||||
- `user` - Access user profile information
|
||||
- `public_repo` - Access public repositories
|
||||
- `repo` - Access private repositories
|
||||
- `notifications` - Read notifications
|
||||
- `gist` - Access gists
|
||||
- `read:org` - Read organization membership
|
||||
- `repo_hooks` - Manage repository webhooks
|
||||
|
||||
## Configuration
|
||||
|
||||
### Schedule
|
||||
- **Frequency**: Every 5 minutes (`*/5 * * * *`)
|
||||
- **Sync Window**: 24 hours (configurable)
|
||||
- **Rate Limiting**: Built-in GitHub API rate limit handling
|
||||
|
||||
### Data Processing
|
||||
- **Deduplication**: Filters out duplicate events using timestamps
|
||||
- **Entity Extraction**: Extracts users, repositories, PR/issue numbers
|
||||
- **Relationship Mapping**: Creates connections between entities
|
||||
- **Temporal Tracking**: Maintains event chronology
|
||||
|
||||
## Event Types
|
||||
|
||||
### User Activities
|
||||
```
|
||||
{username} created PR #{number} in {repo}: {title}
|
||||
{username} created issue #{number} in {repo}: {title}
|
||||
{username} commented on PR #{number} in {repo}: {title}
|
||||
{username} commented on issue #{number} in {repo}: {title}
|
||||
{username} assigned themselves to issue #{number} in {repo}: {title}
|
||||
```
|
||||
|
||||
### Notifications
|
||||
```
|
||||
Issue #{number} assigned to {username} in {repo}: {title}
|
||||
{actor} commented on {username}'s PR #{number} in {repo}: {body}
|
||||
{actor} mentioned {username} in {repo} issue #{number}: {body}
|
||||
{username} requested to review PR #{number} in {repo}: {title}
|
||||
{actor} changed PR #{number} state to {state} in {repo}: {title}
|
||||
```
|
||||
107
integrations/linear/README.md
Normal file
107
integrations/linear/README.md
Normal file
@ -0,0 +1,107 @@
|
||||
# Linear Integration
|
||||
|
||||
Automatic Linear activity tracking and issue management integration for CORE memory system.
|
||||
|
||||
## Overview
|
||||
|
||||
The Linear integration captures your Linear project activities, issue interactions, and team collaborations, processing them into structured events for CORE's knowledge graph to build intelligent context around your project management workflow.
|
||||
|
||||
## Features
|
||||
|
||||
### 📊 Issue Tracking
|
||||
- **Issue Creation**: Track new issues you create across projects
|
||||
- **Issue Updates**: Monitor changes to issue status, priority, and assignments
|
||||
- **Comments**: Capture comments on issues you're involved with
|
||||
- **Assignments**: Track issues assigned to you or by you
|
||||
|
||||
### 🎯 Project Management
|
||||
- **Project Milestones**: Monitor progress on project goals and deadlines
|
||||
- **Team Workflows**: Track team assignments and collaboration patterns
|
||||
- **Status Changes**: Issue state transitions (todo, in progress, done, etc.)
|
||||
- **Priority Updates**: Changes to issue priority and urgency
|
||||
|
||||
### 🔗 MCP Integration
|
||||
- Direct Linear MCP server integration at `https://mcp.linear.app/mcp`
|
||||
- Provides enhanced functionality for Linear operations
|
||||
- Seamless integration with Linear's GraphQL API
|
||||
|
||||
## Authentication
|
||||
|
||||
Uses **API Key** authentication:
|
||||
- Requires Linear Personal API Token
|
||||
- Full access to your Linear workspace data
|
||||
- Secure token-based authentication
|
||||
|
||||
## Configuration
|
||||
|
||||
### Schedule
|
||||
- **Frequency**: Every 5 minutes (`*/5 * * * *`)
|
||||
- **Sync Types**: Issues, comments, and user actions
|
||||
- **Incremental Sync**: Tracks last sync timestamps for each data type
|
||||
|
||||
### Data Processing
|
||||
- **GraphQL API**: Uses Linear's GraphQL endpoint for efficient data fetching
|
||||
- **User Context**: Fetches your user information for proper attribution
|
||||
- **Temporal Tracking**: Maintains chronological order of activities
|
||||
- **Deduplication**: Prevents duplicate event processing
|
||||
|
||||
## Event Types
|
||||
|
||||
### Issue Management
|
||||
```
|
||||
{username} created issue in {project}: {title}
|
||||
{username} updated issue #{number} in {project}: {title}
|
||||
{username} commented on issue #{number} in {project}: {comment}
|
||||
{username} assigned issue #{number} to {assignee} in {project}: {title}
|
||||
Issue #{number} status changed to {status} in {project}: {title}
|
||||
Issue #{number} priority changed to {priority} in {project}: {title}
|
||||
```
|
||||
|
||||
### Project Activities
|
||||
```
|
||||
{username} created milestone in {project}: {milestone}
|
||||
{username} completed milestone in {project}: {milestone}
|
||||
Team assignment updated for issue #{number} in {project}: {title}
|
||||
```
|
||||
|
||||
## Knowledge Graph Integration
|
||||
|
||||
Events are processed into CORE's knowledge graph with:
|
||||
- **Entities**: Users, projects, issues, milestones, teams
|
||||
- **Relationships**: Created, assigned, commented, completed, collaborated
|
||||
- **Attributes**: Issue numbers, status, priority, timestamps
|
||||
- **Context**: Project associations, team memberships, workflow stages
|
||||
|
||||
## Sync Management
|
||||
|
||||
The integration maintains separate sync timestamps for:
|
||||
- **Issues**: `lastIssuesSync` - New and updated issues
|
||||
- **Comments**: `lastCommentsSync` - Comment activity
|
||||
- **User Actions**: `lastUserActionsSync` - Specific user-initiated activities
|
||||
|
||||
This ensures comprehensive coverage without missing activities across different Linear data types.
|
||||
|
||||
## Rate Limits & Performance
|
||||
|
||||
- **GraphQL Efficiency**: Single requests fetch related data
|
||||
- **Pagination Support**: Handles large datasets with cursor-based pagination
|
||||
- **API Rate Limits**: Respects Linear's API limits with intelligent backoff
|
||||
- **Error Handling**: Graceful degradation on API failures
|
||||
- **Incremental Updates**: Only fetches changes since last sync
|
||||
|
||||
## Usage
|
||||
|
||||
The integration runs automatically once configured with your Linear API key:
|
||||
|
||||
1. **Fetch User Context**: Get your Linear user information
|
||||
2. **Query Recent Activities**: Fetch issues, comments, and actions since last sync
|
||||
3. **Process Events**: Convert Linear data into standardized event format
|
||||
4. **Extract Entities**: Identify users, projects, issues, and relationships
|
||||
5. **Create Episodes**: Generate memory episodes for knowledge graph ingestion
|
||||
6. **Update Sync State**: Save timestamps for next incremental sync
|
||||
|
||||
## API Reference
|
||||
|
||||
- **Linear GraphQL API**: https://developers.linear.app/docs/graphql/working-with-the-graphql-api
|
||||
- **Authentication**: https://developers.linear.app/docs/graphql/working-with-the-graphql-api#authentication
|
||||
- **Rate Limiting**: https://developers.linear.app/docs/graphql/working-with-the-graphql-api#rate-limiting
|
||||
144
integrations/slack/README.md
Normal file
144
integrations/slack/README.md
Normal file
@ -0,0 +1,144 @@
|
||||
# Slack Integration
|
||||
|
||||
Real-time Slack workspace activity tracking via webhooks for CORE memory system.
|
||||
|
||||
## Overview
|
||||
|
||||
The Slack integration captures your workspace communications, reactions, and collaborations through real-time webhooks and API access, creating a comprehensive memory layer of your team interactions and project discussions.
|
||||
|
||||
## Features
|
||||
|
||||
### 💬 Message Tracking
|
||||
- **Channel Messages**: Monitor messages in channels you're active in
|
||||
- **Direct Messages**: Track DM conversations and threads
|
||||
- **Thread Participation**: Capture threaded discussions and replies
|
||||
- **Mentions**: Track when you're @mentioned in conversations
|
||||
|
||||
### 🎯 Team Collaboration
|
||||
- **Reactions**: Track emoji reactions on messages
|
||||
- **Stars**: Monitor starred messages and important content
|
||||
- **Channel Management**: Track channel joins, leaves, and participation
|
||||
- **Team Interactions**: Capture cross-team communication patterns
|
||||
|
||||
### 🔗 MCP Integration
|
||||
- **Stdio MCP Server**: Uses dedicated Slack MCP server for enhanced functionality
|
||||
- **Message Tools**: Supports message creation and interaction tools
|
||||
- **Real-time Events**: Webhook-based instant event delivery
|
||||
|
||||
## Authentication
|
||||
|
||||
Uses **OAuth2** with comprehensive scopes:
|
||||
- `stars:read` & `stars:write` - Access starred content
|
||||
- `team:read` & `users:read` - Team and user information
|
||||
- `channels:read` & `channels:history` - Public channel access
|
||||
- `groups:read` - Private channel access (if member)
|
||||
- `im:read` & `im:history` - Direct message access
|
||||
- `mpim:read`, `mpim:write` & `mpim:history` - Multi-party DM access
|
||||
- `chat:write` - Message sending capabilities
|
||||
- `reactions:read` & `reactions:write` - Reaction access
|
||||
- `users.profile:read` - User profile information
|
||||
|
||||
## Configuration
|
||||
|
||||
### Data Collection Method
|
||||
- **Real-time Webhooks**: Instant event delivery (unlike scheduled sync)
|
||||
- **Event Streaming**: Continuous monitoring of workspace activity
|
||||
- **Context-aware**: Captures conversation context and threading
|
||||
- **User-scoped**: Only accesses data you have permission to see
|
||||
|
||||
### MCP Server Setup
|
||||
```json
|
||||
{
|
||||
"type": "stdio",
|
||||
"url": "https://integrations.heysol.ai/slack/mcp/slack-mcp-server",
|
||||
"env": {
|
||||
"SLACK_MCP_XOXP_TOKEN": "${config:access_token}",
|
||||
"SLACK_MCP_ADD_MESSAGE_TOOL": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Event Types
|
||||
|
||||
### Message Activities
|
||||
```
|
||||
{username} sent message in #{channel}: {message}
|
||||
{username} replied to thread in #{channel}: {reply}
|
||||
{username} sent DM to {recipient}: {message}
|
||||
{username} mentioned {target} in #{channel}: {message}
|
||||
```
|
||||
|
||||
### Interaction Events
|
||||
```
|
||||
{username} reacted with :{emoji}: to message in #{channel}
|
||||
{username} starred message in #{channel}: {message}
|
||||
{username} joined channel #{channel}
|
||||
{username} left channel #{channel}
|
||||
```
|
||||
|
||||
### Team Collaboration
|
||||
```
|
||||
{username} created channel #{channel}
|
||||
{username} archived channel #{channel}
|
||||
{username} updated channel #{channel} topic: {topic}
|
||||
Team discussion started in #{channel} about {topic}
|
||||
```
|
||||
|
||||
|
||||
## Webhook Event Processing
|
||||
|
||||
The integration processes various Slack webhook events:
|
||||
- **Message Events**: New messages, edits, deletions
|
||||
- **Reaction Events**: Emoji reactions added/removed
|
||||
- **Channel Events**: Channel creation, archiving, topic changes
|
||||
- **User Events**: Joins, leaves, status changes
|
||||
- **Thread Events**: Threaded conversation activity
|
||||
|
||||
### Event Processing Flow
|
||||
1. **Webhook Receipt**: Real-time event from Slack
|
||||
2. **Event Validation**: Verify event authenticity and permissions
|
||||
3. **Context Enrichment**: Fetch additional message/user/channel context
|
||||
4. **Activity Creation**: Generate structured activity event
|
||||
5. **Knowledge Graph**: Send to CORE for entity extraction
|
||||
|
||||
## Knowledge Graph Integration
|
||||
|
||||
Events create rich relationships in CORE's knowledge graph:
|
||||
- **Entities**: Users, channels, messages, teams, workspaces
|
||||
- **Relationships**: Sent, replied, mentioned, reacted, joined, starred
|
||||
- **Attributes**: Timestamps, message content, reaction types, channel topics
|
||||
- **Context**: Workspace culture, team dynamics, project discussions
|
||||
|
||||
## Privacy & Security
|
||||
|
||||
### Data Access
|
||||
- **User-scoped Permissions**: Only data you have access to
|
||||
- **Workspace Boundaries**: Confined to connected workspace
|
||||
- **Message Content**: Captures text for context (respects channel permissions)
|
||||
- **Sensitive Data**: Follows Slack's data handling guidelines
|
||||
|
||||
### Security Measures
|
||||
- **OAuth2 Flow**: Secure token-based authentication
|
||||
- **Webhook Verification**: Validates event authenticity
|
||||
- **Rate Limiting**: Respects Slack API limits
|
||||
- **Error Handling**: Graceful handling of permission errors
|
||||
|
||||
## Usage
|
||||
|
||||
The integration operates through real-time webhooks:
|
||||
|
||||
1. **Webhook Setup**: Configure Slack webhook endpoints
|
||||
2. **Event Reception**: Receive real-time workspace events
|
||||
3. **Context Fetching**: Enrich events with additional API data
|
||||
4. **Activity Generation**: Create structured activity messages
|
||||
5. **Entity Processing**: Extract users, channels, topics for knowledge graph
|
||||
6. **Memory Integration**: Store in CORE for intelligent recall
|
||||
|
||||
|
||||
## API Reference
|
||||
|
||||
- **Slack Web API**: https://api.slack.com/web
|
||||
- **Events API**: https://api.slack.com/events-api
|
||||
- **OAuth2 Guide**: https://api.slack.com/authentication/oauth-v2
|
||||
- **Webhook Events**: https://api.slack.com/events
|
||||
- **Rate Limiting**: https://api.slack.com/docs/rate-limits
|
||||
Loading…
x
Reference in New Issue
Block a user