🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
AI Memory Assistant for OpenClaw Agents
Give your AI agent a brain that actually remembers — across sessions, across agents, across time.
A LanceDB-backed OpenClaw memory plugin that stores preferences, decisions, and project context, then auto-recalls them in future sessions.
✅ Fully adapted for OpenClaw 2026.3+ new plugin architecture
🔄 Uses before_prompt_build hooks (replacing deprecated before_agent_start)
🩺 Run openclaw doctor --fix after upgrading
English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Français | Español | Deutsch | Italiano | Русский | Português (Brasil)
Why memory-lancedb-pro?
Most AI agents have amnesia. They forget everything the moment you start a new chat.
memory-lancedb-pro is a production-grade long-term memory plugin for OpenClaw that turns your agent into an AI Memory Assistant — it automatically captures what matters, lets noise naturally fade, and retrieves the right memory at the right time. No manual tagging, no configuration headaches.
Your AI Memory Assistant in Action
Without memory — every session starts from zero:
You: "Use tabs for indentation, always add error handling."
(next session)
You: "I already told you — tabs, not spaces!" 😤
(next session)
You: "...seriously, tabs. And error handling. Again."
With memory-lancedb-pro — your agent learns and remembers:
You: "Use tabs for indentation, always add error handling."
(next session — agent auto-recalls your preferences)
Agent: (silently applies tabs + error handling) ✅
You: "Why did we pick PostgreSQL over MongoDB last month?"
Agent: "Based on our discussion on Feb 12, the main reasons were..." ✅
That's the difference an AI Memory Assistant makes — it learns your style, recalls past decisions, and delivers personalized responses without you repeating yourself.
What else can it do?
|
What you get |
| Auto-Capture |
Your agent learns from every conversation — no manual memory_store needed |
| Smart Extraction |
LLM-powered 6-category classification: profiles, preferences, entities, events, cases, patterns |
| Intelligent Forgetting |
Weibull decay model — important memories stay, noise naturally fades away |
| Hybrid Retrieval |
Vector + BM25 full-text search, fused with cross-encoder reranking |
| Context Injection |
Relevant memories automatically surface before each reply |
| Multi-Scope Isolation |
Per-agent, per-user, per-project memory boundaries |
| Any Provider |
OpenAI, Jina, Gemini, Ollama, or any OpenAI-compatible API |
| Full Toolkit |
CLI, backup, migration, upgrade, export/import — production-ready |
Quick Start
CPU Requirement: Your CPU must support AVX instructions. LanceDB native vector search may require AVX2 on some Linux x64 builds and can crash AVX-only CPUs with SIGILL; set retrieval.disableNativeCosine: true or MEMORY_LANCEDB_DISABLE_NATIVE_COSINE=1 to use a scoped row scan plus JavaScript cosine ranking. Check CPU flags with: grep -o 'avx[^ ]*' /proc/cpuinfo | head -1 (no output = not supported). See #419 and #644 for details.
Option A: One-Click Install Script (Recommended)
The community-maintained setup script handles install, upgrade, and repair in one command:
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
bash setup-memory.sh
See Ecosystem below for the full list of scenarios the script covers and other community tools.
Option B: Manual Install
Via OpenClaw CLI (recommended):
openclaw plugins install memory-lancedb-pro@beta
Or via npm:
npm i memory-lancedb-pro@beta
If using npm, you will also need to add the plugin's install directory as an absolute path in plugins.load.paths in your openclaw.json. This is the most common setup issue.
Add to your openclaw.json:
{
"plugins": {
"slots": { "memory": "memory-lancedb-pro" },
"entries": {
"memory-lancedb-pro": {
"enabled": true,
"config": {
"embedding": {
"provider": "openai-compatible",
"apiKey": "${OPENAI_API_KEY}",
"model": "text-embedding-3-small"
},
"autoCapture": true,
"autoRecall": true,
"smartExtraction": true,
"canonicalCorpus": {
"enabled": true,
"syncOnSearch": true
},
"dreaming": {
"enabled": false
},
"extractMinMessages": 2,
"extractMaxChars": 8000,
"sessionMemory": { "enabled": false }
}
}
}
}
}
Why these defaults?
autoCapture + smartExtraction → your agent learns from every conversation automaticallyautoRecall → relevant memories are injected before each replyextractMinMessages: 2 → extraction triggers in normal two-turn chatssessionMemory.enabled: false → avoids polluting retrieval with session summaries on day one
⚠️ Memory Architecture (Important)
When memory-lancedb-pro owns the OpenClaw memory slot, it now exposes one memory capability with two coordinated stores:
| Memory Layer |
Storage |
What it's for |
Recallable? |
| Plugin Memory |
LanceDB (vector store) |
Semantic recall via memory_recall / auto-recall |
✅ Yes |
| Canonical Corpus |
MEMORY.md, memory/**/*.md, recent session transcripts, memory/dreaming/**/*.md |
Source-of-truth files and public artifacts |
✅ Via LanceDB semantic index when canonicalCorpus.enabled is true |
Key principle:
Canonical files remain the source of truth. LanceDB is the semantic index used to retrieve them with grounded paths, line spans, snippets, and citations.
What this means for you:
- Need semantic recall? → Use
memory_store or let auto-capture do it
memory/YYYY-MM-DD.md → treat as a daily journal / log that can also be indexed for semantic lookupMEMORY.md → curated human-readable reference that can be indexed as canonical contextmemory/dreaming/**/*.md → dream reports exposed as public artifacts and indexed as reflection context- Session JSONL transcripts → indexed as
source: "sessions" when canonicalCorpus.includeSessionTranscripts is enabled
- Plugin memory → primary write path for durable facts, preferences, decisions, and auto-captured memories
OpenClaw hosts receive:
api.registerMemoryCapability({ runtime, promptBuilder, flushPlanResolver, publicArtifacts })- runtime search results shaped as
path, startLine, endLine, snippet, source, and citation
- public artifacts for
MEMORY.md, memory/**/*.md, dream reports, and the dreaming event log at memory/.dreams/events.jsonl
Dreaming compatibility is configured under the same plugin entry. If dreaming.enabled is true while this plugin owns plugins.slots.memory, OpenClaw can use the memory-core dreaming sidecar against this plugin's memory capability and public artifacts.
Validate & restart:
openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | grep "memory-lancedb-pro"
You should see:
memory-lancedb-pro: smart extraction enabledmemory-lancedb-pro@...: plugin registered
Done! Your agent now has long-term memory.
More installation paths (existing users, upgrades)
Already using OpenClaw?
- Add the plugin with an absolute
plugins.load.paths entry
- Bind the memory slot:
plugins.slots.memory = "memory-lancedb-pro"
- Verify:
openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats
Upgrading from pre-v1.1.0?
# 1) Backup
openclaw memory-pro export --scope global --output memories-backup.json
# 2) Dry run
openclaw memory-pro upgrade --dry-run
# 3) Run upgrade
openclaw memory-pro upgrade
# 4) Verify
openclaw memory-pro stats
See CHANGELOG-v1.1.0.md for behavior changes and upgrade rationale.
Turning on Jina task hints on an existing database?
Task hints are two config keys under the plugin's embedding block:
"memory-lancedb-pro": {
"config": {
"embedding": {
"model": "jina-embeddings-v5-text-small",
"taskQuery": "retrieval.query",
"taskPassage": "retrieval.passage"
}
}
}
They only affect vectors written after you set them. Rows already in your store
were embedded without a task hint, so a query embedded with retrieval.query is
compared against passages that live in a different vector space — you get roughly
half the benefit, silently.
To fix existing rows, re-embed into a fresh database and cut over to it. Do
not re-embed in place: reembed writes each row with table.add() (append by
id, not replace), so an in-place run — which is exactly what --force unlocks —
leaves the old vector beside the new one and doubles every row; retries pile on
more. reembed refuses same-path runs unless you force it, for this reason.
# 0) Stop the gateway so nothing writes mid-migration.
# 1) Back up the whole store — a real filesystem copy of the LanceDB directory.
# (Do NOT rely on `memory-pro export`: it defaults to --limit 1000 and a single
# --scope, so it silently drops rows past 1000 and every non-global scope.)
cp -r <your dbPath> <your dbPath>.bak
# 2) In the plugin config, set the task hints AND point `dbPath` at a new, empty
# target (e.g. "<your dbPath>-v2"). A fresh target is also what lets you change
# `embedding.dimensions`: a new vector width can only go into a new table.
# 3) Dry run — reads the source, prints the row count, writes nothing.
openclaw memory-pro reembed --source-db <old dbPath> --dry-run
# 4) Re-embed old -> new with the now-current task hints. Source != target, so each
# id lands exactly once. Safe to re-run with --skip-existing if interrupted.
openclaw memory-pro reembed --source-db <old dbPath>
# 5) Verify before trusting the cutover: the "imported" count and
# `memory-pro stats` on the new dbPath must equal the dry-run row count.
openclaw memory-pro stats
# 6) Start the gateway; it now opens the new dbPath.
The same cutover applies whenever you change embedding.model or
embedding.dimensions — always re-embed into a fresh dbPath, never in place.
Telegram Bot Quick Import (click to expand)
If you are using OpenClaw's Telegram integration, the easiest way is to send an import command directly to the main Bot instead of manually editing config.
Send this message:
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 set embedding.taskQuery=retrieval.query and embedding.taskPassage=retrieval.passage
3. Use Jina for reranker
4. Use gpt-4o-mini for the smart-extraction LLM
5. Enable autoCapture, autoRecall, smartExtraction
6. extractMinMessages=2
7. sessionMemory.enabled=false
8. captureAssistant=false
9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3
10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62
11. Generate the final openclaw.json config directly, not just an explanation
Ecosystem
memory-lancedb-pro is the core plugin. The community has built tools around it to make setup and daily use even smoother:
Setup Script — One-Click Install, Upgrade & Repair
CortexReach/toolbox/memory-lancedb-pro-setup
Not just a simple installer — the script intelligently handles a wide range of real-world scenarios:
| Your situation |
What the script does |
| Never installed |
Fresh download → install deps → pick config → write to openclaw.json → restart |
Installed via git clone, stuck on old commit |
Auto git fetch + checkout to latest → reinstall deps → verify |
| Config has invalid fields |
Auto-detect via schema filter, remove unsupported fields |
Installed via npm |
Skips git update, reminds you to run npm update yourself |
openclaw CLI broken due to invalid config |
Fallback: read workspace path directly from openclaw.json file |
extensions/ instead of plugins/ |
Auto-detect plugin location from config or filesystem |
| Already up to date |
Run health checks only, no changes |
bash setup-memory.sh # Install or upgrade
bash setup-memory.sh --dry-run # Preview only
bash setup-memory.sh --beta # Include pre-release versions
bash setup-memory.sh --uninstall # Revert config and remove plugin
Built-in provider presets: Jina / DashScope / SiliconFlow / OpenAI / Ollama, or bring your own OpenAI-compatible API. For full usage (including --ref, --selfcheck-only, and more), see the setup script README.
Claude Code / OpenClaw Skill — AI-Guided Configuration
CortexReach/memory-lancedb-pro-skill
Install this skill and your AI agent (Claude Code or OpenClaw) gains deep knowledge of every feature in memory-lancedb-pro. Just say "help me enable the best config" and get:
- Guided 7-step configuration workflow with 4 deployment plans:
- Full Power (Jina + OpenAI) / Budget (free SiliconFlow reranker) / Simple (OpenAI only) / Fully Local (Ollama, zero API cost)
- All 9 MCP tools used correctly:
memory_recall, memory_store, memory_forget, memory_update, memory_stats, memory_list, self_improvement_log, self_improvement_extract_skill, self_improvement_review (full toolset requires enableManagementTools: true — the default Quick Start config exposes the 4 core tools)
- Common pitfall avoidance: workspace plugin enablement,
autoRecall default-false, jiti cache, env vars, scope isolation, and more
Install for Claude Code:
git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
Install for OpenClaw:
git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
Video Tutorial
Full walkthrough: installation, configuration, and hybrid retrieval internals.
https://youtu.be/MtukF1C8epQ
https://www.bilibili.com/video/BV1zUf2BGEgn/
Architecture
┌─────────────────────────────────────────────────────────┐
│ index.ts (Entry Point) │
│ Plugin Registration · Config Parsing · Lifecycle Hooks │
└────────┬──────────┬──────────┬──────────┬───────────────┘
│ │ │ │
┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
│ store │ │embedder│ │retriever│ │ scopes │
│ .ts │ │ .ts │ │ .ts │ │ .ts │
└────────┘ └────────┘ └────────┘ └─────────────┘
│ │
┌────▼───┐ ┌─────▼──────────┐
│migrate │ │noise-filter.ts │
│ .ts │ │adaptive- │
└────────┘ │retrieval.ts │
└────────────────┘
┌─────────────┐ ┌──────────┐
│ tools.ts │ │ cli.ts │
│ (Agent API) │ │ (CLI) │
└─────────────┘ └──────────┘
For a deep-dive into the full architecture, see docs/memory_architecture_analysis.md.
File Reference (click to expand)
| File |
Purpose |
index.ts |
Plugin entry point. Registers with OpenClaw Plugin API, parses config, mounts lifecycle hooks via api.on() and command hooks via api.registerHook() |
openclaw.plugin.json |
Plugin metadata + full JSON Schema config declaration |
cli.ts |
CLI commands: memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate |
src/store.ts |
LanceDB storage layer. Table creation / FTS indexing / Vector search / BM25 search / CRUD |
src/embedder.ts |
Embedding abstraction. Compatible with any OpenAI-compatible API provider |
src/retriever.ts |
Hybrid retrieval engine. Vector + BM25 → Hybrid Fusion → Rerank → Lifecycle Decay → Filter |
src/scopes.ts |
Multi-scope access control |
src/tools.ts |
Agent tool definitions: memory_recall, memory_store, memory_forget, memory_update + management tools |
src/noise-filter.ts |
Filters out agent refusals, meta-questions, greetings, and low-quality content |
src/adaptive-retrieval.ts |
Determines whether a query needs memory retrieval |
src/migrate.ts |
Migration from built-in memory-lancedb to Pro |
src/smart-extractor.ts |
LLM-powered 6-category extraction with L0/L1/L2 layered storage and two-stage dedup |
src/decay-engine.ts |
Weibull stretched-exponential decay model |
src/tier-manager.ts |
Three-tier promotion/demotion: Peripheral ↔ Working ↔ Core |
Core Features
Hybrid Retrieval
Query → embedQuery() ─┐
├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
Query → BM25 FTS ─────┘
- Vector Search — semantic similarity via LanceDB ANN (cosine distance)
- **BM25 Full-
Это плагин памяти для агентов OpenClaw на базе LanceDB: он хранит предпочтения, решения и контекст проекта, а затем автоматически вспоминает их в будущих сессиях, вместо того чтобы агент забывал всё между чатами.