Morpheus

Morpheus is a local-first AI operator for developers. It runs as a daemon and orchestrates LLMs, MCP tools, DevKit tools, memory, and channels (Web UI, Telegram, Discord, API, webhooks).

Why Morpheus

• Local-first persistence (sessions, messages, usage, tasks).
• Multi-agent architecture (Oracle, Neo, Apoc, Sati, Trinity, Link, Smith) with centralized SubagentRegistry.
• Async task execution with queue + worker + notifier.
• Chronos temporal scheduler for recurring and one-time Oracle executions.
• Smith remote agent system for DevKit execution on isolated machines via WebSocket.
• Multi-channel output via ChannelRegistry (Telegram, Discord) with per-job routing.
• Google Workspace automation via 102 built-in skills (Gmail, Drive, Sheets, Calendar, Docs, Tasks).
• Rich operational visibility in UI (chat traces, tasks, usage, logs, real-time activity visualization).

Multi-Agent Roles

• Oracle: orchestration and routing. Decides direct answer vs async delegation.
• Neo: MCP and internal operational tools (config, diagnostics, analytics).
• Apoc: DevTools/browser execution (filesystem, shell, git, network, packages, processes, system, browser automation).
• Sati: long-term memory retrieval/evaluation.
• Trinity: database specialist. Executes queries, introspects schemas, and manages registered databases (PostgreSQL, MySQL, SQLite, MongoDB).
• Link: documentation specialist. RAG over indexed user documents (PDF, Markdown, TXT, DOCX) with hybrid vector + keyword search.
• Chronos: temporal scheduler. Runs Oracle prompts on a recurring or one-time schedule.
• Smith: remote DevKit executor. Runs DevKit operations on isolated machines (Docker, VMs, cloud) via WebSocket.

Installation

npm install -g morpheus-cli

Quick Start

1. Initialize

morpheus init

Creates:

• ~/.morpheus/zaion.yaml
• ~/.morpheus/mcps.json
• local memory/log folders

2. Start

morpheus start

Useful flags:

morpheus start -y            # auto-restart if another instance is running
morpheus start --no-ui       # disable web UI
morpheus start --port 3333   # override UI port

3. Control Commands

morpheus status
morpheus stop
morpheus restart
morpheus doctor
morpheus session new
morpheus session status

Docker

Docker Compose (recommended)

1. Create an env.docker file (referenced by docker-compose.yml):

cp .env.example env.docker   # or create manually

Minimal env.docker:

OPENAI_API_KEY=sk-...
THE_ARCHITECT_PASS=changeme
MORPHEUS_SECRET=<generate-a-random-secret>

Tip: Generate a secure MORPHEUS_SECRET with: openssl rand -base64 32 or node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

2. Run:

docker compose up -d

The dashboard will be available at http://localhost:3333.

Useful commands:

docker compose logs -f          # follow logs
docker compose restart morpheus # restart the agent
docker compose down             # stop
docker compose down -v          # stop and remove persistent data

Data persistence: configuration and databases are stored in the morpheus_data Docker volume (/root/.morpheus inside the container). They survive container restarts and rebuilds.

Override variables at runtime via the environment block in docker-compose.yml or directly in env.docker. All MORPHEUS_* env vars work the same as in a native install. See the Environment Variables section for the full list.

Docker (standalone)

Build:

docker build -t morpheus .

Run:

docker run -d \
  --name morpheus-agent \
  -p 3333:3333 \
  -e OPENAI_API_KEY=sk-... \
  -e THE_ARCHITECT_PASS=changeme \
  -e MORPHEUS_SECRET=<generate-a-random-secret> \
  -v morpheus_data:/root/.morpheus \
  morpheus

With Telegram:

docker run -d \
  --name morpheus-agent \
  -p 3333:3333 \
  -e OPENAI_API_KEY=sk-... \
  -e THE_ARCHITECT_PASS=changeme \
  -e MORPHEUS_SECRET=<generate-a-random-secret> \
  -e MORPHEUS_TELEGRAM_ENABLED=true \
  -e MORPHEUS_TELEGRAM_TOKEN=<bot-token> \
  -e MORPHEUS_TELEGRAM_ALLOWED_USERS=123456789 \
  -v morpheus_data:/root/.morpheus \
  morpheus

With Discord:

docker run -d \
  --name morpheus-agent \
  -p 3333:3333 \
  -e OPENAI_API_KEY=sk-... \
  -e THE_ARCHITECT_PASS=changeme \
  -e MORPHEUS_SECRET=<generate-a-random-secret> \
  -e MORPHEUS_DISCORD_ENABLED=true \
  -e MORPHEUS_DISCORD_TOKEN=<bot-token> \
  -e MORPHEUS_DISCORD_ALLOWED_USERS=987654321 \
  -v morpheus_data:/root/.morpheus \
  morpheus

Health check: the container exposes GET /health and Docker will probe it every 30s (60s start period, 3 retries before marking unhealthy).

Async Task Execution

Morpheus uses asynchronous delegation by default:

1. Oracle receives user request.
2. If execution is needed, Oracle calls neo_delegate, apoc_delegate, trinity_delegate, or smith_delegate.
3. Delegate tool creates a row in tasks table with origin metadata (channel, session, message, user).
4. Oracle immediately acknowledges task creation.
5. TaskWorker executes pending tasks (routes trinit tasks to Trinity agent, smith tasks to Smith delegator).
6. TaskNotifier sends completion/failure through TaskDispatcher.

Important behavior:

• Oracle stays responsive while tasks run.
• Delegations must be atomic (single objective per task).
• Duplicate/fabricated task acknowledgements are blocked by validation against DB.
• Status follow-ups are handled by Oracle through task_query (no delegation required).

Chronos — Temporal Scheduler

Chronos lets you schedule any Oracle prompt to run at a fixed time or on a recurring schedule.

Schedule types:

• once — run once at a specific time: "in 30 minutes", "tomorrow at 9am", "2026-03-01T09:00:00"
• interval — recurring natural language: "every day at 9am", "every weekday", "every monday and friday at 8am", "every 30 minutes"
• cron — raw 5-field cron: "0 9 * * 1-5"

Execution model:

• Jobs run inside the currently active Oracle session — no isolated sessions are created per job.
• Chronos injects context as an AI message before invoking oracle.chat(), keeping conversation history clean.
• Each job has a notify_channels field: empty = broadcast to all active channels, ["telegram"] = Telegram only, ["discord"] = Discord only.
• When creating jobs via Oracle chat, the channel is auto-detected from the conversation origin. You can override it explicitly: "lembre no Discord", "em todos os canais".

Oracle tools: chronos_schedule, chronos_list, chronos_cancel, chronos_preview

Telegram commands:

• /chronos <prompt> @ <schedule> — create a job
• /chronos_list — list all jobs (🟢 active / 🔴 disabled)
• /chronos_view <id> — view job details and last 5 executions
• /chronos_enable <id> / /chronos_disable <id> / /chronos_delete <id>

Discord slash commands:

• /chronos prompt: time: — create a job (prompt and time as separate fields)
• /chronos_list — list all jobs
• /chronos_view id: / /chronos_disable id: / /chronos_enable id: / /chronos_delete id:

API endpoints (protected):

• GET/POST /api/chronos — list / create jobs
• GET/PUT/DELETE /api/chronos/:id — read / update / delete
• PATCH /api/chronos/:id/enable / .../disable
• GET /api/chronos/:id/executions
• POST /api/chronos/preview — preview next N run timestamps
• GET/POST/DELETE /api/config/chronos

Smith — Remote Agent System

Smith enables remote DevKit execution on isolated machines (Docker, VMs, cloud) via WebSocket.

Architecture:

• SmithRegistry manages WebSocket connections to remote Smith instances (singleton, non-blocking startup).
• SmithDelegator creates a LangChain ReactAgent with proxy tools — local DevKit tools built for schema extraction, filtered by Smith's declared capabilities, wrapped in proxies that forward execution to the remote Smith via WebSocket.
• Oracle delegates via smith_delegate tool (sync or async, like other subagents).

Config (zaion.yaml):

smiths:
  enabled: true
  execution_mode: sync    # or async
  entries:
    - name: smith1
      host: localhost
      port: 7778
      auth_token: secret-token

Key behaviors:

• Hot-reload: Config changes connect/disconnect Smiths without restart (via PUT /api/smiths/config or smith_manage tool).
• Reconnection: Max 3 attempts. 401 auth failures stop retries immediately.
• Non-blocking startup: Smith connection failures don't block daemon boot.

Oracle tools: smith_list (list Smiths + state), smith_manage (add/remove/ping/enable/disable)

API endpoints (protected):

• GET /api/smiths — list all Smiths with status
• GET /api/smiths/config — get Smiths configuration
• PUT /api/smiths/config — update config (hot-reload)
• GET /api/smiths/:name — get specific Smith details
• POST /api/smiths/:name/ping — ping a Smith
• DELETE /api/smiths/:name — remove a Smith

Learn more: The Smith standalone agent has its own repository with setup instructions, Docker support, and protocol documentation at github.com/marcosnunesmbs/smith.

Telegram Experience

Telegram responses use rich HTML formatting conversion with:

• bold/italic/list rendering from markdown-like text
• inline code and fenced code blocks
• auto-wrapped UUIDs in <code> for easier copy

Task results are delivered proactively with metadata (task id, agent, status) and output/error body.

Session commands:

• /session — Show current session info
• /session list — List recent sessions
• /session new — Create new session
• /session switch <id> — Switch to existing session
• /session rename <name> — Rename current session

Voice messages: Telegram voice messages are automatically transcribed (Gemini / Whisper / OpenRouter) and processed as text through the Oracle. If TTS is enabled (audio.tts.enabled: true), Oracle's response is synthesized back to audio and sent as a voice message. Falls back to text if synthesis fails.

Discord Experience

Discord bot responds to DMs only from authorized user IDs (allowedUsers).

Slash commands (registered automatically on startup):

| Command | Description | |---|---| | /help | Show available commands | | /status | Check Morpheus status | | /stats | Token usage statistics | | /session | Show current session info | | /session_list | List recent sessions | | /session_new | Start a new session | | /session_switch id: | Switch to existing session | | /session_rename name: | Rename current session | | /mcps | List MCP servers with tool counts | | /mcpreload | Reload MCP connections and tools | | /mcp_enable name: | Enable an MCP server | | /mcp_disable name: | Disable an MCP server | | /chronos prompt: time: | Schedule a job | | /chronos_list | List all scheduled jobs | | /chronos_view id: | View job + executions | | /chronos_disable id: | Disable a job | | /chronos_enable id: | Enable a job | | /chronos_delete id: | Delete a job |

Voice messages: Discord voice messages and audio file attachments are transcribed and processed identically to Telegram. TTS audio responses are also supported when enabled.

Setup:

1. Create an application at discord.com/developers.
2. Under Bot, enable Message Content Intent (Privileged Gateway Intents).
3. Copy the Bot Token and add it to Settings → Channels → Discord.
4. Add your Discord user ID to Allowed Users.
5. Invite the bot to a server via OAuth2 URL Generator (bot scope). The bot must share a server with you for DMs to work.

Channel Routing

Morpheus uses a central ChannelRegistry so every adapter (Telegram, Discord) registers itself at startup. Task notifications and Chronos job results are routed through the registry:

• notify_channels: [] → broadcast to all active channels
• notify_channels: ["telegram"] → Telegram only
• notify_channels: ["discord"] → Discord only
• origin_channel: 'chronos' (on tasks) → broadcast

Adding a new channel requires only implementing IChannelAdapter (channel, sendMessage, sendMessageToUser, disconnect) and calling ChannelRegistry.register() in start.ts.

Web UI

The dashboard includes:

• Dashboard with real-time 3D agent visualization and Matrix-style activity feed (live agent events via SSE)
• Chat with session management and browser notifications
• Tasks page (stats, filters, details, retry, pagination)
• Agent settings (Oracle/Sati/Neo/Apoc/Trinity/Smiths)
• MCP manager (add/edit/delete/toggle/reload)
• Sati memories (search, bulk delete, pagination)
• Usage stats and model pricing (with optional currency conversion)
• Trinity databases (register/test/refresh schema)
• Chronos scheduler (create/edit/delete jobs, execution history)
• Smiths management (add/edit/delete, real-time status, ping)
• Audit dashboard (session audit, tool call tracking, cost breakdowns with currency conversion)
• Webhooks and notification inbox (with per-webhook API key toggle for public/secured webhooks)
• Logs viewer
• Danger Zone (Settings → reset sessions, tasks, jobs, audit, or factory reset)
• Display currency setting (Settings → Interface): converts USD costs to BRL, EUR, CAD, JPY, GBP, AUD, CHF, ARS, or any custom currency

Chat-specific rendering:

• AI messages rendered as markdown
• Tool payloads shown in collapsible blocks
• SATI-related tool content grouped under SATI Memory
• per-message token badge (input/output)

Configuration (~/.morpheus/zaion.yaml)

agent:
  name: morpheus
  personality: helpful_dev

llm: # Oracle
  provider: openai
  model: gpt-4o
  temperature: 0.7
  context_window: 100
  api_key: env:OPENAI_API_KEY

sati:
  provider: openai
  model: gpt-4o-mini
  temperature: 0.3
  memory_limit: 100
  enabled_archived_sessions: true

neo:
  provider: openai
  model: gpt-4o-mini
  temperature: 0.2
  context_window: 100
  personality: analytical_engineer

apoc:
  provider: openai
  model: gpt-4o-mini
  temperature: 0.2
  working_dir: /home/user/projects
  timeout_ms: 30000
  personality: pragmatic_dev

trinity:
  provider: openai
  model: gpt-4o-mini
  temperature: 0.2
  personality: data_specialist

chronos:
  check_interval_ms: 60000   # polling interval in ms (minimum 60000)
  default_timezone: UTC      # IANA timezone used when none is specified

smiths:
  enabled: false
  execution_mode: async      # 'sync' = inline response, 'async' = background task
  heartbeat_interval_ms: 30000
  connection_timeout_ms: 10000
  task_timeout_ms: 300000
  entries: []                # list of { name, host, port, auth_token }

runtime:
  async_tasks:
    enabled: true

channels:
  telegram:
    enabled: false
    token: env:TELEGRAM_BOT_TOKEN
    allowedUsers: ["123456789"]
  discord:
    enabled: false
    token: env:DISCORD_BOT_TOKEN
    allowedUsers: ["987654321"]

ui:
  enabled: true
  port: 3333

audio:
  enabled: true
  provider: google
  model: gemini-2.5-flash-lite
  maxDurationSeconds: 300
  tts:
    enabled: false           # set to true to respond with audio
    provider: google         # openai | google
    model: gemini-2.5-flash-preview-tts
    voice: Kore              # voice name (provider-specific)
    style_prompt: ""         # optional tone/style prefix (Gemini only)

gws:                         # Google Workspace integration
  enabled: true              # sync and use GWS skills (default: true)
  service_account_json: ""   # path to Google Service Account JSON key

currency:                    # display currency for cost dashboards
  code: USD                  # ISO 4217 code (e.g. BRL, EUR)
  symbol: $                  # symbol shown in UI
  rate: 1.0                  # conversion rate from USD

logging:
  enabled: true
  level: info
  retention: 14d

Environment Variables

Provider-specific keys:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GOOGLE_API_KEY
• OPENROUTER_API_KEY
• TELEGRAM_BOT_TOKEN
• DISCORD_BOT_TOKEN
• THE_ARCHITECT_PASS

Security:

• MORPHEUS_SECRET — AES-256-GCM encryption key for Trinity database passwords and agent API keys. When set, all API keys saved via UI or config file are automatically encrypted at rest.

Generic Morpheus overrides (selected):

| Variable | Target | |---|---| | MORPHEUS_AGENT_NAME | agent.name | | MORPHEUS_AGENT_PERSONALITY | agent.personality | | MORPHEUS_LLM_PROVIDER | llm.provider | | MORPHEUS_LLM_MODEL | llm.model | | MORPHEUS_LLM_TEMPERATURE | llm.temperature | | MORPHEUS_LLM_MAX_TOKENS | llm.max_tokens | | MORPHEUS_LLM_CONTEXT_WINDOW | llm.context_window | | MORPHEUS_LLM_API_KEY | llm.api_key | | MORPHEUS_SATI_PROVIDER | sati.provider | | MORPHEUS_SATI_MODEL | sati.model | | MORPHEUS_SATI_TEMPERATURE | sati.temperature | | MORPHEUS_SATI_MAX_TOKENS | sati.max_tokens | | MORPHEUS_SATI_CONTEXT_WINDOW | sati.context_window | | MORPHEUS_SATI_API_KEY | sati.api_key | | MORPHEUS_SATI_MEMORY_LIMIT | sati.memory_limit | | MORPHEUS_SATI_ENABLED_ARCHIVED_SESSIONS | sati.enabled_archived_sessions | | MORPHEUS_NEO_PROVIDER | neo.provider | | MORPHEUS_NEO_MODEL | neo.model | | MORPHEUS_NEO_TEMPERATURE | neo.temperature | | MORPHEUS_NEO_MAX_TOKENS | neo.max_tokens | | MORPHEUS_NEO_CONTEXT_WINDOW | neo.context_window | | MORPHEUS_NEO_API_KEY | neo.api_key | | MORPHEUS_NEO_BASE_URL | neo.base_url | | MORPHEUS_NEO_PERSONALITY | neo.personality | | MORPHEUS_APOC_PROVIDER | apoc.provider | | MORPHEUS_APOC_MODEL | apoc.model | | MORPHEUS_APOC_TEMPERATURE | apoc.temperature | | MORPHEUS_APOC_MAX_TOKENS | apoc.max_tokens | | MORPHEUS_APOC_CONTEXT_WINDOW | apoc.context_window | | MORPHEUS_APOC_API_KEY | apoc.api_key | | MORPHEUS_APOC_WORKING_DIR | apoc.working_dir | | MORPHEUS_APOC_TIMEOUT_MS | apoc.timeout_ms | | MORPHEUS_APOC_PERSONALITY | apoc.personality | | MORPHEUS_TRINITY_PROVIDER | trinity.provider | | MORPHEUS_TRINITY_MODEL | trinity.model | | MORPHEUS_TRINITY_TEMPERATURE | trinity.temperature | | MORPHEUS_TRINITY_API_KEY | trinity.api_key | | MORPHEUS_TRINITY_PERSONALITY | trinity.personality | | MORPHEUS_AUDIO_PROVIDER | audio.provider | | MORPHEUS_AUDIO_MODEL | audio.model | | MORPHEUS_AUDIO_ENABLED | audio.enabled | | MORPHEUS_AUDIO_API_KEY | audio.apiKey | | MORPHEUS_AUDIO_MAX_DURATION | audio.maxDurationSeconds | | MORPHEUS_AUDIO_TTS_ENABLED | audio.tts.enabled | | MORPHEUS_AUDIO_TTS_PROVIDER | audio.tts.provider | | MORPHEUS_AUDIO_TTS_MODEL | audio.tts.model | | MORPHEUS_AUDIO_TTS_VOICE | audio.tts.voice | | MORPHEUS_AUDIO_TTS_API_KEY | audio.tts.apiKey | | MORPHEUS_AUDIO_TTS_STYLE_PROMPT | audio.tts.style_prompt | | MORPHEUS_CURRENCY_CODE | currency.code | | MORPHEUS_CURRENCY_SYMBOL | currency.symbol | | MORPHEUS_CURRENCY_RATE | currency.rate | | MORPHEUS_TELEGRAM_ENABLED | channels.telegram.enabled | | MORPHEUS_TELEGRAM_TOKEN | channels.telegram.token | | MORPHEUS_TELEGRAM_ALLOWED_USERS | channels.telegram.allowedUsers | | MORPHEUS_DISCORD_ENABLED | channels.discord.enabled | | MORPHEUS_DISCORD_TOKEN | channels.discord.token | | MORPHEUS_DISCORD_ALLOWED_USERS | channels.discord.allowedUsers | | MORPHEUS_UI_ENABLED | ui.enabled | | MORPHEUS_UI_PORT | ui.port | | MORPHEUS_GWS_ENABLED | gws.enabled | | MORPHEUS_GWS_SERVICE_ACCOUNT_JSON | gws.service_account_json | | MORPHEUS_LOGGING_ENABLED | logging.enabled | | MORPHEUS_LOGGING_LEVEL | logging.level | | MORPHEUS_LOGGING_RETENTION | logging.retention |

Precedence order:

1. Provider-specific environment variable
2. Generic MORPHEUS_* variable
3. zaion.yaml
4. Defaults

Skills

Skills are user-defined instruction templates that extend Morpheus capabilities. Each skill is a folder in ~/.morpheus/skills/ containing a single SKILL.md file with YAML frontmatter for metadata.

How Skills Work

Skills are instruction templates loaded into Oracle's context on-demand:

1. User request matches a skill's examples/description
2. Oracle calls load_skill tool with the skill name
3. Tool returns the skill's full content (SKILL.md)
4. Oracle follows the instructions using its existing tools (delegation, MCP, etc.)

Creating a Skill

mkdir -p ~/.morpheus/skills/my-skill

SKILL.md:

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
author: your-name
enabled: true
tags:
  - automation
  - example
examples:
  - "Example prompt that triggers this skill"
---

# My Skill

You are an expert at [domain]. Follow these instructions...

## Your Task
[Instructions for Oracle to execute]

Using Skills

Once a skill is loaded, Oracle follows the instructions using its available tools:

User: "Review the code in src/auth.ts"
Oracle: [loads code-reviewer skill via load_skill]
Oracle: [executes review using its tools and returns result]

Managing Skills

CLI Commands:

# View loaded skills
morpheus skills

# Reload skills from disk
morpheus skills --reload

API Endpoints:

GET    /api/skills           - List all skills
GET    /api/skills/:name     - Get skill details
POST   /api/skills/reload    - Reload from filesystem
POST   /api/skills/:name/enable   - Enable skill
POST   /api/skills/:name/disable  - Disable skill

Telegram/Discord Commands:

/skills              - List skills
/skill_reload        - Reload skills
/skill_enable <name> - Enable a skill
/skill_disable <name> - Disable a skill

Sample Skills

Example skills are available in examples/skills/:

• code-reviewer - Reviews code for issues and best practices
• git-helper - Assists with Git operations

Copy them to your skills directory:

cp -r examples/skills/* ~/.morpheus/skills/

Google Workspace (GWS) Integration

Morpheus integrates with Google Workspace via the gws CLI tool. 102 built-in skills provide structured instructions for automating Gmail, Drive, Sheets, Calendar, Docs, Tasks, and more.

Prerequisites

1. Install the gws CLI:

   npm install -g @nicholasgriffintn/google-workspace-cli

2. Create a Google Service Account:

   • Go to Google Cloud Console
   • Create or select a project
   • Enable desired APIs (Gmail, Drive, Sheets, Calendar, Docs, etc.)
   • IAM & Admin → Service Accounts → Create Service Account
   • Grant the service account Domain-Wide Delegation if needed
   • Create a JSON key and download it

3. Configure Morpheus:

   Add to ~/.morpheus/zaion.yaml:

   gws:
     enabled: true
     service_account_json: /path/to/your-service-account-key.json

   Or via environment variable:

   MORPHEUS_GWS_SERVICE_ACCOUNT_JSON=/path/to/your-service-account-key.json

How It Works

GWS skills are synced automatically at startup from the built-in gws-skills/skills/ directory to ~/.morpheus/skills/. Skills are organized in four categories:

| Category | Count | Description | |---|---|---| | Services | 17 | Core API skills (gws-gmail, gws-drive, gws-sheets, gws-calendar, gws-docs, gws-tasks, etc.) | | Helpers | 22 | Shortcut skills for common operations (gws-gmail-send, gws-drive-upload, gws-sheets-append, gws-calendar-insert) | | Personas | 10 | Role-based skill bundles (persona-exec-assistant, persona-project-manager, persona-hr-coordinator) | | Recipes | 42+ | Multi-step task sequences (recipe-create-doc-from-template, recipe-send-team-announcement, recipe-plan-weekly-schedule) |

Usage Examples

Just ask Morpheus naturally — Apoc auto-detects GWS tasks and loads the right skills:

"Send an email to [email protected] with the weekly report"
"Create a Google Sheet named 'Q2 Budget' with columns for category, amount, and notes"
"List my unread Gmail messages"
"Add an event to my calendar tomorrow at 10 AM: Team standup"
"Upload specs/spec.md to my Google Drive"

Oracle can also explicitly load skills via load_skill when needed.

Skill Customization

GWS skills use smart sync with MD5 hashing:

• New skills: Automatically copied on startup
• Unmodified skills: Updated to latest version
• User-customized skills: Preserved (your edits are never overwritten)

To customize a skill, edit the SKILL.md file in ~/.morpheus/skills/<skill-name>/. Your changes will be preserved across updates.

Docker

Add the service account JSON as a volume mount:

docker run -d \
  --name morpheus-agent \
  -p 3333:3333 \
  -e MORPHEUS_GWS_SERVICE_ACCOUNT_JSON=/root/.morpheus/gws/credentials.json \
  -v /path/to/your-key.json:/root/.morpheus/gws/credentials.json:ro \
  -v morpheus_data:/root/.morpheus \
  morpheus

Link — Document RAG

Link is a documentation specialist subagent that provides RAG (Retrieval-Augmented Generation) over user documents.

Supported formats: PDF, Markdown, TXT, DOCX

Document storage: ~/.morpheus/docs/

Embedding database: ~/.morpheus/memory/link.db (SQLite with sqlite-vec)

Using Link

Oracle automatically delegates to Link when users ask about their documents:

User: "What does my contract say about termination?"
Oracle: [delegates to Link via link_delegate]
Link: [searches indexed documents and returns answer with citations]

Managing Documents

Web UI: Navigate to /documents to upload, delete, and reindex documents.

API Endpoints:

GET    /api/link/documents           - List all documents
POST   /api/link/upload              - Upload a document
DELETE /api/link/documents/:id       - Delete a document
POST   /api/link/documents/:id/reindex - Reindex a document

Configuration

link:
  provider: openai
  model: gpt-4o-mini
  temperature: 0.2
  personality: documentation_specialist
  execution_mode: async    # 'sync' = inline, 'async' = background task
  max_results: 10          # max search results per query
  score_threshold: 0.5     # minimum similarity score (0-1)
  chunk_size: 1000         # characters per chunk
  chunk_overlap: 200       # overlap between chunks

MCP Configuration

Configure MCP servers in ~/.morpheus/mcps.json.

{
  "coingecko": {
    "transport": "http",
    "url": "https://mcps.example.com/coingecko/mcp"
  },
  "filesystem": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
  }
}

API Highlights

Public endpoints:

• GET /health
• GET /api/health
• POST /api/webhooks/trigger/:webhook_name (auth via x-api-key)

Authenticated endpoints (x-architect-pass):

• Sessions: /api/sessions*
• Chat: POST /api/chat
• Tasks: GET /api/tasks, GET /api/tasks/stats, GET /api/tasks/:id, POST /api/tasks/:id/retry
• Config: /api/config, /api/config/sati, /api/config/neo, /api/config/apoc, /api/config/trinity, /api/config/link, /api/config/chronos, /api/config/smiths
• MCP: /api/mcp/* (servers CRUD + reload + status)
• Sati memories: /api/sati/memories*
• Link documents: /api/link/documents, /api/link/upload, /api/link/documents/:id/reindex
• Trinity databases: GET/POST/PUT/DELETE /api/trinity/databases, POST /api/trinity/databases/:id/test, POST /api/trinity/databases/:id/refresh-schema
• Chronos: GET/POST /api/chronos, GET/PUT/DELETE /api/chronos/:id, PATCH /api/chronos/:id/enable, PATCH /api/chronos/:id/disable, GET /api/chronos/:id/executions, POST /api/chronos/preview
• Smiths: GET /api/smiths, GET/PUT /api/smiths/config, GET/DELETE /api/smiths/:name, POST /api/smiths/:name/ping
• Usage/model pricing/logs/restart
• Webhook management and webhook notifications

API Payload/Response Examples

Auth header for protected endpoints:

x-architect-pass: <THE_ARCHITECT_PASS>

Example POST /api/chat payload:

{
  "sessionId": "d18e23e6-67db-4ec1-b614-95eeaf399827",
  "message": "faça um ping em 8.8.8.8"
}

Example POST /api/chat response:

{
  "response": "Task created: 477fddfc-fab8-49e8-ac00-84b110e7f4ba (apoc)."
}

Example GET /api/tasks/:id response:

{
  "id": "477fddfc-fab8-49e8-ac00-84b110e7f4ba",
  "agent": "apoc",
  "status": "completed",
  "input": "Ping 8.8.8.8 and report packet stats",
  "context": "User asked from Telegram",
  "output": "Host reachable. 0% loss.",
  "error": null,
  "origin_channel": "telegram",
  "session_id": "d18e23e6-67db-4ec1-b614-95eeaf399827",
  "origin_message_id": "727",
  "origin_user_id": "5852279085",
  "attempt_count": 1,
  "max_attempts": 3,
  "available_at": 1771558600000,
  "created_at": 1771558600000,
  "started_at": 1771558601050,
  "finished_at": 1771558603030,
  "updated_at": 1771558603030,
  "worker_id": "task-worker-b16cb906",
  "notify_status": "sent",
  "notify_attempts": 0,
  "notify_last_error": null,
  "notified_at": 1771558604210
}

Example webhook trigger payload (POST /api/webhooks/trigger/:webhook_name):

{
  "event": "deploy_finished",
  "environment": "production",
  "status": "success",
  "sha": "b8a6d4f"
}

Example webhook trigger response:

{
  "accepted": true,
  "notification_id": "17ce970d-cde0-4f06-9c9f-5ef92c48aa48"
}

Complete payload and response examples for all endpoints are in DOCUMENTATION.md (Section 8. API Reference (Complete Payloads and Response Examples)).

Development

npm install
npm run build
npm run dev:cli
npm run dev:ui
npm test

Project Structure

src/
  channels/
    telegram.ts          # Telegram adapter (commands, voice, inline buttons)
    discord.ts           # Discord adapter (slash commands, voice, DM-only)
    registry.ts          # ChannelRegistry — central adapter router
  cli/         # start/stop/restart/status/doctor
  config/
    paths.ts             # Centralized PATHS constants (all DB/dir paths)
    schemas.ts           # Zod validation schemas
    manager.ts           # Config loading + env precedence
  devkit/      # Apoc tool factories
  http/        # API, auth, webhooks, server
  runtime/
    container.ts         # ServiceContainer — DI composition root
    oracle.ts            # Orchestration brain
    gws-sync.ts          # Smart sync of built-in GWS skills
    display.ts           # Activity event emission for real-time visualization
    ports/               # Port interfaces (INotifier, ITaskEnqueuer, IChatHistory, ILLMProviderFactory, IAuditEmitter)
    adapters/            # Concrete adapter implementations for ports
    skills/
      registry.ts        # SkillRegistry singleton — manages loaded skills
      loader.ts          # Discovers and parses SKILL.md files
      tool.ts            # load_skill tool for Oracle
    providers/
      factory.ts         # ProviderFactory — strategy-based LLM creation
      strategies.ts      # IProviderStrategy + per-provider implementations
    subagents/
      registry.ts        # SubagentRegistry — single source of truth
      apoc.ts            # DevKit execution subagent
      neo.ts             # MCP tool orchestration subagent
      trinity/           # Database specialist subagent
      link/              # Document RAG subagent
    chronos/
      worker.ts          # polling timer and job execution
      repository.ts      # SQLite-backed job and execution store
      parser.ts          # natural-language schedule parser
    smiths/
      registry.ts        # SmithRegistry — manages all connections
      connection.ts      # WebSocket client per Smith instance
      delegator.ts       # LLM agent with proxy tools for remote execution
    memory/
    tasks/
    tools/
    webhooks/
  ui/          # React dashboard

Related Docs

• ARCHITECTURE.md
• PRODUCT.md
• DOCUMENTATION.md

License

MIT