Update

Memory Layer v2.0.0 is the current stable release. It is a breaking major upgrade from v1: PostgreSQL data migrates in place and old bundles still import, but direct API clients, configuration, and renamed CLI commands need review.

Read the v2.0.0 release notes before upgrading a production installation.

1. Back up and inspect

Stop if either diagnostic already reports a database or authentication problem:

memory --version
memory status --project <project-slug>
memory doctor
memory health

Back up PostgreSQL before starting the v2 binary:

pg_dump "$DATABASE_URL" > memory-layer-before-v2.sql

If DATABASE_URL is stored only in memory-layer.env, load it through your normal secret-management workflow rather than copying it into shell history. For a portable memory-level backup, also export important projects:

memory bundle export --project <project-slug> --out <project-slug>-before-v2.mlbundle.zip

2. Review the v2 breaks

Delete capnp_unix_socket and capnp_tcp_addr; the TUI and clients now use the /ws WebSocket stream.
Replace memory automation flush with memory watcher flush, memory capture task with memory capture, and memory dev init with memory dev. Use memory wizard instead of the removed memory setup.
Update direct HTTP integrations from the running service's GET /v1/openapi.yaml. v2 removed /v1/stats, /v1/offline/pending, and the browser auth-token handoff, and consolidated loop/activity routes.
Treat [writer], --writer-id, and MEMORY_LAYER_WRITER_ID as advisory labels. The authenticated principal supplies durable authorship.
Expect new bundle exports to use deterministic schema v2. Existing schema v1 bundles remain importable.

3. Install v2.0.0

Choose the command for the way you installed Memory Layer.

Debian or Ubuntu

Download the matching v2.0.0 .deb and checksum from GitHub Releases, verify the checksum, then install it:

sha256sum -c memory-layer_2.0.0_amd64.deb.sha256
sudo dpkg -i memory-layer_2.0.0_amd64.deb

Use the arm64 filenames on 64-bit ARM Linux.

Homebrew

brew update
brew upgrade 3vilM33pl3/memory/memory-layer

macOS package or Windows MSI

Download the v2.0.0 installer and matching checksum from the release page, then run it over the existing installation. Windows remains a per-user install under %LOCALAPPDATA%\Programs\Memory Layer.

Source checkout

Check out the signed v2.0.0 tag, build with --locked, and follow the same service restart and verification steps as your original source installation.

4. Restart and migrate

memory service restart-all
memory doctor
memory health
memory status --project <project-slug>

The service applies append-only migrations 0027-0032 at startup. Do not run a v1 binary against the migrated database. To roll back, restore the database backup and the previous binary/config together.

Refresh repo-local Memory Layer skills only after reviewing the preview:

cd /path/to/project
memory upgrade --dry-run
memory upgrade

5. Verify integrations

memory --version
memory query --project <project-slug> --question "What changed recently?"
memory resume --project <project-slug>
memory watcher status --project <project-slug>
memory mcp status

Direct API clients should fetch GET /v1/openapi.yaml from the upgraded service. MCP and agent clients should reconnect after the service restart so they negotiate the current tool surface.

Read Release compatibility and known limitations, Operations, or Doctor and health.