GitHub - mziqudhd92/soul-os: Open-source runtime for persistent AI avatars — HEXACO personality, episodic memory, dual-process chat, MCP for Cursor, and Soul Studio for building .soul.json souls.

# Watch locally (no Docker)
./scripts/demo-hybrid-cli.sh --simulate
# or: npm run demo

# Against a running sidecar kernel
docker compose -f docker-compose.sidecar.yml --profile bridge-mock up -d
./scripts/demo-hybrid-cli.sh

git clone https://github.com/mziqudhd92/soul-os.git
cd soul-os
docker compose up --build

docker compose -f docker-compose.sidecar.yml --profile bridge-mock up -d
npm run smoke:hybrid   # ensure → doctor → prepare → print system_prompt

# Idempotent avatar bootstrap
curl -s -X POST http://localhost:8001/v1/avatars/ensure \
  -H "Content-Type: application/json" \
  -d '{"external_key":"demo-bot","soul":'"$(cat examples/support-bot/support-bot.soul.json)"'}'

# Prepare (returns system_prompt for your LLM)
curl -s -X POST http://localhost:8001/hybrid/prepare \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"<BOT_ID>","query":"What is the refund policy?"}'

# Register example support bot (JSON)
curl -s -X POST http://localhost:8000/v1/avatars \
  -H "Content-Type: application/json" \
  -d @examples/support-bot/support-bot.soul.json

# Save the returned "id" as BOT_ID, then teach one fact:
curl -X POST http://localhost:8000/memory/ingest \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"<BOT_ID>","content":"Refunds within 30 days of purchase."}'

# Stream a reply (SSE)
curl -N -X POST http://localhost:8000/chat/generate \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"<BOT_ID>","message":"Can I get a refund?"}'

# Included in docker compose, or run alone (kernel must be on :8000):
pip install -e packages/soulos-studio
soulos-studio

import asyncio
from soulos.client import SoulOSClient

async def main():
    soul = SoulOSClient(base_url="http://localhost:8000")
    avatar = await soul.register_avatar("examples/support-bot/support-bot.soul")
    avatar_id = avatar["id"]
    await soul.ingest_memory(avatar_id, "Refunds within 30 days.")

    parts = []
    async for event in soul.send_message(avatar_id, "Can I get a refund?"):
        if event["type"] == "message":
            parts.append(event["text"])
        if event["type"] == "cognitive_state":
            print("path:", event.get("current_path"))
    print("".join(parts))

asyncio.run(main())

npm install @soulos/sdk   # from monorepo: npm run build:sdk

import { SoulOSClient } from "@soulos/sdk";
import { registerAvatarFromFile } from "@soulos/sdk/node";

const soul = new SoulOSClient({ baseUrl: "http://localhost:8000" });
const { id } = await registerAvatarFromFile(soul, "./examples/support-bot/support-bot.soul.json");

for await (const e of soul.sendMessage(id, "I need a refund")) {
  if (e.type === "message") process.stdout.write(e.text);
}

http://localhost:8000/mcp/sse

packages/soulos-core/      Kernel API + MCP          → :8000
packages/soulos-studio/    Soul Studio UI            → :8765
packages/soulos-gateway/   Cloud gateway             → :8080
packages/soulos-sdk/       TypeScript + Python clients
examples/                  support-bot, dev-twin, companion
spec/soul.schema.json      Soul file JSON Schema
docs/                      Guides, reference, deployment

npm run seed          # optional demo data
npm run test:all      # kernel + bridge + gateway + studio + sdk