AI Companion API - IXO Docs Hub

The AI Companion API enables seamless integration between personal sovereign AI agents and client applications, providing users with personalized AI assistance while maintaining data sovereignty and privacy.

Overview

The AI Companion API provides a standardized interface for connecting personal sovereign AI agents with various client applications. Each companion agent operates through a dedicated Matrix bot service that connects to the user’s Matrix room via the Matrix MCP (Matrix Client-Server Protocol) interface.

The Matrix MCP interface is currently in development. This documentation serves as a placeholder and will be updated as the implementation progresses.

Key Capabilities

Sovereign AI Agents

Personal AI assistants that respect user data sovereignty and privacy

Matrix Integration

Secure communication through Matrix protocol and rooms

Multi-Client Support

Connect with web, mobile, and desktop applications

Personalization

Customizable AI behavior and knowledge base

Architecture

Implementation Guide

Setup Matrix Connection

import { MatrixClient } from '@ixo/matrixclient-sdk';

// Initialize Matrix client
const matrixClient = new MatrixClient({
  baseUrl: 'https://matrix.ixo.world',
  userId: '@user:ixo.world',
  accessToken: 'YOUR_ACCESS_TOKEN'
});

Connect to Companion Bot

// Connect to companion bot room
const companionRoom = await matrixClient.joinRoom('#companion:ixo.world');

// Listen for messages
matrixClient.on('Room.timeline', (event, room) => {
  if (room.roomId === companionRoom.roomId && event.getType() === 'm.room.message') {
    const content = event.getContent();
    console.log(`Companion: ${content.body}`);
  }
});

Send Commands

// Send message to companion
async function askCompanion(question) {
  await matrixClient.sendMessage(companionRoom.roomId, {
    msgtype: 'm.text',
    body: question
  });
}

// Example usage
askCompanion('What's the weather forecast for today?');

Handle Responses

// Process companion responses
function handleCompanionResponse(response) {
  // Parse response format
  const { text, actions, attachments } = parseResponse(response);
  
  // Update UI or trigger actions
  updateUI(text);
  processActions(actions);
  displayAttachments(attachments);
}

API Reference

// Authenticate with companion service
async function authenticateCompanion(credentials) {
  const response = await fetch('https://api.ixo.world/companion/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(credentials)
  });
  
  return await response.json();
}

// Message format
interface CompanionMessage {
  id: string;           // Unique message ID
  sender: string;       // Sender identifier
  content: {
    type: string;       // Message type (text, action, media)
    body: string;       // Text content
    metadata?: any;     // Additional data
  };
  timestamp: number;    // Unix timestamp
}

// Send message
async function sendMessage(roomId, message) {
  return await matrixClient.sendMessage(roomId, {
    msgtype: message.content.type,
    body: message.content.body,
    metadata: message.content.metadata
  });
}

// Configure companion preferences
async function configureCompanion(roomId, preferences) {
  return await matrixClient.sendStateEvent(
    roomId,
    'ixo.companion.config',
    preferences,
    ''
  );
}

// Example configuration
const preferences = {
  language: 'en',
  timezone: 'UTC+2',
  privacyLevel: 'high',
  responseStyle: 'concise',
  knowledgeDomains: ['finance', 'health', 'technology']
};

Use Cases

Personal Assistant

Daily task management, reminders, and information retrieval

Knowledge Navigator

Guide through complex information and learning resources

Data Analyst

Process and analyze personal or Organisational data

Domain Expert

Specialized knowledge in specific domains like finance or healthcare

Privacy & Security

Integration Examples

import { IxoCompanion } from '@ixo/companion-sdk';

// Initialize companion in web app
const companion = new IxoCompanion({
  matrixServer: 'https://matrix.ixo.world',
  credentials: {
    userId: '@user:ixo.world',
    accessToken: 'YOUR_ACCESS_TOKEN'
  }
});

// Connect and interact
await companion.connect();

// Send message and get response
const response = await companion.ask('How can I optimize my investment portfolio?');

// Display in UI
document.getElementById('response').textContent = response.text;

Development Status

The AI Companion API and Matrix MCP interface are currently under development. Key milestones include:

Matrix Protocol Integration

Implementation of the Matrix Client-Server Protocol for secure communication

Bot Service Development

Creation of the companion bot service architecture

Client SDKs

Development of client libraries for web, mobile, and desktop applications

Security & Privacy Framework

Implementation of encryption, data sovereignty, and consent management

Resources

Matrix Protocol

Learn about the Matrix communication protocol

IXO Matrix SDK

Matrix client SDK documentation

AI Companion Guide

Implementation guide for AI companions

GitHub Repository

Source code and examples

For technical support or questions about the AI Companion API, join our Developer Community or contact our Developer Relations Team.

​Overview

​Key Capabilities

Sovereign AI Agents

Matrix Integration

Multi-Client Support

Personalization

​Architecture

​Implementation Guide

​API Reference

​Use Cases

Personal Assistant

Knowledge Navigator

Data Analyst

Domain Expert

​Privacy & Security

​Integration Examples

​Development Status

​Resources

Matrix Protocol

IXO Matrix SDK

AI Companion Guide

GitHub Repository

Overview

Key Capabilities

Architecture

Implementation Guide

API Reference

Use Cases

Privacy & Security

Integration Examples

Development Status

Resources