v2-refactor-temp/docs/breaking-changes/2026-07-27-agent-data-workspace-split.md
Agent identity files (SOUL.md, USER.md) and persistent memory now live with
the Agent instead of inside a Session workspace. App-managed Sessions receive
separate system workspaces. During v1 migration, ordinary files from the former
shared managed workspace are copied to the most recently used Session; older
managed Sessions start with empty workspaces. The complete v1 workspace remains
in its legacy location so downgrading to v1 continues to work.
Identity and memory now follow the Agent consistently across all of its Sessions, while files created in one app-managed Session no longer appear automatically in another. Older migrated Sessions do not receive duplicate snapshots of the single workspace they shared in v1.
External user-selected workspaces remain in place and continue to be used directly.
Nothing — migration is automatic. If an older Session needs files that were copied to the most recently used Session workspace, copy or select those files explicitly after upgrading.
v1 did not store a historical workspace snapshot per Session, so copying its last shared state into every migrated Session would invent duplicate history. The migration preserves one copy under the most recently used Session and documents the intentional change in historical Session context. It also retains the complete v1 workspace for downgrade compatibility.