# LanceDB Pro

# memory-lancedb-pro

Enhanced LanceDB memory plugin for OpenClaw — community reference guide

## Overview

**memory-lancedb-pro** is a community-developed, production-grade long-term memory plugin for OpenClaw. It replaces the built-in `memory-lancedb` plugin with a significantly more capable retrieval pipeline, designed for agents that need persistent, high-quality memory across sessions without manual tagging or configuration overhead.

The core problem it solves: standard OpenClaw agents have no memory between sessions. Every conversation starts from zero. memory-lancedb-pro automatically captures what matters from each session and retrieves relevant context in future ones.

Primary upstream repo: `CortexReach/memory-lancedb-pro`. Several community forks exist (win4r, McBorisson, fryeggs, kvc0769) with varying additions such as Volcengine multimodal embeddings or unified Claude Code/Claude Desktop support.

<div class="callout info" id="bkmrk-openclaw-2026.3%2B-com">**OpenClaw 2026.3+ compatibility:** The CortexReach fork has been updated to use `before_prompt_build` hooks, replacing the deprecated `before_agent_start` hook. If you are on 2026.3.24 or later, use this fork. Run `openclaw doctor --fix` after upgrading.</div>---

## Feature Comparison

<table id="bkmrk-feature-built-in-mem"><thead><tr><th>Feature</th><th>Built-in memory-lancedb</th><th>memory-lancedb-pro</th></tr></thead><tbody><tr><td>Vector search</td><td>✓</td><td>✓</td></tr><tr><td>BM25 full-text search</td><td>✗</td><td>✓</td></tr><tr><td>Hybrid fusion (Vector + BM25)</td><td>✗</td><td>✓ configurable weights</td></tr><tr><td>Cross-encoder reranking</td><td>✗</td><td>✓ Jina, SiliconFlow, Pinecone, etc.</td></tr><tr><td>Recency / time decay scoring</td><td>✗</td><td>✓</td></tr><tr><td>MMR diversity filtering</td><td>✗</td><td>✓</td></tr><tr><td>Multi-scope isolation</td><td>✗</td><td>✓ global / agent / project / user</td></tr><tr><td>Smart LLM extraction</td><td>✗</td><td>✓ optional, uses any OpenAI-compatible LLM</td></tr><tr><td>Management CLI</td><td>✗</td><td>✓ list / search / stats / delete / export / import</td></tr><tr><td>Auto-capture on session end</td><td>✓ basic</td><td>✓ with deduplication, up to 3 per turn</td></tr><tr><td>Auto-recall before prompt</td><td>✓ basic</td><td>✓ adaptive — skips trivial/short queries</td></tr><tr><td>Noise filtering</td><td>✗</td><td>✓</td></tr><tr><td>Migration tool from built-in plugin</td><td>—</td><td>✓</td></tr></tbody></table>

---

## Retrieval Pipeline

Queries pass through a multi-stage pipeline before results are injected into the agent prompt:

1. **Embed query** — using the configured OpenAI-compatible embedding provider
2. **Parallel search** — vector ANN search (cosine distance) + BM25 full-text search run simultaneously
3. **Hybrid fusion** — vector score used as base; BM25 hits receive a configurable weighted boost
4. **Rerank** — optional cross-encoder reranking via external API (60% cross-encoder score + 40% fused score)
5. **Lifecycle decay scoring** — recency boost, time decay, importance weight, length normalisation
6. **Filter** — hard minimum score, noise filter, MMR diversity deduplication
7. **Inject** — surviving memories injected as `<relevant-memories>` context block

If the reranker API fails, the pipeline degrades gracefully to cosine similarity reranking.

---

## Installation

### 1. Clone into your OpenClaw workspace

```
cd ~/.openclaw/workspace
git clone https://github.com/CortexReach/memory-lancedb-pro.git plugins/memory-lancedb-pro
cd plugins/memory-lancedb-pro
npm install
```

<div class="callout warn" id="bkmrk-common-mistake%3A-clon">**Common mistake:** Cloning the repo somewhere other than your workspace and then using a relative path in `plugins.load.paths`. Relative paths are resolved from the workspace root. Use an absolute path if cloning elsewhere.</div>### 2. Disable the built-in memory plugin

Only one memory plugin can be active at a time. If you previously used `memory-lancedb`, disable it before enabling this plugin.

### 3. Add to openclaw.json

```
{
  "plugins": {
    "load": {
      "paths": ["plugins/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
          }
        }
      }
    },
    "slots": {
      "memory": "memory-lancedb-pro"
    }
  }
}
```

Config changes require a gateway restart. With config watch enabled (default), this happens automatically.

---

## Key Configuration Options

<table id="bkmrk-option-default-notes"><thead><tr><th>Option</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td>`autoCapture`</td><td>true</td><td>Capture memories at session end</td></tr><tr><td>`autoRecall`</td><td>true</td><td>Inject memories before prompt build</td></tr><tr><td>`smartExtraction`</td><td>true</td><td>Use LLM to classify memories instead of regex</td></tr><tr><td>`extractMinMessages`</td><td>3</td><td>Minimum messages before extraction runs</td></tr><tr><td>`captureAssistant`</td><td>true</td><td>Set false to only capture user messages</td></tr><tr><td>`retrieval.mode`</td><td>hybrid</td><td>`vector`, `bm25`, or `hybrid`</td></tr><tr><td>`retrieval.vectorWeight`</td><td>0.7</td><td>Weight for vector scores in hybrid fusion</td></tr><tr><td>`retrieval.bm25Weight`</td><td>0.3</td><td>Weight for BM25 scores in hybrid fusion</td></tr><tr><td>`rerank.enabled`</td><td>false</td><td>Enable cross-encoder reranking</td></tr><tr><td>`rerank.candidatePoolSize`</td><td>12</td><td>Candidates passed to reranker</td></tr><tr><td>`rerank.minScore`</td><td>0.6</td><td>Soft minimum score post-rerank</td></tr><tr><td>`rerank.hardMinScore`</td><td>0.62</td><td>Hard cutoff — below this is always dropped</td></tr><tr><td>`sessionMemory.enabled`</td><td>true</td><td>Store session summaries on `/new`</td></tr><tr><td>`autoRecall.minPromptLength`</td><td>15 (EN) / 6 (CJK)</td><td>Skip recall for very short queries</td></tr></tbody></table>

---

## Management CLI

The plugin ships with a CLI for direct memory management:

```
openclaw memory-pro list              # list stored memories
openclaw memory-pro search <query>   # semantic/keyword search
openclaw memory-pro stats             # storage stats
openclaw memory-pro delete <id>      # delete a specific memory
openclaw memory-pro export            # export all memories
openclaw memory-pro import <file>    # import memories
```

---

## Agent Tool Definitions

When loaded, the plugin registers these tools for the agent to use directly:

- `memory_recall` — retrieve relevant memories for a query
- `memory_store` — explicitly store a memory
- `memory_forget` — delete a memory by ID or query
- `memory_update` — update an existing memory

Plus additional management tools exposed via the CLI commands above.

---

## Multi-Scope Isolation

Memories can be scoped to control access between agents and users:

- <span class="tag">global</span> — shared across all agents
- <span class="tag blue">agent:&lt;id&gt;</span> — isolated to a specific agent
- <span class="tag blue">project:&lt;id&gt;</span> — shared within a project
- <span class="tag green">user:&lt;id&gt;</span> — per-user isolation (useful for multi-user bots)
- <span class="tag">custom:&lt;name&gt;</span> — arbitrary named scope

---

## Telegram Setup

If running OpenClaw with Telegram, the easiest way to configure the plugin is via the bot directly. Send the following to your main bot:

```
Help me connect this memory plugin with the most user-friendly configuration:
https://github.com/CortexReach/memory-lancedb-pro
Requirements:
1. Set it as the only active memory plugin
2. Use Jina for embedding and reranker
3. Use gpt-4o-mini for the smart-extraction LLM
... (continue with your preferences)
```

---

## Important Notes

<div class="callout warn" id="bkmrk-jiti-cache%3A-after-mo">**jiti cache:** After modifying any `.ts` file in the plugin, you must clear the jiti cache before restarting the gateway, or OpenClaw will load stale compiled code:  
`rm -rf /tmp/jiti/ && openclaw gateway restart`</div><div class="callout info" id="bkmrk-memory-quality-guide">**Memory quality guidelines:** Never store raw conversation summaries, large blobs, or duplicates. Prefer structured, atomic facts with keywords. On any tool failure or repeated error, call `memory_recall` with relevant keywords before retrying — the fix may already be stored.</div><div class="callout" id="bkmrk-spaced-repetition%3A-f">**Spaced repetition:** Frequently recalled memories decay more slowly, similar to spaced-repetition learning systems.</div>---

## Notable Community Forks

<table id="bkmrk-fork-notable-additio"><thead><tr><th>Fork</th><th>Notable additions</th></tr></thead><tbody><tr><td>`CortexReach/memory-lancedb-pro`</td><td>Primary upstream. Updated for OpenClaw 2026.3+ hook architecture.</td></tr><tr><td>`win4r/memory-lancedb-pro`</td><td>Widely referenced in docs; standard feature set.</td></tr><tr><td>`fryeggs/memory-lancedb-pro`</td><td>Unified edition — extends to Claude Code, Codex CLI, and Claude Desktop via shared LanceDB backend.</td></tr><tr><td>`kvc0769/memory-lancedb-pro`</td><td>Adds Volcengine multimodal embedding support.</td></tr><tr><td>`McBorisson/memory-lancedb-pro`</td><td>Uses RRF fusion (vs. weighted boost in other forks); includes JSONL distillation pipeline.</td></tr></tbody></table>

---

Generated March 2026. Sources: CortexReach/memory-lancedb-pro, openclaw/openclaw docs, LanceDB blog.