Feature Request: existing-user compatibility install / upgrade workflow

[chenhaonan-eth]

Problem / Motivation

memory-lancedb-pro now has multiple installation / migration paths, but for existing OpenClaw users the compatibility story is still too easy to trip over.

Typical "old user" scenarios include:

• already using the built-in memory-lancedb
• already running OpenClaw from an older deployment layout
• previously installed the plugin by git clone / manual path loading
• trying to switch from old config shape to the new sessionStrategy / newer plugin config
• upgrading after watching older install videos / older docs

In practice, this creates a lot of confusion around:

• whether to use openclaw plugins install vs git-clone path loading
• when plugins.allow is required
• which branch/tag should be used
• when to run migrate vs upgrade vs reembed
• how to preserve old data while moving to the new plugin
• how to validate that an existing deployment is actually using the new plugin correctly

The result is that "new install" may be okay, but existing-user compatibility install / upgrade is still brittle and easy to misconfigure.

Proposed Solution

Add a dedicated existing-user compatibility installation / upgrade workflow.

Concretely, one or more of these would help a lot:

1. A first-class "existing deployment" guide in README

   • built-in memory-lancedb → memory-lancedb-pro
   • old git-clone install → plugin-manager install
   • old config → new config mapping
   • how to keep old DB safe during migration

2. A compatibility doctor / wizard

   • detect current install mode
   • detect whether old memory-lancedb data exists
   • detect whether plugin is discoverable but not allowed / not enabled
   • recommend the correct next command automatically

3. A single upgrade path table

   • “If you are in state A, run X”
   • “If you are in state B, run Y”
   • “Do not run Z in this case”

4. Compatibility-safe install script for old users

   • backup old DB/config first
   • patch config surgically
   • validate
   • restart
   • verify plugin registration/hooks

5. Clear terminology cleanup

   • distinguish migrate vs upgrade vs reembed
   • distinguish plugin-manager install vs workspace path install
   • explicitly call out old-video / old-doc users as a supported migration case

Alternatives Considered

Current workaround is to piece this together manually from README, CLI help, issues, and trial-and-error. It works, but it is still too easy for existing users to end up in a half-upgraded state.

Area

Configuration

Additional Context

This is not mainly a “new user onboarding” problem.
It is a backward-compat / existing-user migration UX problem.

The plugin is powerful now, but the old-user transition path should be much more explicit and safer.

[AliceLJY]

Hi @chenhaonan-eth, thanks for the thorough writeup — these are real pain points we've seen from community feedback too.

Good news: many of the things you described already exist in our one-click setup / upgrade script (v3.6):

curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh

# See what it would do without changing anything
bash setup-memory.sh --dry-run

What the script already handles:

• Auto-detect current install mode (git-clone vs npm vs not installed)
• Backup config before any changes
• Schema validation — strips illegal fields before writing (prevents "additional properties" crash)
• Rollback — auto-reverts if upgrade fails
• Self-check — bash setup-memory.sh --selfcheck-only for health diagnostics
• Uninstall — bash setup-memory.sh --uninstall for clean removal

What's still missing (and worth adding based on your suggestions):

• Built-in memory-lancedb → memory-lancedb-pro data migration path — currently manual
• Upgrade path table in README — "if you're in state A, run X"
• Terminology guide — migrate vs upgrade vs reembed clarification

We'll work on improving the README with a dedicated "Existing Users" section. Thanks for pushing on this.