{"id":30174222,"url":"https://github.com/seuros/activematrix","last_synced_at":"2026-03-08T07:32:07.701Z","repository":{"id":302655843,"uuid":"1013196400","full_name":"seuros/activematrix","owner":"seuros","description":"Rails-native Matrix SDK for building multi-agent bot systems and real-time communication features","archived":false,"fork":false,"pushed_at":"2025-12-30T08:48:13.000Z","size":1477,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-11T19:57:51.102Z","etag":null,"topics":["activerecord","agent-system","automation","bot-framework","chatbot","communication","matrix","matrix-api","matrix-client","matrix-protocol","matrix-sdk","messaging","multi-agent","rails","rails-engine","rails-gem","rails-integration","real-time","ruby","state-machine"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seuros.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-03T14:00:56.000Z","updated_at":"2025-12-30T08:48:16.000Z","dependencies_parsed_at":"2025-07-03T15:09:16.708Z","dependency_job_id":"3d6f066b-154e-474e-8ce0-50879292d8ae","html_url":"https://github.com/seuros/activematrix","commit_stats":null,"previous_names":["seuros/activematrix"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/seuros/activematrix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seuros%2Factivematrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seuros%2Factivematrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seuros%2Factivematrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seuros%2Factivematrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seuros","download_url":"https://codeload.github.com/seuros/activematrix/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seuros%2Factivematrix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30248887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T05:41:50.788Z","status":"ssl_error","status_checked_at":"2026-03-08T05:41:39.075Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activerecord","agent-system","automation","bot-framework","chatbot","communication","matrix","matrix-api","matrix-client","matrix-protocol","matrix-sdk","messaging","multi-agent","rails","rails-engine","rails-gem","rails-integration","real-time","ruby","state-machine"],"created_at":"2025-08-12T00:44:35.097Z","updated_at":"2026-03-08T07:32:07.689Z","avatar_url":"https://github.com/seuros.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ActiveMatrix\n\nA Rails-native Matrix SDK for building multi-agent bot systems and real-time communication features. This gem is a fork of the [matrix-sdk](https://github.com/ananace/ruby-matrix-sdk) gem, extensively enhanced with Rails integration, multi-agent architecture, and persistent state management.\n\n## Requirements\n\n- **Ruby 3.4+**\n- **Rails 8.0+**\n- **PostgreSQL 18+** (required for UUIDv7 primary keys)\n\n## Features\n\n- **Multi-Agent Architecture**: Run multiple bots concurrently with async fiber-based lifecycle management\n- **Daemon Binary**: Production-ready `activematrix` daemon with multi-process workers and health probes\n- **Rails Integration**: Deep integration with ActiveRecord, Rails.cache, and Rails.logger\n- **State Machines**: state_machines-powered state management for bot lifecycle\n- **Memory System**: Three-tier memory architecture (agent, conversation, global)\n- **Event Routing**: Intelligent event distribution to appropriate agents\n- **Client Pooling**: Efficient connection management with async semaphores\n- **Generators**: Rails generators for quick bot creation\n- **Inter-Agent Communication**: Built-in messaging between bots\n- **PostgreSQL 18 Features**: UUIDv7 primary keys, JSONB with GIN indexes\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'activematrix'\n```\n\nAnd then execute:\n\n```bash\n$ bundle install\n$ rails generate active_matrix:install\n$ rails db:migrate\n```\n\n## Multi-Agent System Usage\n\n### Creating Your First Bot\n\n```bash\n$ rails generate active_matrix:bot captain\n```\n\nThis creates a bot class in `app/bots/captain_bot.rb`:\n\n```ruby\nclass CaptainBot \u003c ActiveMatrix::Bot::MultiInstanceBase\n  set :accept_invites, true\n  set :command_prefix, '!'\n\n  command :status,\n          desc: 'Get system status',\n          args: '[component]' do |component = nil|\n    if component\n      # Check specific component\n      status = memory.get(\"status_#{component}\") || 'unknown'\n      room.send_notice(\"#{component}: #{status}\")\n    else\n      # Overall status\n      room.send_notice(\"All systems operational!\")\n    end\n  end\n\n  command :deploy,\n          desc: 'Deploy to production',\n          args: 'target' do |target|\n    # Use conversation memory to track deployments\n    deployments = conversation_memory.remember(:deployments) { [] }\n    deployments \u003c\u003c { target: target, time: Time.current }\n    conversation_memory[:deployments] = deployments\n\n    # Notify other agents\n    broadcast_to_agents(:lieutenant, {\n      type: 'deployment',\n      target: target,\n      initiated_by: agent_name\n    })\n\n    room.send_notice(\"Deploying to #{target}...\")\n  end\n\n  # Handle inter-agent messages\n  def receive_message(data, from:)\n    case data[:type]\n    when 'status_report'\n      memory.set(\"status_#{data[:component]}\", data[:status])\n      logger.info \"Received status update from #{from.agent_name}\"\n    end\n  end\nend\n```\n\n### Setting Up Agents\n\n```ruby\n# Create agent records in Rails console or seeds\ncaptain = ActiveMatrix::Agent.create!(\n  name: 'captain',\n  homeserver: 'https://matrix.org',\n  username: 'captain_bot',\n  password: 'secure_password',\n  bot_class: 'CaptainBot',\n  settings: {\n    rooms_to_join: ['!warroom:matrix.org'],\n    command_prefix: '!'\n  }\n)\n\nlieutenant = ActiveMatrix::Agent.create!(\n  name: 'lieutenant',\n  homeserver: 'https://matrix.org',\n  username: 'lieutenant_bot',\n  password: 'secure_password',\n  bot_class: 'LieutenantBot'\n)\n```\n\n### Running the Daemon\n\nThe `activematrix` binary manages your bots in production, similar to Sidekiq or GoodJob:\n\n```bash\n# Start in foreground\nbundle exec activematrix start\n\n# Start with multiple worker processes\nbundle exec activematrix start --workers 3\n\n# Start specific agents only\nbundle exec activematrix start --agents captain,lieutenant\n\n# Daemonize with PID file\nbundle exec activematrix start --daemon --pidfile tmp/pids/activematrix.pid\n\n# Check status (queries health probe)\nbundle exec activematrix status\n\n# Graceful shutdown\nbundle exec activematrix stop\n\n# Reload agent configuration\nbundle exec activematrix reload\n```\n\n**Health Probes** (for Kubernetes/Docker):\n- `GET /health` - Returns 200 if healthy\n- `GET /status` - JSON with detailed agent status\n- `GET /metrics` - Prometheus-compatible metrics\n\n```bash\ncurl http://localhost:3042/health\ncurl http://localhost:3042/status\n```\n\n### Programmatic Agent Management\n\n```ruby\n# Start all agents (blocks until shutdown)\nActiveMatrix::AgentManager.instance.start_all\n\n# Start specific agent\nActiveMatrix::AgentManager.instance.start_agent(captain)\n\n# Check status\nActiveMatrix::AgentManager.instance.status\n# =\u003e { running: 2, agents: [...], monitor_active: true }\n\n# Stop agent\nActiveMatrix::AgentManager.instance.stop_agent(captain)\n\n# Restart agent\nActiveMatrix::AgentManager.instance.restart_agent(captain)\n```\n\n## Memory System\n\n### Agent Memory (Private)\n```ruby\n# In your bot\nmemory.set('last_deployment', Time.current)\nmemory.get('last_deployment')\nmemory.increment('deployment_count')\nmemory.remember('config') { load_config_from_api }\n```\n\n### Conversation Memory (Per User/Room)\n```ruby\n# Automatically available in commands\nconversation_memory[:last_command] = 'deploy'\ncontext = conversation_context # Hash of conversation data\n\n# Track message history\nconversation_memory.add_message(event)\nrecent = conversation_memory.recent_messages(5)\n```\n\n### Global Memory (Shared)\n```ruby\n# Set global data\nglobal_memory.set('system_status', 'operational',\n  category: 'monitoring',\n  expires_in: 5.minutes,\n  public_read: true\n)\n\n# Broadcast to all agents\nglobal_memory.broadcast('alert', {\n  level: 'warning',\n  message: 'High CPU usage detected'\n})\n\n# Share between specific agents\nglobal_memory.share('secret_key', 'value', ['captain', 'lieutenant'])\n```\n\n## Event Routing\n\n```ruby\nclass MonitorBot \u003c ActiveMatrix::Bot::MultiInstanceBase\n  # Route specific events to this bot\n  route event_type: 'm.room.message', priority: 100 do |bot, event|\n    # Custom processing\n  end\n\n  route room_id: '!monitoring:matrix.org' do |bot, event|\n    # Handle all events from monitoring room\n  end\nend\n```\n\n## Basic Client Usage\n\nFor simple, single-bot applications:\n\n```ruby\n# Traditional client usage still works\nclient = ActiveMatrix::Client.new 'https://matrix.org'\nclient.login 'username', 'password'\n\nroom = client.find_room '#matrix:matrix.org'\nroom.send_text \"Hello from ActiveMatrix!\"\n```\n\n## Configuration\n\n```ruby\n# config/initializers/active_matrix.rb\nActiveMatrix.configure do |config|\n  # Agent settings\n  config.agent_startup_delay = 2.seconds\n  config.max_agents_per_process = 10\n  config.agent_health_check_interval = 30.seconds\n\n  # Memory settings\n  config.conversation_history_limit = 20\n  config.conversation_stale_after = 1.day\n  config.memory_cleanup_interval = 1.hour\n\n  # Daemon settings\n  config.daemon_workers = 2\n  config.probe_port = 3042\n  config.probe_host = '0.0.0.0'\n  config.shutdown_timeout = 30\nend\n```\n\n## Testing\n\n```ruby\n# test/bots/captain_bot_test.rb\nclass CaptainBotTest \u003c ActiveSupport::TestCase\n  def setup\n    @agent = ActiveMatrix::Agent.create!(\n      name: 'test_captain',\n      homeserver: 'https://matrix.org',\n      username: 'test_bot',\n      bot_class: 'CaptainBot'\n    )\n  end\n\n  test 'responds to status command' do\n    # Your test logic here\n  end\nend\n```\n\n## Architecture\n\nActiveMatrix implements a sophisticated multi-agent architecture:\n\n- **AgentManager**: Manages lifecycle of all bots using async fibers (start/stop/restart)\n- **AgentRegistry**: Fiber-safe registry of running bot instances\n- **EventRouter**: Routes Matrix events to appropriate bots via async queues\n- **ClientPool**: Manages shared client connections with async semaphores\n- **Memory System**: Hierarchical storage with caching\n- **State Machines**: Track agent states (offline/connecting/online/busy/error)\n\n### Models\n\nAll models are namespaced under `ActiveMatrix::`:\n\n- `ActiveMatrix::Agent` - Bot agent records with state machine\n- `ActiveMatrix::AgentStore` - Per-agent key-value storage\n- `ActiveMatrix::ChatSession` - Conversation context per user/room\n- `ActiveMatrix::KnowledgeBase` - Global shared storage\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/seuros/activematrix\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseuros%2Factivematrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseuros%2Factivematrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseuros%2Factivematrix/lists"}