Spacemolt Multi-Agent System

An autonomous multi-agent system and development toolkit for the SpaceMolt game. Build AI agents that explore, mine, trade, craft, and interact with the game universe using LLM-powered decision making, or control the game programmatically through MCP (Model Context Protocol) integration with Claude.

Overview

The Spacemolt Multi-Agent System is a comprehensive development toolkit and automation platform that provides:

Autonomous Agent Framework

Explore the universe independently using LLM-driven decision making
Learn from experiences and build knowledge over time
Collaborate by sharing information through a persistent knowledge base
Play autonomously with specialized agent types (explorers, miners, traders, fighters, pirates, craftsmen, salvagers, prophets, random)
Persist all discoveries automatically to SQLite storage
Customize agent personalities and behaviors through JSON configuration

Claude AI Integration (MCP)

Direct Control - Play SpaceMolt through Claude using Model Context Protocol
151 Game Commands - Auto-generated tools from OpenAPI spec covering the entire game API
Crafting Intelligence - Query recipes and plan crafting based on inventory
Real-time Updates - WebSocket and SSE bridges for live game state
Multiple Bridges - Choose between WebSocket, SSE, or service-based architectures

Development Tools

Web UI - React/TypeScript frontend for monitoring and controlling agents
REST API - Programmatic control and status monitoring
Knowledge Analytics - Query system for mining discoveries, market data, and routes
Automated Agents - Pre-built specialized bots for common tasks

Each agent has a unique personality that drives their behavior, making decisions based on current situation, past experiences, and cumulative knowledge.

Key Features

🤖 Multiple Integration Modes

LLM-Powered Agents - Autonomous agents with personality-driven decision making
Claude Integration - Direct control via MCP (Model Context Protocol)
Automated Bots - Pre-built specialized agents for specific tasks
Programmatic API - REST API for custom integrations

🎮 Comprehensive Game Coverage

151 Game Commands - Auto-generated from OpenAPI spec, covering entire game API
All Game Systems - Navigation, combat, mining, trading, crafting, factions, bases
Real-time Updates - WebSocket and SSE support for live game state
Version Tracking - Automatic API version compatibility checking

🧠 Knowledge & Learning

Shared Knowledge Base - SQLite database with discoveries from all agents
Advanced Analytics - Rich deposits, depleting resources, danger zones, market trends
Experience Tracking - Complete action history for learning and improvement
Route Optimization - Fuel cost and travel time learning

🛠️ Crafting System

Recipe Database - Complete recipe and skill tree data
Material Planning - Calculate requirements for any craftable item
Profit Analysis - Find profitable crafting opportunities
MCP Integration - Query crafting data through Claude

📊 Monitoring & Control

React Web UI - Modern frontend for monitoring and control
REST API - Programmatic access to agent status and control
Agent Registry - Centralized status and coordination

🔐 Flexible Storage

Multiple Backends - File, encrypted SQLite, OS keyring for credentials
Knowledge Persistence - Long-term accumulation across sessions
Market Data Capture - Historical price and listing tracking
Captain's Log - In-game logging and note-taking

Recent Additions

Claude AI Integration (MCP)

Play SpaceMolt directly through Claude with the Model Context Protocol. Three bridge implementations (WebSocket, SSE, Service) provide 151 auto-generated tools covering the entire game API.

Automated Specialized Agents

Ten pre-built automated agents (explorer, miner, trader, fighter, pirate, salvager, craftsman, prophet, random, llm-miner) provide task-specific automation without requiring LLM setup. Perfect for focused farming, exploration, or testing.

Web-Based Monitoring

React/TypeScript frontend provides modern UI for monitoring agent activity, viewing knowledge base, and controlling agents. Includes real-time dashboards, map views, and analytics.

Advanced Crafting System

Complete crafting database with recipe queries, material requirements calculation, and profit analysis. Integrated with both MCP and agent decision-making.

Enhanced Knowledge Base

Upgraded analytics for market trends, danger zones, route optimization, and resource depletion tracking. Agents share discoveries and learn from collective experience.

Playbook System

Strategic playbooks guide agents in specialized roles (explorer, miner, trader, fighter, etc.) with proven tactics and decision patterns.

MCP Integration - Play Through Claude

Use Claude AI to play SpaceMolt directly through the Model Context Protocol:

Available Bridges:

mcp-ws-bridge - WebSocket bridge with 151 auto-generated game commands
mcp-sse-bridge - Server-Sent Events bridge for streaming updates
mcp-bridge-service - Service-based architecture for persistent connections

Claude Integration Features:

Full game API access (navigation, combat, mining, trading, crafting, missions, factions)
Recipe and skill tree queries for crafting decisions
Real-time game state updates
Market data and price analysis
Faction management and warfare
Base building and management

See cmd/mcp-ws-bridge/README.md and docs/MCP_TOOLS_IMPLEMENTATION.md for details.

Automatic Knowledge Persistence & Analytics

All agent discoveries are automatically saved to a SQLite knowledge base with advanced analytics:

Systems: Names, positions, security levels, factions, connections
POIs: Stations, asteroid belts, planets with resources
Resources: Mining locations with richness, depletion tracking, and trend analysis
Experiences: Complete action history for learning
Anomalies: Automatic detection of rich deposits, depleting resources, and opportunities
Routes: Optimization through learning fuel costs and travel times
Markets: Price analytics and best buy/sell identification
Danger Zones: Hostile activity tracking and risk assessment

Query Tools:

./scripts/query-knowledge.sh systems          # View discovered systems
./scripts/query-analytics.sh rich-deposits    # Find best mining spots
./scripts/query-analytics.sh anomalies        # View detected opportunities

Quick Start

Prerequisites

Core Requirements:

Go 1.24 or later
SpaceMolt Account - Register at spacemolt.com

For LLM-Powered Agents:

Ollama running locally with the llama3.2 model (or other LLM provider)

For Claude Integration:

Claude Desktop or Claude API access for MCP functionality

For Web UI:

Node.js 18+ and npm (for frontend development)

Installing Ollama (Optional - for LLM agents)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama service
ollama serve

# Pull the required model (in another terminal)
ollama pull llama3.2

Building

# Clone the repository
git clone https://github.com/rsned/spacemolt.git
cd spacemolt

# Build core binaries
make build

# Or build specific tools
go build -o bin/agent-server ./cmd/agent-server
go build -o bin/mcp-ws-bridge ./cmd/mcp-ws-bridge

Core Executables:

bin/agent-server - Main server for running autonomous LLM agents
bin/mcp-ws-bridge - MCP bridge for Claude integration

Specialized Automated Agents:

bin/auto-explorer - Automated exploration bot
bin/auto-miner - Automated mining bot
bin/auto-trader - Automated trading bot
bin/auto-fighter - Automated combat bot
bin/auto-pirate - Automated pirate/raider bot
bin/auto-salvager - Automated salvage bot
bin/auto-craftsman - Automated crafting bot
bin/auto-prophet - Automated prophet bot
bin/auto-random - Automated random-action bot
bin/auto-llm-miner - LLM-powered mining bot

Quick Start Guides

Choose your path:

LLM-Powered Autonomous Agents - Continue reading below for full agent setup
Claude Integration (MCP) - See cmd/mcp-ws-bridge/README.md
Automated Bots - See Automated Specialized Agents for pre-built automation
Web UI Development - See frontend/README.md

Running Autonomous LLM Agents

The agent-server is the primary way to run autonomous agents. It handles agent spawning, game connections, credential management, and graceful shutdown.

Basic Usage

# Start all agents found in data/agents/
bin/agent-server

# Start specific agents (highest priority method)
bin/agent-server --agents=explorer-7,miner-2

# Use environment variable
export SPACEMOLT_AGENTS=explorer-7,miner-2
bin/agent-server

# Use configuration file (see agents_config.yaml.example)
bin/agent-server --config=agents_config.yaml

The server will:

Discover agents based on your selection method
Load each agent's personality from data/agents/<id>/personality.json
Check for existing credentials (login) or register new agents
Connect to the game server with retry logic
Start the autonomous decision loop for each agent
Run until you press Ctrl+C for graceful shutdown

Test Agent Setup

Test an agent's personality and LLM connection without connecting to the game:

# Test the explorer-7 personality
bin/test-agent data/agents/explorer-7/personality.json

# Test with SQLite storage (default)
bin/test-agent data/agents/miner-2/personality.json --db-backend=sqlite --db-path=test-knowledge.db

# Test with in-memory storage
bin/test-agent data/agents/pirate-1/personality.json --db-backend=memory

Database Backends

The system supports two knowledge base backends:

SQLite (Default)

Persists all agent knowledge to disk, allowing discoveries to accumulate across sessions:

# Use SQLite (default)
bin/agent-server --db-backend=sqlite --db-path=spacemolt-knowledge.db

Benefits:

Knowledge persists across restarts
Agents remember systems, POIs, and connections from previous sessions
Experience history is maintained
Enables long-term learning and accumulation

Database location:

Default: spacemolt-knowledge.db in current directory
Custom path via --db-path flag

Query the database:

# View all discovered systems
sqlite3 spacemolt-knowledge.db "SELECT id, name, visit_count, last_visited FROM systems;"

# View agent experiences
sqlite3 spacemolt-knowledge.db "SELECT agent_id, type, description, time FROM experiences ORDER BY time DESC LIMIT 20;"

# View registered agents
sqlite3 spacemolt-knowledge.db "SELECT id, name, role, faction FROM agents;"

In-Memory

All knowledge is lost when the program exits:

# Use in-memory backend
bin/agent-server --db-backend=memory

Use cases:

Testing and development
Fresh start each session
No database file management

Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                          SpaceMolt Game Server                          │
│                         (game.spacemolt.com)                            │
│                                                                         │
│  WebSocket API │ HTTP API │ OpenAPI Spec                               │
└────────┬────────────┬─────────────┬──────────────────────────────────┘
         │            │             │
         │            │             │ (sync spec)
         │            │             ▼
         │            │        ┌──────────────────┐
         │            │        │ generate-mcp-    │
         │            │        │ tools            │
         │            │        └────────┬─────────┘
         │            │                 │
         │            │                 ▼ (generates 151 tools)
    ┌────┴────────────┴──────────────────────────────────────┐
    │                                                         │
┌───▼────────────┐  ┌──────────────┐  ┌────────────────────┐│
│ Agent Server   │  │ MCP Bridges  │  │  Web UI / API      ││
│                │  │              │  │                    ││
│ ┌────────────┐ │  │• ws-bridge   │  │• React Frontend    ││
│ │Agent Mgr   │ │  │• sse-bridge  │  │• REST API Server   ││
│ │            │ │  │• service     │  │• Agent Registry    ││
│ │┌──────────┐│ │  │              │  │                    ││
│ ││Runner 1  ││ │  └──────┬───────┘  └─────────┬──────────┘│
│ ││Explorer  ││ │         │                    │            │
│ │└──────────┘│ │         │                    │            │
│ │┌──────────┐│ │         ▼                    ▼            │
│ ││Runner 2  ││ │  ┌──────────────┐   ┌────────────────┐   │
│ ││Miner     ││ │  │ Claude AI    │   │   Monitoring   │   │
│ │└──────────┘│ │  │              │   │   Dashboard    │   │
│ │┌──────────┐│ │  │• Desktop     │   │                │   │
│ ││Runner 3  ││ │  │• API         │   │                │   │
│ ││Fighter   ││ │  │              │   │                │   │
│ │└──────────┘│ │  └──────────────┘   └────────────────┘   │
│ └────────────┘ │                                           │
└────────┬───────┘                                           │
         │                                                   │
         │                                                   │
    ┌────┴─────────────────────┐    ┌──────────────────────┐│
    │                          │    │                      ││
┌────────────────────▼────▼──┐  ┌───────────────┐           ││
│  Knowledge Base            │  │  Credentials  │           ││
│  (SQLite)                  │  │  Storage      │           ││
│                            │  │               │           ││
│• Systems/POIs              │  │• file         │           ││
│• Experiences               │  │• sqlite       │           ││
│• Market Data               │  │• keyring      │           ││
│• Routes                    │  │               │           ││
│• Danger Zones              │  │               │           ││
└────────────────────────────┘  └───────────────┘           ││
                                                            ││
    ┌───────────────────────────────────────────────────────┘│
    │                                                         │
┌───▼────────────┐  ┌──────────────┐                        │
│ Automated      │  │ Ollama LLM   │                        │
│ Agents         │  │              │                        │
│                │  │• llama3.2    │                        │
│• auto-explorer │  │• mistral     │                        │
│• auto-miner    │  │• other       │                        │
│• auto-trader   │  │  models      │                        │
│• auto-fighter  │  │              │                        │
│• auto-pirate   │  └──────────────┘                        │
│• auto-salvager │                                           │
│• auto-craftsman│                                           │
│• auto-prophet  │                                           │
│• auto-random   │                                           │
│• auto-llm-miner│                                           │
└────────────────┘                                           │
                                                             │
└─────────────────────────────────────────────────────────────┘

Key Components:

Agent Server - Core autonomous agent framework with LLM integration
MCP Bridges - Connect Claude AI to the game (WebSocket, SSE, Service)
Knowledge Base - Shared SQLite database for discoveries and analytics
Web UI - React frontend for monitoring and control
API Server - REST API for programmatic agent control
Automated Agents - Specialized pre-built bots for specific tasks
Credentials - Flexible storage (file, encrypted SQLite, OS keyring)

Command-Line Options

Agent Server

bin/agent-server [options]

Agent Selection:
  --agents string
        Comma-separated list of agent IDs (highest priority)
  --agents-dir string
        Directory containing agent personalities (default "data/agents")
  --config string
        Path to configuration file (default "agents_config.yaml")

Server Configuration:
  --server-url string
        Game server WebSocket URL (default "wss://game.spacemolt.com/ws")
  --max-agents int
        Maximum concurrent agents (default 10)
  --decision-interval duration
        Decision interval for agents (default 5s)

Knowledge Base:
  --db-backend string
        Backend: "sqlite" or "memory" (default "sqlite")
  --db-path string
        Path to SQLite database (default "data/spacemolt-knowledge.db")

LLM Configuration:
  --llm-url string
        LLM server URL (default "http://localhost:11434")
  --llm-model string
        LLM model name (default "llama3.2")

Credentials:
  --creds-backend string
        Backend: "file", "sqlite", or "keyring" (default "file")
  --creds-path string
        Path for credentials storage (default "data/credentials")

Environment Variables:

SPACEMOLT_AGENTS - Comma-separated agent IDs (medium priority)
SPACEMOLT_PASSPHRASE - Passphrase for SQLite credential encryption

See cmd/agent-server/README.md for detailed documentation.

Agent Test Utility

bin/test-agent [options] personality.json

Options:
  --db-backend string
        Database backend: "sqlite" or "memory" (default "sqlite")
  --db-path string
        Path to SQLite database file (default "spacemolt-knowledge.db")

How It Works

System Architecture

The agent server manages multiple autonomous agents, each with their own:

WebSocket connection to the game server (required by game architecture)
Personality defining behavior, traits, and motivations
Memory for tracking experiences and discoveries
Decision loop making autonomous choices every 5-10 seconds

Agent Lifecycle

Discovery - Server finds agents using priority order:
- CLI flags (--agents=id1,id2) → Environment (SPACEMOLT_AGENTS) → Config file → Auto-discover
Initialization - For each agent:
- Load personality from data/agents/<agent-id>/personality.json
- Check for existing credentials in provider or data/agents/<agent-id>/credentials.json
Connection & Authentication - Each agent independently:
- First time (no credentials):
  - Connects to game server
  - Registers new account with sanitized username
  - Receives authentication token
  - Saves credentials to provider (with fallback to file)
- Returning agent (has credentials):
  - Connects to game server
  - Logs in with username and token
  - Resumes previous session
- Both include retry logic: up to 3 attempts with exponential backoff (2s, 4s, 8s)
Autonomous Play Loop - Each agent continuously:
- Receives game state updates every 10 seconds (tick)
- Examines current situation (location, fuel, cargo, nearby objects)
- Queries past experiences from knowledge base
- Consults personality traits and motivations
- Uses LLM to decide next action
- Executes action through game client
- Learns from the result (success/failure)
- Updates knowledge base with discoveries
Graceful Shutdown - On Ctrl+C:
- Server stops all agent decision loops
- Closes all WebSocket connections
- Commits knowledge to database
- Exits cleanly

Tick-Based Action System

The game server operates on a 10-second tick cycle:

Action commands (mine, travel, attack, etc.): Limited to 1 per tick
Query commands (get_status, get_system, etc.): Unlimited

Agents respect this by:

Tracking the last tick when an action was executed
Only sending action commands on new ticks
Using queries freely between ticks for information gathering
Retrying immediately if an action fails (failures don't consume tick)

Credential Management

The system supports flexible credential storage:

Backends:

file - Store in <creds-path>/<agent-id>.json (default)
sqlite - Encrypted SQLite database (requires SPACEMOLT_PASSPHRASE)
keyring - OS keyring/keychain integration

Fallback mechanism:

Try primary provider (configured backend)
If provider fails, fall back to data/agents/<agent-id>/credentials.json
Load also checks fallback location if provider has no credentials

This ensures agents can always save/load credentials even if the primary backend fails.

Supported Actions

Navigation:

undock - Leave the current station
dock - Dock at a station in the current system
travel - Travel to a POI within the system
jump - Jump to another star system

Resource Gathering:

mine - Mine resources at the current location

Queries (no tick cost):

get_status - Current player/ship state
get_system - Current system details
get_ship - Detailed vessel specifications
get_skills - Full skill tree

See docs/api_commands_reference.md for the complete list of action and query commands.

Knowledge Persistence

With SQLite backend (default), agents accumulate knowledge over time:

Systems - Discovered star systems with visit counts and timestamps
Connections - Known jump routes between systems
POIs - Points of interest (stations, asteroids, anomalies)
Experiences - Agent action history and outcomes (last 100 per agent)
Agents - Registered agent metadata
Shared knowledge - All agents see each other's discoveries

Agent Personalities

The system includes diverse agent personalities, each specialized for different playstyles:

Explorers - Curiosity-driven agents who document discoveries
Miners - Resource-focused industrial miners
Traders - Commerce-focused merchants maximizing profits
Fighters - Combat specialists and bounty hunters
Pirates - Aggressive raiders plundering trade routes
Salvagers - Scavengers finding value in debris
Craftsmen - Builders and manufacturers
Engineers - Technical specialists and researchers

See data/agents/README.md for detailed documentation on creating and customizing agent personalities.

Creating New Agents

Create a new directory: mkdir -p data/agents/my-agent
Add a personality.json file with the agent's configuration
Run the agent server: bin/agent-server --agents=my-agent

Example personality structure:

{
  "name": "My Agent",
  "id": "my-agent",
  "role": "Explorer",
  "faction": "Independent",
  "traits": {
    "curiosity": 0.8,
    "risk_tolerance": 0.5,
    "altruism": 0.7,
    "patience": 0.6,
    "aggression": 0.2
  },
  "motivations": {
    "primary": "explore_unknown",
    "secondary": "help_others",
    "tertiary": "document_findings"
  },
  "skills": {
    "navigation": "intermediate",
    "scanning": "basic",
    "combat": "novice"
  },
  "biography": "A newly independent explorer seeking to make their mark."
}

Example Sessions

Scenario 1: Starting from Scratch (First Agent)

Create and register your first autonomous agent:

# 1. Make sure you have an agent personality
ls data/agents/explorer-7/personality.json

# 2. Start the agent server (will auto-register)
bin/agent-server --agents=explorer-7

# Output:
# === Spacemolt Agent Server ===
# Found 1 agent(s) to start: [explorer-7]
# ✓ Knowledge base initialized (sqlite)
# ✓ LLM client initialized (llama3.2 @ http://localhost:11434)
# ✓ Credentials provider initialized (file)
# ✓ Agent manager created (max agents: 10)
#
# === Spawning Agents ===
# [explorer-7] Spawning agent: Deep Space Seven (Explorer)
# [explorer-7] Registering new agent
# [explorer-7] ✓ Connected successfully
# [explorer-7] ✓ Registered as explorer-7-Deep_Space_Seven
# [explorer-7] ✓ Saved credentials to data/agents/explorer-7/credentials.json
# ✓ [explorer-7] Started successfully (faction: Terran)
#
# === Agent Server Started ===
# ✓ Successfully started: 1/1 agents
# Press Ctrl+C to stop all agents and exit

# The agent is now:
# - Registered in the game with a new account
# - Credentials saved to data/agents/explorer-7/credentials.json
# - Autonomously exploring and making decisions
# - Building knowledge in data/spacemolt-knowledge.db

# Let it run for 5-10 minutes, then stop with Ctrl+C
# Credentials are saved - next time it will log in automatically!

Scenario 2: Running with Existing Agents

Restart agents that have already been registered (they log in automatically):

# Start the same agent - it will login instead of register
bin/agent-server --agents=explorer-7

# Output:
# [explorer-7] Spawning agent: Deep Space Seven (Explorer)
# [explorer-7] Logging in with existing credentials
# [explorer-7] ✓ Connected successfully
# [explorer-7] ✓ Logged in successfully
# ✓ [explorer-7] Started successfully (faction: Terran)

# The agent:
# - Found existing credentials
# - Logged in with saved username/token
# - Resumed from its last position in the game
# - Remembers all previous discoveries from knowledge base

Scenario 3: Multi-Agent Fleet

Run multiple agents simultaneously with diverse specializations:

# Start a diverse fleet
bin/agent-server --agents=explorer-7,miner-2,trader-1,fighter-1

# Output shows each agent starting:
# [explorer-7] ✓ Logged in successfully (has credentials)
# [miner-2] ✓ Registered as miner-2-Ore_Crusher (first time - no credentials)
# [trader-1] ✓ Logged in successfully (has credentials)
# [fighter-1] ✓ Registered as fighter-1-Steel_Fang (first time - no credentials)
#
# ✓ Successfully started: 4/4 agents

# Watch as they collaborate:
# - Explorer-7: Maps new systems and reports discoveries
# - Miner-2: Focuses on resource extraction
# - Trader-1: Moves goods between stations
# - Fighter-1: Patrols for threats
#
# All agents share the same knowledge base!
# Explorer's discoveries help Miner find resources
# Trader benefits from both Explorer and Miner's intel

Scenario 4: Persistent Knowledge Accumulation

Demonstrate how knowledge persists across sessions:

# Session 1: Initial exploration
bin/agent-server --agents=explorer-7
# Let run for 5 minutes, then Ctrl+C

# Check what was discovered
sqlite3 data/spacemolt-knowledge.db "SELECT id, name, visit_count FROM systems;"
# Output:
# Sol|Sol|3
# Alpha-Centauri|Alpha Centauri|2
# Sirius|Sirius|1

# Session 2: Add more explorers
bin/agent-server --agents=explorer-7,explorer-8,explorer-9

# All three explorers:
# - Share knowledge of the 3 systems already discovered
# - Don't waste time re-exploring known territory
# - Can branch out in different directions
# - Build on each other's discoveries

# Session 3: Bring in specialists after exploration
bin/agent-server --agents=explorer-7,miner-2,miner-3,trader-1

# Specialists benefit from exploration:
# - Miners know which systems have rich asteroids
# - Traders know which stations buy/sell what
# - No wasted exploration time for specialists

Scenario 5: Different Configuration Methods

Use different methods to select agents:

# Method 1: CLI flags (highest priority)
bin/agent-server --agents=miner-2,miner-3

# Method 2: Environment variable
export SPACEMOLT_AGENTS=explorer-7,trader-1
bin/agent-server

# Method 3: Configuration file
cat > agents_config.yaml <<EOF
agents:
  enabled:
    - explorer-7
    - explorer-8
    - miner-2
    - miner-3
    - trader-1
EOF
bin/agent-server --config=agents_config.yaml

# Method 4: Auto-discover (all agents with personality.json)
bin/agent-server --agents-dir=data/agents
# Starts ALL agents found in data/agents/

Scenario 6: Custom Configuration

Run with custom backends and settings:

# Use SQLite for everything with encryption
export SPACEMOLT_PASSPHRASE=my-secure-password
bin/agent-server \
  --agents=explorer-7,miner-2 \
  --db-backend=sqlite \
  --db-path=data/game-knowledge.db \
  --creds-backend=sqlite \
  --creds-path=data/secure-creds.db \
  --llm-model=mistral \
  --decision-interval=3s

# Use memory mode for testing (no persistence)
bin/agent-server \
  --agents=test-agent \
  --db-backend=memory \
  --creds-backend=file

# Connect to custom game server
bin/agent-server \
  --agents=explorer-7 \
  --server-url=ws://localhost:8080/ws

Scenario 7: Handling Failures

The server continues if some agents fail:

bin/agent-server --agents=valid-agent,missing-agent,explorer-7

# Output:
# ❌ [missing-agent] Failed to load personality: file not found
# ✓ [valid-agent] Started successfully
# ✓ [explorer-7] Started successfully
#
# ⚠ Failed to start: 1 agents: [missing-agent]
# ✓ Successfully started: 2/3 agents
# Server continues running with 2 agents

# If ALL agents fail, server exits with error:
bin/agent-server --agents=nonexistent1,nonexistent2
# ❌ FATAL: All agents failed to start
# Check your configuration and credentials
# (exits with code 1)

Claude Integration via MCP

Play SpaceMolt through Claude AI using the Model Context Protocol.

Quick Start with MCP

# Build the MCP bridge
go build -o bin/mcp-ws-bridge ./cmd/mcp-ws-bridge

# Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "spacemolt": {
      "command": "/path/to/bin/mcp-ws-bridge",
      "args": ["--username", "your-username", "--token", "your-token"]
    }
  }
}

# Restart Claude Desktop
# Now Claude can control your SpaceMolt character!

Available MCP Servers

mcp-ws-bridge - Full game control (151 commands)
- Navigation, combat, mining, trading
- Faction management, base building
- Market orders, crafting, missions
- See cmd/mcp-ws-bridge/README.md
mcp-sse-bridge - Server-Sent Events variant
- Alternative architecture for streaming updates
- Same functionality as WebSocket bridge

Example Claude Interactions

You: "Check my ship status in SpaceMolt"
Claude: *uses get_status tool*

You: "Mine some asteroids"
Claude: *uses mine tool repeatedly*

You: "Travel to the nearest station and sell my cargo"
Claude: *uses travel, dock, and view_market tools*

Auto-Generated Tools

The MCP bridge tools are automatically generated from the game's OpenAPI spec:

# Update tools when game API changes
make update-mcp

# This will:
# 1. Download latest openapi.json from game server
# 2. Regenerate all 151 tool definitions
# 3. Update cmd/mcp-ws-bridge/tools_generated.go

See docs/MCP_TOOLS_IMPLEMENTATION.md for details.

Automated Specialized Agents

Pre-built bots for specific tasks (no LLM required):

Available Automated Agents

auto-explorer - Systematically explores and maps systems
auto-miner - Mines resources and sells for profit
auto-trader - Trades goods between stations
auto-fighter - Engages in combat and bounty hunting
auto-pirate - Raids and plunders (use responsibly!)
auto-salvager - Salvages wrecks and debris
auto-craftsman - Crafts items based on available materials
auto-prophet - Prophet-style agent with strategic foresight
auto-random - Random-action agent for testing and exploration
auto-recall - Recall-based agent leveraging past experiences
auto-llm-miner - LLM-powered mining with intelligent decisions

Running Automated Agents

# Build the agent
go build -o bin/auto-miner ./cmd/auto-miner

# Run with credentials
bin/auto-miner --username your-username --token your-token

# Or use credential file
bin/auto-miner --creds-file data/agents/miner-1/credentials.json

# Run in background
nohup bin/auto-miner --username your-username --token your-token > logs/miner.log 2>&1 &

See individual agent READMEs in cmd/auto-*/ for detailed documentation.

Web Interface

React Frontend

Modern web UI for monitoring and controlling agents:

# Setup frontend
cd frontend
npm install

# Development mode
npm run dev

# Production build
npm run build

See frontend/README.md for details.

Simple HTML Dashboard

Lightweight monitoring interface:

# Serve the web directory
cd web
python3 -m http.server 8080

# Visit http://localhost:8080

REST API

Programmatic control and monitoring:

# Start API server (usually part of agent-server)
bin/agent-server --enable-api --api-port 8080

# Query agent status
curl http://localhost:8080/api/agents

# Get specific agent
curl http://localhost:8080/api/agents/explorer-7

# Stream agent events
curl http://localhost:8080/api/stream

See pkg/api/ for API documentation.

Development

Running Linters

golangci-lint run ./...

Running Tests

# Run all tests
go test ./...

# Run specific package tests
go test ./pkg/knowledge/...

# Run tests with verbose output
go test ./pkg/knowledge/... -v

# Run benchmarks
go test ./pkg/knowledge/... -bench=.

Project Structure

spacemolt/
├── cmd/                        # Command-line executables
│   ├── agent-server/           # Main LLM agent server (primary)
│   ├── mcp-ws-bridge/          # MCP WebSocket bridge for Claude
│   ├── mcp-sse-bridge/         # MCP SSE bridge (alternative)
│   ├── mcp-bridge-service/     # MCP service-based architecture
│   ├── generate-mcp-tools/     # Auto-generate MCP tools from OpenAPI
│   ├── update-server-docs/     # Sync API docs from game server
│   ├── auto-explorer/          # Automated exploration bot
│   ├── auto-miner/             # Automated mining bot
│   ├── auto-trader/            # Automated trading bot
│   ├── auto-fighter/           # Automated combat bot
│   ├── auto-pirate/            # Automated pirate/raider bot
│   ├── auto-salvager/          # Automated salvage bot
│   ├── auto-craftsman/         # Automated crafting bot
│   ├── auto-prophet/           # Automated prophet bot
│   ├── auto-random/            # Automated random-action bot
│   ├── auto-recall/            # Automated recall-based bot
│   ├── auto-llm-miner/        # LLM-powered mining bot
│   ├── benchmark/              # Performance benchmarking
│   ├── daily-summary/          # Daily activity summaries
│   ├── skill-tree/             # Skill tree visualization
│   └── ...                     # 20+ additional utilities
├── pkg/                        # Reusable Go packages
│   ├── agent/                  # Agent framework & personality system
│   ├── game/                   # Game client & WebSocket communication
│   ├── credentials/            # Multi-backend credential storage
│   ├── knowledge/              # SQLite knowledge base & analytics
│   ├── llm/                    # LLM client (Ollama/OpenAI compatible)
│   ├── api/                    # REST API server
│   ├── registry/               # Agent status registry
│   ├── prompts/                # Prompt management system
│   ├── config/                 # Configuration management
│   └── version/                # Version compatibility checking
├── internal/                   # Internal packages
│   ├── protocol/               # Internal protocol definitions
│   └── ws/                     # WebSocket utilities
├── server/                     # Agent server implementation
├── frontend/                   # React/TypeScript web UI
│   ├── src/                    # React components & pages
│   ├── public/                 # Static assets
│   ├── package.json            # Node dependencies
│   └── vite.config.ts          # Vite configuration
├── web/                        # Simple HTML/JS monitoring interface
│   ├── index.html              # Dashboard
│   ├── js/                     # JavaScript
│   └── css/                    # Stylesheets
├── data/                       # Data storage (auto-generated)
│   ├── agents/                 # Agent personality configurations
│   │   ├── explorer-7/
│   │   │   ├── personality.json
│   │   │   ├── biography.md
│   │   │   └── credentials.json (auto-generated)
│   │   └── ...
│   ├── spacemolt-knowledge.db  # Shared knowledge base (SQLite)
│   └── credentials/            # File-based credentials
├── diagrams/                   # Architecture and system diagrams
├── docs/                       # Documentation (50+ documents)
│   ├── MCP_TOOLS_IMPLEMENTATION.md
│   ├── api_commands_reference.md
│   └── ...
├── playbook/                   # Strategic playbooks for agents
│   ├── explorer.md
│   ├── miner.md
│   ├── trader.md
│   ├── fighter.md
│   └── ...
├── server_docs/                # Auto-synced API documentation
│   ├── openapi.json            # OpenAPI specification
│   ├── api.md                  # API reference
│   └── skill.md                # Skill tree documentation
├── scripts/                    # Utility scripts
│   ├── query-knowledge.sh      # Query knowledge base
│   ├── query-analytics.sh      # Query analytics
│   └── ...
├── Makefile                    # Build automation
├── agents_config.yaml.example  # Example agent configuration
└── go.mod                      # Go module definition

Troubleshooting

Game Connection Issues

# Test connection to game server
curl https://game.spacemolt.com/api/version

# Verify WebSocket connectivity
# Check firewall rules allow outbound WSS connections

# Test with simple client
go run ./cmd/play-simple --username your-user --token your-token

Ollama Connection Issues (for LLM agents)

# Verify Ollama is running
curl http://localhost:11434/api/tags

# Check if model is available
ollama list

# Pull the required model
ollama pull llama3.2

# Test Ollama directly
curl http://localhost:11434/api/generate -d '{"model":"llama3.2","prompt":"test"}'

MCP Bridge Issues

# Test MCP bridge manually
bin/mcp-ws-bridge --username your-user --token your-token

# Check Claude Desktop logs
# macOS: ~/Library/Logs/Claude/
# Check for MCP server startup errors

# Verify configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Common issues:
# - Incorrect path to mcp-ws-bridge binary
# - Missing or invalid credentials
# - Firewall blocking game server connection

Agent Not Responding

Check agent-server logs for errors
Verify Ollama is running: curl http://localhost:11434/api/tags
Check agent personality file is valid JSON
Ensure agent has valid credentials in credentials.json

Database Issues

# Check database contents
sqlite3 data/spacemolt-knowledge.db ".schema"
sqlite3 data/spacemolt-knowledge.db "SELECT * FROM systems;"

# Check for corruption
sqlite3 data/spacemolt-knowledge.db "PRAGMA integrity_check;"

# Reset database (delete and start fresh)
rm data/spacemolt-knowledge.db
bin/agent-server

Agents Not Spawning

Verify agent directory exists: ls data/agents/explorer-7/
Check personality.json is valid: jq . data/agents/explorer-7/personality.json
Verify credentials if reusing existing agent
Review debug logs for specific errors
Check agent-server logs for detailed error messages

Frontend Development Issues

# Clear frontend cache
cd frontend
rm -rf node_modules package-lock.json
npm install

# Check for TypeScript errors
npm run type-check

# Verify Vite dev server
npm run dev
# Should start on http://localhost:5173

Build Issues

# Clean build cache
go clean -cache -testcache -modcache

# Update dependencies
go mod tidy
go mod download

# Rebuild everything
make clean
make build

# Check for lint errors
make lint

Contributing

Contributions are welcome! Areas of interest:

Agent Development:

New agent personalities and behaviors
Improved decision-making algorithms and strategies
Enhanced learning and knowledge sharing
Better prompt engineering for LLM agents

MCP Integration:

Additional MCP bridges and servers
Better Claude integration patterns
Tool improvements and new capabilities
Enhanced crafting intelligence

Automation:

New specialized automated agents
Improved efficiency algorithms
Better resource management
Advanced trading strategies

UI/UX:

React frontend enhancements
New monitoring dashboards
Better visualization of agent activity
Mobile-responsive designs

Infrastructure:

Performance optimizations
Better error handling and recovery
Enhanced testing coverage
Documentation improvements

Analytics:

Advanced knowledge base queries
Better market analysis
Route optimization
Profit calculation improvements

See existing code for patterns and conventions. All contributions should:

Pass make lint and make test
Include tests for new functionality
Update documentation as needed
Follow Go best practices

License

MIT License - See LICENSE file for details

Acknowledgments

Game & Platform:

SpaceMolt - The game that makes this possible
SpaceMolt community for testing and feedback

AI & LLM:

Ollama - Local LLM inference
Anthropic Claude - MCP integration and AI assistance
Model Context Protocol - Standardized AI integration

Core Libraries:

Lipgloss - Terminal styling
modernc.org/sqlite - Pure Go SQLite
coder/websocket - WebSocket client

Frontend:

React - UI framework
TypeScript - Type safety
Vite - Build tool
Tailwind CSS - Styling

Development:

golangci-lint - Go linting
Go 1.24 - Programming language
OpenAPI specification - API documentation and code generation

Name		Name	Last commit message	Last commit date
Latest commit History 811 Commits
.beads		.beads
admin		admin
cmd		cmd
data		data
diagrams		diagrams
docs		docs
examples		examples
frontend		frontend
internal/protocol		internal/protocol
pkg		pkg
playbook		playbook
reviews		reviews
scripts		scripts
server		server
server_docs		server_docs
temp		temp
web		web
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
agents_config.yaml		agents_config.yaml
agents_config.yaml.example		agents_config.yaml.example
asfas		asfas
go.mod		go.mod
go.sum		go.sum
play_as		play_as
sol-list.txt		sol-list.txt
spacemolt-server.yaml		spacemolt-server.yaml
spacemolt-server.yaml.example		spacemolt-server.yaml.example

Folders and files

Latest commit

History

Repository files navigation

Spacemolt Multi-Agent System

Table of Contents

Overview

Autonomous Agent Framework

Claude AI Integration (MCP)

Development Tools

Key Features

🤖 Multiple Integration Modes

🎮 Comprehensive Game Coverage

🧠 Knowledge & Learning

🛠️ Crafting System

📊 Monitoring & Control

🔐 Flexible Storage

Recent Additions

Claude AI Integration (MCP)

Automated Specialized Agents

Web-Based Monitoring

Advanced Crafting System

Enhanced Knowledge Base

Playbook System

MCP Integration - Play Through Claude

Automatic Knowledge Persistence & Analytics

Quick Start

Prerequisites

Installing Ollama (Optional - for LLM agents)

Building

Quick Start Guides

Running Autonomous LLM Agents

Basic Usage

Test Agent Setup

Database Backends

SQLite (Default)

In-Memory

Architecture

System Overview

Command-Line Options

Agent Server

Agent Test Utility

How It Works

System Architecture

Agent Lifecycle

Tick-Based Action System

Credential Management

Supported Actions

Knowledge Persistence

Agent Personalities

Creating New Agents

Example Sessions

Scenario 1: Starting from Scratch (First Agent)

Scenario 2: Running with Existing Agents

Scenario 3: Multi-Agent Fleet

Scenario 4: Persistent Knowledge Accumulation

Scenario 5: Different Configuration Methods

Scenario 6: Custom Configuration

Scenario 7: Handling Failures

Claude Integration via MCP

Quick Start with MCP

Available MCP Servers

Example Claude Interactions

Auto-Generated Tools

Automated Specialized Agents

Available Automated Agents

Running Automated Agents

Web Interface

React Frontend

Simple HTML Dashboard

REST API

Development

Running Linters

Running Tests

Project Structure

Troubleshooting

Game Connection Issues

Ollama Connection Issues (for LLM agents)

MCP Bridge Issues

Agent Not Responding

Packages