Skip to main content

Session continuity

Use a durable session store to resume Mecatl sessions after a process restart. The store preserves the conversation, state, usage, limits, environment, and session settings.

Availability​

Continuity is available in these forms:

  • Local JSONL: mecated --store-dir DIR persists sessions and their event-log sidecars on one host.
  • Redis: mecak8s --redis-url host:port provides the storage-free deployment's session store and durable event log.
  • Remote drivers: a session-store driver and event-log driver can be supplied independently over the driver protocol.
  • In memory: the default when no store is configured. It is useful for demos and ephemeral runs, but it does not survive restart.

A durable store is also required for persisted Subagent resume: handles and for ACP session loading. The embedded mecatui server uses its configured local state; mecatui connect uses the remote server's capabilities and cannot manage storage policy it does not own.

Persist and resume​

Use a stable store directory when starting a daemon:

mecated serve \
  --store-dir "$HOME/.local/state/mecatl/sessions" \
  --workspace "$PWD"

The store contains prompts, model output, tool arguments and results, owner metadata, and event history. Treat it as sensitive plaintext: keep the directory owner-only, do not commit it, and do not place it in a shared sync folder or unencrypted multi-user backup.

When you prompt an existing terminal session, Mecatl reopens completed sessions and recovers cancelled or failed ones. It repairs incomplete tool-call history before contacting the provider. A session awaiting approval must continue through its approval path.

The durable event log is separate from the snapshot. It records terminal and approval events even when the client disconnects, preserves compaction archives, and can restore allow_always decisions. Events omit raw approval arguments and denial reasons.

Storage choices​

DeploymentSession storeEvent logContinuity
mecated without --store-dirin memoryin memoryprocess lifetime only
mecated --store-dir DIRlocal JSONLJSONL sidecarrestart-safe on one host
mecated --session-store-urlremote gRPC driverlocal/default or separate driverdepends on driver durability
mecated --event-log-urlindependent of session storeremote gRPC driverevent replay depends on driver
mecak8s --redis-urlRedisRedissuitable for stateless pods with shared Redis

--session-store-url replaces --store-dir; the two are mutually exclusive. --event-log-url is independent and can be combined with either session-store choice. A remote backend must advertise the operations the deployment needs; missing capabilities are unavailable, not silently substituted with local file operations.

Retention and maintenance​

Durable stores grow unless the operator sets retention. Child sessions are retained by age and per-family count; main-session deletion is disabled by default and requires explicit acknowledgement. Scheduled-task fire sessions have their own retention policy.

Example operator policy:

retention:
  version: 1
  main:
    max_age: 0
    max_count: 0
  child:
    max_age: 168h
    max_count: 500
  scheduled:
    max_age: 168h
    max_count: 0
  sweep_cadence: 1h
  acknowledge_main_deletion: false

Use the server or mecatui maintenance commands to inspect storage health and produce a dry-run plan before optimizing or deleting. Do not delete files under the store with find, cron, filesystem age rules, or a shell loop. The management path understands session families, sidecars, leases, active runs, and snapshot generations; filename matching does not.

Optimization is non-destructive. Cleanup is destructive and protects unknown, active, awaiting, live, and leased sessions. A stale plan must be discarded and planned again. See Operate local session storage for the platform runbooks and authorization requirements.

Single-writer protection​

A durable snapshot must not be driven by two processes at once. When a lease backend is configured, the run-entry path acquires a per-session lease before running or approving a session. A competing owner receives HTTP 409 or gRPC FAILED_PRECONDITION. Local JSONL stores automatically use a single-host flock lease beneath the store root; this does not provide multi-host safety.

For multiple replicas, use a Kubernetes lease or remote lease driver and keep request routing compatible with the shared store. A lease loss stops renewal and prevents unsafe release assumptions. Without a suitable lease backend, destructive maintenance fails closed rather than relying on process-local liveness.

After losing a lease, a process stops accepting prompts and approvals for that session. Every five minutes, it asks the lease backend whether the lease is free and restores access only after a positive result. An unavailable backend leaves the session blocked for that pass. Without lease support, the session remains blocked until explicitly closed.

Restart and deployment limitations​

  • A durable snapshot does not preserve an in-flight Go goroutine. A process that dies while driving a session leaves recoverable state at the last save boundary; the next owner repairs the terminal state at run entry.
  • Mid-round Team coordination is not reconstructed as one team after restart, although member sessions remain individually persisted and inspectable.
  • The in-memory edit read ledger resets with its workspace/environment instance; the next run may need to read a file again before editing it.
  • Provider credentials and deployment configuration are not session history. The successor must be configured with a compatible provider and any required environment resolver.
  • Environment reattachment for non-local identities requires an explicit deployment resolver. A missing or mismatched resolver fails closed instead of silently using a local workspace.
  • Backups must include the session snapshots and their event-log sidecars using the backend's quiesced backup procedure. Do not copy live JSONL files while the service is writing them.

Next steps​