Developer Documentation

This is the technical hub for integrating BUYaSOOL AI souls into your applications, tools, and workflows. Whether you are running a single soul locally, wiring multiple souls together in a multi-agent mesh, or exposing souls as MCP servers for your favorite IDE, you will find everything you need here.

Quick Start — Running Your First Soul

Prerequisites

• Node.js v18+ — Download from nodejs.org
• Git — For cloning soul repositories
• Ollama (optional, for local LLM) — Download from ollama.com

Steps

1. Download the soul package from the BUYaSOOL store
2. Unzip the package into your working directory
3. Open a terminal and navigate to the soul folder

cd path/to/your-soul-name
npm install
node soul.js

The soul will start in your terminal and present itself with an introduction message. You can now begin chatting directly.

MCP Integration

MCP (Model Context Protocol) allows your soul to register as a tool server that any MCP-compatible host — such as Claude Desktop, Cursor, or Continue — can discover and interact with. This enables your soul to plug directly into your coding environment, reading files, running commands, and providing context-aware assistance.

Registering Your Soul as an MCP Server

Add the following entry to your claude_desktop_config.json, .cursor/config.json, or Continue configuration file:

{
  "mcpServers": {
    "soul-commander": {
      "command": "node",
      "args": ["path/to/soul-commander/soul.js"],
      "env": {}
    }
  }
}

Replace path/to/soul-commander/soul.js with the actual path to the soul you want to register. After saving the configuration, restart the MCP host and your soul will appear as an available tool.

Multi-Agent Setup with Soul Telephone

Soul Telephone acts as a communication mesh that lets multiple souls talk to each other. This enables complex multi-agent workflows where each soul contributes its unique expertise.

Architecture

┌─────────────┐     ┌─────────────┐
│  Soul       │     │  Soul       │
│  Commander  │◄────┤  Strategist │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └──────────┬────────┘
                  │
         ┌────────▼────────┐
         │  Soul Telephone │
         │     (Hub)       │
         └────────┬────────┘
                  │
         ┌────────▼────────┐
         │  Soul           │
         │  Allie          │
         └─────────────────┘

Steps

1. Start the Telephone hub: Run node telephone.js — it listens on a WebSocket port for incoming soul connections.
2. Connect souls: Launch each soul with the --telephone flag pointing to the hub address.
3. Send messages: Souls can now route messages to one another through the hub.

Example: Soul-to-Soul Message

{
  "from": "soul-commander",
  "to": "soul-strategist",
  "type": "request",
  "payload": {
    "action": "analyze_threat",
    "context": "User provided network topology"
  }
}

Soul Features Reference

Troubleshooting

Soul won't start

Verify your Node.js version is v18 or higher by running node --version. If the version is too old, download the latest LTS release from nodejs.org. Also confirm that all dependencies installed without errors during npm install.

MCP not connecting

Check that the path in your MCP config file points to the correct soul.js file. Use an absolute path to avoid ambiguity. After editing the config, restart the MCP host entirely (reloading may not be sufficient).

Memory not persisting

Ensure the soul process has write permissions to its data directory. On Linux or macOS, check folder permissions with ls -la. On Windows, verify the user running the process has write access to the soul's folder.

Need Help?

• GitHub Discussions: Join the community at github.com/anomalyco/cosmic-pyramid-library/discussions
• Email: Reach the team at support@buyasoul.ai