gateway: schedules run as a persona; MCP + SOUL.md migrate; cron timezones

Closing the gaps a config-surface audit of OpenClaw and Hermes surfaced:

- schedules gain agent: (--agent) — the job runs as that persona, bringing
  its instructions, memory, and pinned model; this is memcode's answer to
  both products' per-job model pin, routed through the persona
- schedules gain tz: (--tz) — cron evaluated in a named zone (CRON_TZ);
  OpenClaw job timezones now carry through migration
- MCP servers migrate: Hermes mcp_servers and OpenClaw mcp.servers map to
  the user-scope .mcp.json (same command/args/env/url shape); cwd and tool
  include/exclude filters become notes, never silent drops
- Hermes SOUL.md (agent identity, at the install root, previously missed)
  folds into global memory alongside memories/*

Author: timothyerwin

cmd/admin_tools.go

@@ -474,6 +474,7 @@ func adminSchedule(input json.RawMessage) (string, error) {
 		At        string `json:"at"`
 		Task      string `json:"task"`
 		DeliverTo string `json:"deliver_to"`
+		Agent     string `json:"agent"`
 	}
 	if err := json.Unmarshal(input, &in); err != nil {
 		return "", err

cmd/gateway_schedule.go

@@ -41,6 +41,8 @@ var (
 	scheduleEvery string
 	scheduleAt    string
 	scheduleTo    string
+	scheduleTZ    string
+	scheduleAgent string
 )
 
 // parseAt accepts the ways people naturally write a one-shot time — a duration
@@ -137,7 +139,8 @@ Examples:
 			}
 		}
 		settings.Schedules = append(settings.Schedules, gwconfig.Schedule{
-			Name: name, Cron: scheduleCron, Every: scheduleEvery, At: at, Task: task, DeliverTo: to,
+			Name: name, Cron: scheduleCron, Every: scheduleEvery, At: at, TZ: scheduleTZ,
+			Task: task, DeliverTo: to, Agent: strings.TrimSpace(scheduleAgent),
 		})
 		if err := gwconfig.Save(settings); err != nil {
 			return err
@@ -171,6 +174,12 @@ var gatewayScheduleShowCmd = &cobra.Command{
 			cmd.Printf("at:         %s (one-shot)\n", sc.At)
 		}
 		cmd.Printf("deliver_to: %s\n", sc.DeliverTo)
+		if sc.Agent != "" {
+			cmd.Printf("agent:      %s\n", sc.Agent)
+		}
+		if sc.TZ != "" {
+			cmd.Printf("tz:         %s\n", sc.TZ)
+		}
 		cmd.Printf("task:       %s\n", sc.Task)
 		if sc.Disabled {
 			cmd.Println("state:      disabled")
@@ -206,6 +215,12 @@ var gatewayScheduleEditCmd = &cobra.Command{
 				}
 				sc.DeliverTo = scheduleTo
 			}
+			if scheduleTZ != "" {
+				sc.TZ = scheduleTZ
+			}
+			if scheduleAgent != "" {
+				sc.Agent = strings.TrimSpace(scheduleAgent)
+			}
 			if len(args) > 1 {
 				sc.Task = strings.TrimSpace(strings.Join(args[1:], " "))
 			}
@@ -372,6 +387,8 @@ func scheduleSpecFlags(c *cobra.Command) {
 	c.Flags().StringVar(&scheduleEvery, "every", "", "interval as a Go duration, e.g. 30m or 24h")
 	c.Flags().StringVar(&scheduleAt, "at", "", "one-shot: a duration from now (30m) or a date-time (2026-03-01T09:00)")
 	c.Flags().StringVar(&scheduleTo, "to", "", "where the result is delivered: \"channel:conversation\"")
+	c.Flags().StringVar(&scheduleTZ, "tz", "", "evaluate --cron in this zone, e.g. America/Los_Angeles (default: local)")
+	c.Flags().StringVar(&scheduleAgent, "agent", "", "run as this persona (its pinned model and instructions apply)")
 }
 
 func init() {

cmd/migrate.go

@@ -16,6 +16,7 @@ import (
 	"github.com/memcode-ai/memcode/internal/authflow"
 	gwconfig "github.com/memcode-ai/memcode/internal/gateway/config"
 	"github.com/memcode-ai/memcode/internal/gateway/importer"
+	"github.com/memcode-ai/memcode/internal/mcp"
 	"github.com/memcode-ai/memcode/internal/provider"
 )
 
@@ -59,12 +60,13 @@ directory:
 			return fmt.Errorf("no OpenClaw install found (looked in %s)", strings.Join(searched, ", "))
 		}
 		return runMigration(cmd, migrationSource{
-			display:   "OpenClaw",
-			slug:      "openclaw",
-			dir:       dir,
-			channels:  openClawChannels,
-			memory:    openClawMemory,
-			schedules: importer.ImportOpenClawSchedules,
+			display:    "OpenClaw",
+			slug:       "openclaw",
+			dir:        dir,
+			channels:   openClawChannels,
+			memory:     openClawMemory,
+			schedules:  importer.ImportOpenClawSchedules,
+			mcpServers: openClawMCP,
 		})
 	},
 }
@@ -97,12 +99,13 @@ directory:
 			return fmt.Errorf("no Hermes install found (looked in %s)", filepath.Join(home, ".hermes"))
 		}
 		return runMigration(cmd, migrationSource{
-			display:   "Hermes",
-			slug:      "hermes",
-			dir:       dir,
-			channels:  hermesChannels,
-			memory:    hermesMemory,
-			schedules: importer.ImportHermesSchedules,
+			display:    "Hermes",
+			slug:       "hermes",
+			dir:        dir,
+			channels:   hermesChannels,
+			memory:     hermesMemory,
+			schedules:  importer.ImportHermesSchedules,
+			mcpServers: hermesMCP,
 		})
 	},
 }
@@ -119,6 +122,8 @@ type migrationSource struct {
 	// schedules reads the source's cron jobs into memcode schedules plus notes
 	// for anything that couldn't be carried.
 	schedules func(dir string) ([]gwconfig.Schedule, []string)
+	// mcpServers reads the source's MCP server config into memcode's shape.
+	mcpServers func(dir string) (map[string]mcp.ServerConfig, []string)
 }
 
 // runMigration performs the full migration for a source: channels, provider API
@@ -196,7 +201,26 @@ func runMigration(cmd *cobra.Command, src migrationSource) error {
 	skills, skillNotes := copySkills(filepath.Join(src.dir, "skills"))
 	res.Notes = append(res.Notes, skillNotes...)
 
-	// 4. Memory → extracted from the source's markdown stores into global memory.md.
+	// 4. MCP servers → user scope (~/.memcode/mcp.json), shared by all projects.
+	var mcpCount int
+	if src.mcpServers != nil {
+		servers, mcpNotes := src.mcpServers(src.dir)
+		res.Notes = append(res.Notes, mcpNotes...)
+		existing := mcp.UserServers()
+		for name, sc := range servers {
+			if _, ok := existing[name]; ok {
+				res.Notes = append(res.Notes, fmt.Sprintf("mcp: server %q already configured — kept yours, skipped the import", name))
+				continue
+			}
+			if err := mcp.AddServer("", mcp.ScopeUser, name, sc); err != nil {
+				res.Notes = append(res.Notes, fmt.Sprintf("mcp: server %q could not be written: %v", name, err))
+				continue
+			}
+			mcpCount++
+		}
+	}
+
+	// 5. Memory → extracted from the source's markdown stores into global memory.md.
 	memCount, err := migrateMemories(src)
 	if err != nil {
 		return err
@@ -212,6 +236,9 @@ func runMigration(cmd *cobra.Command, src migrationSource) error {
 	cmd.Printf("  API keys:  %d provider key(s) → global .env\n", len(keys))
 	cmd.Printf("  secrets:   %d credential(s) written\n", len(res.Secrets))
 	cmd.Printf("  skills:    %d imported → ~/.memcode/skills\n", len(skills))
+	if mcpCount > 0 {
+		cmd.Printf("  mcp:       %d server(s) → ~/.memcode/mcp.json (user scope, all projects)\n", mcpCount)
+	}
 	if memCount > 0 {
 		cmd.Printf("  memory:    %d entries → ~/.memcode/memory.md (global, loaded every session)\n", memCount)
 	}
@@ -249,6 +276,23 @@ func hermesChannels(dir string, env map[string]string) (importer.Result, error)
 	return importer.FromHermes(data, env)
 }
 
+// openClawMCP / hermesMCP read each source's MCP server block.
+func openClawMCP(dir string) (map[string]mcp.ServerConfig, []string) {
+	data, err := os.ReadFile(filepath.Join(dir, "openclaw.json"))
+	if err != nil {
+		return nil, nil
+	}
+	return importer.OpenClawMCPServers(data)
+}
+
+func hermesMCP(dir string) (map[string]mcp.ServerConfig, []string) {
+	data, err := os.ReadFile(filepath.Join(dir, "config.yaml"))
+	if err != nil {
+		return nil, nil
+	}
+	return importer.HermesMCPServers(data)
+}
+
 // openClawDir resolves the OpenClaw state directory: an explicit arg, then
 // OpenClaw's own default locations (honoring OPENCLAW_STATE_DIR and the legacy
 // ~/.clawdbot). Returns the found dir (or "") and the locations searched.
@@ -427,10 +471,15 @@ func openClawMemory(dir string) []string {
 // separated by bare § lines. Split on that delimiter rather than re-parsing the
 // markdown, matching Hermes's own destination parser.
 func hermesMemory(dir string) []string {
+	var entries []string
+	// SOUL.md at the install root is the agent's identity file — carry it too.
+	if data, err := os.ReadFile(filepath.Join(dir, "SOUL.md")); err == nil {
+		entries = append(entries, extractMarkdownEntries(string(data))...)
+	}
 	memDir := filepath.Join(dir, "memories")
 	files, err := os.ReadDir(memDir)
 	if err != nil {
-		return nil
+		return entries
 	}
 	var names []string
 	for _, e := range files {
@@ -439,7 +488,6 @@ func hermesMemory(dir string) []string {
 		}
 	}
 	sort.Strings(names)
-	var entries []string
 	for _, n := range names {
 		data, err := os.ReadFile(filepath.Join(memDir, n))
 		if err != nil {

docs/gateway/README.md

@@ -218,12 +218,18 @@ memcode gateway schedule disable standup      # pause; enable resumes
 memcode gateway schedule remove standup
 ```
 
+A schedule can run as a specific persona (`--agent`, or `agent:` in yaml) —
+bringing that persona's instructions, memory, and pinned model
+(`agents.<name>.model`) — and evaluate cron in a named zone (`--tz`).
+
 `cron` and `automations` are accepted aliases for `schedule` (OpenClaw/Hermes
 muscle memory), as are `create`/`rm`/`ls`/`get`/`pause`/`resume` for the verbs.
 `memcode claw migrate` and `memcode hermes migrate` carry existing cron jobs
 over where the source stores them readably (Hermes jobs.json, OpenClaw's legacy
 cron file); jobs in OpenClaw's internal database are reported with exact
-recreate instructions — never silently dropped.
+recreate instructions — never silently dropped. MCP server configs
+(`mcp_servers` / `mcp.servers`) migrate into the user-scope .mcp.json, and
+Hermes's SOUL.md identity file is folded into global memory.
 
 ## Run
 

internal/agent/tools/admin.go

@@ -71,6 +71,7 @@ func AdminDefs() []wire.ToolDef {
 				"at":         str("add only: one-shot RFC3339 time, e.g. \"2026-03-01T09:00:00Z\""),
 				"task":       str("add only: the task to run, in plain language"),
 				"deliver_to": str("add only: where the result goes, channel:conversation"),
+				"agent":      str("add only: run as this persona (its pinned model and instructions apply)"),
 			}, "action", "name"),
 		},
 		{

internal/channels/channels.go

@@ -25,6 +25,10 @@ type Inbound struct {
 	// router's per-channel allow-list doesn't apply. Chat messages leave this
 	// false and are gated by the allow-list; a signed GitHub delivery sets it.
 	Trusted bool
+	// Agent optionally forces the persona for this task. Honored only on Trusted
+	// inbounds (schedules, verified webhooks) — a chat sender picks personas via
+	// /agent, never through a message field.
+	Agent string
 	// IsDirect is true for a 1:1 direct message. A DM always triggers the agent;
 	// a message in a group/channel triggers only when the bot is addressed (see
 	// Mentioned) or the channel is configured to respond to all.

internal/gateway/config/config.go

@@ -176,13 +176,18 @@ func CanonicalRoot(path string) (string, error) {
 // fires). Disabled pauses a schedule without deleting it. This is what turns
 // the gateway from purely reactive into autonomous.
 type Schedule struct {
-	Name      string `yaml:"name"`
-	Every     string `yaml:"every,omitempty"`
-	Cron      string `yaml:"cron,omitempty"`
-	At        string `yaml:"at,omitempty"`
+	Name  string `yaml:"name"`
+	Every string `yaml:"every,omitempty"`
+	Cron  string `yaml:"cron,omitempty"`
+	At    string `yaml:"at,omitempty"`
+	// TZ evaluates Cron in a named zone ("America/Los_Angeles"); empty = local.
+	TZ        string `yaml:"tz,omitempty"`
 	Task      string `yaml:"task"`
 	DeliverTo string `yaml:"deliver_to"`
-	Disabled  bool   `yaml:"disabled,omitempty"`
+	// Agent runs this task as a specific persona — which also decides the model
+	// when that persona pins one. Empty = the conversation's current persona.
+	Agent    string `yaml:"agent,omitempty"`
+	Disabled bool   `yaml:"disabled,omitempty"`
 }
 
 // Webhook is the inbound HTTP listener shared by GitHub/WhatsApp. Defaults to

internal/gateway/importer/mcpservers.go

@@ -0,0 +1,82 @@
+// MCP server migration. Both Hermes (config.yaml mcp_servers) and OpenClaw
+// (openclaw.json mcp.servers) configure MCP servers with the same essential
+// shape memcode's .mcp.json uses — command/args/env for stdio, url for remote —
+// so they carry straight over into the user scope. Fields memcode doesn't have
+// a home for (cwd, per-server tool include/exclude filters) become notes, never
+// silent drops.
+package importer
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	yaml "go.yaml.in/yaml/v4"
+
+	"github.com/memcode-ai/memcode/internal/mcp"
+)
+
+// srcMCPServer covers the fields both products use for one server.
+type srcMCPServer struct {
+	Command string            `yaml:"command" json:"command"`
+	Args    []string          `yaml:"args" json:"args"`
+	Env     map[string]string `yaml:"env" json:"env"`
+	Cwd     string            `yaml:"cwd" json:"cwd"`
+	URL     string            `yaml:"url" json:"url"`
+	Headers map[string]string `yaml:"headers" json:"headers"`
+	Tools   struct {
+		Include []string `yaml:"include" json:"include"`
+		Exclude []string `yaml:"exclude" json:"exclude"`
+	} `yaml:"tools" json:"toolFilter"`
+}
+
+// convertMCP maps one source server to memcode's config, noting what didn't map.
+func convertMCP(name string, s srcMCPServer, notes *[]string) (mcp.ServerConfig, bool) {
+	out := mcp.ServerConfig{Command: s.Command, Args: s.Args, Env: s.Env, URL: s.URL, Headers: s.Headers}
+	if strings.TrimSpace(s.Command) == "" && strings.TrimSpace(s.URL) == "" {
+		*notes = append(*notes, fmt.Sprintf("mcp: server %q has neither a command nor a url — skipped", name))
+		return out, false
+	}
+	if strings.TrimSpace(s.Cwd) != "" {
+		*notes = append(*notes, fmt.Sprintf("mcp: server %q set a working directory (%s), which memcode doesn't carry — it runs from the project root", name, s.Cwd))
+	}
+	if len(s.Tools.Include) > 0 || len(s.Tools.Exclude) > 0 {
+		*notes = append(*notes, fmt.Sprintf("mcp: server %q had a tool include/exclude filter, which memcode doesn't carry — all its tools are available (gated by approval)", name))
+	}
+	return out, true
+}
+
+// HermesMCPServers reads the mcp_servers block of a Hermes config.yaml.
+func HermesMCPServers(configYAML []byte) (map[string]mcp.ServerConfig, []string) {
+	var hc struct {
+		Servers map[string]srcMCPServer `yaml:"mcp_servers"`
+	}
+	if err := yaml.Unmarshal(configYAML, &hc); err != nil || len(hc.Servers) == 0 {
+		return nil, nil
+	}
+	return convertAll(hc.Servers)
+}
+
+// OpenClawMCPServers reads the mcp.servers block of an openclaw.json.
+func OpenClawMCPServers(data []byte) (map[string]mcp.ServerConfig, []string) {
+	var oc struct {
+		MCP struct {
+			Servers map[string]srcMCPServer `json:"servers"`
+		} `json:"mcp"`
+	}
+	if err := json.Unmarshal(data, &oc); err != nil || len(oc.MCP.Servers) == 0 {
+		return nil, nil
+	}
+	return convertAll(oc.MCP.Servers)
+}
+
+func convertAll(servers map[string]srcMCPServer) (map[string]mcp.ServerConfig, []string) {
+	out := map[string]mcp.ServerConfig{}
+	var notes []string
+	for name, s := range servers {
+		if sc, ok := convertMCP(name, s, &notes); ok {
+			out[name] = sc
+		}
+	}
+	return out, notes
+}

internal/gateway/importer/mcpservers_test.go

@@ -0,0 +1,41 @@
+package importer
+
+import "testing"
+
+func TestHermesMCPServers(t *testing.T) {
+	yaml := `
+mcp_servers:
+  github:
+    command: gh-mcp
+    args: ["--stdio"]
+    env: {GH_TOKEN: x}
+  docs:
+    url: https://mcp.example.com/sse
+  broken:
+    cwd: /tmp
+`
+	servers, notes := HermesMCPServers([]byte(yaml))
+	if len(servers) != 2 {
+		t.Fatalf("want 2 servers, got %d (%+v)", len(servers), servers)
+	}
+	if s := servers["github"]; s.Command != "gh-mcp" || len(s.Args) != 1 || s.Env["GH_TOKEN"] != "x" {
+		t.Errorf("stdio server mapped wrong: %+v", s)
+	}
+	if s := servers["docs"]; s.URL != "https://mcp.example.com/sse" {
+		t.Errorf("remote server mapped wrong: %+v", s)
+	}
+	if len(notes) == 0 {
+		t.Error("the command-less server must produce a note")
+	}
+}
+
+func TestOpenClawMCPServers(t *testing.T) {
+	data := `{"mcp":{"servers":{"linear":{"command":"linear-mcp","toolFilter":{"include":["issues"]}}}}}`
+	servers, notes := OpenClawMCPServers([]byte(data))
+	if len(servers) != 1 || servers["linear"].Command != "linear-mcp" {
+		t.Fatalf("mapped wrong: %+v", servers)
+	}
+	if len(notes) == 0 {
+		t.Error("a dropped tool filter must produce a note")
+	}
+}