EchoMemory

Guide users through installing, configuring, using, and troubleshooting the EchoMemory Cloud OpenClaw Plugin. Use for plugin setup, local email OTP onboarding, manual API key fallback, local mode vs cloud mode switching, local UI startup, gateway restart checks, localhost viewer issues, normal /echo-memory command usage, and natural-language routing to current EchoMemory plugin functions.

EchoMemory Plugin

Use this skill when the user is setting up, using, or debugging the EchoMemory OpenClaw plugin.

Also use it for normal EchoMemory usage requests after setup, especially when the user asks in plain language instead of naming the exact command.

Prefer the plugin's current runtime behavior over old repo habits:

• the plugin starts the local UI during openclaw gateway startup
• localUiAutoOpenOnGatewayStart defaults to true
• if a local UI page is already open, gateway restart should let that page reconnect and refresh instead of spawning a redundant new browser window
• packaged installs can expose a Plugin updates section in the local UI sidebar for version checks, release links, update actions, and gateway restart
• the Plugin updates section now appears at the bottom of the setup sidebar, below Configuration
• the top bar shows the plugin version badge beside OpenClaw Smart Clusters
• removing the API key from the local UI forces local-only mode for future loads
• local sync state is now kept in a stable OpenClaw-home state path so reinstalling or upgrading the plugin should not reset prior synced-file status
• sensitive files in the local UI are warning-labeled but still readable locally; the warning is for caution, not a localhost read blocker

Important install-source distinction:

• packaged installs are the intended target for in-app updates
• linked repos and local checkouts are development installs and should still be updated through local dev workflows
• do not assume the active plugin copy lives under ~/.openclaw/node_modules; on newer OpenClaw versions the active runtime may come from ~/.openclaw/extensions
• if the local UI looks newer than the backend behavior, check for multiple plugin copies or multiple gateway processes before assuming the repo code is active

OpenClaw memory layout

This plugin works best when the user understands the difference between the OpenClaw workspace layout, the local UI surface, and the cloud sync surface.

Typical OpenClaw memory files:

~/.openclaw/
  workspace/
    MEMORY.md
    memory/
      2026-03-17.md
      2026-03-16.md
      topics/
      private/

Recommended mental model:

• workspace/MEMORY.md: curated long-term memory and durable notes worth keeping visible
• workspace/memory/YYYY-MM-DD.md: daily logs and session-by-session memory capture
• workspace/memory/topics/ or similar subfolders: topic-specific markdown files for local browsing and organization
• workspace/memory/private/: local private notes that may appear in the local UI scan path and should be reviewed carefully before assuming they belong in cloud sync

Important behavior difference:

• cloud sync reads top-level .md files from the configured memoryDir
• the local UI scans the wider OpenClaw workspace recursively and can show more files than the cloud sync path imports

That means a user can see a file in the local UI without that file necessarily being included in cloud sync.

Initial setup from zero

Use this flow when the user has not installed the plugin yet.

Official references:

• OpenClaw Marketplace: https://openclawdir.com/plugins/echomemory-ArQh3g
• NPM package: https://www.npmjs.com/package/@echomem/openclaw-memory
• GitHub repo: https://github.com/Atlas-Graph-Academy/EchoMemory-Cloud-OpenClaw-Plugin

OpenClaw version note:

• on 2026.3.22+, native openclaw skills install exists for skills, but plugin source precedence also changed
• this skill should guide plugin installs through exact local paths, --link, or the exact scoped npm package
• do not recommend bare openclaw plugins install <name> for EchoMemory because newer OpenClaw versions may resolve bare names through ClawHub first
• the published npm package is now @echomem/openclaw-memory, but the runtime plugin id for config and uninstall remains echo-memory-cloud-openclaw-plugin

Recommended setup order:

1. Confirm the user already has OpenClaw installed and can run openclaw.
2. Install the plugin from a published source or local repo.
3. Connect Echo Cloud from the local UI with email and OTP, or use the manual API key fallback.
4. Add the plugin config and set tools.profile to "full".
5. Restart the gateway.
6. Verify the local UI and command surface.
7. Confirm the user understands which local markdown files are visible locally versus actually synced to cloud.

Install options

Published package install inside the OpenClaw home directory:

cd $HOME\.openclaw
npm install @echomem/openclaw-memory

Local repo install:

openclaw plugins install "C:\Users\Your Name\Documents\GitHub\EchoMemory-Cloud-OpenClaw-Plugin"

Linked local repo install for active development:

openclaw plugins install --link "C:\Users\Your Name\Documents\GitHub\EchoMemory-Cloud-OpenClaw-Plugin"

Important Windows pitfall:

• quote the plugin path if it contains spaces, or openclaw plugins install may parse the path incorrectly
• on 2026.3.22+, avoid bare plugin names and use the exact scoped package or exact local path instead

Cleanup and reinstall

When the user wants to remove an old install cleanly, use the exact OpenClaw uninstall command instead of describing manual cleanup first:

openclaw plugins uninstall echo-memory-cloud-openclaw-plugin

Helpful variants:

• openclaw plugins uninstall echo-memory-cloud-openclaw-plugin --dry-run
• openclaw plugins uninstall echo-memory-cloud-openclaw-plugin --keep-files

uninstall removes the plugin entry, tracked install record, allowlist entry, and linked load path when applicable. By default it also removes the plugin install directory under OpenClaw's active extensions root.

Do not assume the active plugin always lives under ~/.openclaw/node_modules. On newer OpenClaw versions the active install may be tracked under ~/.openclaw/extensions.

After uninstall:

1. remove stale config ids like plugins.entries.echomemory-cloud if present
2. run openclaw gateway restart
3. reinstall from npm or the intended local path
4. run openclaw gateway restart again

Do not tell users that reinstalling the plugin should reset synced-file history. Current behavior is supposed to preserve sync state across versions under the OpenClaw home state directory.

Account connection

Preferred path for first-time and returning users:

1. Open the plugin local UI and expand the Setup sidebar.
2. Under Quick connect, enter the user's email and click Connect with email.
3. Enter the 6-digit OTP sent by EchoMemory / Supabase.
4. The plugin and backend handle the rest:
   • existing users are verified
   • brand-new users are created through the OpenClaw path
   • the OpenClaw onboarding shortcut is applied server-side
   • a new scoped ec_... API key is generated automatically
   • the key is written to ~/.openclaw/.env
   • the UI refreshes into connected mode

Generated key scope expectation:

• memory:read
• memory:write
• ingest:write

Manual fallback:

1. Expand Advanced: enter API key manually in the local UI Setup sidebar.
2. Paste an existing ec_... key and save local settings.
3. If the user needs to manage website keys directly, use https://www.iditor.com/api after login.

Required host setup

In ~/.openclaw/openclaw.json, set:

{
  "tools": {
    "profile": "full"
  }
}

The default coding profile is too restrictive for normal EchoMemory plugin usage.

If the user wants EchoMemory to fully replace OpenClaw's built-in memory recall, also guide them to disable the core memory tools in the same config:

{
  "tools": {
    "profile": "full",
    "deny": ["memory_search", "memory_get"]
  }
}

Important distinction:

• the local UI checkbox Echo-only memory retrieval blocks OpenClaw memory_search and memory_get at runtime after Echo cloud access is verified
• tools.deny in ~/.openclaw/openclaw.json is the stronger and recommended setup when the user wants EchoMemory to fully own memory retrieval
• after adding tools.deny, the user should restart openclaw gateway

Valid first config

Use this as the baseline cloud-mode setup for a new install:

{
  "tools": {
    "profile": "full"
  },
  "plugins": {
    "entries": {
      "echo-memory-cloud-openclaw-plugin": {
        "enabled": true,
        "config": {
          "apiKey": "ec_your_key_here",
          "memoryDir": "C:\\Users\\your-user\\.openclaw\\workspace\\memory",
          "autoSync": false,
          "localOnlyMode": false,
          "localUiAutoOpenOnGatewayStart": true,
          "localUiAutoInstall": true,
          "syncIntervalMinutes": 15,
          "batchSize": 10,
          "requestTimeoutMs": 300000
        }
      }
    }
  }
}

For the default OpenClaw layout, memoryDir is usually:

~/.openclaw/workspace/memory

This is the cloud sync directory. By current plugin behavior, sync reads the top-level markdown files inside that directory.

Environment file alternative in ~/.openclaw/.env:

ECHOMEM_API_KEY=ec_your_key_here
ECHOMEM_MEMORY_DIR=C:\Users\your-user\.openclaw\workspace\memory
ECHOMEM_AUTO_SYNC=false
ECHOMEM_LOCAL_ONLY_MODE=false
ECHOMEM_LOCAL_UI_AUTO_OPEN_ON_GATEWAY_START=true
ECHOMEM_LOCAL_UI_AUTO_INSTALL=true
ECHOMEM_SYNC_INTERVAL_MINUTES=15
ECHOMEM_BATCH_SIZE=10
ECHOMEM_REQUEST_TIMEOUT_MS=300000

Important note:

• with the current one-click flow, users do not need to hand-edit ECHOMEM_API_KEY; the plugin can write it automatically after email verification

First restart and verification

After install and config changes:

openclaw gateway restart

Successful startup usually includes:

• plugin discovery succeeded
• local UI dependency install/build messages on first run if assets are missing
• [echo-memory] Local workspace viewer: http://127.0.0.1:17823

Successful local UI verification now also includes:

• the setup sidebar showing Plugin updates at the bottom
• the top bar showing the current plugin version
• packaged installs showing install-source and latest-version data inside Plugin updates

Recommended first smoke test order:

1. /echo-memory whoami
2. /echo-memory status
3. /echo-memory sync
4. /echo-memory search <known memory topic>

If the user is not ready for cloud setup yet, local-only mode is still valid. Read references/mode-switching.md.

First checks

1. Confirm the plugin is installed or linked.

openclaw plugins install "C:\path\to\EchoMemory-Cloud-OpenClaw-Plugin"

or

openclaw plugins install --link "C:\path\to\EchoMemory-Cloud-OpenClaw-Plugin"

2. Confirm tools.profile is "full" in ~/.openclaw/openclaw.json.
3. Confirm the plugin config entry exists at plugins.entries.echo-memory-cloud-openclaw-plugin.
4. Restart the gateway after install or config changes.

openclaw gateway restart

Mode switching

Use cloud mode when the user wants sync and retrieval from EchoMemory cloud:

• localOnlyMode: false
• apiKey: "ec_..."
• key scopes should include ingest:write and memory:read
• if they also want EchoMemory to be the only memory retrieval path, recommend tools.deny: ["memory_search", "memory_get"] in ~/.openclaw/openclaw.json

Use local mode when the user only wants localhost browsing of markdown files:

• localOnlyMode: true
• API key can be blank
• the local UI should still be available

If the user wants to switch modes, read references/mode-switching.md.

Local UI behavior

If the user asks to "view memories" and does not explicitly mention graph, public memories, or iditor.com, treat that as the local UI, not the cloud graph.

Successful gateway startup usually includes:

[echo-memory] Local workspace viewer: http://127.0.0.1:17823

If the plugin is loaded but the user still cannot open the viewer:

1. confirm the gateway was restarted
2. confirm localhost port 17823 is listening
3. confirm localUiAutoInstall was not disabled before the first run
4. use the fallback script at scripts/start-local-ui.mjs

Explain the surface clearly when needed:

• the local UI is a localhost workspace browser over OpenClaw markdown files
• it can show more workspace files than the cloud sync importer uploads
• cloud mode status in the UI depends on both config and a working API client, not just the presence of a saved key string
• local UI warnings for sensitive files do not mean the file is unreadable locally; they are caution labels while the underlying localhost viewer still reads the markdown content from disk
• the setup sidebar includes a Plugin updates panel for packaged installs; it is not the primary update path for linked local repos
• if the update panel shows Unknown, Unavailable, or route 404 errors, verify that the running gateway is using the same plugin copy as the visible frontend

Normal usage routing

Map normal-language requests to the current plugin surface instead of replying from generic memory or setup knowledge.

Use echo_memory_onboard or /echo-memory onboard when the user asks about:

• install or link steps
• marketplace, npm, or GitHub sources
• first-time setup from zero
• uninstall, cleanup, or clean reinstall steps
• signup, email OTP connection, local account creation, manual API key fallback
• configuration, troubleshooting, or how the plugin works
• the command list itself
• how to fully replace OpenClaw memory_search / memory_get
• what the local UI Echo-only memory retrieval checkbox really changes

Use echo_memory_local_ui or /echo-memory view when the user asks to:

• open, browse, launch, or get the URL for local memories
• view markdown memories on localhost
• open the workspace viewer or local UI

Use echo_memory_search or /echo-memory search <query> when the user asks:

• "what do you remember about ..."
• "search my memories for ..."
• "find my notes about ..."
• for prior facts, plans, dates, preferences, or decisions already stored in EchoMemory cloud

If the user says they enabled the local UI Echo-only memory retrieval option but OpenClaw still reaches for core memory tools, explicitly tell them to add tools.deny: ["memory_search", "memory_get"] to ~/.openclaw/openclaw.json and restart the gateway.

If the user expects a local file to appear in cloud search, verify that the file is actually inside the sync directory and not only visible through the wider local UI workspace scan.

Use echo_memory_status or /echo-memory status when the user asks about:

• whether EchoMemory is working
• sync health, last sync, import progress, or recent imports

Use echo_memory_sync or /echo-memory sync when the user asks to:

• sync, refresh, import, upload, or push local markdown memories to the cloud

Use /echo-memory whoami when the user wants to verify:

• the current EchoMemory identity
• the token type
• the active scopes on the current API key

Use echo_memory_graph_link or graph commands when the user asks for:

• the memory graph
• the cloud graph or graph view
• an iditor.com memory page
• the public memories page

Choose the graph target carefully:

• private graph: echo_memory_graph_link with visibility: private or /echo-memory graph
• public memories page: echo_memory_graph_link with visibility: public or /echo-memory graph public

Use /echo-memory help when the user explicitly asks for the command list.

Working flow

1. Install or link the plugin.
2. Set tools.profile to "full".
3. If the user wants EchoMemory to fully replace OpenClaw memory recall, also set tools.deny for memory_search and memory_get.
4. Set plugin config or ~/.openclaw/.env.
5. Restart openclaw gateway.
6. Verify the localhost viewer URL appears in gateway logs.
7. For cloud mode, run:

/echo-memory whoami
/echo-memory status
/echo-memory sync
/echo-memory search <known topic>

If the user is already set up and wants a quick usage reference, read references/normal-usage.md.

Configuration examples

Cloud mode:

{
  "plugins": {
    "entries": {
      "echo-memory-cloud-openclaw-plugin": {
        "enabled": true,
        "config": {
          "apiKey": "ec_your_key_here",
          "localOnlyMode": false,
          "memoryDir": "C:\\Users\\your-user\\.openclaw\\workspace\\memory",
          "localUiAutoOpenOnGatewayStart": true,
          "localUiAutoInstall": true
        }
      }
    }
  }
}

Local mode:

{
  "plugins": {
    "entries": {
      "echo-memory-cloud-openclaw-plugin": {
        "enabled": true,
        "config": {
          "localOnlyMode": true,
          "memoryDir": "C:\\Users\\your-user\\.openclaw\\workspace\\memory",
          "localUiAutoOpenOnGatewayStart": true,
          "localUiAutoInstall": true
        }
      }
    }
  }
}

Cloud mode with OpenClaw core memory tools disabled:

{
  "tools": {
    "profile": "full",
    "deny": ["memory_search", "memory_get"]
  },
  "plugins": {
    "entries": {
      "echo-memory-cloud-openclaw-plugin": {
        "enabled": true,
        "config": {
          "apiKey": "ec_your_key_here",
          "localOnlyMode": false,
          "memoryDir": "C:\\Users\\your-user\\.openclaw\\workspace\\memory",
          "localUiAutoOpenOnGatewayStart": true,
          "localUiAutoInstall": true,
          "disableOpenClawMemoryToolsWhenConnected": true
        }
      }
    }
  }
}

References

• references/initial-setup.md: zero-to-working install path, account creation, config, and first verification checks
• references/normal-usage.md: current commands, plain-language trigger mapping, and when to use local UI versus graph
• references/mode-switching.md: exact local/cloud toggles, config precedence, and restart rules
• references/troubleshooting.md: failure patterns for plugin discovery, local UI startup, auth, and sync
• scripts/start-local-ui.mjs: manual fallback to launch the local UI when the gateway cannot start it