memory-lancedb-pro

Production-grade long-term memory system (v1.1.0-beta.8) for OpenClaw AI agents. Provides persistent, intelligent memory storage using LanceDB with hybrid vector + BM25 retrieval, LLM-powered Smart Extraction, Weibull decay lifecycle, and multi-scope isolation.

For full technical details (thresholds, formulas, database schema, source file map), see

references/full-reference.md

Applying the Optimal Config (Step-by-Step Workflow)

When the user says "help me enable the best config", "apply optimal configuration", or similar, follow this exact procedure:

Step 1 — Present configuration plans and let user choose

Present these three plans in a clear comparison, then ask the user to pick one:

Plan A — 🏆 Full Power (Best Quality)

• Embedding: Jina

  jina-embeddings-v5-text-small

  (task-aware, 1024-dim)
• Reranker: Jina

  jina-reranker-v3

  (cross-encoder, same key)
• LLM: OpenAI

  gpt-4o-mini

  (Smart Extraction)
• Keys needed:

  JINA_API_KEY

  +

  OPENAI_API_KEY

• Get keys: Jina → https://jina.ai/api-key · OpenAI → https://platform.openai.com/api-keys
• Cost: Both paid (Jina has free tier with limited quota)
• Best for: Production deployments, highest retrieval quality

Plan B — 💰 Budget (Free Reranker)

• Embedding: Jina

  jina-embeddings-v5-text-small

• Reranker: SiliconFlow

  BAAI/bge-reranker-v2-m3

  (free tier available)
• LLM: OpenAI

  gpt-4o-mini

• Keys needed:

  JINA_API_KEY

  +

  SILICONFLOW_API_KEY

  +

  OPENAI_API_KEY

• Get keys: Jina → https://jina.ai/api-key · SiliconFlow → https://cloud.siliconflow.cn/account/ak · OpenAI → https://platform.openai.com/api-keys
• Cost: Jina embedding paid, SiliconFlow reranker free tier, OpenAI paid
• Best for: Cost-sensitive deployments that still want reranking

Plan C — 🟢 Simple (OpenAI Only)

• Embedding: OpenAI

  text-embedding-3-small

• Reranker: None (vector+BM25 fusion only, no cross-encoder)
• LLM: OpenAI

  gpt-4o-mini

• Keys needed:

  OPENAI_API_KEY

  only
• Get key: https://platform.openai.com/api-keys
• Cost: OpenAI paid only
• Best for: Users who already have OpenAI and want minimal setup

Plan D — 🖥️ Fully Local (Ollama, No API Keys)

• Embedding: Ollama

  mxbai-embed-large

  (1024-dim, recommended) or

  nomic-embed-text:v1.5

  (768-dim, lighter)
• Reranker: None — Ollama has no cross-encoder reranker; retrieval uses vector+BM25 fusion only
• LLM: Ollama via OpenAI-compatible endpoint — recommended models with reliable JSON/structured output:

  • qwen3:8b

    (recommended — best JSON output, native structured output, ~5.2GB)

  • qwen3:14b

    (better quality, ~9GB, needs 16GB VRAM)

  • llama4:scout

    (multimodal MoE, 10M ctx, ~12GB)

  • mistral-small3.2

    (24B, 128K ctx, excellent instruction following, ~15GB)

  • mistral-nemo

    (12B, 128K ctx, efficient, ~7GB)
• Keys needed: None — fully local, no external API calls
• Prerequisites:
  • Ollama installed: https://ollama.com/download
  • Models pulled (see Step 5 below)
  • Ollama running: macOS = launch the app from Applications; Linux =

    systemctl start ollama

    or

    ollama serve

• Cost: Free (hardware only)
• RAM requirements: mxbai-embed-large ~670MB; qwen3:8b ~5.2GB; qwen3:14b ~9GB; llama4:scout ~12GB; mistral-small3.2 ~15GB
• Trade-offs: No cross-encoder reranking = lower retrieval precision than Plans A/B; Smart Extraction quality depends on local LLM — if extraction produces garbage, set

  "smartExtraction": false

• Best for: Privacy-sensitive deployments, air-gapped environments, zero API cost

After user selects a plan, ask in one message:

1. Please provide the required API key(s) for your chosen plan (paste directly, or say "already set as env vars")
2. Are the env vars already set in your OpenClaw Gateway process? (If unsure, answer No)
3. Where is your

   openclaw.json

   ? (Skip if you want me to find it automatically)

If the user already stated their provider/keys in context, skip asking and proceed.

Do NOT proceed to Step 2 until API keys have been collected and verified (Step 2 below).

Step 2 — Verify API Keys (MANDATORY — do not skip)

Run ALL key checks for the chosen plan before touching any config. If any check fails, STOP and tell the user which key failed and why. Do not proceed to Step 3.

Plan A / Plan B — Jina embedding check:

curl -s -o /dev/null -w "%{http_code}" \
  https://api.jina.ai/v1/embeddings \
  -H "Authorization: Bearer <JINA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"jina-embeddings-v5-text-small","input":["test"]}'

Plan A / B / C — OpenAI check:

curl -s -o /dev/null -w "%{http_code}" \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer <OPENAI_API_KEY>"

Plan B — SiliconFlow reranker check:

curl -s -o /dev/null -w "%{http_code}" \
  https://api.siliconflow.com/v1/rerank \
  -H "Authorization: Bearer <SILICONFLOW_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"BAAI/bge-reranker-v2-m3","query":"test","documents":["test doc"]}'

Plan D — Ollama check:

curl -s -o /dev/null -w "%{http_code}" http://localhost:11434/api/tags

Interpret results:

200

201

401

403

402

429

000

If any check fails: Tell the user exactly which provider failed, the HTTP code received, and what to fix. Do not proceed with installation until all required keys pass their checks.

If the user says keys are set as env vars in the gateway process, run checks using

${VAR_NAME}

Step 3 — Find openclaw.json

Check these locations in order:

# Most common locations
ls ~/.openclaw/openclaw.json
ls ~/openclaw.json
# Ask the gateway where it's reading config from
openclaw config get --show-path 2>/dev/null || echo "not found"

If not found, ask the user for the path.

Step 4 — Read current config

# Read and display current plugins config before changing anything
openclaw config get plugins.entries.memory-lancedb-pro 2>/dev/null
openclaw config get plugins.slots.memory 2>/dev/null

Check what already exists — never blindly overwrite existing settings.

Step 5 — Build the merged config based on chosen plan

Use the config block for the chosen plan. Substitute actual API keys inline if the user provided them directly; keep

${ENV_VAR}

Plan A config (

plugins.entries.memory-lancedb-pro.config

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "rerank": "cross-encoder",
    "rerankProvider": "jina",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankApiKey": "${JINA_API_KEY}",
    "candidatePoolSize": 12,
    "minScore": 0.6,
    "hardMinScore": 0.62,
    "filterNoise": true
  },
  "sessionMemory": { "enabled": false }
}

Plan B config:

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "rerank": "cross-encoder",
    "rerankProvider": "siliconflow",
    "rerankModel": "BAAI/bge-reranker-v2-m3",
    "rerankEndpoint": "https://api.siliconflow.com/v1/rerank",
    "rerankApiKey": "${SILICONFLOW_API_KEY}",
    "candidatePoolSize": 12,
    "minScore": 0.5,
    "hardMinScore": 0.55,
    "filterNoise": true
  },
  "sessionMemory": { "enabled": false }
}

Plan C config:

{
  "embedding": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "text-embedding-3-small",
    "baseURL": "https://api.openai.com/v1"
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "filterNoise": true,
    "minScore": 0.3,
    "hardMinScore": 0.35
  },
  "sessionMemory": { "enabled": false }
}

Plan D config (replace models as needed —

qwen3:8b

mxbai-embed-large

{
  "embedding": {
    "apiKey": "ollama",
    "model": "mxbai-embed-large",
    "baseURL": "http://localhost:11434/v1",
    "dimensions": 1024
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 4000,
  "llm": {
    "apiKey": "ollama",
    "model": "qwen3:8b",
    "baseURL": "http://localhost:11434/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "filterNoise": true,
    "minScore": 0.25,
    "hardMinScore": 0.28
  },
  "sessionStrategy": "none"
}

Plan D prerequisites — run BEFORE applying config:

# 1. Verify Ollama is running (should return JSON with model list)
curl http://localhost:11434/api/tags

# 2. Pull embedding model (choose one):
ollama pull mxbai-embed-large          # recommended: 1024-dim, beats text-embedding-3-large, ~670MB
ollama pull snowflake-arctic-embed2    # best multilingual local option, ~670MB
ollama pull nomic-embed-text:v1.5      # classic stable, 768-dim, ~270MB

# 3. Pull LLM for Smart Extraction (choose one based on RAM):
ollama pull qwen3:8b           # recommended: best JSON/structured output, ~5.2GB
ollama pull qwen3:14b          # better quality, ~9GB, needs 16GB VRAM
ollama pull llama4:scout       # multimodal MoE, 10M ctx, ~12GB
ollama pull mistral-small3.2   # 24B, 128K ctx, excellent, ~15GB
ollama pull mistral-nemo       # 12B, 128K ctx, efficient, ~7GB

# 4. Verify models are installed
ollama list

# 5. Quick sanity check — embedding endpoint works:
curl http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"test"}'
# Should return a JSON with a 1024-element vector

If Smart Extraction produces garbled/invalid output: The local LLM may not support structured JSON reliably. Try

qwen3:8b

{ "smartExtraction": false }

If Ollama is on a different host or Docker: Replace

http://localhost:11434/v1

http://192.168.1.100:11434/v1

OLLAMA_HOST=0.0.0.0

For the

plugins.entries.memory-lancedb-pro.config

openclaw.json

Step 6 — Apply the config

Read the current

openclaw.json

plugins.entries.memory-lancedb-pro

Method 1 —

openclaw plugins install

load.paths

allow

{
  "plugins": {
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "<<OPTIMAL CONFIG HERE>>"
        }
      }
    }
  }
}

Method 2 — git clone with manual path (workspace plugin): Both

load.paths

allow

{
  "plugins": {
    "load": { "paths": ["plugins/memory-lancedb-pro"] },
    "allow": ["memory-lancedb-pro"],
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "<<OPTIMAL CONFIG HERE>>"
        }
      }
    }
  }
}

Step 7 — Validate and restart

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

Expected output confirms:

• memory-lancedb-pro: smart extraction enabled

• memory-lancedb-pro@...: plugin registered

Step 8 — Verify

openclaw plugins info memory-lancedb-pro
openclaw hooks list --json | grep -E "before_agent_start|agent_end|command:new"
openclaw memory-pro stats

Then do a quick smoke test:

1. Store: call

   memory_store

   with

   text: "test memory for verification"

2. Recall: call

   memory_recall

   with

   query: "test memory"

3. Confirm the memory is returned

Installation

Quick Install (Beginner-Friendly)

For new users, the community one-click installer handles everything automatically — path detection, schema validation, auto-update, provider selection, and rollback:

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

Options:

--dry-run

--beta

--ref v1.2.0

--selfcheck-only

--uninstall

Source: https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup

Requirements

• Node.js 24 recommended (Node 22 LTS minimum,

  22.16+

  )
• LanceDB ≥ 0.26.2
• OpenAI SDK ≥ 6.21.0
• TypeBox 0.34.48

Install Method 1 — via OpenClaw plugin manager (recommended)

# Install from npm registry (@beta tag = latest pre-release, e.g. 1.1.0-beta.8)
openclaw plugins install memory-lancedb-pro@beta

# Install stable release from npm (@latest tag, e.g. 1.0.32)
openclaw plugins install memory-lancedb-pro

# Or install from a local git clone — use master branch (matches npm @beta)
git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git /tmp/memory-lancedb-pro
openclaw plugins install /tmp/memory-lancedb-pro

npm vs GitHub branches:

@beta

installs from the npm registry (not directly from GitHub). The repo has two long-lived branches:

master

is the release branch (matches npm

@beta

),

main

is older/behind. Always clone

master

if you want code that matches the published beta.

Then bind the memory slot and add your config (see Configuration section below):

{
  "plugins": {
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": { "<<your config here>>" }
      }
    }
  }
}

Restart and verify:

openclaw gateway restart
openclaw plugins info memory-lancedb-pro

Install Method 2 — git clone with manual path (Path A for development)

⚠️ Critical: Workspace plugins (git-cloned paths) are disabled by default in OpenClaw. You MUST explicitly enable them.

# 1. Clone into workspace
cd /path/to/your/openclaw/workspace
git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git plugins/memory-lancedb-pro
cd plugins/memory-lancedb-pro && npm install

Add to

openclaw.json

enabled: true

allow

{
  "plugins": {
    "load": { "paths": ["plugins/memory-lancedb-pro"] },
    "allow": ["memory-lancedb-pro"],
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "embedding": {
            "apiKey": "${JINA_API_KEY}",
            "model": "jina-embeddings-v5-text-small",
            "baseURL": "https://api.jina.ai/v1",
            "dimensions": 1024,
            "taskQuery": "retrieval.query",
            "taskPassage": "retrieval.passage",
            "normalized": true
          }
        }
      }
    }
  }
}

Validate and restart:

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

Expected log output:

• memory-lancedb-pro: smart extraction enabled

• memory-lancedb-pro@...: plugin registered

Install Method 3 — Existing deployments (Path B)

Use absolute paths in

plugins.load.paths

plugins.allow

plugins.slots.memory = "memory-lancedb-pro"

plugins.entries.memory-lancedb-pro.enabled: true

Then restart and verify:

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

New User First-Install Checklist

After the plugin starts successfully, determine which scenario applies and run the corresponding steps:

Scenario A — Coming from built-in

memory-lancedb

The old plugin stores data in LanceDB at

~/.openclaw/memory/lancedb

# 1. Check if old data exists and is readable
openclaw memory-pro migrate check

# 2. Preview what would be migrated (dry run)
openclaw memory-pro migrate run --dry-run

# 3. Run the actual migration
openclaw memory-pro migrate run

# 4. Verify migrated data
openclaw memory-pro migrate verify
openclaw memory-pro stats

If the old database is at a non-default path:

openclaw memory-pro migrate check --source /path/to/old/lancedb
openclaw memory-pro migrate run --source /path/to/old/lancedb

Scenario B — Existing memories exported as JSON

If you have memories in the standard JSON export format:

# Preview import (dry run)
openclaw memory-pro import memories.json --scope global --dry-run

# Import
openclaw memory-pro import memories.json --scope global

Expected JSON schema:

{
  "version": "1.0",
  "memories": [
    {
      "text": "Memory content (required)",
      "category": "preference|fact|decision|entity|other",
      "importance": 0.7,
      "timestamp": 1234567890000
    }
  ]
}

Scenario C — Memories stored in Markdown files (AGENTS.md, MEMORY.md, etc.)

There is no direct markdown import — the import command only accepts JSON. You need to convert first.

Manual conversion approach:

1. Open the markdown file(s) containing memories
2. For each memory entry, create a JSON object with

   text

   ,

   category

   ,

   importance

3. Save as a JSON file following the schema above
4. Run

   openclaw memory-pro import

Or use

memory_store

memory_store(text="<extracted memory>", category="fact", importance=0.8)

Note: Markdown-based memory files (MEMORY.md, AGENTS.md) are workspace context files, not the same as the LanceDB memory store. You only need to migrate them if you want that content searchable via

memory_recall

.

Scenario D — Fresh install, no prior memories

No migration needed. Verify the plugin is working with a quick smoke test:

openclaw memory-pro stats     # should show 0 memories

Then trigger a conversation —

autoCapture

LanceDB Version Compatibility

No manual action required for LanceDB version changes.

The plugin requires

@lancedb/lancedb ^0.26.2

LanceDB 0.26+ changed how numeric columns are returned (Arrow

BigInt

timestamp

importance

_distance

_score

Number(...)

TL;DR: LanceDB version compatibility is fully automatic. See the table below for when each maintenance command actually applies.

Upgrading plugin code vs. data

Command distinction (important):

openclaw plugins update memory-lancedb-pro

openclaw plugins update --all

openclaw memory-pro upgrade

openclaw memory-pro migrate

memory-lancedb

openclaw memory-pro reembed

When do you need

memory-pro upgrade

Run it if you installed memory-lancedb-pro before the smart-memory format was introduced (i.e., entries are missing

memory_category

• memory_recall

  returns results but without meaningful categories

• memory-pro list --json

  shows entries with no

  l0_abstract

  /

  l1_overview

  fields

Safe upgrade sequence:

# 1. Backup first
openclaw memory-pro export --scope global --output memories-backup.json

# 2. Preview what would change
openclaw memory-pro upgrade --dry-run

# 3. Run upgrade (uses LLM by default for L0/L1/L2 generation)
openclaw memory-pro upgrade

# 4. Verify results
openclaw memory-pro stats
openclaw memory-pro search "your known keyword" --scope global --limit 5

Upgrade options:

openclaw memory-pro upgrade --no-llm          # skip LLM, use simple text truncation
openclaw memory-pro upgrade --batch-size 5    # slower but safer for large collections
openclaw memory-pro upgrade --limit 50        # process only first N entries
openclaw memory-pro upgrade --scope global    # limit to one scope

Plugin management commands

openclaw plugins list                           # show all discovered plugins
openclaw plugins info memory-lancedb-pro        # show plugin status and config
openclaw plugins enable memory-lancedb-pro      # enable a disabled plugin
openclaw plugins disable memory-lancedb-pro     # disable without removing
openclaw plugins update memory-lancedb-pro      # update npm-installed plugin
openclaw plugins update --all                   # update all npm plugins
openclaw plugins doctor                         # health check for all plugins
openclaw plugins install ./path/to/plugin       # install local plugin (copies + enables)
openclaw plugins install @scope/plugin@beta     # install from npm registry
openclaw plugins install -l ./path/to/plugin    # symlink for dev (no copy)

Gateway restart required after:

plugins install

,

plugins enable

,

plugins disable

,

plugins update

, or any change to

openclaw.json

. Changes do not take effect until the gateway is restarted.

openclaw gateway restart

Easy-to-Miss Setup Steps

1. Gateway restart required after any change: After installing, enabling, disabling, updating, or changing config in

   openclaw.json

   , you MUST run

   openclaw gateway restart

   — changes are NOT hot-reloaded.
2. Workspace plugins are DISABLED by default: After git clone, you MUST add

   plugins.allow: ["memory-lancedb-pro"]

   AND

   plugins.entries.memory-lancedb-pro.enabled: true

   — without these the plugin silently does not load.
3. Env vars in gateway process:

   ${OPENAI_API_KEY}

   requires env vars set in the OpenClaw Gateway service process—not just your shell.
4. Absolute vs. relative paths: For existing deployments, always use absolute paths in

   plugins.load.paths

   .

5. baseURL

   not

   baseUrl

   : The embedding (and llm) config field is

   baseURL

   (capital URL), NOT

   baseUrl

   . Using the wrong casing causes a schema validation error: "must NOT have additional properties". Also note the required

   /v1

   suffix:

   http://localhost:11434/v1

   , not

   http://localhost:11434

   . Do not confuse with

   agents.defaults.memorySearch.remote.baseUrl

   which uses a different casing.
6. jiti cache invalidation: After modifying

   .ts

   files under plugins, run

   rm -rf /tmp/jiti/

   BEFORE

   openclaw gateway restart

   .
7. Unknown plugin id = error: OpenClaw treats unknown ids in

   entries

   ,

   allow

   ,

   deny

   , or

   slots

   as validation errors. The plugin id must be discoverable before referencing it.
8. Separate LLM config: If embedding and LLM use different providers, configure the

   llm

   section separately — it falls back to embedding key/URL otherwise.
9. Scope isolation: Multi-scope requires explicit

   scopes.agentAccess

   mapping — without it, agents only see

   global

   scope.
10. Session memory hook: Fires on

    /new

    command — test with an actual

    /new

    invocation.
11. Reranker credentials: When switching providers, update both

    rerankApiKey

    AND

    rerankEndpoint

    .
12. Config check before assuming defaults: Run

    openclaw config get plugins.entries.memory-lancedb-pro

    to verify what's actually loaded.
13. Custom config/state paths via env vars: OpenClaw respects the following environment variables for custom paths:

    • OPENCLAW_HOME

      — sets the root config/data directory (default:

      ~/.openclaw/

      )

    • OPENCLAW_CONFIG_PATH

      — absolute path to

      openclaw.json

      override

    • OPENCLAW_STATE_DIR

      — override for runtime state/data directory Set these in the OpenClaw Gateway process's environment if the default

      ~/.openclaw/

      path is not appropriate.

Post-Installation Verification

openclaw doctor                                 # full health check (recommended)
openclaw config validate                        # config schema check only
openclaw plugins info memory-lancedb-pro        # plugin status
openclaw plugins doctor                         # plugin-specific health
openclaw hooks list --json | grep memory        # confirm hooks registered
openclaw memory-pro stats
openclaw memory-pro list --scope global --limit 5

Full smoke test checklist:

• ✅ Plugin info shows

  enabled: true

  and config loaded
• ✅ Hooks include

  before_agent_start

  ,

  agent_end

  ,

  command:new

• ✅ One

  memory_store

  →

  memory_recall

  round trip via tools
• ✅ One exact-ID search hit
• ✅ One natural-language search hit
• ✅ If session memory enabled: one real

  /new

  test

Troubleshooting — Error Message Quick Reference

Config validation tool (from CortexReach/toolbox):

# Download once
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/scripts/config-validate.mjs -o config-validate.mjs
# Run against your openclaw.json
node config-validate.mjs
# Or validate a specific config snippet
node config-validate.mjs --json '{"embedding":{"baseURL":"http://localhost:11434/v1","model":"bge-m3","apiKey":"ollama"}}'

Exit code 0 = pass/warn, 1 = errors found.

must NOT have additional properties

config.embedding

baseUrl

baseURL

must NOT have additional properties

memory-lancedb-pro: plugin not found

plugins.allow

enabled: false

plugins.allow: ["memory-lancedb-pro"]

enabled: true

Unknown plugin id

entries

slots

${OPENAI_API_KEY}

before_agent_start

agent_end

openclaw gateway restart

baseURL

http://localhost:11434/v1

/v1

baseURL

baseUrl

memory-pro stats

autoCapture

extractMinMessages

autoCapture: true

extractMinMessages

autoRecall

"autoRecall": true

jiti

.ts

rm -rf /tmp/jiti/

openclaw gateway restart

Configuration

Minimal Quick-Start

{
  "embedding": {
    "provider": "openai-compatible",
    "apiKey": "${OPENAI_API_KEY}",
    "model": "text-embedding-3-small"
  },
  "autoCapture": true,
  "autoRecall": true,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "sessionMemory": { "enabled": false }
}

Note:

autoRecall

true

Optimal Production Config (recommended)

Uses Jina for both embedding and reranking — best retrieval quality:

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "~/.openclaw/memory/lancedb-pro",
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "enableManagementTools": false,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "rerank": "cross-encoder",
    "rerankProvider": "jina",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankApiKey": "${JINA_API_KEY}",
    "candidatePoolSize": 12,
    "minScore": 0.6,
    "hardMinScore": 0.62,
    "filterNoise": true,
    "lengthNormAnchor": 500,
    "timeDecayHalfLifeDays": 60,
    "reinforcementFactor": 0.5,
    "maxHalfLifeMultiplier": 3
  },
  "sessionMemory": { "enabled": false, "messageCount": 15 }
}

Why these settings excel:

• Jina embeddings: Task-aware vectors (

  taskQuery

  /

  taskPassage

  ) optimized for retrieval
• Hybrid mode 0.7/0.3: Balances semantic understanding with exact keyword matching
• Jina reranker v3: Cross-encoder reranking significantly improves relevance

• candidatePoolSize: 12

  +

  minScore: 0.6

  : Aggressive filtering reduces noise

• captureAssistant: false

  : Prevents storing agent-generated boilerplate

• sessionMemory: false

  : Avoids polluting retrieval with session summaries

Full Config (all options)

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "~/.openclaw/memory/lancedb-pro",
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "enableManagementTools": false,
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "minScore": 0.3,
    "hardMinScore": 0.35,
    "rerank": "cross-encoder",
    "rerankProvider": "jina",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankApiKey": "${JINA_API_KEY}",
    "candidatePoolSize": 20,
    "recencyHalfLifeDays": 14,
    "recencyWeight": 0.1,
    "filterNoise": true,
    "lengthNormAnchor": 500,
    "timeDecayHalfLifeDays": 60,
    "reinforcementFactor": 0.5,
    "maxHalfLifeMultiplier": 3
  },
  "scopes": {
    "default": "global",
    "definitions": {
      "global": { "description": "Shared knowledge" },
      "agent:discord-bot": { "description": "Discord bot private" }
    },
    "agentAccess": {
      "discord-bot": ["global", "agent:discord-bot"]
    }
  },
  "sessionStrategy": "none",
  "memoryReflection": {
    "storeToLanceDB": true,
    "injectMode": "inheritance+derived",
    "agentId": "memory-distiller",
    "messageCount": 120,
    "maxInputChars": 24000,
    "thinkLevel": "medium"
  },
  "selfImprovement": {
    "enabled": true,
    "beforeResetNote": true,
    "ensureLearningFiles": true
  },
  "mdMirror": { "enabled": false },
  "decay": {
    "recencyHalfLifeDays": 30,
    "recencyWeight": 0.4,
    "frequencyWeight": 0.3,
    "intrinsicWeight": 0.3,
    "betaCore": 0.8,
    "betaWorking": 1.0,
    "betaPeripheral": 1.3
  },
  "tier": {
    "coreAccessThreshold": 10,
    "coreCompositeThreshold": 0.7,
    "coreImportanceThreshold": 0.8,
    "workingAccessThreshold": 3,
    "workingCompositeThreshold": 0.4,
    "peripheralCompositeThreshold": 0.15,
    "peripheralAgeDays": 60
  }
}

Configuration Field Reference

Embedding

apiKey

${ENV_VAR}

model

baseURL

dimensions

taskQuery

retrieval.query

taskPassage

retrieval.passage

normalized

provider

openai-compatible

chunking

Top-Level

dbPath

~/.openclaw/memory/lancedb-pro

autoCapture

agent_end

autoRecall

captureAssistant

smartExtraction

extractMinMessages

extractMaxChars

enableManagementTools

autoRecallMinLength

autoRecallMinRepeated

sessionStrategy

systemSessionMemory

memoryReflection

systemSessionMemory

none

autoRecallTopK

autoRecallSelectionMode

mmr

mmr

legacy

setwise-v2

autoRecallCategories

["preference","fact","decision","entity","other"]

autoRecallExcludeReflection

autoRecallMaxAgeDays

autoRecallMaxEntriesPerKey

LLM (for Smart Extraction)

llm.apiKey

embedding.apiKey

llm.model

openai/gpt-oss-120b

llm.baseURL

embedding.baseURL

Retrieval

mode

hybrid

hybrid

vector

bm25

vectorWeight

bm25Weight

minScore

hardMinScore

rerank

cross-encoder

cross-encoder

lightweight

none

rerankProvider

jina

jina

siliconflow

voyage

pinecone

vllm

rerankModel

jina-reranker-v3

rerankEndpoint

rerankApiKey

candidatePoolSize

recencyHalfLifeDays

recencyWeight

timeDecayHalfLifeDays

reinforcementFactor

maxHalfLifeMultiplier

filterNoise

lengthNormAnchor

Access reinforcement note: Reinforcement is whitelisted to

source: "manual"

Session Strategy (v1.1.0+)

Use

sessionStrategy

"systemSessionMemory"

"memoryReflection"

"none"

memoryReflection

sessionStrategy: "memoryReflection"

storeToLanceDB

writeLegacyCombined

injectMode

inheritance+derived

inheritance-only

inheritance+derived

agentId

"memory-distiller"

messageCount

maxInputChars

timeoutMs

thinkLevel

medium

off

minimal

low

medium

high

errorReminderMaxEntries

dedupeErrorSignals

memoryReflection.recall

mode

fixed

fixed

dynamic

topK

includeKinds

["invariant"]

invariant

derived

maxAgeDays

maxEntriesPerKey

minRepeated

minScore

minPromptLength

Session Memory (deprecated — legacy compat only)

⚠️

sessionMemory

is a legacy compatibility shim since v1.1.0. Prefer

sessionStrategy

instead.

• sessionMemory.enabled: true

  → maps to

  sessionStrategy: "systemSessionMemory"

• sessionMemory.enabled: false

  → maps to

  sessionStrategy: "none"

sessionMemory.enabled

/new

sessionMemory.messageCount

memoryReflection.messageCount

Self-Improvement Governance

selfImprovement.enabled

self_improvement_log

selfImprovement.beforeResetNote

selfImprovement.skipSubagentBootstrap

selfImprovement.ensureLearningFiles

LEARNINGS.md

ERRORS.md

Tool activation rules:

• self_improvement_log

  : requires

  selfImprovement.enabled: true

  (default — active unless explicitly disabled)

• self_improvement_extract_skill

  +

  self_improvement_review

  : additionally require

  enableManagementTools: true

Markdown Mirror

mdMirror.enabled

.md

mdMirror.dir

Decay

decay.recencyHalfLifeDays

decay.recencyWeight

retrieval.recencyWeight

decay.frequencyWeight

decay.intrinsicWeight

decay.betaCore

decay.betaWorking

decay.betaPeripheral

decay.coreDecayFloor

decay.workingDecayFloor

decay.peripheralDecayFloor

decay.staleThreshold

decay.searchBoostMin

decay.importanceModulation

Tier Management

tier.coreAccessThreshold

tier.coreCompositeThreshold

tier.coreImportanceThreshold

tier.workingAccessThreshold

tier.workingCompositeThreshold

tier.peripheralCompositeThreshold

tier.peripheralAgeDays

MCP Tools

Core Tools (auto-registered)

memory_recall

query

limit

scope

category

preference|fact|decision|entity|reflection|other

memory_store

text

importance

category

scope

agent:<id>

memory_forget

query

memoryId

scope

memory_update

preference

entity

memoryId

text

preference

entity

importance

category

Management Tools (enable with

enableManagementTools: true

)

memory_stats

• scope

  (string, optional): Filter by scope

memory_list

• limit

  (number, optional, default 10, max 50),

  scope

  ,

  category

  ,

  offset

  (pagination)

Self-Improvement Tools

self_improvement_log

is enabled by default (

selfImprovement.enabled: true

).

self_improvement_extract_skill

and

self_improvement_review

additionally require

enableManagementTools: true

.

self_improvement_log

type

"learning"

"error"

summary

details

suggestedAction

category

correction|best_practice|knowledge_gap

correction|bug_fix|integration_issue

area

frontend|backend|infra|tests|docs|config

priority

low|medium|high|critical

self_improvement_extract_skill

learningId

LRN-YYYYMMDD-001

ERR-*

skillName

sourceFile

LEARNINGS.md

LEARNINGS.md|ERRORS.md

outputDir

"skills"

self_improvement_review

Smart Extraction

LLM-powered automatic memory classification and storage triggered after conversations.

Enable

{
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini"
  }
}

Minimal (reuses embedding API key — no separate

llm

{
  "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" },
  "smartExtraction": true
}

Disable:

{ "smartExtraction": false }

6-Category Classification

fact

preference

entity

decision

fact

other

L0/L1/L2 Layered Content per Memory

• L0 (Abstract): Single-sentence index (min 5 chars)
• L1 (Overview): Structured markdown summary
• L2 (Content): Full narrative detail

Two-Stage Deduplication

1. Vector pre-filter: Similarity ≥ 0.7 finds candidates
2. LLM decision:

   CREATE | MERGE | SKIP | SUPPORT | CONTEXTUALIZE | CONTRADICT

Embedding Providers

jina-embeddings-v5-text-small

https://api.jina.ai/v1

jina-embeddings-v4

https://api.jina.ai/v1

text-embedding-3-large

https://api.openai.com/v1

text-embedding-3-small

https://api.openai.com/v1

text-embedding-v4

https://dashscope.aliyuncs.com/compatible-mode/v1

gemini-embedding-2-preview

https://generativelanguage.googleapis.com/v1beta/openai/

gemini-embedding-001

https://generativelanguage.googleapis.com/v1beta/openai/

mxbai-embed-large

http://localhost:11434/v1

snowflake-arctic-embed2

http://localhost:11434/v1

nomic-embed-text:v1.5

http://localhost:11434/v1

DashScope rerank note: DashScope is not a

rerankProvider

rerankProvider: "jina"

"retrieval": {
  "rerank": "cross-encoder",
  "rerankProvider": "jina",
  "rerankModel": "qwen3-rerank",
  "rerankEndpoint": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",
  "rerankApiKey": "${DASHSCOPE_API_KEY}"
}

Multi-key failover: Set

apiKey

Reranker Providers

rerankProvider

jina

https://api.jina.ai/v1/rerank

jina-reranker-v3

jina

https://api.jina.ai/v1/rerank

jina-reranker-m0

siliconflow

https://api.siliconflow.com/v1/rerank

BAAI/bge-reranker-v2-m3

voyage

https://api.voyageai.com/v1/rerank

rerank-2.5

{model, query, documents}

top_n

pinecone

https://api.pinecone.io/rerank

bge-reranker-v2-m3

vllm

Jina key can be reused for both embedding and reranking.

Multi-Scope Isolation

global

agent:<id>

custom:<name>

project:<id>

user:<id>

Default access:

global

agent:<id>

scopes.agentAccess

To disable memory entirely (unbind the slot without removing the plugin):

{ "plugins": { "slots": { "memory": "none" } } }

Memory Lifecycle (Weibull Decay)

Three Tiers

Promotion/Demotion Rules

• Peripheral → Working: access ≥ 3 AND score ≥ 0.4
• Working → Core: access ≥ 10 AND score ≥ 0.7 AND importance ≥ 0.8
• Working → Peripheral: score < 0.15 OR (age > 60 days AND access < 3)
• Core → Working: score < 0.15 AND access < 3

Hybrid Retrieval

Fusion:

weightedFusion = (vectorScore × 0.7) + (bm25Score × 0.3)

Pipeline: RRF Fusion → Cross-Encoder Rerank → Lifecycle Decay Boost → Length Norm → Hard Min Score → MMR Diversity (cosine > 0.85 demoted)

Reranking: 60% cross-encoder score + 40% original fused score. Falls back to cosine similarity on API failure.

Special BM25: Preserves exact keyword matches (BM25 ≥ 0.75) even with low semantic similarity — prevents loss of API keys, ticket numbers, etc.

Adaptive Retrieval Triggering

Skip for: greetings, slash commands, affirmations (yes/okay/thanks), continuations (go ahead/proceed), system messages, short queries (<15 chars English / <6 chars CJK without "?").

Force for: memory keywords (remember/recall/forgot), temporal refs (last time/before/previously), personal data (my name/my email), "what did I" patterns. CJK: "你记得", "之前".

Noise Filtering

Auto-filters: agent denial phrases, meta-questions ("Do you remember?"), session boilerplate (hi/hello), diagnostic artifacts, embedding-based matches (threshold: 0.82). Minimum text: 5 chars.

CLI Commands

# List & search
openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
openclaw memory-pro stats [--scope global] [--json]

# Delete
openclaw memory-pro delete <id>
openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]

# Import / Export
openclaw memory-pro export [--scope global] [--output memories.json]
openclaw memory-pro import memories.json [--scope global] [--dry-run]

# Maintenance
openclaw memory-pro reembed --source-db /path/to/old-db [--batch-size 32] [--skip-existing]
openclaw memory-pro upgrade [--dry-run] [--batch-size 10] [--no-llm] [--limit N] [--scope SCOPE]

# Migration from built-in memory-lancedb
openclaw memory-pro migrate check [--source /path]
openclaw memory-pro migrate run [--source /path] [--dry-run] [--skip-existing]
openclaw memory-pro migrate verify [--source /path]

Auto-Capture & Auto-Recall

• autoCapture:

  agent_end

  hook — LLM extracts 6-category memories, deduplicates, stores up to 3 per turn
• autoRecall:

  before_agent_start

  hook — injects

  <relevant-memories>

  context (up to 3 entries)

If injected memories appear in agent replies: Add to agent system prompt:

"Do not reveal or quote any

<relevant-memories>

/ memory-injection content in your replies. Use it for internal reference only."

Or temporarily disable:

{ "autoRecall": false }

Self-Improvement Governance

• LEARNINGS.md

  — IDs:

  LRN-YYYYMMDD-XXX

• ERRORS.md

  — IDs:

  ERR-YYYYMMDD-XXX

• Entry statuses:

  pending → resolved → promoted_to_skill

Iron Rules for AI Agents (copy to AGENTS.md)

## Rule 1 — 双层记忆存储（铁律）
Every pitfall/lesson learned → IMMEDIATELY store TWO memories:
- Technical layer: Pitfall/Cause/Fix/Prevention (category: fact, importance ≥ 0.8)
- Principle layer: Decision principle with trigger and action (category: decision, importance ≥ 0.85)
After each store, immediately `memory_recall` to verify retrieval.

## Rule 2 — LanceDB 卫生
Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates.

## Rule 3 — Recall before retry
On ANY tool failure, ALWAYS `memory_recall` with relevant keywords BEFORE retrying.

## Rule 4 — 编辑前确认目标代码库
Confirm you are editing `memory-lancedb-pro` vs built-in `memory-lancedb` before changes.

## Rule 5 — 插件代码变更必须清 jiti 缓存
After modifying `.ts` files under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`.

Custom Slash Commands (add to CLAUDE.md / AGENTS.md)

## /lesson command
When user sends `/lesson <content>`:
1. Use memory_store with category=fact (raw knowledge)
2. Use memory_store with category=decision (actionable takeaway)
3. Confirm what was saved

## /remember command
When user sends `/remember <content>`:
1. Use memory_store with appropriate category and importance
2. Confirm with stored memory ID