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

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

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