Skip to main content
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

  • Dedicated bot for each companion agent
  • Secure communication channel
  • Event-driven messaging
  • End-to-end encryption support
  • Persistent connection management
  • Client-server protocol implementation
  • Authentication and authorization
  • Room management
  • Message encryption
  • Media handling
  • SDK libraries for various platforms
  • WebSocket connections
  • Event listeners
  • Message formatting
  • UI components

​
Implementation Guide

1

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'
});
2

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}`);
  }
});
3

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?');
4

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

  • User maintains control of all data
  • Local processing options
  • Selective sharing controls
  • Data retention policies
  • Export and deletion capabilities
  • End-to-end encryption
  • Zero-knowledge protocols
  • Secure key management
  • Encrypted storage
  • Secure communication channels

​
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:
1

Matrix Protocol Integration

Implementation of the Matrix Client-Server Protocol for secure communication
2

Bot Service Development

Creation of the companion bot service architecture
3

Client SDKs

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

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.