Compared to Built-in memory-lancedb (click to expand)
| Feature | Built-in `memory-lancedb` | **memory-lancedb-pro** |
| --- | :---: | :---: |
| Vector search | Yes | Yes |
| BM25 full-text search | - | Yes |
| Hybrid fusion (Vector + BM25) | - | Yes |
| Cross-encoder rerank (multi-provider) | - | Yes |
| Recency boost & time decay | - | Yes |
| Length normalization | - | Yes |
| MMR diversity | - | Yes |
| Multi-scope isolation | - | Yes |
| Noise filtering | - | Yes |
| Adaptive retrieval | - | Yes |
| Management CLI | - | Yes |
| Session memory | - | Yes |
| Task-aware embeddings | - | Yes |
| **LLM Smart Extraction (6-category)** | - | Yes (v1.1.0) |
| **Weibull Decay + Tier Promotion** | - | Yes (v1.1.0) |
| Any OpenAI-compatible embedding | Limited | Yes |
Full Configuration Example
```json { "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, "maxInputChars": 1400, "clientTimeoutMs": 30000 }, "dbPath": "~/.openclaw/memory/lancedb-pro", "autoCapture": true, "autoRecall": true, "retrieval": { "mode": "hybrid", "vectorWeight": 0.7, "bm25Weight": 0.3, "minScore": 0.3, "rerank": "cross-encoder", "rerankApiKey": "${JINA_API_KEY}", "rerankModel": "jina-reranker-v3", "rerankEndpoint": "https://api.jina.ai/v1/rerank", "rerankProvider": "jina", "candidatePoolSize": 20, "recencyHalfLifeDays": 14, "recencyWeight": 0.1, "filterNoise": true, "disableNativeCosine": false, "lengthNormAnchor": 500, "hardMinScore": 0.35, "timeDecayHalfLifeDays": 60, "reinforcementFactor": 0.5, "maxHalfLifeMultiplier": 3 }, "enableManagementTools": false, "scopes": { "default": "global", "definitions": { "global": { "description": "Shared knowledge" }, "agent:discord-bot": { "description": "Discord bot private" } }, "agentAccess": { "discord-bot": ["global", "agent:discord-bot"] } }, "sessionStrategy": "none", "sessionMemory": { "enabled": false, "messageCount": 15 }, "smartExtraction": true, "llm": { "apiKey": "${OPENAI_API_KEY}", "model": "gpt-4o-mini", "baseURL": "https://api.openai.com/v1" }, "extractMinMessages": 2, "extractMaxChars": 8000 } ```Embedding Providers
Works with **OpenAI-compatible embedding APIs**, including provider-specific payload adapters for services such as Jina and Voyage: | Provider | Model | Base URL | Dimensions | | --- | --- | --- | --- | | **Jina** (recommended) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | | **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | | **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | | **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | | **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | provider-specific | Voyage embedding requests use Voyage's `model` + `input` payload shape. When `requestDimensions` is configured it is sent as `output_dimension`; OpenAI-only fields such as `encoding_format` are omitted. Set `embedding.maxInputChars` for local embedding servers with small context or batch limits. The plugin applies a conservative default for `nomic-embed-text`; with automatic chunking enabled, longer documents are split before the cap is applied to each provider request.Rerank Providers
Cross-encoder reranking supports multiple providers via `rerankProvider`: | Provider | `rerankProvider` | Example Model | | --- | --- | --- | | **Jina** (default) | `jina` | `jina-reranker-v3` | | **SiliconFlow** (free tier available) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | | **Voyage AI** | `voyage` | `rerank-2.5` | | **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | Any Jina-compatible rerank endpoint also works โ set `rerankProvider: "jina"` and point `rerankEndpoint` to your service (e.g., Hugging Face TEI, DashScope `qwen3-rerank`).Smart Extraction (LLM) โ v1.1.0
When `smartExtraction` is enabled (default: `true`), the plugin uses an LLM to intelligently extract and classify memories instead of regex-based triggers. | Field | Type | Default | Description | |-------|------|---------|-------------| | `smartExtraction` | boolean | `true` | Enable/disable LLM-powered 6-category extraction | | `llm.auth` | string | `api-key` | `api-key` uses `llm.apiKey` / `embedding.apiKey`; `oauth` uses a plugin-scoped OAuth token file by default | | `llm.apiKey` | string | *(falls back to `embedding.apiKey`)* | API key for the LLM provider | | `llm.model` | string | `openai/gpt-oss-120b` | LLM model name | | `llm.baseURL` | string | *(falls back to `embedding.baseURL`)* | LLM API endpoint | | `llm.oauthProvider` | string | `openai-codex` | OAuth provider id used when `llm.auth` is `oauth` | | `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | OAuth token file used when `llm.auth` is `oauth` | | `llm.timeoutMs` | number | `30000` | LLM request timeout in milliseconds | | `extractMinMessages` | number | `2` | Minimum messages before extraction triggers | | `extractMaxChars` | number | `8000` | Maximum characters sent to the LLM | OAuth `llm` config (use existing Codex / ChatGPT login cache for LLM calls): ```json { "llm": { "auth": "oauth", "oauthProvider": "openai-codex", "model": "gpt-5.4", "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", "timeoutMs": 30000 } } ``` Notes for `llm.auth: "oauth"`: - `llm.oauthProvider` is currently `openai-codex`. - OAuth tokens default to `~/.openclaw/.memory-lancedb-pro/oauth.json`. - You can set `llm.oauthPath` if you want to store that file somewhere else. - `auth login` snapshots the previous api-key `llm` config next to the OAuth file, and `auth logout` restores that snapshot when available. - Switching from `api-key` to `oauth` does not automatically carry over `llm.baseURL`. Set it manually in OAuth mode only when you intentionally want a custom ChatGPT/Codex-compatible backend.Legacy CPU Fallback
If an AVX-only Linux x64 host crashes inside LanceDB native vector search with `SIGILL`, disable native cosine and let memory-lancedb-pro scan scoped rows and rank them in JavaScript: ```json { "retrieval": { "disableNativeCosine": true } } ``` You can also set `MEMORY_LANCEDB_DISABLE_NATIVE_COSINE=1` for the same behavior.Lifecycle Configuration (Decay + Tier)
| Field | Default | Description | |-------|---------|-------------| | `decay.recencyHalfLifeDays` | `30` | Base half-life for Weibull recency decay | | `decay.frequencyWeight` | `0.3` | Weight of access frequency in composite score | | `decay.intrinsicWeight` | `0.3` | Weight of `importance ร confidence` | | `decay.betaCore` | `0.8` | Weibull beta for `core` memories | | `decay.betaWorking` | `1.0` | Weibull beta for `working` memories | | `decay.betaPeripheral` | `1.3` | Weibull beta for `peripheral` memories | | `tier.coreAccessThreshold` | `10` | Min recall count before promoting to `core` | | `tier.peripheralAgeDays` | `60` | Age threshold for demoting stale memories |Access Reinforcement
Frequently recalled memories decay more slowly (spaced-repetition style). Config keys (under `retrieval`): - `reinforcementFactor` (0-2, default: `0.5`) โ set `0` to disable - `maxHalfLifeMultiplier` (1-10, default: `3`) โ hard cap on effective half-lifeLocking and concurrent writers
`memory-lancedb-pro` uses a cross-process file lock for LanceDB writes. This is enough for one gateway process, multiple agents through that gateway, and local processes that share the same database directory. Redis is not required for those deployments. Redis locking is enabled when `locking.redis.enabled` is true, when `redisUrl`/`locking.redis.url` is set, or when `MEMORY_LANCEDB_REDIS_URL` is present in that process environment. For multi-machine or multi-container writers, read [Lock Management](docs/lock-management.md) before sharing a LanceDB directory across processes, and make sure every writer uses the same lock configuration.If injected memories show up in replies
Sometimes the model may echo the injected `Auto-recall timeout tuning
Auto-recall has a configurable timeout (default 5s) to prevent stalling agent startup. If you're behind a proxy or using a high-latency embedding API, increase it: ```json { "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecallTimeoutMs": 8000 } } } } } ``` If auto-recall consistently times out, check your embedding API latency first. The timeout only affects the automatic injection path โ manual `memory_recall` tool calls are not affected.Auto-recall rerank cost model
When `autoRecall=true` and hybrid retrieval uses `retrieval.rerank="cross-encoder"` with an external rerank API such as Jina, every eligible prompt can make a rerank request. The number of documents sent to that request is governed by auto-recall's retrieve limit and the retriever's rerank input window, not directly by `retrieval.candidatePoolSize` or by the final `autoRecallMaxItems` injection cap. For example, with `autoRecallMaxItems: 3`, auto-recall asks retrieval for 6 items and hybrid retrieval may send up to 12 candidates to the external reranker before injecting at most 3 memories. To reduce external rerank usage, lower `autoRecallMaxItems` or `maxRecallPerTurn`, switch `retrieval.rerank` to `"lightweight"` or `"none"`, increase `autoRecallMinLength`, or keep auto-recall disabled and use manual `memory_recall` where appropriate. Startup logs warn when auto-recall plus hybrid cross-encoder rerank can send more items to the reranker than it will inject. Debug auto-recall stats include the actual `rerankInput`, `rerankInputLimit`, `retrieveLimit`, `rerank`, `rerankProvider`, and configured `retrievalCandidatePoolSize`.Session Memory
- Triggered on `/new` command โ saves previous session summary to LanceDB - Disabled by default (OpenClaw already has native `.jsonl` session persistence) - Configurable message count (default: 15) See [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) for deployment modes and `/new` verification.Custom Slash Commands (e.g. /lesson)
Add to your `CLAUDE.md`, `AGENTS.md`, or system prompt: ```markdown ## /lesson command When the user sends `/lessonIron Rules for AI Agents
> Copy the block below into your `AGENTS.md` so your agent enforces these rules automatically. ```markdown ## Rule 1 โ Dual-layer memory storage Every pitfall/lesson learned โ IMMEDIATELY store TWO memories: - Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] (category: fact, importance >= 0.8) - Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] (category: decision, importance >= 0.85) ## Rule 2 โ LanceDB hygiene 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 target codebase Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. ## Rule 5 โ Clear jiti cache after plugin code changes After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. ```Database Schema
LanceDB table `memories`: | Field | Type | Description | | --- | --- | --- | | `id` | string (UUID) | Primary key | | `text` | string | Memory text (FTS indexed) | | `vector` | float[] | Embedding vector | | `category` | string | Storage category: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | | `scope` | string | Scope identifier (e.g., `global`, `agent:main`) | | `importance` | float | Importance score 0-1 | | `timestamp` | int64 | Creation timestamp (ms) | | `metadata` | string (JSON) | Extended metadata | Common `metadata` keys in v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` > **Note on categories:** The top-level `category` field uses 6 storage categories. The 6-category semantic labels from Smart Extraction (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) are stored in `metadata.memory_category`.Troubleshooting
### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) On LanceDB 0.26+, some numeric columns may be returned as `BigInt`. Upgrade to **memory-lancedb-pro >= 1.0.14** โ this plugin now coerces values using `Number(...)` before arithmetic.
