dayartcrew-web/masday-workflow-rust - Project IndopenSource

README

masday-workflow-rust

Current version: 0.3.74

Unified AI coding agent platform built on Model Context Protocol (MCP) — Rust Implementation

Migration Status: Complete. Backend migrated from TypeScript to Rust.

This is the Rust implementation of masday-workflow, providing a robust, type-safe backend with the MCP protocol. The project combines a multi-agent workflow system with 4-layer memory (working, episodic, long-term, graph) and exposes MCP tools for AI agents.

Install

One-line install (Linux/macOS/Windows Git Bash):

curl -fsSL https://github.com/dayartcrew-web/masday-workflow-rust/releases/latest/download/install.sh | bash

Auto-detects: Linux / macOS / Windows × x86_64 / aarch64

Manual download: Linux x86_64 · Windows x86_64 · All releases

📖 Full install guide: docs/install-guide.md

masday quickstart          # One-command setup (db + agents + MCP)
masday --version           # Check version
masday status              # Check health

Quick Start

Prerequisites

Rust 1.85+ (install)
mingw-w64 (for Windows cross-compile, optional)

Setup

# Clone and setup
git clone <repo-url>
cd masday-workflow-rust
bash scripts/setup.sh

# Build Rust crates
cargo build --workspace

# Run MCP server (exposes tools via stdio, uses SQLite — no database setup needed)
cargo run -p masday-mcp

# Run API server (REST endpoints, requires PostgreSQL)
DATABASE_URL=postgresql://USER:PASS@localhost:54341/masday_workflow \
  cargo run -p masday-api

# Build release binaries
cargo build --release --workspace

Note: The MCP stdio server (masday-mcp) runs in SQLite-only mode — it creates ~/.masday/data.db automatically. No PostgreSQL or API server required for local use. PostgreSQL is only needed for the API server (masday-api) or remote deployments.

Architecture

Architecture — Local Mode (stdio, SQLite)

┌──────────────┐     ┌──────────────────────────────────┐
│  MCP Client  │────>│  masday-mcp (standalone binary)   │
│  (Claude/etc)│stdio│  ┌──────────┐  ┌──────────────┐  │
└──────────────┘     │  │ 20 Tool  │  │   SQLite     │  │
                     │  │ Domains  │──│  ~/.masday/  │  │
                     │  └──────────┘  │  data.db     │  │
                     └──────────────────────────────────┘

Architecture — Remote Mode (HTTP/SSE → API → PostgreSQL)

┌──────────────┐     ┌──────────────────────────────┐     ┌─────────────┐
│  MCP Client  │────>│  API Server (masday-api)     │────>│  PostgreSQL │
│  (Claude/etc)│HTTP │  (Axum)                      │      │             │
└──────────────┘     │                              │     └─────────────┘
                     │  ┌────────┐  ┌───────────┐  │
┌──────────────┐     │  │Service │  │ 20 Tool   │  │     ┌─────────────┐
│  Dashboard   │────>│  │ Layer  │  │ Domains   │  │────>│ Redis Cache │
│  (Next.js)   │HTTP │  └────────┘  └───────────┘  │     └─────────────┘
└──────────────┘     └──────────────────────────────┘

Remote mode env vars (API server only):

DATABASE_URL="postgresql://USER:PASS@localhost:54341/masday_workflow"
MASDAY_API_KEY="your-api-key"

Rust Crates

Crate	Description
masday-core	Shared types, errors, constants
masday-db	Repository layer (sqlx, PostgreSQL, deadpool)
masday-service	Business logic (workflow, memory, policy, capability)
masday-api	HTTP API layer (Axum, REST endpoints)
masday-mcp	MCP server (stdio/local: 70 tools; HTTP/remote: 92 tools; SQLite + PostgreSQL)
masday-cli	Command-line interface

Memory Stack

Masday uses a 3-layer persistence architecture:

Layer 1: File-based Memory (Claude Code native)

~/.claude/projects/<project>/memory/
├── MEMORY.md              ← Index (auto-loaded every session)
├── decision-name.md       ← Individual memory files
└── another-fact.md

Each file = 1 fact with frontmatter (name, description, metadata.type)
MEMORY.md = table of contents loaded into context at every session start
Written by Claude via Write tool, not MCP
Best for: user preferences, critical decisions, project constraints

Layer 2: SQLite/PostgreSQL Memory (MCP `memory_*` tools)

Local:  ~/.masday/data.db → table: memories
Remote: PostgreSQL        → table: memories (with pgvector)

Store/search via mcp__masday__memory_store, memory_search, memory_recall
4-layer model: working → episodic → long-term → graph
Local mode (SQLite): Feature hashing vectorizer (not neural embeddings)
- hash(text) → [f32; 768] — non-cryptographic hash functions
- Vectors stored as BLOB in SQLite
- Cosine similarity computed in Rust code (brute-force, not SQL)
- Suitable for hundreds of memories, not thousands
Remote mode (PostgreSQL): pgvector extension for proper vector search
- ORDER BY embedding <=> $query_vector — indexable with IVFFlat/HNSW
- Scales to millions of vectors
Scoring: similarity×0.6 + importance×0.2 + recency×0.1 + usage×0.1

Layer 3: Knowledge Graph (MCP `graph_*` tools)

Local:  ~/.masday/data.db → tables: graph_nodes, graph_edges
Remote: PostgreSQL        → tables: graph_nodes, graph_edges

Concepts as nodes, relationships as edges
Jaccard similarity auto-link (threshold 0.3)

4-Layer Memory Model

  +----------------------------------------------------------+
  |                   WORKING MEMORY                         |
  |              In-process RAM, per session                 |
  +----------------------------------------------------------+
                           |
  +----------------------------------------------------------+
  |                  EPISODIC MEMORY                         |
  |            Last N messages per session                   |
  |         Persisted to EpisodicMemory table                |
  +----------------------------------------------------------+
                           |
  +----------------------------------------------------------+
  |                 LONG-TERM MEMORY                         |
  |   Scoring: similarity×0.6 + importance×0.2               |
  |            + recency×0.1 + usage×0.1                     |
  |   Memory table (SQLite BLOB or PostgreSQL pgvector)      |
  +----------------------------------------------------------+
                           |
  +----------------------------------------------------------+
  |                 KNOWLEDGE GRAPH                          |
  |             Nodes & edges, auto-linked                   |
  |        GraphNode + GraphEdge tables                      |
  +----------------------------------------------------------+

Embedding Implementation

Mode	Vectorizer	Storage	Search	Scale
Local (SQLite)	Feature hashing (768-dim)	BLOB column	Rust brute-force cosine	~100s
Remote (PostgreSQL)	ONNX nomic-embed-text or OpenAI	pgvector column	`ORDER BY <=>` (IVFFlat/HNSW index)	~millions

Workflow States

INIT --> ANALYZE --> PLAN --> EXECUTE --> VERIFY --> DONE
  |                    |    |      |          |
  |--> DONE            |    |      |--> FIX --|
  |--> FAILED          |    |--> PAUSED       |--> FIX --> EXECUTE
                       |--> FAILED    |
                                      |--> FAILED
                                         FIX --> DONE
                                         FIX --> FAILED

MCP Tools (92 HTTP / 70 stdio, across 20 domains)

The masday-mcp crate exposes 70 tools in stdio/local mode (masday mcp, SQLite) and 92 tools in HTTP/remote mode (via masday-api, PostgreSQL). The per-domain counts below are the HTTP/remote superset; stdio mode registers a subset of each domain.

Tool Namespaces

Namespace	Tools	Description
workflow	23	Workflow lifecycle, tasks, plans, parallel branches
memory	11	4-layer memory (working, episodic, long-term, graph)
semantic-search	3	Context packs, code search, fingerprinting
policy	6	Validation, drift detection, workflow audit
capability	11	Agent/skill registry, system health, scaffolding
filesystem	5	File operations (read, write, list, delete)
review	2	Review submission, decision tracking
session	3	Session state management
local	4	Local file-based state (.masday/)
git	3	Git operations
npm	2	Package manager operations
docker	3	Docker operations
cicd	3	CI/CD operations
github	3	GitHub operations
tests	1	Test runner
reminder	3	Stale/stuck workflow detection

CLI Commands Reference

Setup & Install

masday setup                # Interactive setup wizard (first-time)
masday quickstart           # One-command setup: db + migrate + install + ready
masday install              # Install masday into current project
masday install --force      # Force overwrite existing configs
masday install --standalone # Standalone mode — templates only, no build
masday install --remote URL # Connect to remote API server
masday install --skip-build # Skip cargo build, use existing binaries
masday uninstall            # Remove masday from current project

Update

masday update               # Download latest binary from GitHub Releases
                            # Copies to ~/.masday/bin/, re-syncs config

Services

masday status               # Check health of all services
masday serve                # Start API server + dashboard (port 30101)
masday serve --port 8080    # Start on custom port
masday mcp                  # Start MCP server (stdio — used by AI platforms)

Database

masday db start             # Start PostgreSQL and Redis containers
masday db stop              # Stop all containers
masday db reset             # Delete data and recreate containers

Local Embeddings

masday embed setup                    # Download ONNX Runtime + default model
masday embed setup --model bge-small-en-v1.5  # Download specific model
masday embed status                   # Show embedding setup status
masday embed remove                   # Remove all embedding artifacts
masday embed remove --models-only     # Remove models, keep ONNX Runtime

Supported models:

Model	Dimensions	Description
`all-MiniLM-L6-v2` (default)	384	Fast, good quality
`bge-small-en-v1.5`	384	BGE small variant
`bge-base-en-v1.5`	768	BGE base, higher quality

Developer Commands (from source)

# Build
cargo build --workspace              # Build all crates
cargo build --release               # Optimized release build
cargo build -p masday-mcp           # Build specific crate

# Run
cargo run -p masday-mcp             # Start MCP server
cargo run -p masday-api             # Start API server

# Test
cargo test --workspace              # Run all tests
cargo test -p masday-service        # Test specific crate
cargo test -- --nocapture          # Show test output

# Lint
cargo clippy --workspace -- -D warnings  # Lint with warnings as errors
cargo fmt --all                     # Format code
cargo fmt --all -- --check         # Check formatting

# Clean
cargo clean                         # Remove build artifacts

Release Commands

# Build and release from project root (Linux + Windows)
bash scripts/release.sh v0.3.74

# Build Linux only
bash scripts/release.sh v0.3.74 --linux-only

# Test without uploading
bash scripts/release.sh v0.3.74 --dry-run

Release Artifacts

Binary	Linux	Windows	Size
masday (CLI)	`masday-linux-x86_64` (39MB)	`masday-windows-x86_64.exe` (15MB)	CLI + MCP server wrapper
masday-mcp (standalone)	`masday-mcp-linux-x86_64` (3.3MB)	`masday-mcp-windows-x86_64.exe` (2.9MB)	Lightweight MCP server

Note: Windows binary is built without local ONNX embeddings. Use remote embedding provider (Ollama/OpenAI) on Windows.

Configuration

All config lives under ~/.masday/:

~/.masday/
├── config.toml       ← Configuration (auto-created by quickstart)
├── bin/
│   └── masday       ← CLI binary
└── data.db          ← SQLite database (local mode, auto-created)

Quickstart Wizard

Run masday quickstart for an interactive setup wizard:

Local mode — Docker PostgreSQL + migrations + API server
Remote mode — Connect to existing API server (URL + API key + optional DB URL)
Standalone mode — Agents & skills only, no DB/API

The wizard automatically:

Detects installed platforms (Claude Code, Gemini, VS Code, OpenCode)
Registers MCP servers for all selected platforms
Syncs agents, skills, and hooks
Saves config to ~/.masday/config.toml

Config File (`~/.masday/config.toml`)

mode = "local"                          # local | remote | standalone
api_url = "http://localhost:30101"
api_key = "***"
database_url = "postgresql://USER:PASS@localhost:54341/masday_workflow"
embedding_provider = "local"             # local | ollama | openai
embedding_model = "all-MiniLM-L6-v2"
embedding_dimensions = 384
port = 30101
platforms = ["claude-code"]

Environment Variables

Local mode (default) — the MCP stdio server requires no configuration. It uses SQLite at ~/.masday/data.db automatically.

Remote mode — only the API server needs env vars. MCP clients connect directly via HTTP/SSE:

# ── API Server (masday-api) ──────────────────────────────
DATABASE_URL="postgresql://USER:PASS@localhost:54341/masday_workflow"
MASDAY_API_KEY="your-api-key"           # Auth key for MCP clients

# ── Optional (both modes) ────────────────────────────────
RUST_LOG="info"                         # debug, info, warn, error
RUST_BACKTRACE="1"                      # Enable backtrace on panic

Note: The MCP binary in local mode needs zero env vars. For remote deployments, skip the binary entirely and point MCP clients directly at the API server via HTTP/SSE.

MCP Stdio Binary (Zero Config)

The masday-mcp binary runs standalone:

Database: SQLite at ~/.masday/data.db (auto-created on first run)
No PostgreSQL needed for local development
No API server needed — the binary contains all 20 tool domains directly

MCP Configuration

The scripts/setup.sh script generates MCP configuration files for different platforms:

Claude Code: .mcp.json
Gemini CLI: .gemini/settings.json
VS Code Copilot: .vscode/mcp.json

All configurations point to the Rust MCP binary: target/debug/masday-mcp (or target/release/masday-mcp for release builds).

MCP Binary Distribution

The masday binary wraps the MCP server — run masday mcp to start. A separate lightweight masday-mcp binary is also available.

Database: SQLite at ~/.masday/data.db (auto-created on first run)
No PostgreSQL needed for local development
No API server needed — the binary contains all 20 tool domains directly

Download from GitHub Releases:

# Linux — full CLI (includes MCP server)
curl -fsSL -o masday \
  https://github.com/dayartcrew-web/masday-workflow-rust/releases/latest/download/masday-linux-x86_64
chmod +x masday

# Linux — standalone MCP server only
curl -fsSL -o masday-mcp \
  https://github.com/dayartcrew-web/masday-workflow-rust/releases/latest/download/masday-mcp-linux-x86_64
chmod +x masday-mcp

# Windows PowerShell
Invoke-WebRequest -Uri "https://github.com/dayartcrew-web/masday-workflow-rust/releases/latest/download/masday-windows-x86_64.exe" -OutFile "masday.exe"

For stdio mode (recommended — SQLite, no external services needed):

{
  "mcpServers": {
    "masday": {
      "type": "stdio",
      "command": "/path/to/masday-mcp"
    }
  }
}

No environment variables needed — the binary creates ~/.masday/data.db on first run.

For remote deployments (no MCP binary needed — point directly to API server):

{
  "mcpServers": {
    "masday": {
      "url": "http://localhost:30101/mcp"
    }
  }
}

Database

Local Mode — SQLite (default for stdio)

The MCP stdio binary (masday-mcp) uses SQLite for persistence. No setup required.

Location: ~/.masday/data.db
Auto-created on first run with all required tables
Zero config — works out of the box

# Check your database
sqlite3 ~/.masday/data.db ".tables"

Remote Mode — PostgreSQL + pgvector (for API server)

The API server (masday-api) uses PostgreSQL 16 with pgvector for multi-user deployments.

# Start PostgreSQL with pgvector
docker-compose up -d

# Run migrations
cargo run -p masday-db -- migrate

Schema (16 tables, shared between SQLite and PostgreSQL)

workflows — Workflow instances
tasks — Task instances
plans — Workflow plans
memories — Long-term memories
episodic_memories — Episodic memories
graph_nodes / graph_edges — Knowledge graph
review_decisions — Review decisions
session_states — Session state
workflow_reminders — Stale/stuck reminders
parallel_branches — Parallel execution branches

Tech Stack

Layer	Technology
Language	Rust (2021 edition)
Runtime	Tokio async runtime
Database	SQLite (stdio, local mode) / PostgreSQL 16 + pgvector (API, remote mode)
API	Axum (REST HTTP)
Protocol	Model Context Protocol (MCP) over stdio
Cache	Redis (optional)
Validation	Serde + serde_json
Logging	tracing
Testing	built-in `cargo test`
CLI	clap 4.5
Error Handling	thiserror (lib) + anyhow (app)

Development Workflow

Adding New MCP Tools

Define types in masday-core/src/types.rs
Add repository methods in masday-db/src/repos/
Add service logic in masday-service/src/
Add HTTP endpoint in masday-api/src/routes/
Add MCP tool handler in masday-mcp/src/tools/
Register tool in masday-mcp/src/main.rs
Add tests in each crate's tests/ module

Running Tests

# Unit tests (all crates)
cargo test --workspace

# Integration tests
cargo test --workspace --test '*_integration'

# With output
cargo test --workspace -- --nocapture

# Specific test
cargo test -p masday-service test_workflow_create

Linting and Formatting

# Format all code
cargo fmt --all

# Check formatting (CI)
cargo fmt --all -- --check

# Lint with clippy
cargo clippy --workspace -- -D warnings

# Fix clippy warnings
cargo clippy --workspace --fix

Platform Support

Platform	Agents	Skills	MCP Config	Location
Claude Code	`.claude/agents/*.md`	`.claude/skills/*/SKILL.md`	`.mcp.json`	Project root
Gemini CLI	`.gemini/agents/`	`.gemini/skills/`	`.gemini/settings.json`	`~/.gemini/`
VS Code Copilot	`.github/agents/`	N/A	`.vscode/mcp.json`	Project root
OpenCode	`.opencode/agent/`	`.opencode/skills/`	Custom	`~/.config/opencode/`

Run bash scripts/setup.sh to install to all platforms.

Migration from TypeScript

This project was migrated from a TypeScript monorepo to Rust. The migration is complete:

Removed (TypeScript)

❌ packages/* (13 TypeScript packages)
❌ apps/agent-runner (TypeScript MCP server)
❌ apps/api (Express API)
❌ apps/desktop (Electron desktop app)
❌ pnpm-workspace.yaml (multi-package workspace)
❌ turbo.json (Turborepo build)
❌ vitest.config.ts (Vitest tests)

Replaced by Rust

✅ masday-core — replaces packages/core, packages/shared-utils
✅ masday-db — replaces packages/db, packages/store
✅ masday-service — replaces packages/workflow-engine, packages/memory, packages/policy, etc.
✅ masday-api — replaces apps/api (Express)
✅ masday-mcp — replaces apps/agent-runner (MCP server)
✅ masday-cli — replaces packages/cli

Kept (TypeScript)

🟡 apps/dashboard — Next.js frontend (still actively used)

Migration Benefits

Benefit	TypeScript → Rust
Type Safety	Runtime type errors → Compile-time guarantees
Performance	Single-threaded event loop → Multi-core Tokio
Database	Drizzle runtime checks → sqlx compile-time checks
Memory	JSON fallback → Proper API error handling
Connections	Stale connections → deadpool with health checks

Contributing

Fork the repository
Create a feature branch (git checkout -b feat/my-feature)
Follow Rust conventions:
- cargo fmt must pass
- cargo clippy must pass with no warnings
- Write tests (cargo test)
- Keep functions under 50 lines
- Use Result<T, E> for error handling
Submit a pull request

Conventions

Naming: snake_case for functions/modules, PascalCase for types
Error Handling: thiserror for library errors, anyhow for app errors
Async: Use tokio runtime, #[tokio::test] for async tests
Database: sqlx compile-time checked queries only
Serialization: serde derive for all types crossing boundaries

Troubleshooting

Build Errors

# Clear build cache
cargo clean

# Update dependencies
cargo update

# Check Rust version
rustc --version  # Should be 1.85+

Database Connection (API Server Only)

# Check PostgreSQL is running (API server mode only)
docker-compose ps

# Check DATABASE_URL in .env
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL

MCP Server Not Starting

# Check binary exists
ls -la target/debug/masday-mcp

# Build if missing
cargo build -p masday-mcp

# Check logs
RUST_LOG=debug cargo run -p masday-mcp

# Verify SQLite database
sqlite3 ~/.masday/data.db ".tables"

License

MIT

Credits

Built on top of outstanding open source software:

Core

Rust — Systems programming language
Tokio — Async runtime
Axum — Web framework
sqlx — Database toolkit
Serde — Serialization framework

Database

PostgreSQL — Advanced database
pgvector — Vector similarity search
deadpool — Connection pool

Protocol

Model Context Protocol — Agent communication standard

Frontend

Next.js — React framework
Zustand — State management
Tailwind CSS — Styling

masday-workflow-rust

masday-workflow-rust

README

masday-workflow-rust

Install

Quick Start

Prerequisites

Setup

Architecture

Architecture — Local Mode (stdio, SQLite)

Architecture — Remote Mode (HTTP/SSE → API → PostgreSQL)

Rust Crates

Memory Stack

Layer 1: File-based Memory (Claude Code native)

Layer 2: SQLite/PostgreSQL Memory (MCP memory_* tools)

Layer 3: Knowledge Graph (MCP graph_* tools)

4-Layer Memory Model

Embedding Implementation

Workflow States

MCP Tools (92 HTTP / 70 stdio, across 20 domains)

Tool Namespaces

CLI Commands Reference

Setup & Install

Update

Services

Database

Local Embeddings

Developer Commands (from source)

Release Commands

Release Artifacts

Configuration

Quickstart Wizard

Config File (~/.masday/config.toml)

Environment Variables

MCP Stdio Binary (Zero Config)

MCP Configuration

MCP Binary Distribution

Database

Local Mode — SQLite (default for stdio)

Remote Mode — PostgreSQL + pgvector (for API server)

Schema (16 tables, shared between SQLite and PostgreSQL)

Tech Stack

Development Workflow

Adding New MCP Tools

Running Tests

Linting and Formatting

Platform Support

Migration from TypeScript

Removed (TypeScript)

Replaced by Rust

Kept (TypeScript)

Migration Benefits

Contributing

Conventions

Troubleshooting

Build Errors

Database Connection (API Server Only)

MCP Server Not Starting

License

Credits

Core

Database

Protocol

Frontend

Layer 2: SQLite/PostgreSQL Memory (MCP `memory_*` tools)

Layer 3: Knowledge Graph (MCP `graph_*` tools)

Config File (`~/.masday/config.toml`)