SKILL.md
$27
Flags:
bash setup-memory.sh --dry-run # Preview changes only
bash setup-memory.sh --beta # Include pre-release versions
bash setup-memory.sh --uninstall # Revert config and remove plugin
bash setup-memory.sh --selfcheck-only # Health checks, no changesThe script handles fresh installs, upgrades from git-cloned versions, invalid config fields, broken CLI fallback, and provider presets (Jina, DashScope, SiliconFlow, OpenAI, Ollama).
Option B: OpenClaw CLI
openclaw plugins install memory-lancedb-pro@betaOption C: npm
npm i memory-lancedb-pro@betaCritical: When installing via npm, you must add the plugin's absolute install path to plugins.load.paths in openclaw.json. This is the most common setup issue.
Minimal Configuration ( openclaw.json )
{
"plugins": {
"load": {
"paths": ["/absolute/path/to/node_modules/memory-lancedb-pro"]
},
"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,
"extractMinMessages": 2,
"extractMaxChars": 8000,
"sessionMemory": { "enabled": false }
}
}
}
}
}Why these defaults:
autoCapture+smartExtraction→ agent learns from conversations automatically, no manual calls needed
autoRecall→ memories injected before each reply
extractMinMessages: 2→ triggers in normal two-turn chats
sessionMemory.enabled: false→ avoids polluting retrieval with session summaries early on
Full Production Configuration
{
"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",
"baseURL": "https://api.openai.com/v1"
},
"reranker": {
"provider": "jina",
"apiKey": "${JINA_API_KEY}",
"model": "jina-reranker-v2-base-multilingual"
},
"extraction": {
"provider": "openai-compatible",
"apiKey": "${OPENAI_API_KEY}",
"model": "gpt-4o-mini"
},
"autoCapture": true,
"captureAssistant": false,
"autoRecall": true,
"smartExtraction": true,
"extractMinMessages": 2,
"extractMaxChars": 8000,
"enableManagementTools": true,
"retrieval": {
"mode": "hybrid",
"vectorWeight": 0.7,
"bm25Weight": 0.3,
"topK": 10
},
"rerank": {
"enabled": true,
"type": "cross-encoder",
"candidatePoolSize": 12,
"minScore": 0.6,
"hardMinScore": 0.62
},
"decay": {
"enabled": true,
"model": "weibull",
"halfLifeDays": 30
},
"sessionMemory": { "enabled": false },
"scopes": {
"agent": true,
"user": true,
"project": true
}
}
}
}
}
}Provider Options for Embedding
Provider
provider value
Notes
OpenAI / compatible
"openai-compatible"
Requires apiKey, optional baseURL
Jina
"jina"
Requires apiKey
Gemini
"gemini"
Requires apiKey
Ollama
"ollama"
Local, zero API cost, set baseURL
DashScope
"dashscope"
Requires apiKey
SiliconFlow
"siliconflow"
Requires apiKey, free reranker tier
Deployment Plans
Full Power (Jina + OpenAI):
{
"embedding": { "provider": "jina", "apiKey": "${JINA_API_KEY}", "model": "jina-embeddings-v3" },
"reranker": { "provider": "jina", "apiKey": "${JINA_API_KEY}", "model": "jina-reranker-v2-base-multilingual" },
"extraction": { "provider": "openai-compatible", "apiKey": "${OPENAI_API_KEY}", "model": "gpt-4o-mini" }
}Budget (SiliconFlow free reranker):
{
"embedding": { "provider": "openai-compatible", "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" },
"reranker": { "provider": "siliconflow", "apiKey": "${SILICONFLOW_API_KEY}", "model": "BAAI/bge-reranker-v2-m3" },
"extraction": { "provider": "openai-compatible", "apiKey": "${OPENAI_API_KEY}", "model": "gpt-4o-mini" }
}Fully Local (Ollama, zero API cost):
{
"embedding": { "provider": "ollama", "baseURL": "http://localhost:11434", "model": "nomic-embed-text" },
"extraction": { "provider": "ollama", "baseURL": "http://localhost:11434", "model": "llama3" }
}CLI Reference
Validate config and restart after any changes:
openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | grep "memory-lancedb-pro"Expected startup log output:
memory-lancedb-pro: smart extraction enabled
memory-lancedb-pro@1.x.x: plugin registeredMemory Management CLI
# Stats overview
openclaw memory-pro stats
# List memories (with optional scope/filter)
openclaw memory-pro list
openclaw memory-pro list --scope user --limit 20
openclaw memory-pro list --filter "typescript"
# Search memories
openclaw memory-pro search "coding preferences"
openclaw memory-pro search "database decisions" --scope project
# Delete a memory by ID
openclaw memory-pro forget <memory-id>
# Export memories (for backup or migration)
openclaw memory-pro export --scope global --output memories-backup.json
openclaw memory-pro export --scope user --output user-memories.json
# Import memories
openclaw memory-pro import --input memories-backup.json
# Upgrade schema (when upgrading plugin versions)
openclaw memory-pro upgrade --dry-run # Preview first
openclaw memory-pro upgrade # Run upgrade
# Plugin info
openclaw plugins info memory-lancedb-proMCP Tool API
The plugin exposes MCP tools to the agent. Core tools are always available; management tools require enableManagementTools: true in config.
Core Tools (always available)
#### memory_recall
Retrieve relevant memories for a query.
// Agent usage pattern
const results = await memory_recall({
query: "user's preferred code style",
scope: "user", // "agent" | "user" | "project" | "global"
topK: 5
});#### memory_store
Manually store a memory.
await memory_store({
content: "User prefers tabs over spaces, always wants error handling",
category: "preference", // "profile" | "preference" | "entity" | "event" | "case" | "pattern"
scope: "user",
tags: ["coding-style", "typescript"]
});#### memory_forget
Delete a specific memory by ID.
await memory_forget({ id: "mem_abc123" });#### memory_update
Update an existing memory.
await memory_update({
id: "mem_abc123",
content: "User now prefers 2-space indentation (changed from tabs on 2026-03-01)",
category: "preference"
});Management Tools (requires enableManagementTools: true )
#### memory_stats
const stats = await memory_stats({ scope: "global" });
// Returns: total count, category breakdown, decay stats, db size#### memory_list
const list = await memory_list({ scope: "user", limit: 20, offset: 0 });#### self_improvement_log
Log an agent learning event for meta-improvement tracking.
await self_improvement_log({
event: "user corrected indentation preference",
context: "User asked me to switch from tabs to spaces",
improvement: "Updated coding-style preference memory"
});#### self_improvement_extract_skill
Extract a reusable pattern from a conversation.
await self_improvement_extract_skill({
conversation: "...",
domain: "code-review",
skillName: "typescript-strict-mode-setup"
});#### self_improvement_review
Review and consolidate recent self-improvement logs.
await self_improvement_review({ days: 7 });Smart Extraction: 6 Memory Categories
When smartExtraction: true, the LLM automatically classifies memories into:
Category
What gets stored
Example
profile
User identity, background
"User is a senior TypeScript developer"
preference
Style, tool, workflow choices
"Prefers functional programming patterns"
entity
Projects, people, systems
"Project 'Falcon' uses PostgreSQL + Redis"
event
Decisions made, things that happened
"Chose Vite over webpack on 2026-02-15"
case
Solutions to specific problems
"Fixed CORS by adding proxy in vite.config.ts"
pattern
Recurring behaviors, habits
"Always asks for tests before implementation"
Hybrid Retrieval Internals
With retrieval.mode: "hybrid", every recall runs:
- Vector search — semantic similarity via embeddings (weight:
vectorWeight, default 0.7)
- BM25 full-text search — keyword matching (weight:
bm25Weight, default 0.3)
- Score fusion — results merged with weighted RRF (Reciprocal Rank Fusion)
- Cross-encoder rerank — top
candidatePoolSizecandidates reranked by a cross-encoder model
- Score filtering — results below
hardMinScoreare dropped
"retrieval": {
"mode": "hybrid",
"vectorWeight": 0.7,
"bm25Weight": 0.3,
"topK": 10
},
"rerank": {
"enabled": true,
"type": "cross-encoder",
"candidatePoolSize": 12,
"minScore": 0.6,
"hardMinScore": 0.62
}Retrieval mode options:
"vector"— pure semantic search only
"bm25"— pure keyword search only
"hybrid"— both fused (recommended)
Multi-Scope Isolation
Scopes let you isolate memories by context. Enabling all three gives maximum flexibility:
"scopes": {
"agent": true, // Memories specific to this agent instance
"user": true, // Memories tied to a user identity
"project": true // Memories tied to a project/workspace
}When recalling, specify scope to narrow results:
// Get only project-level memories
await memory_recall({ query: "database choices", scope: "project" });
// Get user preferences across all agents
await memory_recall({ query: "coding style", scope: "user" });
// Global recall across all scopes
await memory_recall({ query: "error handling patterns", scope: "global" });Weibull Decay Model
Memories naturally fade over time. The decay model prevents stale memories from polluting retrieval.
"decay": {
"enabled": true,
"model": "weibull",
"halfLifeDays": 30
}- Memories accessed frequently get their decay clock reset
- Important, repeatedly-recalled memories effectively become permanent
- Noise and one-off mentions fade naturally after ~30 days
Upgrading
From pre-v1.1.0
# 1. Backup first — always
openclaw memory-pro export --scope global --output memories-backup-$(date +%Y%m%d).json
# 2. Preview schema changes
openclaw memory-pro upgrade --dry-run
# 3. Run the upgrade
openclaw memory-pro upgrade
# 4. Verify
openclaw memory-pro statsSee CHANGELOG-v1.1.0.md in the repo for behavior changes and upgrade rationale.
Troubleshooting
Plugin not loading
# Check plugin is recognized
openclaw plugins info memory-lancedb-pro
# Validate config (catches JSON errors, unknown fields)
openclaw config validate
# Check logs for registration
openclaw logs --follow --plain | grep "memory-lancedb-pro"Common causes:
- Missing or relative
plugins.load.paths(must be absolute when using npm install)
plugins.slots.memorynot set to"memory-lancedb-pro"
- Plugin not listed under
plugins.entries
autoRecall not injecting memories
By default autoRecall is false in some versions — explicitly set it to true:
"autoRecall": trueAlso confirm the plugin is bound to the memory slot, not just loaded.
Jiti cache issues after upgrade
# Clear jiti transpile cache
rm -rf ~/.openclaw/.cache/jiti
openclaw gateway restartMemories not being extracted from conversations
- Check
extractMinMessages— must be ≥ number of turns in the conversation (set to2for normal chats)
- Check
extractMaxChars— very long contexts may be truncated; increase to12000if needed
- Verify extraction LLM config has a valid
apiKeyand reachable endpoint
- Check logs:
openclaw logs --follow --plain | grep "extraction"
Retrieval returns nothing or poor results
- Confirm
retrieval.modeis"hybrid"not"bm25"alone (BM25 requires indexed content)
- Lower
rerank.hardMinScoretemporarily (try0.4) to see if results exist but are being filtered
- Check embedding model is consistent between store and recall operations — changing models requires re-embedding
Environment variable not resolving
Ensure env vars are exported in the shell that runs OpenClaw, or use a .env file loaded by your process manager. The ${VAR} syntax in openclaw.json is resolved at startup.
export OPENAI_API_KEY="sk-..."
export JINA_API_KEY="jina_..."
openclaw gateway restartTelegram Bot Quick Config Import
If using OpenClaw's Telegram integration, send this to the bot to auto-configure:
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
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 explanationResources
- Video walkthrough (YouTube): https://youtu.be/MtukF1C8epQ
- Video walkthrough (Bilibili): https://www.bilibili.com/video/BV1zUf2BGEgn/