### Start CORE Service with Docker Compose

Source: https://github.com/redplanethq/core/blob/main/README.md

This command initiates the CORE services using Docker Compose. It downloads and runs the necessary containers in detached mode (-d), making the system accessible after setup.

```shell
docker-compose up -d
```

--------------------------------

### Start Core Services with Docker Compose

Source: https://github.com/redplanethq/core/blob/main/apps/init/README.md

Starts all Core services, which are managed as Docker containers. This command utilizes Docker Compose and is used for daily development after the initial setup.

```bash
core start
```

--------------------------------

### Initialize Core Development Environment

Source: https://github.com/redplanethq/core/blob/main/apps/init/README.md

Initializes the Core development environment with full configuration. This is a one-time setup command that guides the user through prerequisites check, environment configuration, Docker services startup, database health check, Trigger.dev setup, Docker registry login, and task deployment.

```bash
core init
```

--------------------------------

### Install Core SDK with npm

Source: https://github.com/redplanethq/core/blob/main/packages/sdk/README.md

Installs the Core SDK package using npm. This is the first step in building an integration.

```bash
npm install @Core/core-sdk
```

--------------------------------

### Install CORE CLI with npm

Source: https://github.com/redplanethq/core/blob/main/apps/init/README.md

Installs the CORE CLI globally using npm. This command requires Node.js and npm to be installed on your system.

```bash
npm install -g @redplanethq/core
```

--------------------------------

### Download and Install CORE Browser Extension

Source: https://github.com/redplanethq/core/blob/main/README.md

Instructions for downloading and installing the CORE browser extension from the Chrome Web Store. This extension allows users to save content from various websites directly into their CORE memory.

```plaintext
Download the Extension from the Chrome Web Store.
Login to CORE dashboard.
Navigate to Settings (bottom left)
Go to API Key → Generate new key → Name it “extension.”
Open the extension, paste your API key, and save.
```

--------------------------------

### Install mcp-auth-proxy using npm

Source: https://github.com/redplanethq/core/blob/main/packages/mcp-proxy/README.md

This command installs the mcp-auth-proxy package using npm. This is the first step before using the library in your project.

```bash
npm install mcp-auth-proxy
```

--------------------------------

### Custom CORE Integration with TypeScript SDK

Source: https://context7.com/redplanethq/core/llms.txt

Provides a TypeScript example for building custom integrations with the CORE SDK. It demonstrates handling setup and sync events, fetching activities, and defining the integration's specification. This requires the '@redplanethq/sdk' package.

```typescript
// integrations/custom/src/index.ts
import {
  IntegrationCLI,
  IntegrationEventPayload,
  IntegrationEventType,
  Spec,
} from '@redplanethq/sdk';

class CustomIntegrationCLI extends IntegrationCLI {
  constructor() {
    super('custom-integration', '1.0.0');
  }

  protected async handleEvent(eventPayload: IntegrationEventPayload): Promise<any> {
    switch (eventPayload.event) {
      case IntegrationEventType.SETUP:
        // Initialize integration account
        const { API_KEY } = eventPayload.eventBody;
        // Validate credentials
        return [
          {
            type: 'account_created',
            data: { accountId: 'unique-id' }
          }
        ];

      case IntegrationEventType.SYNC:
        // Sync data from external service
        const activities = await this.fetchActivities(eventPayload.config);
        return activities.map(activity => ({
          type: 'activity',
          data: {
            text: activity.description,
            source: 'custom-integration',
            sourceURL: activity.url,
            timestamp: activity.createdAt
          }
        }));

      default:
        return [{ type: 'error', data: 'Unsupported event type' }];
    }
  }

  protected async getSpec(): Promise<Spec> {
    return {
      name: 'Custom Integration',
      key: 'custom-integration',
      description: 'Sync data from custom platform',
      icon: 'custom',
      auth: {
        OAuth2: {
          token_url: 'https://api.custom.com/oauth/token',
          authorization_url: 'https://api.custom.com/oauth/authorize',
          scopes: ['read', 'write'],
          scope_separator: ' '
        }
      }
    };
  }

  private async fetchActivities(config: any): Promise<any[]> {
    // Implement your custom logic here
    return [];
  }
}

function main() {
  const cli = new CustomIntegrationCLI();
  cli.parse();
}

main();

```

```json
// integrations/custom/package.json
{
  "name": "@core/integration-custom",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "ts-node src/index.ts"
  },
  "dependencies": {
    "@redplanethq/sdk": "^0.1.0"
  },
  "devDependencies": {
    "typescript": "^5.5.4"
  }
}

```

--------------------------------

### Clone Core Repository

Source: https://github.com/redplanethq/core/blob/main/apps/init/README.md

Clones the Core development repository from GitHub. This command requires Git to be installed on your system. It is the first step in the initial setup process.

```bash
git clone https://github.com/redplanethq/core.git
cd core
```

--------------------------------

### Start CORE Services with Docker Compose

Source: https://github.com/redplanethq/core/blob/main/docs/self-hosting/docker.mdx

This command starts all the necessary CORE services defined in the Docker Compose file in detached mode. Ensure you have completed the preceding steps, including setting up environment variables.

```bash
docker compose up -d
```

--------------------------------

### Smart Memory Rules Example (Text)

Source: https://github.com/redplanethq/core/blob/main/docs/integrations/overview.mdx

Examples of user-defined rules for filtering and controlling which activities are ingested into the CORE memory graph. These rules specify conditions for adding or ignoring activities based on assignee, channel, or repository.

```text
Only add Linear issues that are assigned to me
Ignore Slack messages from #random channel
Add all GitHub commits to the TaskMaster repository
```

--------------------------------

### Clone CORE Repository and Navigate

Source: https://github.com/redplanethq/core/blob/main/README.md

This command clones the CORE repository from GitHub and changes the directory to the cloned repository. It's the first step in setting up the self-hosted version of CORE.

```shell
git clone https://github.com/RedPlanetHQ/core.git
cd core
```

--------------------------------

### Development Workflow Use Cases

Source: https://github.com/redplanethq/core/blob/main/docs/mcp/overview.mdx

Examples of natural language commands for interacting with development tools like Linear and GitHub through the CORE MCP endpoint. These demonstrate task automation and information retrieval.

```natural_language
"Create a Linear issue for the authentication bug I just found"
"Search GitHub for similar issues in our repository"
"Update the issue status to In Progress and assign it to me"
```

--------------------------------

### Self-Hosting CORE with Docker

Source: https://context7.com/redplanethq/core/llms.txt

Instructions for deploying CORE on your own infrastructure using Docker. This involves cloning the repository, configuring environment variables in a `.env` file, and starting the services using `docker-compose`. Includes commands to check service status and view logs.

```bash
# Clone repository
git clone https://github.com/RedPlanetHQ/core.git
cd core

# Configure environment variables
cat > .env << EOF
# Database Configuration
POSTGRES_USER=docker
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=core
DATABASE_URL=postgresql://docker:your_secure_password@postgres:5432/core?schema=core

# Neo4j Graph Database
NEO4J_URI=bolt://neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password
NEO4J_AUTH=neo4j/your_neo4j_password

# OpenAI Configuration (required for entity extraction)
OPENAI_API_KEY=sk-your-openai-key
EMBEDDING_MODEL=text-embedding-3-small
MODEL=gpt-4-turbo-2024-04-09

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_TLS_DISABLED=true

# Application Configuration
APP_ORIGIN=http://localhost:3033
REMIX_APP_PORT=3033
SESSION_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
MAGIC_LINK_SECRET=$(openssl rand -hex 32)

# Queue Provider
QUEUE_PROVIDER=bullmq

# Optional: Google OAuth
AUTH_GOOGLE_CLIENT_ID=your_google_client_id
AUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
EOF

# Start all services (PostgreSQL, Neo4j, Redis, Web App)
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f webapp

# Access CORE at http://localhost:3033

```

```yaml
# This is a placeholder for the docker-compose.yml file content.
The actual content would define the services, networks, and volumes for PostgreSQL, Neo4j, Redis, and the web application.
```

--------------------------------

### MCP Server Configuration

Source: https://context7.com/redplanethq/core/llms.txt

Configuration examples for connecting MCP clients (like Claude and Cursor) to the CORE MCP server.

```APIDOC
## Claude Desktop Configuration

### Description
Configuration for Claude Desktop to use CORE as an MCP server.

### File Location
`~/Library/Application Support/Claude/claude_desktop_config.json`

### Configuration Example
```json
{
  "mcpServers": {
    "core-memory": {
      "url": "https://api.core.heysol.ai/api/v1/mcp",
      "transport": {
        "type": "sse"
      },
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}
```

## Cursor Configuration

### Description
Configuration for Cursor to use CORE as an MCP server.

### File Location
`~/.cursor/mcp.json`

### Configuration Example
```json
{
  "mcpServers": {
    "core": {
      "url": "https://api.core.heysol.ai/api/v1/mcp?spaceId=550e8400-e29b-41d4-a716-446655440000",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}
```

## Available MCP Tools

### Description
List of tools available through the MCP interface.

- **memory_ingest**: Store conversations/documents.
- **memory_search**: Hybrid search with BM25+vector+BFS.
- **memory_get_spaces**: List available spaces.
- **memory_about_user**: Get user profile.
- **memory_get_space**: Get space details.
- **get_integrations**: List connected integrations.
- **get_integration_actions**: Get integration tools.
- **execute_integration_action**: Run integration actions.

### Example Usage (memory_search)
```typescript
// User: "What did I say about my coding preferences?"
// Claude calls: memory_search({ query: "coding preferences", limit: 10 })
// Returns episodes and facts about user's stated preferences
```
```

--------------------------------

### Test Integration Commands using Node.js CLI

Source: https://github.com/redplanethq/core/blob/main/packages/sdk/README.md

Execute integration tests directly via the command line using the Node.js distribution of the Redplanet HQ Core. These commands cover testing specifications, setup procedures with event bodies and integration definitions, and webhook processing with event data and configuration.

```bash
# Test spec
node dist/index.js spec

# Test setup
node dist/index.js setup --event-body '{"code":"test"}' --integration-definition '{}'

# Test webhook processing
node dist/index.js process --event-data '{"type":"test"}' --config '{"token":"test"}'
```

--------------------------------

### Project Management Use Cases

Source: https://github.com/redplanethq/core/blob/main/docs/mcp/overview.mdx

Examples of natural language commands for project management tasks, integrating Linear, GitHub, and Slack via the CORE MCP endpoint. These showcase cross-tool workflow automation.

```natural_language
"Show me all Linear issues assigned to the frontend team"
"Create a GitHub issue and link it to Linear issue DEV-123"
"Send a Slack update to #engineering about the deployment"
```

--------------------------------

### GET /api/v1/mcp

Source: https://github.com/redplanethq/core/blob/main/docs/mcp/configuration.mdx

Configure CORE's MCP endpoint with query parameters to specify your source and which integrations to include or exclude.

```APIDOC
## GET /api/v1/mcp

### Description
This endpoint allows configuration of the CORE MCP by specifying a `source` and controlling which `integrations` are enabled or disabled.

### Method
GET

### Endpoint
https://core.heysol.ai/api/v1/mcp

### Parameters
#### Query Parameters
- **source** (string) - Required - Identifies your connection in the dashboard. Examples: `Claude`, `Cursor`, `VSCode`.
- **integrations** (string) - Optional - Specify which integrations to include, comma-separated. Example: `github,linear`.
- **no_integrations** (boolean) - Optional - Disable all integrations, enabling CORE tools only. Example: `true`.

### Request Example
```json
{
  "example": "https://core.heysol.ai/api/v1/mcp?source=Claude"
}
```

### Response
(No specific success response body is detailed in the provided text, but the configuration is applied based on the query parameters.)

#### Success Response (200)
(Response details not specified in the provided text.)

#### Response Example
(Response example not specified in the provided text.)
```

--------------------------------

### Research and Context Use Cases

Source: https://github.com/redplanethq/core/blob/main/docs/mcp/overview.mdx

Examples of natural language queries for retrieving information from Slack, memory graphs, and GitHub through the CORE MCP endpoint. These illustrate how to access historical data and code context.

```natural_language
"Find all previous discussions about Redis performance in Slack"
"Search my memory for decisions related to database architecture"
"Show GitHub commits related to the authentication system"
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/redplanethq/core/blob/main/README.md

This step involves creating or updating the `.env` file in the CORE directory to set environment variables, specifically the OpenAI API key. This key is essential for CORE to interact with OpenAI services.

```shell
OPENAI_API_KEY=your_openai_api_key
```

--------------------------------

### Bash Command to Create New Integration Directory

Source: https://github.com/redplanethq/core/blob/main/integrations/README.md

A bash command to create a new directory for a new integration within the integrations folder. This is the first step in the development guide for adding new integrations.

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

--------------------------------

### TypeScript Integration Class using Core SDK

Source: https://github.com/redplanethq/core/blob/main/packages/sdk/README.md

Example of creating an integration class by extending the IntegrationCLI base class from the Core SDK. It handles different event types and defines integration metadata.

```typescript
import { IntegrationCLI, IntegrationEventPayload, Spec } from '@Core/core-sdk';

class MyIntegration extends IntegrationCLI {
  constructor() {
    super('my-integration', '1.0.0');
  }

  protected async handleEvent(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    switch (eventPayload.event) {
      case 'SETUP':
        return this.handleSetup(eventPayload);
      case 'PROCESS':
        return this.handleProcess(eventPayload);
      case 'IDENTIFY':
        return this.handleIdentify(eventPayload);
      case 'SYNC':
        return this.handleSync(eventPayload);
      default:
        throw new Error(`Unknown event type: ${eventPayload.event}`);
    }
  }

  protected async getSpec(): Promise<Spec> {
    return {
      name: 'My Integration',
      key: 'my-integration',
      description: 'Integration with My Service',
      icon: 'https://example.com/icon.png',
      auth: {
        OAuth2: {
          token_url: 'https://api.example.com/oauth/token',
          authorization_url: 'https://api.example.com/oauth/authorize',
          scopes: ['read', 'write'],
        },
      },
    };
  }

  private async handleSetup(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Process OAuth response and return tokens to save
    const { code } = eventPayload.eventBody;
    // Exchange code for tokens...
    return {
      access_token: 'token',
      refresh_token: 'refresh_token',
      expires_at: Date.now() + 3600000,
    };
  }

  private async handleProcess(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Handle webhook events
    const { eventData } = eventPayload.eventBody;
    // Process event and return activity...
    return {
      type: 'message',
      user: 'user123',
      content: 'Hello world',
      timestamp: new Date(),
    };
  }

  private async handleIdentify(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Extract account ID from webhook
    const { team_id } = eventPayload.eventBody;
    return { id: team_id };
  }

  private async handleSync(
    eventPayload: IntegrationEventPayload,
  ): Promise<any> {
    // Perform scheduled sync
    const { config } = eventPayload;
    // Fetch data since last sync...
    return {
      activities: [
        /* activity data */
      ],
      state: { last_sync: new Date().toISOString() },
    };
  }
}

// CLI entry point
const integration = new MyIntegration();
integration.parse();

```

--------------------------------

### Example GitHub User Activity Events

Source: https://github.com/redplanethq/core/blob/main/integrations/github/README.md

Demonstrates the structured format for various user activities in GitHub, such as creating Pull Requests or Issues, commenting, and self-assignment. These events are processed and ingested into the CORE knowledge graph.

```plaintext
{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}
```

--------------------------------

### Initialize MCP Authentication Client and Initiate OAuth Flow (TypeScript)

Source: https://github.com/redplanethq/core/blob/main/packages/mcp-proxy/README.md

This TypeScript code snippet demonstrates how to initialize the MCP authentication client and start the OAuth authentication flow. It includes callbacks for saving credentials and initiating the authorization URL retrieval. Ensure 'db.saveCredentials' is implemented to persist tokens.

```typescript
import { createMCPAuthClient } from 'mcp-auth-proxy'

const authClient = createMCPAuthClient(
  {
    serverUrl: 'https://mcp.example.com/sse',
    clientName: 'My App'
  },
  // Callback to save credentials to your database
  async (credentials) => {
    await db.saveCredentials({
      serverUrl: credentials.serverUrl,
      accessToken: credentials.tokens.access_token,
      refreshToken: credentials.tokens.refresh_token,
      expiresAt: credentials.expiresAt
    })
  }
)

// Step 1: Get authorization URL
const authFlow = await authClient.initiateAuth()
console.log('Redirect user to:', authFlow.authUrl)
// Save authFlow.state - you'll need it for step 2

// Step 2: Complete authentication (in your OAuth callback route)
const result = await authClient.completeAuth({
  code: 'code_from_oauth_callback',
  state: authFlow.state  // Must match from step 1
})
```

--------------------------------

### List Spaces API Endpoint

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

This is an HTTP GET request to retrieve a list of all existing spaces.

```http
GET /api/v1/spaces
```

--------------------------------

### Example GitHub Notification Events

Source: https://github.com/redplanethq/core/blob/main/integrations/github/README.md

Illustrates the structured format for GitHub notifications, including issue assignments, PR review requests, comments on user content, mentions, and state changes. These processed notifications enrich the CORE memory system.

```plaintext
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}
```

--------------------------------

### Agents.md Memory Integration Instructions (Markdown)

Source: https://github.com/redplanethq/core/blob/main/docs/providers/kilo-code.mdx

This Markdown content provides detailed instructions for an AI agent on integrating with CORE's memory system. It specifies automatic behaviors for 'memory_search' at the start of conversations and 'memory_ingest' at the end, along with cognitive approaches, search triggers, quality questions, storage protocols, and what data to include or exclude.

```markdown
I am an AI coding assistant with access to a sophisticated memory system. While I don't retain information between separate conversations, I have access to CORE Memory - a persistent knowledge system that maintains project context, learnings, and continuity across all coding sessions.

**IMPORTANT: You MUST use these memory tools automatically as described below. This is not optional.**

## Memory Tools Integration

### Memory Search (`memory_search`)

**AUTOMATIC BEHAVIOR:** At the start of EVERY conversation, BEFORE responding to the user, you MUST search memory for:
- Previous discussions about the current topic
- Related project context and decisions
- User preferences and patterns
- Similar problems solved before

**Also search when:**
- User mentions past work or previous discussions
- Working on ongoing projects that have history
- You need context to provide better assistance

**Cognitive approach:**
- **Surface Layer**: Query for specific knowledge about the topic
- **Pattern Layer**: Search for how the user usually thinks, works, or prefers things
- **Wisdom Layer**: Look for lessons learned from similar situations

**Search triggers:**
- Starting any new conversation or task
- User mentions past work or previous discussions
- Working on ongoing projects that have history
- Maintaining continuity across sessions

**Quality questions to ask yourself:**
- "What don't I know that I should?"
- "What does this user care about that I might miss?"
- "What went right/wrong in similar situations?"


### Memory Ingest (`memory_ingest`)

**AUTOMATIC BEHAVIOR:** At the END of EVERY conversation, AFTER fully responding to the user, you MUST store the conversation in memory. This is the FINAL action before completing your response.

**Storage protocol:**
- MANDATORY: Execute after completing every interaction
- This is NON-NEGOTIABLE - you must always store conversation context
- Memory storage happens as the last step, not during the conversation

**What to capture:**

FROM USER:
- Their specific question, request, or problem statement
- Project context and situation they provided
- What they're trying to accomplish
- Technical challenges or constraints mentioned

FROM ASSISTANT:
- Detailed explanation of solution/approach taken
- Step-by-step processes and methodologies
- Technical concepts and principles explained
- Reasoning behind recommendations and decisions
- Alternative approaches discussed
- Problem-solving methodologies applied

**Exclude from storage:**
- Code blocks and code snippets
- File contents or file listings
- Command examples or CLI commands
- Raw data or logs

**Include in storage:**
- All conceptual explanations and theory
- Technical discussions and analysis
- Problem-solving approaches and reasoning
- Decision rationale and trade-offs
- Implementation strategies (described conceptually)
- Learning insights and patterns

**Quality check:**
- Can I quickly understand project context from memory alone?
- Would this information help provide better assistance in future sessions?
- Does stored context capture key decisions and reasoning?

```

--------------------------------

### Configure Webhooks for Activity Events using cURL

Source: https://context7.com/redplanethq/core/llms.txt

Receive real-time notifications when new activities are ingested. This includes creating a webhook with specified events and URL, an example of a webhook payload, and a note on signature verification using HMAC SHA-256. Uses cURL for interaction.

```bash
# Create webhook
curl -X POST https://api.core.heysol.ai/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/core",
    "events": ["activity.created", "episode.ingested"],
    "secret": "whsec_xxxxxxxxxxxxxxxx"
  }'

# Webhook payload example
{
  "event": "activity.created",
  "timestamp": "2025-01-15T12:00:00Z",
  "data": {
    "activityId": "activity-uuid",
    "text": "Fixed bug in authentication flow",
    "source": "github",
    "sourceURL": "https://github.com/user/repo/pull/123",
    "integrationAccountId": "account-uuid"
  }
}

# Verify webhook signature (HMAC SHA-256)
# X-Core-Signature: t=timestamp,v1=signature
```

--------------------------------

### Build and Package Integration with npm

Source: https://github.com/redplanethq/core/blob/main/packages/sdk/README.md

Commands to build and package an integration after development using npm. This prepares the integration for deployment.

```bash
npm run build
npm pack
```

--------------------------------

### GET /api/v1/spaces

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

Retrieves a list of all available spaces. This is useful for getting an overview of all organized memory categories.

```APIDOC
## GET /api/v1/spaces

### Description
Retrieves a list of all available spaces. This is useful for getting an overview of all organized memory categories.

### Method
GET

### Endpoint
/api/v1/spaces

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of spaces to return.
- **offset** (integer) - Optional - The number of spaces to skip before returning results.

### Response
#### Success Response (200 OK)
- **spaces** (array) - A list of space objects.
  - **id** (string) - The unique identifier for the space.
  - **name** (string) - The name of the space.
  - **description** (string) - The description of the space.

#### Response Example
```json
{
  "spaces": [
    {
      "id": "space-123",
      "name": "Project Alpha",
      "description": "All documents related to Project Alpha."
    },
    {
      "id": "space-456",
      "name": "Design Discussions",
      "description": "Discussions regarding UI/UX design."
    }
  ]
}
```
```

--------------------------------

### Clone CORE Repository and Navigate to Docker Directory

Source: https://github.com/redplanethq/core/blob/main/docs/self-hosting/docker.mdx

This snippet demonstrates how to clone the CORE repository from GitHub and then navigate into the Docker hosting directory. This is the first step in manually deploying CORE using Docker.

```bash
# Clone the repository
git clone https://github.com/RedPlanetHQ/core.git
cd core/hosting/docker
```

--------------------------------

### Get Space Episodes API Endpoint

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

This is an HTTP GET request to retrieve all episodes associated with a specific space, identified by its spaceId.

```http
GET /api/v1/spaces/{spaceId}/episodes
```

--------------------------------

### Get Space Summary API Endpoint

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

This is an HTTP GET request to retrieve the automatically generated summary for a specific space, identified by its spaceId.

```http
GET /api/v1/spaces/{spaceId}/summary
```

--------------------------------

### Get Space Details API Endpoint

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

This is an HTTP GET request to retrieve detailed information about a specific space, identified by its unique spaceId.

```http
GET /api/v1/spaces/{spaceId}
```

--------------------------------

### Install CORE MCP Server for Claude Code CLI

Source: https://github.com/redplanethq/core/blob/main/docs/providers/claude-code.mdx

This command registers the CORE MCP server with Claude Code, establishing the connection endpoint for memory operations. It requires the Claude Code CLI to be installed and a CORE account.

```bash
claude mcp add --transport http core-memory https://core.heysol.ai/api/v1/mcp?source=Claude-Code
```

--------------------------------

### Configuration Options

Source: https://github.com/redplanethq/core/blob/main/packages/mcp-proxy/README.md

Details on the configuration objects used for setting up the MCP authentication client and proxy.

```APIDOC
## Configuration Options

### `MCPRemoteClientConfig`

```typescript
interface MCPRemoteClientConfig {
  serverUrl: string;                    // MCP server URL (e.g., 'https://mcp.example.com/sse')
  clientName?: string;                  // OAuth client name for identification
  callbackPort?: number;               // Port for the OAuth callback listener (defaults to system-assigned)
  host?: string;                       // Host for the OAuth callback (defaults to 'localhost')
  transportStrategy?: TransportStrategy; // Strategy for transport: 'sse-first' | 'http-first' | 'sse-only' | 'http-only'
  headers?: Record<string, string>;    // Additional headers to include in requests
}
```

### `ProxyConnectionConfig`

```typescript
interface ProxyConnectionConfig {
  serverUrl: string;                    // MCP server URL (e.g., 'https://mcp.example.com/sse')
  transportStrategy?: TransportStrategy; // Transport preference: 'sse-first' | 'http-first' | 'sse-only' | 'http-only'
  timeout?: number;                    // Request timeout in milliseconds (default: 30000)
  headers?: Record<string, string>;    // Additional headers to include in requests
}
```

### `TransportStrategy`

Type alias for transport strategy options:
```typescript
type TransportStrategy = 'sse-first' | 'http-first' | 'sse-only' | 'http-only';
```
```

--------------------------------

### GET /api/v1/spaces/{spaceId}/episodes

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

Retrieves a list of all episodes currently assigned to a specific space.

```APIDOC
## GET /api/v1/spaces/{spaceId}/episodes

### Description
Retrieves a list of all episodes currently assigned to a specific space.

### Method
GET

### Endpoint
/api/v1/spaces/{spaceId}/episodes

### Parameters
#### Path Parameters
- **spaceId** (string) - Required - The unique identifier of the space whose episodes to retrieve.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of episodes to return.
- **offset** (integer) - Optional - The number of episodes to skip before returning results.

### Response
#### Success Response (200 OK)
- **episodes** (array) - A list of episode objects.
  - **id** (string) - The unique identifier for the episode.
  - **title** (string) - The title of the episode.
  - **timestamp** (string) - The timestamp when the episode was created or last updated.

#### Response Example
```json
{
  "episodes": [
    {
      "id": "episode-abc",
      "title": "Initial Project Proposal",
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "id": "episode-def",
      "title": "Architecture Design Document",
      "timestamp": "2023-10-27T11:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Minimal docker-compose.yml Structure for CORE Services

Source: https://context7.com/redplanethq/core/llms.txt

This docker-compose.yml file defines the minimal structure for setting up the necessary services for the CORE project, including PostgreSQL, Neo4j, Redis, and the web application. It specifies images, environment variables, volumes, and dependencies between services. Ensure environment variables like POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, NEO4J_AUTH, DATABASE_URL, NEO4J_URI, REDIS_HOST, and OPENAI_API_KEY are set in your environment.

```yaml
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  neo4j:
    image: neo4j:5.13.0
    environment:
      NEO4J_AUTH: ${NEO4J_AUTH}
      NEO4J_PLUGINS: '["apoc", "graph-data-science"]'
    volumes:
      - neo4j_data:/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  webapp:
    build:
      context: .
      dockerfile: ./docker/Dockerfile
    ports:
      - "3033:3033"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      NEO4J_URI: ${NEO4J_URI}
      REDIS_HOST: ${REDIS_HOST}
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    depends_on:
      - postgres
      - neo4j
      - redis

volumes:
  postgres_data:
  neo4j_data:
  redis_data:
```

--------------------------------

### GET /api/v1/spaces/{spaceId}

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

Retrieves detailed information about a specific space, including its name, description, and associated memories.

```APIDOC
## GET /api/v1/spaces/{spaceId}

### Description
Retrieves detailed information about a specific space, including its name, description, and associated memories.

### Method
GET

### Endpoint
/api/v1/spaces/{spaceId}

### Parameters
#### Path Parameters
- **spaceId** (string) - Required - The unique identifier of the space to retrieve.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the space.
- **name** (string) - The name of the space.
- **description** (string) - The description of the space.

#### Response Example
```json
{
  "id": "space-123",
  "name": "Project Alpha",
  "description": "All documents related to Project Alpha."
}
```
```

--------------------------------

### GET /api/v1/spaces/{spaceId}/summary

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

Retrieves the automatically generated summary for a specific space. This provides a high-level overview of the space's content.

```APIDOC
## GET /api/v1/spaces/{spaceId}/summary

### Description
Retrieves the automatically generated summary for a specific space. This provides a high-level overview of the space's content.

### Method
GET

### Endpoint
/api/v1/spaces/{spaceId}/summary

### Parameters
#### Path Parameters
- **spaceId** (string) - Required - The unique identifier of the space whose summary to retrieve.

### Response
#### Success Response (200 OK)
- **summary** (string) - The generated summary of the space's content.

#### Response Example
```json
{
  "summary": "This space contains discussions and documents related to Project Alpha, focusing on the initial proposal, architecture design, and key decision-making processes."
}
```
```

--------------------------------

### Manual Trigger.dev Deployment

Source: https://github.com/redplanethq/core/blob/main/apps/init/README.md

Provides commands for manual Trigger.dev login and task deployment. These commands are used when the automatic deployment within the `core init` process fails. Requires npx and pnpm.

```bash
npx trigger.dev@v4-beta login -a http://localhost:8030
pnpm trigger:deploy
```

--------------------------------

### Create Space API

Source: https://github.com/redplanethq/core/blob/main/docs/concepts/spaces.mdx

This endpoint allows you to programmatically create a new Space for organizing your CORE memories. You can provide a name and an optional description to guide its purpose.

```APIDOC
## POST /api/v1/spaces

### Description
Creates a new Space to organize CORE memories. Spaces act as distinct, project-specific contexts that automatically group related memories and maintain living summaries.

### Method
POST

### Endpoint
/api/v1/spaces

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the Space (max 100 characters).
- **description** (string) - Optional - A description or rule to guide what memories should be stored in this Space.

### Request Example
```json
{
  "name": "Core-Features",
  "description": "Feature discussions, design decisions, and implementation notes for CORE"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the newly created Space.
- **name** (string) - The name of the Space.
- **description** (string) - The description of the Space.
- **createdAt** (string) - The timestamp when the Space was created.

#### Response Example
```json
{
  "id": "space_abc123xyz",
  "name": "Core-Features",
  "description": "Feature discussions, design decisions, and implementation notes for CORE",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Create .github Directory and Agents.md

Source: https://github.com/redplanethq/core/blob/main/docs/providers/vscode.mdx

These bash commands create the necessary directory structure and an empty Agents.md file in the project root. This file will subsequently be populated with instructions for enabling automatic memory integration with CORE.

```bash
mkdir -p .github
touch .github/Agents.md
```

--------------------------------

### Connect Integrations (Slack, GitHub, Linear) using cURL

Source: https://context7.com/redplanethq/core/llms.txt

Set up OAuth integrations to automatically sync activity into memory. This involves creating an integration account with an API key, listing connected integrations, and disconnecting them. Uses cURL for command-line interaction.

```bash
# Create integration account with API key (Linear example)
curl -X POST https://api.core.heysol.ai/api/v1/integration_account \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationDefinitionId": "linear-integration-id",
    "credentials": {
      "API_KEY": "lin_api_xxxxxxxxxxxxx"
    }
  }'

# Response
{
  "id": "account-uuid",
  "integrationDefinitionId": "linear-integration-id",
  "status": "connected",
  "mcpConfig": {
    "command": "linear-mcp-server",
    "args": [],
    "env": {
      "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
    }
  }
}

# List connected integrations
curl -X GET https://api.core.heysol.ai/api/v1/integrations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Disconnect integration
curl -X POST https://api.core.heysol.ai/api/v1/integration_account/disconnect \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "account-uuid"
  }'
```

--------------------------------

### Interact with Linear MCP Tools via CORE

Source: https://github.com/redplanethq/core/blob/main/docs/integrations/linear.mdx

Demonstrates how to use Linear's MCP (Multi-Channel Protocol) tools directly through CORE's unified endpoint within AI coding environments like Claude Code or Cursor. This allows for seamless issue creation, updates, and searching without leaving the IDE.

```natural_language
"Create a Linear issue: Fix authentication bug in login flow"
"Update issue DEV-123 status to In Progress"
"Add comment to current issue: Implemented fix, ready for testing"
"Search Linear issues assigned to me"
```

--------------------------------

### Query Knowledge Graph Structure using cURL

Source: https://context7.com/redplanethq/core/llms.txt

Retrieve clustered graph data for visualization and analysis. Includes endpoints for getting clustered triplets and facts from a specific episode. Uses cURL for these queries.

```bash
curl -X GET https://api.core.heysol.ai/api/v1/graph/clustered \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Response
{
  "triplets": [
    {
      "subject": {
        "uuid": "entity-1",
        "name": "User",
        "type": "Person"
      },
      "predicate": {
        "uuid": "entity-2",
        "name": "prefers",
        "type": "Relationship"
      },
      "object": {
        "uuid": "entity-3",
        "name": "TypeScript",
        "type": "Technology"
      },
      "statement": {
        "uuid": "statement-1",
        "fact": "User prefers TypeScript for new projects",
        "validAt": "2025-01-15T10:30:00Z"
      }
    }
  ],
  "spaces": [
    {
      "id": "space-1",
      "name": "Web Development",
      "episodeCount": 42
    }
  ]
}

# Get facts from specific episode
curl -X GET https://api.core.heysol.ai/api/v1/episodes/episode-uuid/facts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Create Kilo Code Agents.md File for Memory Instructions

Source: https://github.com/redplanethq/core/blob/main/docs/providers/kilo-code.mdx

This bash command creates an empty Markdown file named 'Agents.md' inside the '.kilo-code' directory. This file will contain instructions for the AI agent on how to interact with CORE's memory system, including automatic search and ingest behaviors.

```bash
touch .kilo-code/Agents.md
```

--------------------------------

### Set Linear Memory Rules in CORE

Source: https://github.com/redplanethq/core/blob/main/docs/integrations/linear.mdx

Define specific rules for what Linear data should be included in your CORE memory. This allows for granular control over the context that AI models have access to, ensuring relevance and efficiency. For example, you can specify that only issues assigned to you should be added.

```text
Only add Linear issues that are assigned to me in my CORE memory
```

--------------------------------

### Integrations API

Source: https://context7.com/redplanethq/core/llms.txt

Manage and connect third-party integrations like Slack, GitHub, and Linear to automatically sync activity into memory using OAuth.

```APIDOC
## POST /api/v1/integration_account

### Description
Create an integration account with an API key for a specific integration (e.g., Linear).

### Method
POST

### Endpoint
https://api.core.heysol.ai/api/v1/integration_account

### Parameters
#### Request Body
- **integrationDefinitionId** (string) - Required - The ID of the integration definition.
- **credentials** (object) - Required - An object containing the credentials for the integration.
  - **API_KEY** (string) - Required - The API key for the integration.

### Request Example
```json
{
  "integrationDefinitionId": "linear-integration-id",
  "credentials": {
    "API_KEY": "lin_api_xxxxxxxxxxxxx"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the integration account.
- **integrationDefinitionId** (string) - The ID of the integration definition.
- **status** (string) - The connection status of the integration.
- **mcpConfig** (object) - Configuration for the integration.
  - **command** (string)
  - **args** (array)
  - **env** (object)

#### Response Example
```json
{
  "id": "account-uuid",
  "integrationDefinitionId": "linear-integration-id",
  "status": "connected",
  "mcpConfig": {
    "command": "linear-mcp-server",
    "args": [],
    "env": {
      "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
    }
  }
}
```

## GET /api/v1/integrations

### Description
List all connected integrations.

### Method
GET

### Endpoint
https://api.core.heysol.ai/api/v1/integrations

### Response
#### Success Response (200)
Returns a list of connected integrations.

## POST /api/v1/integration_account/disconnect

### Description
Disconnect an integration account.

### Method
POST

### Endpoint
https://api.core.heysol.ai/api/v1/integration_account/disconnect

### Parameters
#### Request Body
- **accountId** (string) - Required - The ID of the integration account to disconnect.

### Request Example
```json
{
  "accountId": "account-uuid"
}
```

### Response
#### Success Response (200)
Indicates successful disconnection.
```

--------------------------------

### Track Ingestion Status and Logs using cURL

Source: https://context7.com/redplanethq/core/llms.txt

Monitor the ingestion pipeline and debug failed ingestions. This involves getting the status of the ingestion queue, listing ingestion logs with filtering options, and retrying failed ingestions. Uses cURL for these operations.

```bash
# Get ingestion queue status
curl -X GET https://api.core.heysol.ai/api/v1/ingestion-queue.status?queueId=queue-uuid \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Response
{
  "id": "queue-uuid",
  "status": "COMPLETED",
  "episodeBody": "Original text content",
  "progress": 100,
  "error": null,
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:45Z"
}

# List ingestion logs with filtering
curl -X GET "https://api.core.heysol.ai/api/v1/logs?source=cursor&status=FAILED&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Retry failed ingestion
curl -X POST https://api.core.heysol.ai/api/v1/logs/log-uuid/retry \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Configure GitHub Copilot Instructions for CORE Memory

Source: https://github.com/redplanethq/core/blob/main/docs/providers/vscode.mdx

This configuration file sets up GitHub Copilot to utilize CORE Memory. It enforces mandatory memory operations like searching for context before responding and storing interaction details afterward. This ensures that Copilot acts as a persistent development partner, maintaining continuity and leveraging project knowledge across sessions.

```markdown
---
alwaysApply: true
---
I am Copilot, an AI coding assistant with access to CORE Memory - a persistent knowledge system that maintains project context across sessions.

**MANDATORY MEMORY OPERATIONS:**

1. **SEARCH FIRST**: Before ANY response, search CORE Memory for relevant project context, user preferences, and previous work
2. **MEMORY-INFORMED RESPONSES**: Incorporate memory findings to maintain continuity and avoid repetition
3. **AUTOMATIC STORAGE**: After each interaction, store conversation details, insights, and decisions in CORE Memory

**Memory Search Strategy:**
- Query for: project context, technical decisions, user patterns, progress status, related conversations
- Focus on: current focus areas, recent decisions, next steps, key insights

**Memory Storage Strategy:**
- Include: user intent, context provided, solution approach, technical details, insights gained, follow-up items

**Response Workflow:**
1. Search CORE Memory for relevant context
2. Integrate findings into response planning
3. Provide contextually aware assistance
4. Store interaction details and insights

**Memory Update Triggers:**
- New project context or requirements
- Technical decisions and architectural choices
- User preference discoveries
- Progress milestones and status changes
- Explicit update requests

**Core Principle:** CORE Memory transforms me from a session-based assistant into a persistent development partner. Always search first, respond with context, and store for continuity.
```

--------------------------------

### Configure CORE MCP Server for Codex CLI

Source: https://github.com/redplanethq/core/blob/main/docs/providers/codex.mdx

This snippet demonstrates how to create the necessary directory and open the Codex configuration file using bash commands. It ensures the configuration file exists before editing.

```bash
# Create config directory if needed
mkdir -p ~/.codex

# Open config file in your editor
code ~/.codex/config.toml -r
```

--------------------------------

### Configure Session Hooks in settings.local.json

Source: https://github.com/redplanethq/core/blob/main/docs/providers/claude-code.mdx

This JSON snippet configures session hooks for automating memory operations. It defines actions to be taken at the start of a session and when a user submits a prompt, including searching memory for context and ingesting conversation summaries.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"🧠 SESSION STARTED: Search memory for context about: $(basename $(pwd)) project, previous conversations, and related work. Do this before responding to user queries.\""
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '💭 CONTEXT SEARCH: Before responding, use memory-search to search for: previous discussions about this topic, related project context, and similar problems solved before. Before this conversation ends, you must use memory-ingest to store: [USER] their question/request + [ASSISTANT] your solution/explanation/reasoning. Do this storage as the very last action.'"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Create Cursor Agents Directory and File

Source: https://github.com/redplanethq/core/blob/main/docs/providers/cursor.mdx

This Bash command sequence creates the necessary directory and an empty Agents.md file within the `.cursor` directory in your project root. This file is used to configure memory instructions for AI agents.

```bash
mkdir -p .cursor
touch .cursor/Agents.md
```