CompozyOS Migration GuideCopy Anchor Link

v0.4.0 is the first stable CompozyOS release. It follows the v0.3.0 beta line, and Homebrew and npm latest move from v0.2.15 to v0.4.0.

• From any v0.3.0 beta: update in place from the app's Update action or with compozy update; no reinstall is needed. The first start applies User scope and All projects. Before that, follow Memory removal, then Networks, Bridges, and Sandbox removal, if you are upgrading from a beta that predates them.
• From v0.2: v0.2 has reached end of life and receives no further releases. The numbered sections below describe the v0.2.15 clean-state transition.

CompozyOS v0.3 is a hard cut, not an in-place compatibility release. It keeps the compozy binary and the .compozy/tasks/ task format, but replaces the workflow runner with a daemon-owned environment for creating, automating, and supervising agent work. Runtime databases, command names, extension contracts, and review behavior do not carry forward automatically.

This guide uses v0.2.15 (8f8908afd70c731b815e20282bacad05aa026827) as the legacy baseline. Back up your global and workspace .compozy/ directories before changing installations.

User scope and All projects (v0.4.0)Copy Anchor Link

v0.4.0 upgrades in place. Nothing needs editing by hand and no data is deleted. Stop the daemon and back up COMPOZY_HOME (including compozy.db, its SQLite sidecars, and workspaces/) before the first start, as for any release.

What the first start changesCopy Anchor Link

• The hidden COMPOZY_HOME project becomes User. Earlier releases ran personal tasks, automations, Loop judges, and managed Goals inside a hidden project registered at COMPOZY_HOME (usually ~/.compozy). The upgrade moves that work, and any leftover home-folder registration, into the User scope of each profile that owns it. Session identities and creation stamps are unchanged. Terminal history and retained recordings are copied per profile and verified before the old journal folder is renamed with a .migrated suffix. Desktop layouts are copied when no User layout exists. The hidden project is removed only after every store reports completion and no table still references it. An interrupted upgrade resumes on the next start.
• Exceptions stay projects. A hidden project that has worktrees, or that a Loop-targeting automation points at, stays an ordinary project (keep_project, logged once). Reach it by its ID or name.
• Nothing is dropped. Rows that cannot move (name collisions with existing User rows, coordination rows, extension bindings and dev links, model discovery contexts) are kept in the user_scope_migration_archive table with their original JSON and source identity; progress is in user_scope_migrations. Colliding automation names are renamed <name> (migrated). Keep .migrated folders until you no longer need a rollback.
• Reserved project names are renamed. user, global, and names starting with @ are reserved. Existing projects with those names are renamed deterministically (leading @ stripped, -project appended when the result is empty or reserved, then the usual uniqueness suffix). Workspace IDs never change.
• Automation run history gains attribution. Older runs whose job or trigger still exists record its project as derived; the rest stay unknown and read "Unknown project".

Update scripts and integrationsCopy Anchor Link

To move off shell.sessions.scope now:

compozy config unset shell.sessions.scope
compozy config set shell.sessions.group_by project

In v0.5.0 the daemon converts scope = "all-workspaces" into group_by = "project" when grouping is unset, drops the key with a logged notice, and removes it from config.toml on the next apply.

Agent definitions with workspace_accessCopy Anchor Link

workspace_access: unrestricted is a new AGENT.md field. Daemons older than v0.4.0 decode AGENT.md strictly and refuse files that contain it, so upgrade every daemon that reads a shared agents folder before adding the field. The field reintroduces a grant for this one purpose, superseding the earlier rule that cross-workspace access has no grant vocabulary. Tasks, automations, and Loop runs saved before v0.4.0 carry no grant ceiling; save them again as the operator if a granted agent should keep its access when they run.

Memory removalCopy Anchor Link

The memory removal release removes the memory feature family from CompozyOS: agent memory, Dream consolidation, the Knowledge app, and the workspace knowledge/ prompt injector. It also removes CompozyOS's own session compaction, which relied on the memory checkpoint service. The removal covers the daemon, CLI, HTTP/UDS, native tools, MCP, the extension Host API and SDKs, configuration, Web UI, and documentation. This is an intentional breaking change with no compatibility aliases or deprecation window. It does not block the upgrade: the daemon starts on an upgraded home without any manual step, and leftovers in your own files are archived or ignored instead of rejected.

No replacement memory or knowledge feature is provided. Authored context remains AGENT.md, SOUL.md, HEARTBEAT.md, and skills. Sessions, agents, Loops, Tasks, and Goals keep working.

Before upgradingCopy Anchor Link

Stop the daemon and back up compozy.db together with the global state directory, workspace .compozy/ directories, and config.toml. Memory database state is dropped permanently and the new release has no reader or export command for it: the index, decision log, recall signals, Dream run history, and extractor state. Export anything you need to retain with the previous release first. The Markdown memory files are not database state and stay on disk. Do not run an older binary against the upgraded databases; restore the complete pre-upgrade backup to roll back.

What the first start changesCopy Anchor Link

Nothing needs editing by hand. On the first start:

• Global database migration 00130. 00130_retire_memory.sql drops the memory tables, their full-text indexes, and goose_db_version_memory; deletes memory.consolidated automation triggers together with their overlays, catalog rows, gateway ingress bindings, and owned secret refs (run history stays); and deletes legacy dream sessions and the memory-extractor and checkpoint-summary child sessions with their dependent rows. Session directories on disk are not removed.
• Session database migration 00009. 00009_unarchive_compaction_spans.sql restores the events that the removed CompozyOS compaction had archived, together with their transcript entries and tool routes, so old compacted sessions show their full history again in the transcript, search, outline, and fork and rewind anchors. Events archived by a conversation rewind stay archived.
• Config archive. When the global, profile, or workspace config.toml contains [memory] (every sub-table), [roles.dream], [roles.checkpoint_summary], [roles.memory_extractor], [roles.memory_controller], [session.compaction], an [[automation.triggers]] entry with event = "memory.consolidated", or hook-matcher keys compaction_reason / compaction_strategy, the daemon removes them and appends them, commented, at the end of the same file under # Archived retired memory and compaction settings; these values are inactive.. The rewrite is atomic and lossless, logged once as config.retired_keys_archived, and a second start changes nothing. Archiving these memory and compaction settings never blocks a start: if the file changes while it is being rewritten, or the daemon cannot write it (for example a read-only directory), the daemon logs a config.retired_keys_archive_failed warning with the path and the reason, loads with the retired values inactive, leaves the file untouched, and tries again on the next load. Explicitly setting a retired key (compozy config set memory.enabled true) is still refused.
• Ignored leftovers. memory_policy in a SOUL.md is ignored: it is not rendered, never raises a diagnostic, and the file is not rewritten (the Web editor drops it on the next save). Retired compozy__memory* tool and toolset IDs in an agent, profile, or session tool policy are dropped with a tools.retired_ids_ignored warning. An extension manifest that declares memory.backend, memory/recall|store|forget, or the memory.read|write consent still loads with those entries dropped and one extension.retired_entries_ignored warning; an extension automation resource whose trigger event is memory.consolidated is skipped with the same warning and the rest of the extension loads. The hook-matcher keys compaction_reason and compaction_strategy in AGENT.md and SKILL.md hook declarations are ignored with one agent.retired_entries_ignored or skills.retired_entries_ignored warning per file, and the file is left untouched.
• Saved desktop layouts. The Knowledge window is dropped from saved layouts, including persisted layout resources, a Settings window on /settings/memory moves to /settings, and the reconciled layout is saved once.
• Files stay. No file is deleted or rewritten: Markdown memory under ~/.compozy/profiles/<name>/memory/, <workspace>/.compozy/memory/, and agent memory/ directories (including _inbox/ candidates the extractor never consumed), <workspace>/knowledge/ directories, and ledger.jsonl session files. Nothing reads them any more. Copy what you want to keep and delete the rest whenever you like. The session directories of the deleted legacy sessions also stay in place; the daemon never recatalogs them and logs observe.session_recovery_skipped once per session.

Removed surfacesCopy Anchor Link

• CLI: the whole compozy memory tree (list, show, write, edit, delete, search, reindex, history, health, promote, reset, reload, scope-show, decisions, recall, dream, daily, extractor, provider, adhoc). compozy status -o json no longer has a memory object and its schema_version is 2026-10-07. compozy roles list shows coordinator and auto_title only; compozy profile delete --dry-run has no memory_entries; compozy extension init --template memory-backend-ts is gone.
• HTTP/UDS: the 40 /api/memory*, /api/settings/memory, and /api/workspaces/{id}/memory/** operations answer 404 like any unknown path. dream leaves the session type enum, the four memory roles leave the settings and roles payloads, and component=memory is an invalid event filter.
• Native tools and MCP: the 35 compozy__memory_* tools, the compozy__memory and compozy__memory_admin toolsets, and compozy_host__memory__recall|store|forget. These IDs are retired permanently.
• Extensions and SDKs: the Host API memory/recall|store|forget (JSON-RPC -32601), the memory.backend capability, consent atoms memory:read|write, the marketplace ceiling memory.read, the memory-backend-ts scaffold, and the TypeScript and Go SDK memory members and types. Rebuild extensions against the current SDK.
• Configuration and automation: [memory], [session.compaction], the four memory roles, and the memory.consolidated trigger event (creating a trigger on it fails validation). The auto-title role keeps working; its deadline is a fixed 60 seconds.
• Web: the Knowledge app and /knowledge, Settings → Memory, the Home Memory tile, and the memory role panels. Settings now has 18 sections.
• Prompts: agents no longer receive memory startup content, per-turn recall, or the <workspace-knowledge-snapshot> block.

Compaction changesCopy Anchor Link

CompozyOS no longer compacts a session itself: no threshold, timer, or usage reading makes it summarize, archive, or start a child session. The agent owns its context window.

• Bounded rebuilds. Every replay of a transcript into a new agent session (resume without native load, runtime or model replacement, account fallback, prompt recovery, continue/fork) is bounded by [session.derive] max_replay_bytes and max_message_bytes, keeps the newest messages, pins the earliest user message, states that the workspace is authoritative, and points to compozy__session_history for the omitted history.
• Observed agent compaction (experimental). When the agent supports the ACP compaction capability, each compaction appears as one compaction item in the session transcript and Web timeline, as compaction snapshot rows plus one session.compaction_fired event with the new payload (compaction_id, trigger, context_used, context_size) in compozy session events and compozy session history, and as one usage marker. pressure_threshold and the marker fields from_sequence, to_sequence, pressure, strategy, and span_archived are removed. Events recorded before the upgrade stay in the ledger as opaque history and never produce a marker.
• Compact now (experimental). compozy session compact <session-id>, POST /api/workspaces/{workspace_id}/sessions/{session_id}/compact, the native tool compozy__session_compact, and the Compact now button in the Web context rail ask the agent to compact through the command it advertises (/compact or /compress). The Goal executor uses the same command. See Context compaction.
• Hooks. context.pre_compact and context.post_compact are observation-only: only labels can be patched, and the deny, summary, and context_blocks patches are removed. The matcher keys compaction_reason and compaction_strategy become compaction_trigger (requested or agent).

Update scripts, extensions, and automationCopy Anchor Link

Stop calling the removed commands, routes, tools, and SDK members; there are no aliases. Remove memory tool entries from AGENT.md toolsets/tools and from profile and session tool policies when convenient, delete memory_policy from SOUL.md, remove memory.backend and memory/* entries from extension manifests, and replace compaction_reason / compaction_strategy hook matchers with compaction_trigger; AGENT.md and SKILL.md hook matchers are ignored with a warning for now, but an AGENT.md hook cannot target the context events at all, so declare those hooks in config.toml, an extension manifest, or a skill. Tool-policy wildcards such as compozy__memory* are not rewritten; they simply match nothing. The leftovers are tolerated for now but not forever.

Temporary compatibilityCopy Anchor Link

The config archive, the memory_policy ignore rule, the retired tool-ID filter, the extension manifest and automation-resource filters, and the AGENT.md and SKILL.md hook-matcher filters are one shim generation. They are removed in v0.6.0. Run at least one release that contains them before upgrading to v0.6.0, and clean the leftovers listed above so nothing depends on them.

Networks, Bridges, and Sandbox removalCopy Anchor Link

The package cleanup release removes the CompozyOS Network, Bridges, and managed Sandbox products across the daemon, CLI, HTTP/UDS, native tools, SDKs, configuration, Web UI, and documentation. This is an intentional breaking change with no compatibility aliases or deprecation window.

Before upgradingCopy Anchor Link

Stop the daemon and back up its global state directory, workspace .compozy/ directories, and config.toml. Export any Network messages or Bridge delivery records you need to retain using the previous release. The new release has no reader or recovery command for retired state. Do not run an older binary against the upgraded database; restore the complete pre-upgrade backup to roll back.

Database migration 00121Copy Anchor Link

Opening an existing database applies 00121_retire_network_bridges_sandbox.sql transactionally. It permanently drops Network channels, threads, messages, subscriptions, participation, coordination, audit/timeline projections, and wake queues; Bridge instances, routes, delivery history, secret bindings, target directories, and task subscriptions; and notification presets and their delivery permits. Network wake runs, their dependent records, and triage state owned by retired Network actors are removed; triage state belonging to retained actors is preserved. References from retained Tasks and task events to those removed runs are cleared. Product-specific Network, Bridge, and Sandbox fields are removed from retained runtime records. Historical Loop channel-message events are removed.

Ordinary sessions and their local histories, Tasks and ordinary task runs, execution profiles, Loops and Goal nodes, memory, workspaces, attention notifications, and task status cursors remain. Agent SOUL.md and HEARTBEAT.md documents, revisions, schedules, and wake policy remain supported. Session supervision and task lease heartbeats also remain supported.

Update configuration and integrationsCopy Anchor Link

Remove product configuration for Network, Bridges, and managed Sandboxes, including default Sandbox selection and remote Sandbox drivers. Remove retired fields from session, Task, profile, job, and Loop requests. Scripts must stop calling retired CLI commands, routes, native tools, and SDK methods; there are no aliases. Rebuild extensions against the current SDK. Agent capability catalogs remain local authoring inputs for Task worker selection.

Gateway and webhooks remain supported. Extensions declare their reachability requirement with [gateway] and explicit permission atoms:

[gateway]
permissions = ["gateway.private", "gateway.public"]

Declare only the permissions the extension needs. Install, update, and development-link callers confirm the returned gateway_requirement_digest using --confirm-gateway-requirement in the CLI or confirm_gateway_digest in the request. The database migration retains the recorded digest, confirmer, and confirmation time under the Gateway names. A changed requirement requires a matching confirmation; removal of Network must not grant public ingress implicitly. Legacy network_participation manifests are not converted or accepted as Gateway declarations. Rebuild those extensions with [gateway], inspect the new requirement digest, and confirm it before using Gateway capabilities. The retained database tuple preserves the previous consent record; it does not authorize a different manifest or bypass confirmation after this hardcut.

Provider-native execution permissions and sandbox policies, operating-system isolation, MCP/ACP stdio adapters, and the Herdr hook IPC bridge are independent of the removed products.

1. Command mapCopy Anchor Link

Install the current release through one of these paths:

brew install compozy/compozy/compozy

npm install -g @compozy/cli

curl -fsSL https://compozy.com/install.sh | sh

go install github.com/compozy/compozy@<release-tag>

The hosted installer pins the latest published release for you. For go install, copy the exact pinned tag from the latest release notes.

Workspace-scoped v0.3 commands infer the active workspace in this order: positional workspace ref, --workspace, COMPOZY_WORKSPACE, validated session identity, then the current working directory. Run commands anywhere under a registered workspace root. Use --workspace <id|name|path> only to override that context.

The primary delivery mappings are:

The complete v0.2 flag-family disposition is:

2. Configuration translation contractCopy Anchor Link

No live config migrator ships in the current release. This section is the manual translation contract. Apply global and workspace changes separately. v0.3 precedence is per-run value, then workspace [loops.inputs.<loop>], then global input default, then the Loop definition default. Explicit false, 0, and valid empty strings remain present values.

Provider mapping is exact: codex → codex, claude → claude, cursor-agent → cursor, opencode → opencode, pi → pi, gemini → gemini, and copilot → copilot. Drop droid, devin, kiro, and legacy-only reasoning ultra as unsupported_destination_value; never silently alias or weaken them. kiro is no longer a built-in provider; an operator who still uses Kiro CLI can declare it as a custom provider with command = "kiro-cli-chat acp". The v0.2 schema had no persisted defaults.provider or defaults.pr, so do not fabricate either.

You can manage an input default manually now:

cd /absolute/project/root

compozy config set loops.inputs.implement-tasks.auto_commit false \
  --scope workspace

compozy config get loops.inputs.implement-tasks.auto_commit

compozy config unset loops.inputs.implement-tasks.auto_commit \
  --scope workspace

These commands use cwd discovery. Set COMPOZY_WORKSPACE for a shell-wide override or pass --workspace <id|name|path> for a one-command override.

HTTP and UDS expose exact-scope inspect, replace, set, and delete operations under /api/workspaces/{workspace_id}/loops/{name}/input-defaults. Configured values are checked against the named Loop only during dry-run or submission, because Loops can enroll dynamically.

3. Config migrator statusCopy Anchor Link

compozy migrate config does not ship in the current release. Do not run that command, build automation around it, or assume the daemon will read v0.2 config as a fallback.

To move from v0.2:

1. Back up ~/.compozy/ and each <workspace>/.compozy/ directory.
2. Translate the config manually with the table above into a fresh v0.3 config.
3. Move legacy-owned agents/ and extensions/ directories out of the colliding .compozy/ namespace. Do not let v0.3 enroll their old formats.
4. Start v0.3 with clean runtime state; do not copy global.db, daemon sockets, locks, logs, run directories, or other v0.2 state into the new runtime.
5. Keep the backup until the new journey and required task evidence have been verified.

The old v0.2 compozy migrate command is unrelated. It converts XML-tagged task and review artifacts into frontmatter. If your task tree still contains <task_context> or <review_context>, run the v0.2.15 converter before replacing the CLI. No v0.3 config command replaces that artifact conversion.

4. Where the skills wentCopy Anchor Link

The v0.3 dev-cycle extension bundles exactly eight retained process skills:

• cy-create-spec
• cy-create-tasks
• cy-execute-task
• cy-workflow-memory
• cy-review-round
• cy-fix-reviews
• cy-final-verify
• git-rebase

They are versioned resources of the extension and are exposed through the runtime's skill/resource surfaces. The legacy compozy skill is retired; the new official skills/compozy/ guide is the runtime and contributor manual, not one of the nine dev-cycle process skills.

The v0.2 compozy setup helper copied or symlinked public skills and reusable AGENT.md files into external agent-CLI homes. v0.3 has no equivalent external-CLI installer. Use compozy skill for daemon-managed local or marketplace skills, compozy agent for runtime agent definitions, and compozy extension for versioned extension resources. Copying the old installed files forward does not make them compatible.

Process guidance must not call tasks validate: that command is removed and loop validate checks Loop definitions, not task artifacts. Use the validation gates that the selected Loop and repository actually provide.

5. Deferred and removed surfacesCopy Anchor Link

This table is the exhaustive legacy-surface ledger. “Removed” means no compatibility alias, route, loader, or hidden fallback ships in v0.3.

The web route mapping is a semantic mapping, not a redirect promise. v0.3 intentionally ships no legacy route aliases.

Legacy README anchor dispositionCopy Anchor Link

The v0.2 README accumulated inbound links from package registries, search results, and external articles. The v0.3 front door keeps each semantic successor at the matching heading. Removed pipeline-era sections have no empty heading stub; their disposition is explicit here.

6. License metadata correctionCopy Anchor Link

CompozyOS remained MIT-licensed. Some old distribution metadata incorrectly stamped artifacts as BSL-1.1; v0.3 corrects that metadata to match the repository's MIT license. This is a distribution metadata correction, not a relicense.

7. Go library and SDK close-outCopy Anchor Link

v0.3 is distributed as the CompozyOS binary and runtime, not as a compatibility release of the old public Go library. Code importing the root facade, pkg/compozy/events, pkg/compozy/runs, or the old Go extension SDK will not compile against v0.3. Pin the final v0.2.x module while you maintain that integration, or redesign it against v0.3 CLI/HTTP/UDS/tool/extension contracts.

Extension authors use the published @compozy/extension-sdk npm package or the github.com/compozy/compozy/sdk/go module. Both are version-matched to the daemon. Scaffold current projects with compozy extension init.

8. Domain, channels, and clean stateCopy Anchor Link

https://compozy.com serves the v0.3 site from the single cut. The former domain retires without a redirect layer. Legacy source and release collateral remain frozen on the legacy/v0.2 branch; v0.2 has reached end of life and receives no further releases.

Release channels:

• Homebrew (compozy/compozy/compozy), npm @compozy/cli, the hosted installer, and versioned go install all serve the current stable release, starting with v0.4.0;
• an install on any v0.3.0 beta updates in place to the latest stable release from the app's Update action or compozy update.

Start runtime history clean. Preserve committable task artifacts under .compozy/tasks/, translate configuration manually, and do not carry daemon databases or legacy extension/setup directories into the new runtime. The task schema remains useful; runtime state does not.

For Git, keep authored task/config artifacts according to your repository policy and ignore runtime state inside the shared directory. At minimum, review rules for:

.compozy/compozy.db
.compozy/workspace.toml
.compozy/daemon.sock
.compozy/daemon.lock
.compozy/logs/
.compozy/cache/

Do not ignore the entire .compozy/ directory when the repository commits .compozy/tasks/, Loop definitions, skills, agents, or workspace configuration. After backup and manual translation, run a dry delivery plan first, inspect the reported input origins/runtime provenance, then start the real run and follow the final-line /loop-runs/<id> URL.

Authoring portable Agent PluginsCopy Anchor Link

For new cross-client packages, keep the standard Agent Plugins 1.0.0 layout: a root plugin.json with its canonical $schema, skills/ and optional mcp.json. CompozyOS also loads client manifests under .claude-plugin/, .codex-plugin/ and .cursor-plugin/ through adapters. Existing client packages do not need to be rewritten for installation; only supported skills and MCP declarations are loaded, and unsupported commands, agents and hooks are reported as client_component_ignored. See Agent Plugins interoperability.

Marketplace acquisition hard cutCopy Anchor Link

MCP servers embedded in previously installed ClawHub/Marketplace skills are disabled. Their skill files and provenance remain readable; manual MCPs and extension-provided MCPs are unaffected. skills.allowed_marketplace_mcp is retired and archived as inactive comments on config load; remove it from scripts that write config or Settings payloads. The archive does not grant runtime access.

Marketplace discovery now uses compozy marketplace search [query], compozy marketplace info <entry_id> and compozy marketplace refresh. Remove --kind and the kind argument previously passed to info. HTTP and UDS clients use GET /api/marketplace, GET /api/marketplace/entries/{entry_id} and POST /api/marketplace/refresh; old kind and grouped-search routes are removed. Native compozy__marketplace_search no longer accepts kind.

Install packaged resources through the existing extension install surfaces. The old compozy mcp install, remote compozy skill search|install|update|remove commands and POST /api/settings/mcp-servers/install are removed. Existing extension packages, identities, acquisition references, credentials and management remain supported. Installed skill files and provenance remain readable through local skill commands; manual MCP configuration and authorization remain supported.

Remove active skills.marketplace.registry and skills.marketplace.base_url settings from configuration templates. Existing files are migrated once by archiving those values as inactive comments in the same atomic config write; unrelated settings are preserved. The active runtime and config set no longer consume these acquisition settings. Catalog mirrors must serve v3/extensions.json and v3/marketplaces.json; missing v3 reports a source failure rather than reading a root feed.

Extension installation no longer accepts runtime_name or --runtime-name. Runtime names are allocated automatically. Extension inputs use their own credential namespace; manual MCP Vault references cannot be imported into extension inputs. See the Unreleased migration block in release notes for the append-only database upgrades and preserved state.