EchoMem

---
name: echo-memory
description: "Guide users through installing, configuring, using, and troubleshooting the EchoMemory Cloud OpenClaw Plugin. Use for plugin setup, API key onboarding, 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`
- browser auto-open is skipped automatically on headless, SSH, or CI sessions
- removing the API key from the local UI forces local-only mode for future loads

## 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:

```text
~/.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/echo-memory-cloud-openclaw-plugin`
- GitHub repo: `https://github.com/Atlas-Graph-Academy/EchoMemory-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. Create an EchoMemory account and API key.
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:

```powershell
cd $HOME\.openclaw
npm install @echomem/echo-memory-cloud-openclaw-plugin
```

Local repo install:

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

Linked local repo install for active development:

```powershell
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

### Account and API key

For first-time users:

1. Sign up at `https://iditor.com/signup/openclaw`.
2. Complete the 6-digit OTP email flow.
3. If prompted on first login, use referral code:

```text
openclawyay
```

4. Open `https://www.iditor.com/api`.
5. Create an API key that starts with `ec_`.
6. Recommended scopes: `ingest:write` and `memory:read`.

### Required host setup

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

```json5
{
  "tools": {
    "profile": "full"
  }
}
```

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

### Valid first config

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

```json5
{
  "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:

```text
~/.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`:

```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
```

### First restart and verification

After install and config changes:

```powershell
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`

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`](./references/mode-switching.md).

## First checks

1. Confirm the plugin is installed or linked.

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

or

```powershell
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.

```powershell
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`

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`](./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:

```text
[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`](./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

## 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
- signup, OTP, referral code, API key creation
- configuration, troubleshooting, or how the plugin works
- the command list itself

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 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. Set plugin config or `~/.openclaw/.env`.
4. Restart `openclaw gateway`.
5. Verify the localhost viewer URL appears in gateway logs.
6. For cloud mode, run:

```text
/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`](./references/normal-usage.md).

## Configuration examples

Cloud mode:

```json5
{
  "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:

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

---

# EchoMemory Initial Setup

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

## Official plugin links

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

## What the plugin does

- syncs local markdown memories into EchoMemory cloud
- exposes `/echo-memory` commands for status, sync, search, graph, onboarding, and identity checks
- starts a local localhost workspace UI during gateway startup
- makes EchoMemory functions reachable from natural language through the registered tool surface

## OpenClaw file structure to expect

Typical local layout:

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

Useful interpretation:

- `workspace/MEMORY.md` is the curated long-term memory file
- `workspace/memory/` is the usual daily memory area
- date-named files like `2026-03-17.md` are normal daily logs
- subfolders such as `topics/` help local organization

Important current behavior:

- the local UI can browse the wider workspace markdown structure
- cloud sync uses the configured `memoryDir`
- the current sync importer reads top-level `.md` files from that `memoryDir`

So "visible in the local UI" is not the same as "already included in cloud sync."

## Install paths

Published package install:

```powershell
cd $HOME\.openclaw
npm install @echomem/echo-memory-cloud-openclaw-plugin
```

Install from a local repo path:

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

Install as a link during active development:

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

Important install rule:

- OpenClaw needs the plugin discoverable from its own plugin resolution path
- a global npm install by itself is not enough
- the most reliable paths are:
  - `npm install` inside `$HOME/.openclaw`
  - `openclaw plugins install ...`
  - `openclaw plugins install --link ...`

Do not assume "installed somewhere on the machine" means OpenClaw can load it.

## Account setup

1. Sign up at `https://iditor.com/signup/openclaw`.
2. Complete the email OTP flow.
3. If first login asks for it, use referral code:

```text
openclawyay
```

4. Create an API key at `https://www.iditor.com/api`.
5. Use scopes `ingest:write` and `memory:read`.

## Required OpenClaw host config

Set `tools.profile` to `"full"` in `~/.openclaw/openclaw.json`.

Use the exact plugin entry key:

```text
plugins.entries.echo-memory-cloud-openclaw-plugin
```

Do not use old or guessed keys like:

- `echomemory-cloud`
- any other shortened alias

If an old key is already present, remove it instead of keeping both.

## Minimum working plugin config

```json5
{
  "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
        }
      }
    }
  }
}
```

For most users, the right starting value is:

```text
memoryDir = ~/.openclaw/workspace/memory
```

If a user stores important notes in `workspace/MEMORY.md` or deeper subfolders, explain that they may still see those locally while cloud sync behavior is driven by `memoryDir`.

## First restart

```powershell
openclaw gateway restart
```

Use `openclaw gateway restart`, not a generic `openclaw restart`, when you want the plugin service lifecycle to reload cleanly.

Expected signs of a healthy startup:

- the plugin loads without `plugin not found`
- the local UI may install/build assets on first run
- the gateway log shows `[echo-memory] Local workspace viewer: http://127.0.0.1:17823`

Transient restart pitfall:

- right after enabling or patching the plugin config, OpenClaw can briefly reject new work with messages like `Gateway is draining for restart; new tasks are not accepted`
- that is usually a restart timing issue, not proof that the plugin is broken
- wait for the gateway to finish restarting, then retry

## First checks

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

Also verify a file-path expectation:

1. the files the user expects to sync are actually in the configured `memoryDir`
2. the user is not assuming every markdown file visible in the local UI is part of cloud sync

If the localhost UI is not active after restart:

1. check gateway logs for the local workspace viewer line
2. check whether the plugin was actually discovered
3. if discovery is blocked, use the fallback script in [`../scripts/start-local-ui.mjs`](../scripts/start-local-ui.mjs)

## Common install pitfalls

- Windows paths with spaces must be quoted
- restart the gateway after install or config changes
- `tools.profile` must be `full`
- the plugin entry key must be exactly `echo-memory-cloud-openclaw-plugin`
- stale config entries can keep producing misleading warnings even after the real plugin is installed
- a plugin installed globally but not under OpenClaw's resolution path will still look "not found"
- if OpenClaw is older than the plugin target version, discovery can fail even though the package is installed

## Valuable real-world setup lessons

These came from an actual setup/debug session and are worth checking early:

1. Wrong plugin ID wastes time fast.
   Use `echo-memory-cloud-openclaw-plugin` exactly.

2. Stale config entries create noisy false trails.
   If logs mention something like `plugins.entries.echomemory-cloud: plugin not found`, remove the stale key and keep only the real plugin entry.

3. Global install is not enough.
   If OpenClaw says the plugin is missing, install it into `~/.openclaw` or via `openclaw plugins install`.

4. Gateway restart timing can look like failure.
   If tasks are rejected while the gateway is draining, wait for restart completion before debugging further.

5. Local mode can persist unexpectedly.
   If the UI sidebar saved an API key but the app still says local mode, verify both:
   - `localOnlyMode` is `false`
   - the API key is available from the winning config source

6. Manual local UI startup is a fallback, not the preferred steady state.
   It is useful when discovery fails, especially around version mismatch, but normal operation should come from plugin startup on `openclaw gateway restart`.

7. Local UI and cloud sync do not cover the exact same file set.
   If a note appears in the local viewer but not in cloud search, check whether it lives inside the configured sync directory and whether it is a top-level markdown file for the current importer.

---

# EchoMemory Mode Switching

Use this reference when the user wants to move between localhost-only usage and EchoMemory cloud sync.

## Cloud mode

Cloud mode requires:

- `localOnlyMode: false`
- a valid `apiKey`
- a gateway restart after the change

Recommended plugin config:

```json5
{
  "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",
          "autoSync": true,
          "localUiAutoOpenOnGatewayStart": true,
          "localUiAutoInstall": true,
          "syncIntervalMinutes": 15,
          "batchSize": 10
        }
      }
    }
  }
}
```

Expected behavior after `openclaw gateway restart`:

- the local UI still starts on localhost
- the viewer should not say local-only mode
- `/echo-memory whoami` should succeed
- `/echo-memory sync` should be able to upload markdown memories

## Local mode

Local mode requires:

- `localOnlyMode: true`
- no API key requirement

Recommended plugin config:

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

Expected behavior after `openclaw gateway restart`:

- the local UI still starts
- localhost browsing works
- cloud sync and cloud identity checks are unavailable by design

## Config precedence

The plugin resolves config in this order:

1. `plugins.entries.echo-memory-cloud-openclaw-plugin.config.*`
2. `~/.openclaw/.env`
3. process environment
4. plugin defaults

Relevant environment variables:

- `ECHOMEM_API_KEY`
- `ECHOMEM_MEMORY_DIR`
- `ECHOMEM_LOCAL_ONLY_MODE`
- `ECHOMEM_LOCAL_UI_AUTO_OPEN_ON_GATEWAY_START`
- `ECHOMEM_LOCAL_UI_AUTO_INSTALL`
- `ECHOMEM_AUTO_SYNC`

## Safe switching sequence

1. Update plugin config or `~/.openclaw/.env`.
2. Make sure the local-only flag and API key agree with the intended mode.
3. Restart the gateway.
4. Verify the gateway log shows the local workspace viewer URL.
5. In cloud mode, run `/echo-memory whoami` and `/echo-memory status`.

## Important pitfall

If the user removes the API key in the local UI sidebar, the plugin saves `ECHOMEM_LOCAL_ONLY_MODE=true` to the local env file. That local-only flag can keep winning on later restarts until it is changed back.

---

# EchoMemory Normal Usage

Use this reference for everyday EchoMemory requests after setup is already working.

## Current command surface

- `/echo-memory onboard`
- `/echo-memory view`
- `/echo-memory status`
- `/echo-memory search <query>`
- `/echo-memory graph`
- `/echo-memory graph public`
- `/echo-memory sync`
- `/echo-memory whoami`
- `/echo-memory help`

## Natural-language routing

Use onboarding when the user asks how to install, configure, authenticate, sign up, get an API key, or troubleshoot the plugin.

Use the local UI when the user asks to:

- open local memories
- browse markdown memories
- launch the localhost viewer
- get the local workspace URL

Use search when the user asks to:

- remember prior notes
- find stored context on a topic
- look up plans, dates, people, preferences, or decisions from imported memories

Use status when the user asks:

- whether EchoMemory is working
- when the last sync ran
- what the current import state is

Use sync when the user asks to:

- sync now
- refresh the cloud copy
- upload local markdown files

Use graph commands when the user explicitly wants the cloud graph or public memory page.

## Local UI versus graph

Do not confuse these two surfaces:

- local UI: localhost viewer for local markdown files
- graph: iditor.com pages for private or public cloud graph views

If the user says "view my memories" without saying graph, iditor, or public page, prefer the local UI.

Do not confuse local UI with cloud sync either:

- local UI can show the wider OpenClaw workspace markdown structure
- cloud retrieval depends on what was actually imported from `memoryDir`
- a file being browsable locally does not guarantee it will appear in cloud search

Common local file expectations:

- `workspace/MEMORY.md` for curated long-term memory
- `workspace/memory/YYYY-MM-DD.md` for daily logs
- topic or project subfolders for local organization

## Tool mapping

- `echo_memory_onboard`: setup, onboarding, commands, troubleshooting
- `echo_memory_local_ui`: localhost viewer URL and optional browser open
- `echo_memory_search`: semantic cloud memory retrieval
- `echo_memory_status`: local sync summary plus backend import status
- `echo_memory_sync`: push local markdown memories into EchoMemory cloud
- `echo_memory_graph_link`: private graph login link or public memories link

---

# EchoMemory Troubleshooting

Use this reference for the common breakpoints in the plugin flow.

## Plugin installed but not behaving

Check these in order:

1. the plugin is actually installed or linked
2. `tools.profile` is `"full"` in `~/.openclaw/openclaw.json`
3. the plugin config entry key is exactly `echo-memory-cloud-openclaw-plugin`
4. `openclaw gateway restart` was run after the last change
5. there are no stale plugin entries still present under `plugins.entries`

## `plugin not found: echo-memory-cloud-openclaw-plugin`

Likely causes:

- the plugin was never installed
- the install path was not quoted on Windows
- the gateway was not restarted after install
- the package was installed globally, but not where OpenClaw discovers plugins
- the OpenClaw version is older than the plugin discovery target

Preferred fix:

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

If discovery is still blocked, start the local UI manually with [`../scripts/start-local-ui.mjs`](../scripts/start-local-ui.mjs).

Also check for stale warnings like:

```text
plugins.entries.echomemory-cloud: plugin not found
```

That means an old config entry is still present and should be removed.

## Local UI does not open on gateway restart

Expected behavior:

- the service starts the local UI during gateway startup
- browser auto-open only happens on local desktop sessions

Checks:

1. find `[echo-memory] Local workspace viewer:` in gateway logs
2. verify port `17823` is listening
3. confirm `localUiAutoInstall` is not disabled before the first run
4. confirm the gateway is fully back up and not still draining from restart

Manual fallback:

```powershell
node .\echo-memory\scripts\start-local-ui.mjs
```

## Local UI shows local-only mode unexpectedly

Likely causes:

1. `localOnlyMode` is still `true`
2. the API key is blank
3. `ECHOMEM_LOCAL_ONLY_MODE=true` was saved in `~/.openclaw/.env`
4. the OpenClaw plugin config is overriding what the local UI sidebar saved
5. a manually started local UI server was launched without a usable API client

Fix:

1. set `localOnlyMode` back to `false`
2. restore a valid `ec_...` API key
3. restart the gateway

Important precedence rule:

- plugin config beats `.env`
- if the sidebar writes the API key to `.env` but `openclaw.json` still says `localOnlyMode: true`, the UI can remain stuck in local mode

Manual server pitfall:

- the local UI can still show local mode if the fallback server was started without both:
  - a config with `localOnlyMode: false`
  - an initialized API client

## `/echo-memory` commands fail with authorization errors

If Slack returns `This command requires authorization`, the plugin may be loaded and OpenClaw is blocking the request.

Check:

- `channels.slack.allowFrom`
- channel-specific user allowlists
- then restart the gateway

If the failure happens immediately after config edits, also consider that the gateway may still be restarting.

## `/echo-memory sync` or search returns nothing

Check:

1. the API key includes `ingest:write` and `memory:read`
2. `memoryDir` points to the markdown directory you expect
3. the local markdown files actually exist
4. the user is testing with a known imported topic rather than a narrow literal phrase

## Version mismatch fallback

If the plugin package is installed but OpenClaw still does not discover it, check the OpenClaw version.

Observed failure pattern:

- plugin package present
- gateway restart succeeds
- local UI is not started by the plugin
- logs still imply plugin discovery failure

In that case:

1. update OpenClaw if possible
2. otherwise use [`../scripts/start-local-ui.mjs`](../scripts/start-local-ui.mjs) as a temporary fallback for the localhost UI

This fallback can get the UI working even when full plugin auto-discovery is blocked.

---

# start-local-ui.mjs

#!/usr/bin/env node
import { constants } from "node:fs";
import { access } from "node:fs/promises";
import { homedir } from "node:os";
import path from "node:path";
import { pathToFileURL } from "node:url";

function parseArgs(argv) {
  const args = {
    local: false,
    cloud: false,
    apiKey: "",
    memoryDir: "",
  };

  for (let index = 0; index < argv.length; index += 1) {
    const value = argv[index];
    if (value === "--local") {
      args.local = true;
      continue;
    }
    if (value === "--cloud") {
      args.cloud = true;
      continue;
    }
    if (value === "--api-key") {
      args.apiKey = argv[index + 1] || "";
      index += 1;
      continue;
    }
    if (value === "--memory-dir") {
      args.memoryDir = argv[index + 1] || "";
      index += 1;
    }
  }

  return args;
}

async function ensureReadable(filePath) {
  await access(filePath, constants.R_OK);
}

async function importFromPlugin(pluginRoot, relativePath) {
  const absolutePath = path.join(pluginRoot, relativePath);
  await ensureReadable(absolutePath);
  return import(pathToFileURL(absolutePath).href);
}

const args = parseArgs(process.argv.slice(2));
const openclawHome = path.join(homedir(), ".openclaw");
const pluginRoot = path.join(openclawHome, "node_modules", "@echomem", "echo-memory-cloud-openclaw-plugin");
const workspaceDir = path.join(openclawHome, "workspace");

try {
  await ensureReadable(path.join(pluginRoot, "package.json"));
} catch {
  console.error("EchoMemory plugin was not found under ~/.openclaw/node_modules.");
  console.error("Install the plugin first, then restart the gateway or rerun this script.");
  process.exit(1);
}

const [{ buildConfig }, { createApiClient }, { startLocalServer }] = await Promise.all([
  importFromPlugin(pluginRoot, "lib/config.js"),
  importFromPlugin(pluginRoot, "lib/api-client.js"),
  importFromPlugin(pluginRoot, "lib/local-server.js"),
]);

const overrideConfig = {};
if (args.local) {
  overrideConfig.localOnlyMode = true;
}
if (args.cloud) {
  overrideConfig.localOnlyMode = false;
}
if (args.apiKey) {
  overrideConfig.apiKey = args.apiKey;
}
if (args.memoryDir) {
  overrideConfig.memoryDir = args.memoryDir;
}

const cfg = buildConfig(overrideConfig);
const client = !cfg.localOnlyMode && cfg.apiKey ? createApiClient(cfg) : null;

console.log("EchoMemory manual local UI startup");
console.log(`Mode: ${cfg.localOnlyMode ? "local" : "cloud"}`);
console.log(`Memory dir: ${cfg.memoryDir}`);
console.log(`API key: ${cfg.apiKey ? `${cfg.apiKey.slice(0, 3)}...${cfg.apiKey.slice(-3)}` : "not set"}`);

const url = await startLocalServer(workspaceDir, {
  apiClient: client,
  cfg,
  syncRunner: null,
});

console.log(`Local workspace viewer: ${url}`);

---

## References

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