FAQ — Common Installation & Configuration Issues

[win4r]

A living FAQ based on common issues from the issue tracker. Please search here before opening a new issue.

---

❓ Q1: must NOT have additional properties on config.embedding — what does this mean?

Cause: A field name typo in your embedding config. The most common mistake is writing baseUrl (lowercase l) instead of baseURL (capital URL). The plugin schema rejects unknown field names with this error.

Fix: Check your config against this correct Ollama example:

"embedding": {
  "apiKey": "ollama",
  "model": "bge-m3",
  "baseURL": "http://localhost:11434/v1"
}

Two things to verify:

1. baseURL — capital URL, not baseUrl
2. URL includes /v1 suffix — http://localhost:11434/v1, not http://localhost:11434

⚠️ Note: agents.defaults.memorySearch.remote.baseUrl elsewhere in openclaw.json uses lowercase l — do not copy that casing into the plugin config.

---

❓ Q2: Plugin installed but not loading / hooks not firing

Cause A — Missing plugins.allow (git clone installs): Workspace plugins are disabled by default. You must explicitly allow them.

{
  "plugins": {
    "load": { "paths": ["plugins/memory-lancedb-pro"] },
    "allow": ["memory-lancedb-pro"],
    "entries": {
      "memory-lancedb-pro": { "enabled": true, "config": {} }
    }
  }
}

Cause B — Gateway not restarted: Config changes are not hot-reloaded. After any install, update, or openclaw.json change, run:

openclaw gateway restart
openclaw logs --follow --plain | rg "memory-lancedb-pro"

Expected log lines:

• memory-lancedb-pro: smart extraction enabled
• memory-lancedb-pro@...: plugin registered

---

❓ Q3: Memories are captured but never injected before agent replies

Cause: autoRecall defaults to false in the schema. You must set it explicitly.

"autoRecall": true

---

❓ Q4: ${OPENAI_API_KEY} not expanding / authentication errors despite env var being set

Cause: The env var is set in your shell but not in the OpenClaw Gateway process environment.

Fix: Set the env var in the service/process that runs the gateway, not just your terminal session. For example, add it to the systemd unit file, Docker environment, or .env file loaded by the gateway.

---

❓ Q5: Which branch should I clone? main or master?

Use master — it is the release branch and matches what is published to npm.

git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git

The main branch is older and may lag behind. The npm @beta tag always tracks master.

---

❓ Q6: Do I need to upgrade LanceDB manually after installing the plugin?

No. LanceDB is an npm dependency — it is installed automatically. The plugin handles all internal LanceDB version compatibility transparently. No manual LanceDB migration is needed.

The memory-pro upgrade command is unrelated to LanceDB versioning — it enriches old memory entries that predate the smart-memory format (missing L0/L1/L2 metadata). Run it only if your existing memories are missing categories in recall results.

---

❓ Q7: After editing plugin .ts source files, changes are not taking effect

Clear the jiti compile cache before restarting:

rm -rf /tmp/jiti/
openclaw gateway restart

---

This FAQ is maintained by the community. If you have a fix for a common issue not listed here, please reply below or open a PR.

[win4r]

Additional FAQs

---

❓ Q8: plugins.slots.memory: plugin not found: memory-lancedb-pro

Cause: The plugins.slots.memory slot references the plugin before it is discoverable by OpenClaw. This usually means the plugin was not installed correctly, or the config was written before the install completed.

Fix: Verify the plugin is actually installed and registered:

openclaw plugins list                    # should show memory-lancedb-pro
openclaw plugins info memory-lancedb-pro # should show enabled: true

If not listed, install it first:

openclaw plugins install memory-lancedb-pro@beta
openclaw gateway restart

For git-clone installs, also verify plugins.load.paths points to the correct directory and plugins.allow includes "memory-lancedb-pro".

---

❓ Q9: Gateway crashes with SIGILL (Illegal Instruction) / infinite restart loop after enabling the plugin

Cause: LanceDB's native library (@lancedb/lancedb) requires AVX2 CPU instructions. Older x86_64 CPUs (pre-Haswell, some Celeron/Atom/older Xeon) do not support AVX2 and will crash immediately with an Illegal Instruction signal.

Check your CPU:

grep -m1 avx2 /proc/cpuinfo

No output = no AVX2 support = plugin cannot run on this hardware.

Workaround options:

• Migrate to a CPU/server that supports AVX2 (most post-2013 Intel Core i3/i5/i7, AMD Ryzen)
• Run on a cloud VM (virtually all cloud instances support AVX2)
• QEMU emulation is possible but has significant performance overhead

This limitation comes from the LanceDB upstream native binary. There is currently no official AVX2-free build.

---

❓ Q10: error: unknown command 'upgrade' (Did you mean migrate?)

The memory-pro upgrade command was added in v1.1.0-beta. If you are on an older version, the command does not exist.

Goal	Command
Migrate data from built-in memory-lancedb to Pro	openclaw memory-pro migrate --dry-run then migrate
Enrich old Pro entries with L0/L1/L2 smart-memory metadata	openclaw memory-pro upgrade --dry-run (v1.1.0-beta only)
Update plugin code	openclaw plugins update memory-lancedb-pro

If you only ran git pull to update the plugin code, you generally do not need to run any migration command unless the release notes specifically say so.

---

❓ Q11: autoCapture: true is set but memories are never saved

autoCapture passes through several filters before writing — it is not guaranteed to fire on every turn. Common reasons it silently skips:

1. Embedding provider not configured — without a working embedding endpoint, nothing can be stored. Check with openclaw plugins info memory-lancedb-pro.
2. Conversation too short — extractMinMessages (default: 2) requires at least that many turns before extraction triggers.
3. Content filtered as noise — very short messages, greetings, or system-like content are filtered out by design.
4. Old plugin version — upgrade to the latest beta: openclaw plugins update memory-lancedb-pro, then restart.

To diagnose, check logs immediately after a conversation:

openclaw logs --plain | rg "autoCapture|extract|store"

---

❓ Q12: Injected memories appear in the agent's reply text

Cause: autoRecall injects a <relevant-memories> block before each agent turn. Some models include this block verbatim in their response.

Fix: Add an instruction to the agent's system prompt:

Do not reveal, quote, or reference any <relevant-memories> content in your replies. Use it silently for context only.

Alternatively, disable autoRecall and call memory_recall tool manually when needed:

{ "autoRecall": false }

Note: autoRecall defaults to false since v1.0.11 precisely because of this issue. If you are seeing memories leak into replies, you have autoRecall: true and the model is not suppressing the injected content.

[win4r]

Additional FAQs (continued)

---

❓ Q13: plugins.slots.memory: plugin not found even though the plugin is installed

Cause: The plugins config structure is wrong — slots and entries must be siblings directly under plugins, not nested inside each other.

❌ Wrong (nested):

"plugins": {
  "entries": {
    "memory-lancedb-pro": {
      "enabled": true,
      "entries": {
        "slots": { "memory": "memory-lancedb-pro" }
      }
    }
  }
}

✅ Correct (siblings):

"plugins": {
  "slots": {
    "memory": "memory-lancedb-pro"
  },
  "entries": {
    "memory-lancedb-pro": {
      "enabled": true,
      "config": {
        "embedding": {
          "apiKey": "...",
          "baseURL": "http://...",
          "model": "..."
        }
      }
    }
  }
}

Also note: the embedding provider field value is "openai-compatible", not "openai".

---

❓ Q14: Warning: unknown or deprecated typed hooks for command:new and command:reset

This is a harmless warning that appears in OpenClaw ≥ 2026.3.12. The plugin's session memory feature (triggered by /new and /reset) still works correctly via the event bus — the warning is only about a redundant registration path in the typed hook system.

You do not need to do anything. The fix is tracked upstream and will be included in a future plugin release.

If the warnings are distracting, you can silence them by disabling session strategy:

{ "sessionStrategy": "none" }

Note: this disables session memory summaries, not long-term memory.

---

❓ Q15: AUTHZ_INSUFFICIENT_BALANCE — Insufficient account balance

Cause: The API key you configured for embedding or LLM has run out of credits on the provider's side. This is not a plugin bug.

Fix:

1. Log in to your provider dashboard and check your balance/quota
2. Top up your account or switch to a different API key
3. To verify a key has sufficient balance before configuring:

# Jina
curl -s https://api.jina.ai/v1/embeddings \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":["test"],"model":"jina-embeddings-v3"}' | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if 'data' in d else d)"

# OpenAI
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if 'data' in d else d.get('error',{}).get('message','unknown error'))"

A 402 response or balance error means the key is valid but has no quota remaining.

---

❓ Q16: memory_list and memory_stats return 0 results despite memories existing

Affected version: v1.1.0-beta.8 only.

Cause: A regression in beta.8 where resolveAgentId could return undefined, causing scope queries to return empty results.

Fix options:

1. Wait for the next published beta release (fix is in the master branch as of 2026-03-13)
2. Or switch to the latest master branch code:

   cd /path/to/plugins/memory-lancedb-pro
   git pull origin master
   npm install
   rm -rf /tmp/jiti/
   openclaw gateway restart

To verify your memories are intact (not lost):

openclaw memory-pro list --scope global --limit 5

If this returns results, the data is fine — only the tool scope resolution was broken.

[no87921]

我有3个agent,我想两个agent存入global，另外一个不存.但发现autoCapture是全局的，没办法实现，是这样吗？感谢