Help
Known limitations
Memory Layer v2.0.0 is the current stable release. It is a breaking major release: databases migrate in place and bundle v1 imports remain supported, but v1 clients, direct API integrations, and configuration need review before an upgrade.
Read the v2.0.0 release notes and Update guide before changing a production install.
v2 compatibility targets
| Surface | v2 expectation |
|---|---|
| CLI | Current documented core commands and --json shapes are the public surface. Removed v1 spellings are migration notes only. |
| HTTP API | Operations marked x-stability: core in the running OpenAPI document are the integration boundary. Control-plane operations marked internal can evolve. |
| Database | Migrations are append-only; applied migrations are not edited. |
| Bundles | New exports use deterministic schema v2; schema v1 imports remain supported. |
| MCP | Read-only query, global search, resume, resource, and prompt tools remain adapters over the service API. |
| Packages | Debian amd64/arm64, Homebrew, macOS Intel/Apple Silicon, and Windows x86_64 are release targets. |
Advanced surfaces
| Surface | Limitation |
|---|---|
| Loop automation | Approval-gated by design; risky actions stop for human review. |
| Code graph UI | Falls back to a flat 2D canvas renderer without WebGL; depends on extraction coverage for each repository. |
| Eval research workflows | Release claims still require reviewed held-out suites and a passing gate. |
| Demo web UI | Uses browser-local sample data and is not a live backend. |
Breaking changes from v1
- Cap'n Proto endpoints and config keys are gone; live clients use
/ws. memory automation flushbecamememory watcher flush,memory capture taskbecamememory capture, andmemory dev initbecamememory dev.memory setupwas removed in favour ofmemory wizard./v1/stats,/v1/offline/pending, and the browser auth-token handoff were removed; several loop and activity routes were consolidated.- Authenticated principals now determine durable authorship.
--writer-idand[writer]remain advisory labels. - Authorization uses explicit permission sets. Role names remain convenient presets, not an ordinal authorization ladder.
Upgrade checklist
Before upgrading:
memory status --project <project-slug>
memory doctor
pg_dump "$DATABASE_URL" > memory-layer-before-upgrade.sqlAfter upgrading:
memory service restart-all
memory doctor
memory health
memory status --project <project-slug>
memory upgrade --dry-runThe service applies migrations 0027-0032 at startup. Do not run an older binary
against a migrated database; restore the pre-upgrade backup if you need to roll
back. Review memory upgrade --dry-run before refreshing repo-local skills.
Read Operations, Doctor and health, or Update.