Skip to content
Back to search

memory-lancedb-pro-skill

Claude Code skill for memory-lancedb-pro — production-grade long-term memory plugin for OpenClaw

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cortexreach--memory-lancedb-pro-skill/badge.svg)](/listings/cortexreach--memory-lancedb-pro-skill)

HTML

<a href="/listings/cortexreach--memory-lancedb-pro-skill"><img src="/api/listings/cortexreach--memory-lancedb-pro-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

**For Claude Code users:** - [Claude Code](https://claude.ai/code) CLI installed - [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) plugin configured as an MCP server

**For OpenClaw users:** - [OpenClaw](https://openclaw.ai) gateway running - `memory-lancedb-pro` plugin installed via `openclaw plugins install memory-lancedb-pro@beta`

Install the skill

> **Note:** This is a *skill* (knowledge file for AI agents), not a plugin. Skills are installed by placing them in your skills directory — there is no `openclaw skills install` command.

**Option A — clone this repo (recommended):**

For **Claude Code** users:

git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro

For **OpenClaw** users:

git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill

**Option B — download ZIP from GitHub:**

1. Click **Code → Download ZIP** on the [repository page](https://github.com/CortexReach/memory-lancedb-pro-skill) 2. Extract and place in your skills directory:

# Claude Code
unzip memory-lancedb-pro-skill-main.zip
mv memory-lancedb-pro-skill-main ~/.claude/skills/memory-lancedb-pro

# OpenClaw
unzip memory-lancedb-pro-skill-main.zip
mv memory-lancedb-pro-skill-main ~/.openclaw/workspace/skills/memory-lancedb-pro-skill

**Verify the skill is loaded:**

# Claude Code: the skill loads automatically based on trigger conditions
# To test: ask Claude Code "help me configure memory-lancedb-pro"

# OpenClaw: check skill discovery
openclaw skills list

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 1,402 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: memory-lancedb-pro
  3. description: This skill should be used when working with memory-lancedb-pro, a production-grade long-term memory MCP plugin for OpenClaw AI agents. Use when installing, configuring, or using any feature of memory-lancedb-pro including Smart Extraction, hybrid retrieval, memory lifecycle management, multi-scope isolation, self-improvement governance, or any MCP memory tools (memory_recall, memory_store, memory_forget, memory_update, memory_stats, memory_list, self_improvement_log, self_improvement_extract_skill, self_improvement_review).
  4. ---
  5. # memory-lancedb-pro
  6. 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.
  7. For full technical details (thresholds, formulas, database schema, source file map), see `references/full-reference.md`.
  8. ---
  9. ## Applying the Optimal Config (Step-by-Step Workflow)
  10. When the user says "help me enable the best config", "apply optimal configuration", or similar, follow this exact procedure:
  11. ### Step 1 — Present configuration plans and let user choose
  12. Present these three plans in a clear comparison, then ask the user to pick one:
  13. ---
  14. **Plan A — 🏆 Full Power (Best Quality)**
  15. - Embedding: Jina `jina-embeddings-v5-text-small` (task-aware, 1024-dim)
  16. - Reranker: Jina `jina-reranker-v3` (cross-encoder, same key)
  17. - LLM: OpenAI `gpt-4o-mini` (Smart Extraction)
  18. - Keys needed: `JINA_API_KEY` + `OPENAI_API_KEY`
  19. - Get keys: Jina → https://jina.ai/api-key · OpenAI → https://platform.openai.com/api-keys
  20. - Cost: Both paid (Jina has free tier with limited quota)
  21. - Best for: Production deployments, highest retrieval quality
  22. **Plan B — 💰 Budget (Free Reranker)**
  23. - Embedding: Jina `jina-embeddings-v5-text-small`
  24. - Reranker: SiliconFlow `BAAI/bge-reranker-v2-m3` (free tier available)
  25. - LLM: OpenAI `gpt-4o-mini`
  26. - Keys needed: `JINA_API_KEY` + `SILICONFLOW_API_KEY` + `OPENAI_API_KEY`
  27. - Get keys: Jina → https://jina.ai/api-key · SiliconFlow → https://cloud.siliconflow.cn/account/ak · OpenAI → https://platform.openai.com/api-keys
  28. - Cost: Jina embedding paid, SiliconFlow reranker free tier, OpenAI paid
  29. - Best for: Cost-sensitive deployments that still want reranking
  30. **Plan C — 🟢 Simple (OpenAI Only)**
  31. - Embedding: OpenAI `text-embedding-3-small`
  32. - Reranker: None (vector+BM25 fusion only, no cross-encoder)
  33. - LLM: OpenAI `gpt-4o-mini`
  34. - Keys needed: `OPENAI_API_KEY` only
  35. - Get key: https://platform.openai.com/api-keys
  36. - Cost: OpenAI paid only
  37. - Best for: Users who already have OpenAI and want minimal setup
  38. **Plan D — 🖥️ Fully Local (Ollama, No API Keys)**
  39. - Embedding: Ollama `mxbai-embed-large` (1024-dim, recommended) or `nomic-embed-text:v1.5` (768-dim, lighter)
  40. - Reranker: **None** — Ollama has no cross-encoder reranker; retrieval uses vector+BM25 fusion only
  41. - LLM: Ollama via OpenAI-compatible endpoint — recommended models with reliable JSON/structured output:
  42. - `qwen3:8b` (**recommended** — best JSON output, native structured output, ~5.2GB)
  43. - `qwen3:14b` (better quality, ~9GB, needs 16GB VRAM)
  44. - `llama4:scout` (multimodal MoE, 10M ctx, ~12GB)
  45. - `mistral-small3.2` (24B, 128K ctx, excellent instruction following, ~15GB)
  46. - `mistral-nemo` (12B, 128K ctx, efficient, ~7GB)
  47. - Keys needed: **None** — fully local, no external API calls
  48. - Prerequisites:
  49. - Ollama installed: https://ollama.com/download
  50. - Models pulled (see Step 5 below)
  51. - Ollama running: macOS = launch the app from Applications; Linux = `systemctl start ollama` or `ollama serve`
  52. - Cost: Free (hardware only)
  53. - RAM requirements: mxbai-embed-large ~670MB; qwen3:8b ~5.2GB; qwen3:14b ~9GB; llama4:scout ~12GB; mistral-small3.2 ~15GB
  54. - 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`
  55. - Best for: Privacy-sensitive deployments, air-gapped environments, zero API cost
  56. ---
  57. After user selects a plan, ask in one message:
  58. 1. Please provide the required API key(s) for your chosen plan (paste directly, or say "already set as env vars")
  59. 2. Are the env vars already set in your OpenClaw Gateway process? (If unsure, answer No)
  60. 3. Where is your `openclaw.json`? (Skip if you want me to find it automatically)
  61. If the user already stated their provider/keys in context, skip asking and proceed.
  62. **Do NOT proceed to Step 2 until API keys have been collected and verified (Step 2 below).**
  63. ### Step 2 — Verify API Keys (MANDATORY — do not skip)
  64. **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.
  65. **Plan A / Plan B — Jina embedding check:**
  66. ```bash
  67. curl -s -o /dev/null -w "%{http_code}" \
  68. https://api.jina.ai/v1/embeddings \
  69. -H "Authorization: Bearer <JINA_API_KEY>" \
  70. -H "Content-Type: application/json" \
  71. -d '{"model":"jina-embeddings-v5-text-small","input":["test"]}'
  72. ```
  73. **Plan A / B / C — OpenAI check:**
  74. ```bash
  75. curl -s -o /dev/null -w "%{http_code}" \
  76. https://api.openai.com/v1/models \
  77. -H "Authorization: Bearer <OPENAI_API_KEY>"
  78. ```
  79. **Plan B — SiliconFlow reranker check:**
  80. ```bash
  81. curl -s -o /dev/null -w "%{http_code}" \
  82. https://api.siliconflow.com/v1/rerank \
  83. -H "Authorization: Bearer <SILICONFLOW_API_KEY>" \
  84. -H "Content-Type: application/json" \
  85. -d '{"model":"BAAI/bge-reranker-v2-m3","query":"test","documents":["test doc"]}'
  86. ```
  87. **Plan D — Ollama check:**
  88. ```bash
  89. curl -s -o /dev/null -w "%{http_code}" http://localhost:11434/api/tags
  90. ```
  91. **Interpret results:**
  92. | HTTP code | Meaning | Action |
  93. |-----------|---------|--------|
  94. | `200` / `201` | Key valid, quota available | ✅ Continue |
  95. | `401` / `403` | Invalid or expired key | ❌ STOP — ask user to check key |
  96. | `402` | Payment required / no credits | ❌ STOP — ask user to top up account |
  97. | `429` | Rate limited or quota exceeded | ❌ STOP — ask user to check billing/quota |
  98. | `000` / connection refused | Service unreachable | ❌ STOP — ask user to check network / Ollama running |
  99. **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.**
  100. If the user says keys are set as env vars in the gateway process, run checks using `${VAR_NAME}` substituted inline or ask them to paste the key temporarily for verification.
  101. ### Step 3 — Find openclaw.json
  102. Check these locations in order:
  103. ```bash
  104. # Most common locations
  105. ls ~/.openclaw/openclaw.json
  106. ls ~/openclaw.json
  107. # Ask the gateway where it's reading config from
  108. openclaw config get --show-path 2>/dev/null || echo "not found"
  109. ```
  110. If not found, ask the user for the path.
  111. ### Step 4 — Read current config
  112. ```bash
  113. # Read and display current plugins config before changing anything
  114. openclaw config get plugins.entries.memory-lancedb-pro 2>/dev/null
  115. openclaw config get plugins.slots.memory 2>/dev/null
  116. ```
  117. **Check what already exists** — never blindly overwrite existing settings.
  118. ### Step 5 — Build the merged config based on chosen plan
  119. Use the config block for the chosen plan. Substitute actual API keys inline if the user provided them directly; keep `${ENV_VAR}` syntax if they confirmed env vars are set in the gateway process.
  120. **Plan A config (`plugins.entries.memory-lancedb-pro.config`):**
  121. ```json
  122. {
  123. "embedding": {
  124. "apiKey": "${JINA_API_KEY}",
  125. "model": "jina-embeddings-v5-text-small",
  126. "baseURL": "https://api.jina.ai/v1",
  127. "dimensions": 1024,
  128. "taskQuery": "retrieval.query",
  129. "taskPassage": "retrieval.passage",
  130. "normalized": true
  131. },
  132. "autoCapture": true,
  133. "autoRecall": true,
  134. "captureAssistant": false,
  135. "smartExtraction": true,
  136. "extractMinMessages": 2,
  137. "extractMaxChars": 8000,
  138. "llm": {
  139. "apiKey": "${OPENAI_API_KEY}",
  140. "model": "gpt-4o-mini",
  141. "baseURL": "https://api.openai.com/v1"
  142. },
  143. "retrieval": {
  144. "mode": "hybrid",
  145. "vectorWeight": 0.7,
  146. "bm25Weight": 0.3,
  147. "rerank": "cross-encoder",
  148. "rerankProvider": "jina",
  149. "rerankModel": "jina-reranker-v3",
  150. "rerankEndpoint": "https://api.jina.ai/v1/rerank",
  151. "rerankApiKey": "${JINA_API_KEY}",
  152. "candidatePoolSize": 12,
  153. "minScore": 0.6,
  154. "hardMinScore": 0.62,
  155. "filterNoise": true
  156. },
  157. "sessionMemory": { "enabled": false }
  158. }
  159. ```
  160. **Plan B config:**
  161. ```json
  162. {
  163. "embedding": {
  164. "apiKey": "${JINA_API_KEY}",
  165. "model": "jina-embeddings-v5-text-small",
  166. "baseURL": "https://api.jina.ai/v1",
  167. "dimensions": 1024,
  168. "taskQuery": "retrieval.query",
  169. "taskPassage": "retrieval.passage",
  170. "normalized": true
  171. },
  172. "autoCapture": true,
  173. "autoRecall": true,
  174. "captureAssistant": false,
  175. "smartExtraction": true,
  176. "extractMinMessages": 2,
  177. "extractMaxChars": 8000,
  178. "llm": {
  179. "apiKey": "${OPENAI_API_KEY}",
  180. "model": "gpt-4o-mini",
  181. "baseURL": "https://api.openai.com/v1"
  182. },
  183. "retrieval": {
  184. "mode": "hybrid",
  185. "vectorWeight": 0.7,
  186. "bm25Weight": 0.3,
  187. "rerank": "cross-encoder",
  188. "rerankProvider": "siliconflow",
  189. "rerankModel": "BAAI/bge-reranker-v2-m3",
  190. "rerankEndpoint": "https://api.siliconflow.com/v1/rerank",
  191. "rerankApiKey": "${SILICONFLOW_API_KEY}",
  192. "candidatePoolSize": 12,
  193. "minScore": 0.5,
  194. "hardMinScore": 0.55,
  195. "filterNoise": true
  196. },
  197. "sessionMemory": { "enabled": false }
  198. }
  199. ```
  200. **Plan C config:**
  201. ```json
  202. {
  203. "embedding": {
  204. "apiKey": "${OPENAI_API_KEY}",
  205. "model": "text-embedding-3-small",
  206. "baseURL": "https://api.openai.com/v1"
  207. },
  208. "autoCapture": true,
  209. "autoRecall": true,
  210. "captureAssistant": false,
  211. "smartExtraction": true,
  212. "extractMinMessages": 2,
  213. "extractMaxChars": 8000,
  214. "llm": {
  215. "apiKey": "${OPENAI_API_KEY}",
  216. "model": "gpt-4o-mini",
  217. "baseURL": "https://api.openai.com/v1"
  218. },
  219. "retrieval": {
  220. "mode": "hybrid",
  221. "vectorWeight": 0.7,
  222. "bm25Weight": 0.3,
  223. "filterNoise": true,
  224. "minScore": 0.3,
  225. "hardMinScore": 0.35
  226. },
  227. "sessionMemory": { "enabled": false }
  228. }
  229. ```
  230. **Plan D config (replace models as needed — `qwen3:8b` recommended for LLM, `mxbai-embed-large` for embedding):**
  231. ```json
  232. {
  233. "embedding": {
  234. "apiKey": "ollama",
  235. "model": "mxbai-embed-large",
  236. "baseURL": "http://localhost:11434/v1",
  237. "dimensions": 1024
  238. },
  239. "autoCapture": true,
  240. "autoRecall": true,
  241. "captureAssistant": false,
  242. "smartExtraction": true,
  243. "extractMinMessages": 2,
  244. "extractMaxChars": 4000,
  245. "llm": {
  246. "apiKey": "ollama",
  247. "model": "qwen3:8b",
  248. "baseURL": "http://localhost:11434/v1"
  249. },
  250. "retrieval": {
  251. "mode": "hybrid",
  252. "vectorWeight": 0.7,
  253. "bm25Weight": 0.3,
  254. "filterNoise": true,
  255. "minScore": 0.25,
  256. "hardMinScore": 0.28
  257. },
  258. "sessionStrategy": "none"
  259. }
  260. ```
  261. **Plan D prerequisites — run BEFORE applying config:**
  262. ```bash
  263. # 1. Verify Ollama is running (should return JSON with model list)
  264. curl http://localhost:11434/api/tags
  265. # 2. Pull embedding model (choose one):
  266. ollama pull mxbai-embed-large # recommended: 1024-dim, beats text-embedding-3-large, ~670MB
  267. ollama pull snowflake-arctic-embed2 # best multilingual local option, ~670MB
  268. ollama pull nomic-embed-text:v1.5 # classic stable, 768-dim, ~270MB
  269. # 3. Pull LLM for Smart Extraction (choose one based on RAM):
  270. ollama pull qwen3:8b # recommended: best JSON/structured output, ~5.2GB
  271. ollama pull qwen3:14b # better quality, ~9GB, needs 16GB VRAM
  272. ollama pull llama4:scout # multimodal MoE, 10M ctx, ~12GB
  273. ollama pull mistral-small3.2 # 24B, 128K ctx, excellent, ~15GB
  274. ollama pull mistral-nemo # 12B, 128K ctx, efficient, ~7GB
  275. # 4. Verify models are installed
  276. ollama list
  277. # 5. Quick sanity check — embedding endpoint works:
  278. curl http://localhost:11434/v1/embeddings \
  279. -H "Content-Type: application/json" \
  280. -d '{"model":"mxbai-embed-large","input":"test"}'
  281. # Should return a JSON with a 1024-element vector
  282. ```
  283. **If Smart Extraction produces garbled/invalid output:** The local LLM may not support structured JSON reliably. Try `qwen3:8b` first — it has native structured output support. If still failing, disable:
  284. ```json
  285. { "smartExtraction": false }
  286. ```
  287. **If Ollama is on a different host or Docker:** Replace `http://localhost:11434/v1` with the actual host, e.g. `http://192.168.1.100:11434/v1`. Also set `OLLAMA_HOST=0.0.0.0` in the Ollama process to allow remote connections.
  288. For the **`plugins.entries.memory-lancedb-pro.config`** block, merge into the existing `openclaw.json` rather than replacing the whole file. Use a targeted edit of only the memory plugin config section.
  289. ### Step 6 — Apply the config
  290. Read the current `openclaw.json` first, then apply a surgical edit to the `plugins.entries.memory-lancedb-pro` section. Use the template that matches your installation method:
  291. **Method 1 — `openclaw plugins install` (plugin was installed via the plugin manager):**
  292. No `load.paths` or `allow` needed — the plugin manager already registered the plugin.
  293. ```json
  294. {
  295. "plugins": {
  296. "slots": { "memory": "memory-lancedb-pro" },
  297. "entries": {
  298. "memory-lancedb-pro": {
  299. "enabled": true,
  300. "config": {
  301. "<<OPTIMAL CONFIG HERE>>"
  302. }
  303. }
  304. }
  305. }
  306. }
  307. ```
  308. **Method 2 — git clone with manual path (workspace plugin):**
  309. Both `load.paths` AND `allow` are required — workspace plugins are disabled by default.
  310. ```json
  311. {
  312. "plugins": {
  313. "load": { "paths": ["plugins/memory-lancedb-pro"] },
  314. "allow": ["memory-lancedb-pro"],
  315. "slots": { "memory": "memory-lancedb-pro" },
  316. "entries": {
  317. "memory-lancedb-pro": {
  318. "enabled": true,
  319. "config": {
  320. "<<OPTIMAL CONFIG HERE>>"
  321. }
  322. }
  323. }
  324. }
  325. }
  326. ```
  327. ### Step 7 — Validate and restart
  328. ```bash
  329. openclaw config validate
  330. openclaw gateway restart
  331. openclaw logs --follow --plain | rg "memory-lancedb-pro"
  332. ```
  333. Expected output confirms:
  334. - `memory-lancedb-pro: smart extraction enabled`
  335. - `memory-lancedb-pro@...: plugin registered`
  336. ### Step 8 — Verify
  337. ```bash
  338. openclaw plugins info memory-lancedb-pro
  339. openclaw hooks list --json | grep -E "before_agent_start|agent_end|command:new"
  340. openclaw memory-pro stats
  341. ```
  342. Then do a quick smoke test:
  343. 1. Store: call `memory_store` with `text: "test memory for verification"`
  344. 2. Recall: call `memory_recall` with `query: "test memory"`
  345. 3. Confirm the memory is returned
  346. ---
  347. ## Installation
  348. ### Quick Install (Beginner-Friendly)
  349. For new users, the community one-click installer handles everything automatically — path detection, schema validation, auto-update, provider selection, and rollback:
  350. ```bash
  351. curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
  352. bash setup-memory.sh
  353. ```
  354. Options: `--dry-run` (preview only), `--beta` (include pre-release), `--ref v1.2.0` (pin version), `--selfcheck-only`, `--uninstall`.
  355. Source: https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup
  356. ---
  357. ### Requirements
  358. - Node.js 24 recommended (Node 22 LTS minimum, `22.16+`)
  359. - LanceDB ≥ 0.26.2
  360. - OpenAI SDK ≥ 6.21.0
  361. - TypeBox 0.34.48
  362. ### Install Method 1 — via OpenClaw plugin manager (recommended)
  363. ```bash
  364. # Install from npm registry (@beta tag = latest pre-release, e.g. 1.1.0-beta.8)
  365. openclaw plugins install memory-lancedb-pro@beta
  366. # Install stable release from npm (@latest tag, e.g. 1.0.32)
  367. openclaw plugins install memory-lancedb-pro
  368. # Or install from a local git clone — use master branch (matches npm @beta)
  369. git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git /tmp/memory-lancedb-pro
  370. openclaw plugins install /tmp/memory-lancedb-pro
  371. ```
  372. > **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.
  373. Then bind the memory slot and add your config (see Configuration section below):
  374. ```json
  375. {
  376. "plugins": {
  377. "slots": { "memory": "memory-lancedb-pro" },
  378. "entries": {
  379. "memory-lancedb-pro": {
  380. "enabled": true,
  381. "config": { "<<your config here>>" }
  382. }
  383. }
  384. }
  385. }
  386. ```
  387. Restart and verify:
  388. ```bash
  389. openclaw gateway restart
  390. openclaw plugins info memory-lancedb-pro
  391. ```
  392. ### Install Method 2 — git clone with manual path (Path A for development)
  393. > ⚠️ **Critical**: Workspace plugins (git-cloned paths) are **disabled by default** in OpenClaw. You MUST explicitly enable them.
  394. ```bash
  395. # 1. Clone into workspace
  396. cd /path/to/your/openclaw/workspace
  397. git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git plugins/memory-lancedb-pro
  398. cd plugins/memory-lancedb-pro && npm install
  399. ```
  400. Add to `openclaw.json` — the `enabled: true` and the `allow` entry are both required:
  401. ```json
  402. {
  403. "plugins": {
  404. "load": { "paths": ["plugins/memory-lancedb-pro"] },
  405. "allow": ["memory-lancedb-pro"],
  406. "slots": { "memory": "memory-lancedb-pro" },
  407. "entries": {
  408. "memory-lancedb-pro": {
  409. "enabled": true,
  410. "config": {
  411. "embedding": {
  412. "apiKey": "${JINA_API_KEY}",
  413. "model": "jina-embeddings-v5-text-small",
  414. "baseURL": "https://api.jina.ai/v1",
  415. "dimensions": 1024,
  416. "taskQuery": "retrieval.query",
  417. "taskPassage": "retrieval.passage",
  418. "normalized": true
  419. }
  420. }
  421. }
  422. }
  423. }
  424. }
  425. ```
  426. Validate and restart:
  427. ```bash
  428. openclaw config validate
  429. openclaw gateway restart
  430. openclaw logs --follow --plain | rg "memory-lancedb-pro"
  431. ```
  432. Expected log output:
  433. - `memory-lancedb-pro: smart extraction enabled`
  434. - `memory-lancedb-pro@...: plugin registered`
  435. ### Install Method 3 — Existing deployments (Path B)
  436. Use **absolute paths** in `plugins.load.paths`. Add to `plugins.allow`. Bind memory slot: `plugins.slots.memory = "memory-lancedb-pro"`. Set `plugins.entries.memory-lancedb-pro.enabled: true`.
  437. Then restart and verify:
  438. ```bash
  439. openclaw config validate
  440. openclaw gateway restart
  441. openclaw logs --follow --plain | rg "memory-lancedb-pro"
  442. ```
  443. ### New User First-Install Checklist
  444. After the plugin starts successfully, determine which scenario applies and run the corresponding steps:
  445. ---
  446. **Scenario A — Coming from built-in `memory-lancedb` plugin (most common upgrade path)**
  447. The old plugin stores data in LanceDB at `~/.openclaw/memory/lancedb`. Use the migrate command:
  448. ```bash
  449. # 1. Check if old data exists and is readable
  450. openclaw memory-pro migrate check
  451. # 2. Preview what would be migrated (dry run)
  452. openclaw memory-pro migrate run --dry-run
  453. # 3. Run the actual migration
  454. openclaw memory-pro migrate run
  455. # 4. Verify migrated data
  456. openclaw memory-pro migrate verify
  457. openclaw memory-pro stats
  458. ```
  459. If the old database is at a non-default path:
  460. ```bash
  461. openclaw memory-pro migrate check --source /path/to/old/lancedb
  462. openclaw memory-pro migrate run --source /path/to/old/lancedb
  463. ```
  464. ---
  465. **Scenario B — Existing memories exported as JSON**
  466. If you have memories in the standard JSON export format:
  467. ```bash
  468. # Preview import (dry run)
  469. openclaw memory-pro import memories.json --scope global --dry-run
  470. # Import
  471. openclaw memory-pro import memories.json --scope global
  472. ```
  473. Expected JSON schema:
  474. ```json
  475. {
  476. "version": "1.0",
  477. "memories": [
  478. {
  479. "text": "Memory content (required)",
  480. "category": "preference|fact|decision|entity|other",
  481. "importance": 0.7,
  482. "timestamp": 1234567890000
  483. }
  484. ]
  485. }
  486. ```
  487. ---
  488. **Scenario C — Memories stored in Markdown files (AGENTS.md, MEMORY.md, etc.)**
  489. There is **no direct markdown import** — the import command only accepts JSON. You need to convert first.
  490. Manual conversion approach:
  491. 1. Open the markdown file(s) containing memories
  492. 2. For each memory entry, create a JSON object with `text`, `category`, `importance`
  493. 3. Save as a JSON file following the schema above
  494. 4. Run `openclaw memory-pro import`
  495. Or use `memory_store` tool directly in the agent to store individual entries one at a time:
  496. ```
  497. memory_store(text="<extracted memory>", category="fact", importance=0.8)
  498. ```
  499. > **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`.
  500. ---
  501. **Scenario D — Fresh install, no prior memories**
  502. No migration needed. Verify the plugin is working with a quick smoke test:
  503. ```bash
  504. openclaw memory-pro stats # should show 0 memories
  505. ```
  506. Then trigger a conversation — `autoCapture` will start storing memories automatically.
  507. ---
  508. ### LanceDB Version Compatibility
  509. > **No manual action required for LanceDB version changes.**
  510. The plugin requires `@lancedb/lancedb ^0.26.2` as an npm dependency — this is installed automatically when you install or update the plugin. You do not need to manually install or upgrade LanceDB.
  511. LanceDB 0.26+ changed how numeric columns are returned (Arrow `BigInt` type for `timestamp`, `importance`, `_distance`, `_score`). The plugin handles this transparently at runtime via internal `Number(...)` coercion — no migration commands are needed when moving between LanceDB versions.
  512. **TL;DR:** LanceDB version compatibility is fully automatic. See the table below for when each maintenance command actually applies.
  513. ### Upgrading plugin code vs. data
  514. **Command distinction (important):**
  515. | Command | When to use |
  516. |---------|-------------|
  517. | `openclaw plugins update memory-lancedb-pro` | Update **plugin code** after a new release (npm-installed only) |
  518. | `openclaw plugins update --all` | Update all npm-installed plugins at once |
  519. | `openclaw memory-pro upgrade` | Enrich **old memory-lancedb-pro entries** that predate the smart-memory schema (missing L0/L1/L2 metadata + 6-category system) — NOT related to LanceDB version |
  520. | `openclaw memory-pro migrate` | One-time migration from the separate `memory-lancedb` built-in plugin → Pro |
  521. | `openclaw memory-pro reembed` | Rebuild all embeddings after switching embedding model or provider |
  522. **When do you need `memory-pro upgrade`?**
  523. Run it if you installed memory-lancedb-pro before the smart-memory format was introduced (i.e., entries are missing `memory_category` in their metadata). Signs you need it:
  524. - `memory_recall` returns results but without meaningful categories
  525. - `memory-pro list --json` shows entries with no `l0_abstract` / `l1_overview` fields
  526. Safe upgrade sequence:
  527. ```bash
  528. # 1. Backup first
  529. openclaw memory-pro export --scope global --output memories-backup.json
  530. # 2. Preview what would change
  531. openclaw memory-pro upgrade --dry-run
  532. # 3. Run upgrade (uses LLM by default for L0/L1/L2 generation)
  533. openclaw memory-pro upgrade
  534. # 4. Verify results
  535. openclaw memory-pro stats
  536. openclaw memory-pro search "your known keyword" --scope global --limit 5
  537. ```
  538. Upgrade options:
  539. ```bash
  540. openclaw memory-pro upgrade --no-llm # skip LLM, use simple text truncation
  541. openclaw memory-pro upgrade --batch-size 5 # slower but safer for large collections
  542. openclaw memory-pro upgrade --limit 50 # process only first N entries
  543. openclaw memory-pro upgrade --scope global # limit to one scope
  544. ```
  545. ### Plugin management commands
  546. ```bash
  547. openclaw plugins list # show all discovered plugins
  548. openclaw plugins info memory-lancedb-pro # show plugin status and config
  549. openclaw plugins enable memory-lancedb-pro # enable a disabled plugin
  550. openclaw plugins disable memory-lancedb-pro # disable without removing
  551. openclaw plugins update memory-lancedb-pro # update npm-installed plugin
  552. openclaw plugins update --all # update all npm plugins
  553. openclaw plugins doctor # health check for all plugins
  554. openclaw plugins install ./path/to/plugin # install local plugin (copies + enables)
  555. openclaw plugins install @scope/plugin@beta # install from npm registry
  556. openclaw plugins install -l ./path/to/plugin # symlink for dev (no copy)
  557. ```
  558. > **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.
  559. >
  560. > ```bash
  561. > openclaw gateway restart
  562. > ```
  563. ### Easy-to-Miss Setup Steps
  564. 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.
  565. 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.
  566. 3. **Env vars in gateway process**: `${OPENAI_API_KEY}` requires env vars set in the *OpenClaw Gateway service* process—not just your shell.
  567. 4. **Absolute vs. relative paths**: For existing deployments, always use absolute paths in `plugins.load.paths`.
  568. 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.
  569. 6. **jiti cache invalidation**: After modifying `.ts` files under plugins, run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`.
  570. 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.
  571. 8. **Separate LLM config**: If embedding and LLM use different providers, configure the `llm` section separately — it falls back to embedding key/URL otherwise.
  572. 9. **Scope isolation**: Multi-scope requires explicit `scopes.agentAccess` mapping — without it, agents only see `global` scope.
  573. 10. **Session memory hook**: Fires on `/new` command — test with an actual `/new` invocation.
  574. 11. **Reranker credentials**: When switching providers, update both `rerankApiKey` AND `rerankEndpoint`.
  575. 12. **Config check before assuming defaults**: Run `openclaw config get plugins.entries.memory-lancedb-pro` to verify what's actually loaded.
  576. 13. **Custom config/state paths via env vars**: OpenClaw respects the following environment variables for custom paths:
  577. - `OPENCLAW_HOME` — sets the root config/data directory (default: `~/.openclaw/`)
  578. - `OPENCLAW_CONFIG_PATH` — absolute path to `openclaw.json` override
  579. - `OPENCLAW_STATE_DIR` — override for runtime state/data directory
  580. Set these in the OpenClaw Gateway process's environment if the default `~/.openclaw/` path is not appropriate.
  581. ### Post-Installation Verification
  582. ```bash
  583. openclaw doctor # full health check (recommended)
  584. openclaw config validate # config schema check only
  585. openclaw plugins info memory-lancedb-pro # plugin status
  586. openclaw plugins doctor # plugin-specific health
  587. openclaw hooks list --json | grep memory # confirm hooks registered
  588. openclaw memory-pro stats
  589. openclaw memory-pro list --scope global --limit 5
  590. ```
  591. Full smoke test checklist:
  592. - ✅ Plugin info shows `enabled: true` and config loaded
  593. - ✅ Hooks include `before_agent_start`, `agent_end`, `command:new`
  594. - ✅ One `memory_store` → `memory_recall` round trip via tools
  595. - ✅ One exact-ID search hit
  596. - ✅ One natural-language search hit
  597. - ✅ If session memory enabled: one real `/new` test
  598. ---
  599. ## Troubleshooting — Error Message Quick Reference
  600. **Config validation tool** (from [CortexReach/toolbox](https://github.com/CortexReach/toolbox)):
  601. ```bash
  602. # Download once
  603. curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/scripts/config-validate.mjs -o config-validate.mjs
  604. # Run against your openclaw.json
  605. node config-validate.mjs
  606. # Or validate a specific config snippet
  607. node config-validate.mjs --json '{"embedding":{"baseURL":"http://localhost:11434/v1","model":"bge-m3","apiKey":"ollama"}}'
  608. ```
  609. Exit code 0 = pass/warn, 1 = errors found.
  610. | Error message | Root cause | Fix |
  611. |---------------|-----------|-----|
  612. | `must NOT have additional properties` + `config.embedding` | Field name typo in embedding config (e.g. `baseUrl` instead of `baseURL`) | Check all field names against the schema table below — field names are case-sensitive |
  613. | `must NOT have additional properties` (top-level config) | Unknown top-level field in plugin config | Remove or correct the field |
  614. | `memory-lancedb-pro: plugin not found` / plugin silently not loading | `plugins.allow` missing (git-clone install) or `enabled: false` | Add `plugins.allow: ["memory-lancedb-pro"]` and set `enabled: true`, then restart |
  615. | `Unknown plugin id` validation error | Plugin referenced in `entries`/`slots` before it's discoverable | Install/register the plugin first, then add config references |
  616. | `${OPENAI_API_KEY}` not expanding / auth errors despite env var set | Env var not set in the **gateway process** environment | Set the env var in the service that runs OpenClaw gateway, not just your shell |
  617. | Hooks (`before_agent_start`, `agent_end`) not firing | Gateway not restarted after install/config change | Run `openclaw gateway restart` |
  618. | Embedding errors with Ollama | Wrong `baseURL` format | Must be `http://localhost:11434/v1` (with `/v1`), field must be `baseURL` not `baseUrl` |
  619. | `memory-pro stats` shows 0 entries after conversation | `autoCapture` false or `extractMinMessages` not reached | Set `autoCapture: true`; need at least `extractMinMessages` (default 2) turns |
  620. | Memories not injected before agent replies | `autoRecall` is false (schema default) | Explicitly set `"autoRecall": true` |
  621. | `jiti` cache error after editing plugin `.ts` files | Stale compiled cache | Run `rm -rf /tmp/jiti/` then `openclaw gateway restart` |
  622. ---
  623. ## Configuration
  624. ### Minimal Quick-Start
  625. ```json
  626. {
  627. "embedding": {
  628. "provider": "openai-compatible",
  629. "apiKey": "${OPENAI_API_KEY}",
  630. "model": "text-embedding-3-small"
  631. },
  632. "autoCapture": true,
  633. "autoRecall": true,
  634. "smartExtraction": true,
  635. "extractMinMessages": 2,
  636. "extractMaxChars": 8000,
  637. "sessionMemory": { "enabled": false }
  638. }
  639. ```
  640. **Note:** `autoRecall` is **disabled by default** in the plugin schema — explicitly set it to `true` for new deployments.
  641. ### Optimal Production Config (recommended)
  642. Uses Jina for both embedding and reranking — best retrieval quality:
  643. ```json
  644. {
  645. "embedding": {
  646. "apiKey": "${JINA_API_KEY}",
  647. "model": "jina-embeddings-v5-text-small",
  648. "baseURL": "https://api.jina.ai/v1",
  649. "dimensions": 1024,
  650. "taskQuery": "retrieval.query",
  651. "taskPassage": "retrieval.passage",
  652. "normalized": true
  653. },
  654. "dbPath": "~/.openclaw/memory/lancedb-pro",
  655. "autoCapture": true,
  656. "autoRecall": true,
  657. "captureAssistant": false,
  658. "smartExtraction": true,
  659. "extractMinMessages": 2,
  660. "extractMaxChars": 8000,
  661. "enableManagementTools": false,
  662. "llm": {
  663. "apiKey": "${OPENAI_API_KEY}",
  664. "model": "gpt-4o-mini",
  665. "baseURL": "https://api.openai.com/v1"
  666. },
  667. "retrieval": {
  668. "mode": "hybrid",
  669. "vectorWeight": 0.7,
  670. "bm25Weight": 0.3,
  671. "rerank": "cross-encoder",
  672. "rerankProvider": "jina",
  673. "rerankModel": "jina-reranker-v3",
  674. "rerankEndpoint": "https://api.jina.ai/v1/rerank",
  675. "rerankApiKey": "${JINA_API_KEY}",
  676. "candidatePoolSize": 12,
  677. "minScore": 0.6,
  678. "hardMinScore": 0.62,
  679. "filterNoise": true,
  680. "lengthNormAnchor": 500,
  681. "timeDecayHalfLifeDays": 60,
  682. "reinforcementFactor": 0.5,
  683. "maxHalfLifeMultiplier": 3
  684. },
  685. "sessionMemory": { "enabled": false, "messageCount": 15 }
  686. }
  687. ```
  688. **Why these settings excel:**
  689. - **Jina embeddings**: Task-aware vectors (`taskQuery`/`taskPassage`) optimized for retrieval
  690. - **Hybrid mode 0.7/0.3**: Balances semantic understanding with exact keyword matching
  691. - **Jina reranker v3**: Cross-encoder reranking significantly improves relevance
  692. - **`candidatePoolSize: 12` + `minScore: 0.6`**: Aggressive filtering reduces noise
  693. - **`captureAssistant: false`**: Prevents storing agent-generated boilerplate
  694. - **`sessionMemory: false`**: Avoids polluting retrieval with session summaries
  695. ### Full Config (all options)
  696. ```json
  697. {
  698. "embedding": {
  699. "apiKey": "${JINA_API_KEY}",
  700. "model": "jina-embeddings-v5-text-small",
  701. "baseURL": "https://api.jina.ai/v1",
  702. "dimensions": 1024,
  703. "taskQuery": "retrieval.query",
  704. "taskPassage": "retrieval.passage",
  705. "normalized": true
  706. },
  707. "dbPath": "~/.openclaw/memory/lancedb-pro",
  708. "autoCapture": true,
  709. "autoRecall": true,
  710. "captureAssistant": false,
  711. "smartExtraction": true,
  712. "llm": {
  713. "apiKey": "${OPENAI_API_KEY}",
  714. "model": "gpt-4o-mini",
  715. "baseURL": "https://api.openai.com/v1"
  716. },
  717. "extractMinMessages": 2,
  718. "extractMaxChars": 8000,
  719. "enableManagementTools": false,
  720. "retrieval": {
  721. "mode": "hybrid",
  722. "vectorWeight": 0.7,
  723. "bm25Weight": 0.3,
  724. "minScore": 0.3,
  725. "hardMinScore": 0.35,
  726. "rerank": "cross-encoder",
  727. "rerankProvider": "jina",
  728. "rerankModel": "jina-reranker-v3",
  729. "rerankEndpoint": "https://api.jina.ai/v1/rerank",
  730. "rerankApiKey": "${JINA_API_KEY}",
  731. "candidatePoolSize": 20,
  732. "recencyHalfLifeDays": 14,
  733. "recencyWeight": 0.1,
  734. "filterNoise": true,
  735. "lengthNormAnchor": 500,
  736. "timeDecayHalfLifeDays": 60,
  737. "reinforcementFactor": 0.5,
  738. "maxHalfLifeMultiplier": 3
  739. },
  740. "scopes": {
  741. "default": "global",
  742. "definitions": {
  743. "global": { "description": "Shared knowledge" },
  744. "agent:discord-bot": { "description": "Discord bot private" }
  745. },
  746. "agentAccess": {
  747. "discord-bot": ["global", "agent:discord-bot"]
  748. }
  749. },
  750. "sessionStrategy": "none",
  751. "memoryReflection": {
  752. "storeToLanceDB": true,
  753. "injectMode": "inheritance+derived",
  754. "agentId": "memory-distiller",
  755. "messageCount": 120,
  756. "maxInputChars": 24000,
  757. "thinkLevel": "medium"
  758. },
  759. "selfImprovement": {
  760. "enabled": true,
  761. "beforeResetNote": true,
  762. "ensureLearningFiles": true
  763. },
  764. "mdMirror": { "enabled": false },
  765. "decay": {
  766. "recencyHalfLifeDays": 30,
  767. "recencyWeight": 0.4,
  768. "frequencyWeight": 0.3,
  769. "intrinsicWeight": 0.3,
  770. "betaCore": 0.8,
  771. "betaWorking": 1.0,
  772. "betaPeripheral": 1.3
  773. },
  774. "tier": {
  775. "coreAccessThreshold": 10,
  776. "coreCompositeThreshold": 0.7,
  777. "coreImportanceThreshold": 0.8,
  778. "workingAccessThreshold": 3,
  779. "workingCompositeThreshold": 0.4,
  780. "peripheralCompositeThreshold": 0.15,
  781. "peripheralAgeDays": 60
  782. }
  783. }
  784. ```
  785. ---
  786. ## Configuration Field Reference
  787. ### Embedding
  788. | Field | Type | Default | Description |
  789. |-------|------|---------|-------------|
  790. | `apiKey` | string | — | API key (supports `${ENV_VAR}`); array for multi-key failover |
  791. | `model` | string | — | Model identifier |
  792. | `baseURL` | string | provider default | API endpoint |
  793. | `dimensions` | number | provider default | Vector dimensionality |
  794. | `taskQuery` | string | — | Task hint for query embeddings (`retrieval.query`) |
  795. | `taskPassage` | string | — | Task hint for passage embeddings (`retrieval.passage`) |
  796. | `normalized` | boolean | false | Request L2-normalized embeddings |
  797. | `provider` | string | `openai-compatible` | Provider type selector |
  798. | `chunking` | boolean | true | Auto-chunk documents exceeding embedding context limits |
  799. ### Top-Level
  800. | Field | Type | Default | Description |
  801. |-------|------|---------|-------------|
  802. | `dbPath` | string | `~/.openclaw/memory/lancedb-pro` | LanceDB data directory |
  803. | `autoCapture` | boolean | true | Auto-extract memories after agent replies (via `agent_end` hook) |
  804. | `autoRecall` | boolean | **false** (schema default) | Inject memories before agent processing — **set to true explicitly** |
  805. | `captureAssistant` | boolean | false | Include assistant messages in extraction |
  806. | `smartExtraction` | boolean | true | LLM-powered 6-category extraction |
  807. | `extractMinMessages` | number | 2 | Min conversation turns before extraction triggers |
  808. | `extractMaxChars` | number | 8000 | Max context chars sent to extraction LLM |
  809. | `enableManagementTools` | boolean | false | Register CLI management tools as agent tools |
  810. | `autoRecallMinLength` | number | 15 | Min prompt chars to trigger auto-recall (6 for CJK) |
  811. | `autoRecallMinRepeated` | number | 0 | Min turns before same memory can re-inject in same session |
  812. | `sessionStrategy` | string | `systemSessionMemory` | Session pipeline: `memoryReflection` / `systemSessionMemory` / `none` |
  813. ### LLM (for Smart Extraction)
  814. | Field | Type | Default | Description |
  815. |-------|------|---------|-------------|
  816. | `llm.apiKey` | string | falls back to `embedding.apiKey` | LLM API key |
  817. | `llm.model` | string | `openai/gpt-oss-120b` | LLM model for extraction |
  818. | `llm.baseURL` | string | falls back to `embedding.baseURL` | LLM endpoint |
  819. ### Retrieval
  820. | Field | Type | Default | Description |
  821. |-------|------|---------|-------------|
  822. | `mode` | string | `hybrid` | `hybrid` / `vector` (`bm25`-only mode does not exist in schema) |
  823. | `vectorWeight` | number | 0.7 | Weight for vector search |
  824. | `bm25Weight` | number | 0.3 | Weight for BM25 full-text search |
  825. | `minScore` | number | 0.3 | Minimum relevance threshold |
  826. | `hardMinScore` | number | 0.35 | Hard cutoff post-reranking |
  827. | `rerank` | string | `cross-encoder` | Reranking strategy: `cross-encoder` / `lightweight` / `none` |
  828. | `rerankProvider` | string | `jina` | `jina` / `siliconflow` / `voyage` / `pinecone` / `vllm` (Docker Model Runner) |
  829. | `rerankModel` | string | `jina-reranker-v3` | Reranker model name |
  830. | `rerankEndpoint` | string | provider default | Reranker API URL |
  831. | `rerankApiKey` | string | — | Reranker API key |
  832. | `candidatePoolSize` | number | 20 | Candidates to rerank before final filter |
  833. | `recencyHalfLifeDays` | number | 14 | Freshness decay half-life |
  834. | `recencyWeight` | number | 0.1 | Weight of recency in scoring |
  835. | `timeDecayHalfLifeDays` | number | 60 | Memory age decay factor |
  836. | `reinforcementFactor` | number | 0.5 | Access-based half-life multiplier (0–2, set 0 to disable) |
  837. | `maxHalfLifeMultiplier` | number | 3 | Hard cap on reinforcement boost |
  838. | `filterNoise` | boolean | true | Filter refusals, greetings, etc. |
  839. | `lengthNormAnchor` | number | 500 | Reference length for normalization (chars) |
  840. **Access reinforcement note:** Reinforcement is whitelisted to `source: "manual"` only — auto-recall does NOT strengthen memories, preventing noise amplification.
  841. ### Session Strategy (v1.1.0+)
  842. Use `sessionStrategy` (top-level field) to configure the session pipeline:
  843. | Value | Behavior |
  844. |-------|----------|
  845. | `"systemSessionMemory"` **(default)** | Built-in session memory (simpler) |
  846. | `"memoryReflection"` | Advanced LLM-powered reflection with inheritance/derived injection |
  847. | `"none"` | Session summaries disabled |
  848. **`memoryReflection` config** (used when `sessionStrategy: "memoryReflection"`):
  849. | Field | Type | Default | Description |
  850. |-------|------|---------|-------------|
  851. | `storeToLanceDB` | boolean | true | Persist reflections to LanceDB |
  852. | `writeLegacyCombined` | boolean | true | Also write legacy combined row |
  853. | `injectMode` | string | `inheritance+derived` | `inheritance-only` / `inheritance+derived` |
  854. | `agentId` | string | — | Dedicated reflection agent (e.g. `"memory-distiller"`) |
  855. | `messageCount` | number | 120 | Messages to include in reflection |
  856. | `maxInputChars` | number | 24000 | Max chars sent to reflection LLM |
  857. | `timeoutMs` | number | 20000 | Reflection LLM timeout (ms) |
  858. | `thinkLevel` | string | `medium` | Reasoning depth: `off` / `minimal` / `low` / `medium` / `high` |
  859. | `errorReminderMaxEntries` | number | 3 | Max error entries injected into reflection |
  860. | `dedupeErrorSignals` | boolean | true | Deduplicate error signals before injection |
  861. **`memoryReflection.recall` sub-object** (controls which past reflections are retrieved for injection):
  862. | Field | Type | Default | Description |
  863. |-------|------|---------|-------------|
  864. | `mode` | string | `fixed` | Recall mode: `fixed` / `dynamic` |
  865. | `topK` | number | 6 | Max reflection entries retrieved (max 20) |
  866. | `includeKinds` | array | `["invariant"]` | Which kinds to include: `invariant` / `derived` |
  867. | `maxAgeDays` | number | 45 | Max age of reflections to retrieve |
  868. | `maxEntriesPerKey` | number | 10 | Max entries per scope key |
  869. | `minRepeated` | number | 2 | Min times an entry must appear to be included |
  870. | `minScore` | number | 0.18 | Minimum relevance score (range 0–5) |
  871. | `minPromptLength` | number | 8 | Min prompt length to trigger recall |
  872. ### Session Memory (deprecated — legacy compat only)
  873. > ⚠️ **`sessionMemory` is a legacy compatibility shim since v1.1.0.** Prefer `sessionStrategy` instead.
  874. > - `sessionMemory.enabled: true` → maps to `sessionStrategy: "systemSessionMemory"`
  875. > - `sessionMemory.enabled: false` → maps to `sessionStrategy: "none"`
  876. | Field | Type | Default | Description |
  877. |-------|------|---------|-------------|
  878. | `sessionMemory.enabled` | boolean | false | Legacy: enable session summaries on `/new` |
  879. | `sessionMemory.messageCount` | number | 15 | Legacy: maps to `memoryReflection.messageCount` |
  880. ### Self-Improvement Governance
  881. | Field | Type | Default | Description |
  882. |-------|------|---------|-------------|
  883. | `selfImprovement.enabled` | boolean | **true** | Enable self-improvement tools (`self_improvement_log` etc.) — **on by default** |
  884. | `selfImprovement.beforeResetNote` | boolean | true | Inject learning reminder before session reset |
  885. | `selfImprovement.skipSubagentBootstrap` | boolean | true | Skip bootstrap for sub-agents |
  886. | `selfImprovement.ensureLearningFiles` | boolean | true | Auto-create `LEARNINGS.md` / `ERRORS.md` if missing |
  887. **Tool activation rules:**
  888. - `self_improvement_log`: requires `selfImprovement.enabled: true` (default — active unless explicitly disabled)
  889. - `self_improvement_extract_skill` + `self_improvement_review`: additionally require `enableManagementTools: true`
  890. ### Markdown Mirror
  891. | Field | Type | Default | Description |
  892. |-------|------|---------|-------------|
  893. | `mdMirror.enabled` | boolean | false | Mirror memory entries as `.md` files |
  894. | `mdMirror.dir` | string | — | Directory for markdown mirror files |
  895. ### Decay
  896. | Field | Type | Default | Description |
  897. |-------|------|---------|-------------|
  898. | `decay.recencyHalfLifeDays` | number | 30 | Base Weibull decay half-life |
  899. | `decay.recencyWeight` | number | 0.4 | Weight of recency in lifecycle score (distinct from `retrieval.recencyWeight`) |
  900. | `decay.frequencyWeight` | number | 0.3 | Weight of access frequency |
  901. | `decay.intrinsicWeight` | number | 0.3 | Weight of importance × confidence |
  902. | `decay.betaCore` | number | 0.8 | Weibull shape for core memories |
  903. | `decay.betaWorking` | number | 1.0 | Weibull shape for working memories |
  904. | `decay.betaPeripheral` | number | 1.3 | Weibull shape for peripheral memories |
  905. | `decay.coreDecayFloor` | number | 0.9 | Minimum lifecycle score for core tier |
  906. | `decay.workingDecayFloor` | number | 0.7 | Minimum lifecycle score for working tier |
  907. | `decay.peripheralDecayFloor` | number | 0.5 | Minimum lifecycle score for peripheral tier |
  908. | `decay.staleThreshold` | number | 0.3 | Score below which a memory is considered stale |
  909. | `decay.searchBoostMin` | number | 0.3 | Minimum search boost applied to lifecycle score |
  910. | `decay.importanceModulation` | number | 1.5 | Multiplier for importance in lifecycle score |
  911. ### Tier Management
  912. | Field | Type | Default | Description |
  913. |-------|------|---------|-------------|
  914. | `tier.coreAccessThreshold` | number | 10 | Access count for core promotion |
  915. | `tier.coreCompositeThreshold` | number | 0.7 | Lifecycle score for core promotion |
  916. | `tier.coreImportanceThreshold` | number | 0.8 | Minimum importance for core promotion |
  917. | `tier.workingAccessThreshold` | number | 3 | Access count for working promotion |
  918. | `tier.workingCompositeThreshold` | number | 0.4 | Lifecycle score for working promotion |
  919. | `tier.peripheralCompositeThreshold` | number | 0.15 | Score below which demotion occurs |
  920. | `tier.peripheralAgeDays` | number | 60 | Age threshold for stale memory demotion |
  921. ---
  922. ## MCP Tools
  923. ### Core Tools (auto-registered)
  924. **`memory_recall`** — Search long-term memory via hybrid retrieval
  925. | Parameter | Type | Required | Default | Notes |
  926. |-----------|------|----------|---------|-------|
  927. | `query` | string | yes | — | Search query |
  928. | `limit` | number | no | 5 | Max 20 |
  929. | `scope` | string | no | — | Specific scope to search |
  930. | `category` | enum | no | — | `preference\|fact\|decision\|entity\|reflection\|other` |
  931. **`memory_store`** — Save information to long-term memory
  932. | Parameter | Type | Required | Default | Notes |
  933. |-----------|------|----------|---------|-------|
  934. | `text` | string | yes | — | Information to remember |
  935. | `importance` | number | no | 0.7 | Range 0–1 |
  936. | `category` | enum | no | — | Memory classification |
  937. | `scope` | string | no | `agent:<id>` | Target scope |
  938. **`memory_forget`** — Delete memories by search or direct ID
  939. | Parameter | Type | Required | Notes |
  940. |-----------|------|----------|-------|
  941. | `query` | string | one of | Search query to locate memory |
  942. | `memoryId` | string | one of | Full UUID or 8+ char prefix |
  943. | `scope` | string | no | Scope for search/deletion |
  944. **`memory_update`** — Update memory (preserves original timestamp; `preference`/`entity` text updates create a new versioned row preserving history)
  945. | Parameter | Type | Required | Notes |
  946. |-----------|------|----------|-------|
  947. | `memoryId` | string | yes | Full UUID or 8+ char prefix |
  948. | `text` | string | no | New content (triggers re-embedding; `preference`/`entity` creates supersede version) |
  949. | `importance` | number | no | New score 0–1 |
  950. | `category` | enum | no | New classification |
  951. ### Management Tools (enable with `enableManagementTools: true`)
  952. **`memory_stats`** — Usage statistics
  953. - `scope` (string, optional): Filter by scope
  954. **`memory_list`** — List recent memories with filtering
  955. - `limit` (number, optional, default 10, max 50), `scope`, `category`, `offset` (pagination)
  956. ### Self-Improvement Tools
  957. > `self_improvement_log` is **enabled by default** (`selfImprovement.enabled: true`). `self_improvement_extract_skill` and `self_improvement_review` additionally require `enableManagementTools: true`.
  958. **`self_improvement_log`** — Log learning/error entries into LEARNINGS.md / ERRORS.md
  959. | Parameter | Type | Required | Notes |
  960. |-----------|------|----------|-------|
  961. | `type` | enum | yes | `"learning"` or `"error"` |
  962. | `summary` | string | yes | One-line summary |
  963. | `details` | string | no | Detailed context |
  964. | `suggestedAction` | string | no | Action to prevent recurrence |
  965. | `category` | string | no | Learning: `correction\|best_practice\|knowledge_gap`; Error: `correction\|bug_fix\|integration_issue` |
  966. | `area` | string | no | `frontend\|backend\|infra\|tests\|docs\|config` |
  967. | `priority` | string | no | `low\|medium\|high\|critical` |
  968. **`self_improvement_extract_skill`** — Create skill scaffold from a learning entry
  969. | Parameter | Type | Required | Default | Notes |
  970. |-----------|------|----------|---------|-------|
  971. | `learningId` | string | yes | — | Format `LRN-YYYYMMDD-001` or `ERR-*` |
  972. | `skillName` | string | yes | — | Lowercase with hyphens |
  973. | `sourceFile` | enum | no | `LEARNINGS.md` | `LEARNINGS.md\|ERRORS.md` |
  974. | `outputDir` | string | no | `"skills"` | Relative output directory |
  975. **`self_improvement_review`** — Summarize governance backlog (no parameters)
  976. ---
  977. ## Smart Extraction
  978. LLM-powered automatic memory classification and storage triggered after conversations.
  979. ### Enable
  980. ```json
  981. {
  982. "smartExtraction": true,
  983. "extractMinMessages": 2,
  984. "extractMaxChars": 8000,
  985. "llm": {
  986. "apiKey": "${OPENAI_API_KEY}",
  987. "model": "gpt-4o-mini"
  988. }
  989. }
  990. ```
  991. Minimal (reuses embedding API key — no separate `llm` block needed):
  992. ```json
  993. {
  994. "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" },
  995. "smartExtraction": true
  996. }
  997. ```
  998. Disable: `{ "smartExtraction": false }`
  999. ### 6-Category Classification
  1000. | Input Category | Stored As | Dedup Behavior |
  1001. |---------------|-----------|----------------|
  1002. | Profile | `fact` | Always merge (auto-consolidates) |
  1003. | Preferences | `preference` | Conditional merge |
  1004. | Entities | `entity` | Conditional merge |
  1005. | Events | `decision` | Append-only (no merge) |
  1006. | Cases | `fact` | Append-only (no merge) |
  1007. | Patterns | `other` | Conditional merge |
  1008. ### L0/L1/L2 Layered Content per Memory
  1009. - **L0 (Abstract)**: Single-sentence index (min 5 chars)
  1010. - **L1 (Overview)**: Structured markdown summary
  1011. - **L2 (Content)**: Full narrative detail
  1012. ### Two-Stage Deduplication
  1013. 1. **Vector pre-filter**: Similarity ≥ 0.7 finds candidates
  1014. 2. **LLM decision**: `CREATE | MERGE | SKIP | SUPPORT | CONTEXTUALIZE | CONTRADICT`
  1015. ---
  1016. ## Embedding Providers
  1017. | Provider | Model | Base URL | Dimensions | Notes |
  1018. |----------|-------|----------|-----------|-------|
  1019. | Jina (recommended) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | Latest (Feb 2026), task-aware LoRA, 32K ctx |
  1020. | Jina (multimodal) | `jina-embeddings-v4` | `https://api.jina.ai/v1` | 1024 | Text + image, Qwen2.5-VL backbone |
  1021. | OpenAI | `text-embedding-3-large` | `https://api.openai.com/v1` | 3072 | Best OpenAI quality (MTEB 64.6%) |
  1022. | OpenAI | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | Cost-efficient |
  1023. | DashScope (Alibaba) | `text-embedding-v4` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 1024 | Recommended for Chinese users; also supports rerank (see note below) |
  1024. | Google Gemini | `gemini-embedding-2-preview` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | Latest (Mar 2026), multimodal, 100+ languages |
  1025. | Google Gemini | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | Stable text-only |
  1026. | Ollama (local) | `mxbai-embed-large` | `http://localhost:11434/v1` | 1024 | **Recommended local** — beats text-embedding-3-large |
  1027. | Ollama (local) | `snowflake-arctic-embed2` | `http://localhost:11434/v1` | 1024 | Best multilingual local option |
  1028. | Ollama (local) | `nomic-embed-text:v1.5` | `http://localhost:11434/v1` | 768 | Lightweight classic, 270MB |
  1029. **DashScope rerank note:** DashScope is not a `rerankProvider` enum value, but its rerank API response is Jina-compatible. Use `rerankProvider: "jina"` with DashScope's endpoint:
  1030. ```json
  1031. "retrieval": {
  1032. "rerank": "cross-encoder",
  1033. "rerankProvider": "jina",
  1034. "rerankModel": "qwen3-rerank",
  1035. "rerankEndpoint": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",
  1036. "rerankApiKey": "${DASHSCOPE_API_KEY}"
  1037. }
  1038. ```
  1039. **Multi-key failover:** Set `apiKey` as an array for round-robin rotation on 429/503 errors.
  1040. ---
  1041. ## Reranker Providers
  1042. | Provider | `rerankProvider` | Endpoint | Model | Notes |
  1043. |----------|-----------------|----------|-------|-------|
  1044. | Jina (default) | `jina` | `https://api.jina.ai/v1/rerank` | `jina-reranker-v3` | **Latest text reranker** (2025, Qwen3 backbone, 131K ctx) |
  1045. | Jina (multimodal) | `jina` | `https://api.jina.ai/v1/rerank` | `jina-reranker-m0` | Multimodal (text+images), use when docs contain images |
  1046. | SiliconFlow | `siliconflow` | `https://api.siliconflow.com/v1/rerank` | `BAAI/bge-reranker-v2-m3` | Free tier available |
  1047. | Voyage AI | `voyage` | `https://api.voyageai.com/v1/rerank` | `rerank-2.5` | Sends `{model, query, documents}`, no `top_n` |
  1048. | Pinecone | `pinecone` | `https://api.pinecone.io/rerank` | `bge-reranker-v2-m3` | Pinecone customers only |
  1049. | vLLM / Docker Model Runner | `vllm` | Custom endpoint | any compatible model | Self-hosted via Docker Model Runner |
  1050. Jina key can be reused for both embedding and reranking.
  1051. ---
  1052. ## Multi-Scope Isolation
  1053. | Scope Format | Description |
  1054. |-------------|-------------|
  1055. | `global` | Shared across all agents |
  1056. | `agent:<id>` | Agent-specific memories |
  1057. | `custom:<name>` | Custom-named scopes |
  1058. | `project:<id>` | Project-specific memories |
  1059. | `user:<id>` | User-specific memories |
  1060. Default access: `global` + `agent:<id>`. Multi-scope requires explicit `scopes.agentAccess` — see Full Config above.
  1061. **To disable memory entirely** (unbind the slot without removing the plugin):
  1062. ```json
  1063. { "plugins": { "slots": { "memory": "none" } } }
  1064. ```
  1065. ---
  1066. ## Memory Lifecycle (Weibull Decay)
  1067. ### Three Tiers
  1068. | Tier | Decay Floor | Beta | Behavior |
  1069. |------|-------------|------|----------|
  1070. | Core | 0.9 | 0.8 | Gentle sub-exponential decline |
  1071. | Working | 0.7 | 1.0 | Standard exponential (default) |
  1072. | Peripheral | 0.5 | 1.3 | Rapid super-exponential fade |
  1073. ### Promotion/Demotion Rules
  1074. - **Peripheral → Working:** access ≥ 3 AND score ≥ 0.4
  1075. - **Working → Core:** access ≥ 10 AND score ≥ 0.7 AND importance ≥ 0.8
  1076. - **Working → Peripheral:** score < 0.15 OR (age > 60 days AND access < 3)
  1077. - **Core → Working:** score < 0.15 AND access < 3
  1078. ---
  1079. ## Hybrid Retrieval
  1080. **Fusion:** `weightedFusion = (vectorScore × 0.7) + (bm25Score × 0.3)`
  1081. **Pipeline:** RRF Fusion → Cross-Encoder Rerank → Lifecycle Decay Boost → Length Norm → Hard Min Score → MMR Diversity (cosine > 0.85 demoted)
  1082. **Reranking:** 60% cross-encoder score + 40% original fused score. Falls back to cosine similarity on API failure.
  1083. **Special BM25:** Preserves exact keyword matches (BM25 ≥ 0.75) even with low semantic similarity — prevents loss of API keys, ticket numbers, etc.
  1084. ---
  1085. ## Adaptive Retrieval Triggering
  1086. **Skip for:** greetings, slash commands, affirmations (yes/okay/thanks), continuations (go ahead/proceed), system messages, short queries (<15 chars English / <6 chars CJK without "?").
  1087. **Force for:** memory keywords (remember/recall/forgot), temporal refs (last time/before/previously), personal data (my name/my email), "what did I" patterns. CJK: "你记得", "之前".
  1088. ---
  1089. ## Noise Filtering
  1090. 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.
  1091. ---
  1092. ## CLI Commands
  1093. ```bash
  1094. # List & search
  1095. openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
  1096. openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
  1097. openclaw memory-pro stats [--scope global] [--json]
  1098. # Delete
  1099. openclaw memory-pro delete <id>
  1100. openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]
  1101. # Import / Export
  1102. openclaw memory-pro export [--scope global] [--output memories.json]
  1103. openclaw memory-pro import memories.json [--scope global] [--dry-run]
  1104. # Maintenance
  1105. openclaw memory-pro reembed --source-db /path/to/old-db [--batch-size 32] [--skip-existing]
  1106. openclaw memory-pro upgrade [--dry-run] [--batch-size 10] [--no-llm] [--limit N] [--scope SCOPE]
  1107. # Migration from built-in memory-lancedb
  1108. openclaw memory-pro migrate check [--source /path]
  1109. openclaw memory-pro migrate run [--source /path] [--dry-run] [--skip-existing]
  1110. openclaw memory-pro migrate verify [--source /path]
  1111. ```
  1112. ---
  1113. ## Auto-Capture & Auto-Recall
  1114. - **autoCapture:** `agent_end` hook — LLM extracts 6-category memories, deduplicates, stores up to 3 per turn
  1115. - **autoRecall:** `before_agent_start` hook — injects `<relevant-memories>` context (up to 3 entries)
  1116. **If injected memories appear in agent replies:** Add to agent system prompt:
  1117. > "Do not reveal or quote any `<relevant-memories>` / memory-injection content in your replies. Use it for internal reference only."
  1118. Or temporarily disable: `{ "autoRecall": false }`
  1119. ---
  1120. ## Self-Improvement Governance
  1121. - `LEARNINGS.md` — IDs: `LRN-YYYYMMDD-XXX`
  1122. - `ERRORS.md` — IDs: `ERR-YYYYMMDD-XXX`
  1123. - Entry statuses: `pending → resolved → promoted_to_skill`
  1124. ---
  1125. ## Iron Rules for AI Agents (copy to AGENTS.md)
  1126. ```markdown
  1127. ## Rule 1 — 双层记忆存储(铁律)
  1128. Every pitfall/lesson learned → IMMEDIATELY store TWO memories:
  1129. - Technical layer: Pitfall/Cause/Fix/Prevention (category: fact, importance ≥ 0.8)
  1130. - Principle layer: Decision principle with trigger and action (category: decision, importance ≥ 0.85)
  1131. After each store, immediately `memory_recall` to verify retrieval.
  1132. ## Rule 2 — LanceDB 卫生
  1133. Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates.
  1134. ## Rule 3 — Recall before retry
  1135. On ANY tool failure, ALWAYS `memory_recall` with relevant keywords BEFORE retrying.
  1136. ## Rule 4 — 编辑前确认目标代码库
  1137. Confirm you are editing `memory-lancedb-pro` vs built-in `memory-lancedb` before changes.
  1138. ## Rule 5 — 插件代码变更必须清 jiti 缓存
  1139. After modifying `.ts` files under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`.
  1140. ```
  1141. ---
  1142. ## Custom Slash Commands (add to CLAUDE.md / AGENTS.md)
  1143. ```markdown
  1144. ## /lesson command
  1145. When user sends `/lesson <content>`:
  1146. 1. Use memory_store with category=fact (raw knowledge)
  1147. 2. Use memory_store with category=decision (actionable takeaway)
  1148. 3. Confirm what was saved
  1149. ## /remember command
  1150. When user sends `/remember <content>`:
  1151. 1. Use memory_store with appropriate category and importance
  1152. 2. Confirm with stored memory ID
  1153. ```
README.md · README · 233 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # memory-lancedb-pro — OpenClaw Memory Skill
  2. > **Claude Code Skill** for [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) — production-grade long-term memory plugin for OpenClaw AI agents.
  3. This skill gives Claude Code deep, accurate knowledge of every feature in `memory-lancedb-pro` (v1.1.0-beta.8): installation, optimal configuration, Smart Extraction, hybrid retrieval, Weibull decay lifecycle, multi-scope isolation, self-improvement governance, and all MCP tools.
  4. ---
  5. ## What this skill does
  6. When installed, Claude Code can:
  7. - **Guide you through a 7-step optimal configuration workflow** — just say _"help me enable the best config"_
  8. - **Present 4 deployment plans** (Full Power / Budget / Simple / Fully Local) with provider links and tradeoffs
  9. - **Install, configure, and verify** the plugin using `openclaw plugins install` or git clone
  10. - **Set up Ollama** for fully local, zero-API-cost deployment
  11. - **Configure every feature**: Smart Extraction, hybrid retrieval, reranking, multi-scope, Weibull decay, session memory, self-improvement governance
  12. - **Use all 9 MCP tools** correctly: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review`
  13. - **Avoid common pitfalls** — workspace plugin enablement, `autoRecall` default-false, jiti cache, env vars, scope isolation, etc.
  14. ---
  15. ## Installation
  16. ### Prerequisites
  17. **For Claude Code users:**
  18. - [Claude Code](https://claude.ai/code) CLI installed
  19. - [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) plugin configured as an MCP server
  20. **For OpenClaw users:**
  21. - [OpenClaw](https://openclaw.ai) gateway running
  22. - `memory-lancedb-pro` plugin installed via `openclaw plugins install memory-lancedb-pro@beta`
  23. ### Install the skill
  24. > **Note:** This is a *skill* (knowledge file for AI agents), not a plugin. Skills are installed by placing them in your skills directory — there is no `openclaw skills install` command.
  25. **Option A — clone this repo (recommended):**
  26. For **Claude Code** users:
  27. ```bash
  28. git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
  29. ```
  30. For **OpenClaw** users:
  31. ```bash
  32. git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
  33. ```
  34. **Option B — download ZIP from GitHub:**
  35. 1. Click **Code → Download ZIP** on the [repository page](https://github.com/CortexReach/memory-lancedb-pro-skill)
  36. 2. Extract and place in your skills directory:
  37. ```bash
  38. # Claude Code
  39. unzip memory-lancedb-pro-skill-main.zip
  40. mv memory-lancedb-pro-skill-main ~/.claude/skills/memory-lancedb-pro
  41. # OpenClaw
  42. unzip memory-lancedb-pro-skill-main.zip
  43. mv memory-lancedb-pro-skill-main ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
  44. ```
  45. **Verify the skill is loaded:**
  46. ```bash
  47. # Claude Code: the skill loads automatically based on trigger conditions
  48. # To test: ask Claude Code "help me configure memory-lancedb-pro"
  49. # OpenClaw: check skill discovery
  50. openclaw skills list
  51. ```
  52. ---
  53. ## Skill Structure
  54. ```
  55. memory-lancedb-pro/
  56. ├── SKILL.md # Main skill file (loaded into context automatically)
  57. └── references/
  58. └── full-reference.md # Deep technical reference (loaded on demand)
  59. ```
  60. ### Progressive disclosure
  61. | Level | What loads | When |
  62. |-------|-----------|------|
  63. | Metadata (`name` + `description`) | Always | ~100 words, negligible |
  64. | `SKILL.md` body | When skill triggers | Operational workflows, all config options |
  65. | `references/full-reference.md` | On demand | DB schema, Weibull formulas, source file map, scoring internals |
  66. ---
  67. ## Trigger phrases
  68. Claude Code loads this skill automatically when you mention:
  69. - `memory-lancedb-pro`, `memory pro`, `lancedb pro`
  70. - `help me enable the best config` / `apply optimal configuration`
  71. - `memory_recall`, `memory_store`, `memory_forget`, `memory_update`
  72. - `Smart Extraction`, `autoCapture`, `autoRecall`
  73. - `hybrid retrieval`, `reranker`, `BM25`, `Weibull decay`
  74. - `self_improvement_log`, `LEARNINGS.md`, `ERRORS.md`
  75. ---
  76. ## Covered Features
  77. ### Installation & Setup
  78. - 3 installation methods: `openclaw plugins install`, git clone with manual path, existing deployment migration
  79. - Plugin enablement rules: `plugins.allow`, `plugins.entries.<id>.enabled`, `plugins.slots.memory`
  80. - Workspace plugin gotchas (disabled by default, requires explicit `allow`)
  81. - Custom path env vars: `OPENCLAW_HOME`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`
  82. - Post-installation smoke test checklist
  83. ### 7-Step Optimal Config Workflow
  84. When you say **"help me enable the best config"**, Claude will:
  85. 1. Present 4 deployment plans with provider links
  86. 2. Ask about your existing API keys and config location
  87. 3. Find and read your current `openclaw.json`
  88. 4. Build a merged config block for your chosen plan
  89. 5. Apply it with the correct template (Method 1 vs Method 2)
  90. 6. Validate and restart the gateway
  91. 7. Run a full smoke test
  92. ### 4 Deployment Plans
  93. | Plan | Embedding | Reranker | LLM | API Keys |
  94. |------|-----------|----------|-----|----------|
  95. | **A — Full Power** | Jina `jina-embeddings-v5-text-small` | Jina `jina-reranker-v3` | OpenAI `gpt-4o-mini` | Jina + OpenAI |
  96. | **B — Budget** | Jina embeddings | SiliconFlow BGE (free tier) | OpenAI `gpt-4o-mini` | Jina + SiliconFlow + OpenAI |
  97. | **C — Simple** | OpenAI `text-embedding-3-small` | None | OpenAI `gpt-4o-mini` | OpenAI only |
  98. | **D — Local** | Ollama `nomic-embed-text` (768-dim) | None | Ollama `qwen2.5:7b` | None (free) |
  99. Each plan includes: API key acquisition links, cost notes, RAM requirements (Plan D), and tradeoff explanations.
  100. ### Smart Extraction
  101. - 6-category LLM-powered classification: Profile → `fact`, Preferences → `preference`, Entities → `entity`, Events → `decision`, Cases → `fact`, Patterns → `other`
  102. - L0/L1/L2 layered storage (Abstract / Overview / Full Content)
  103. - Two-stage deduplication: vector pre-filter (≥ 0.7) + LLM decision (`CREATE | MERGE | SKIP | SUPPORT | CONTEXTUALIZE | CONTRADICT`)
  104. - Config: `smartExtraction`, `extractMinMessages`, `extractMaxChars`, `llm.*`
  105. ### Hybrid Retrieval
  106. - Fusion: `(vectorScore × 0.7) + (bm25Score × 0.3)` via RRF
  107. - Pipeline: RRF → Cross-Encoder Rerank → Lifecycle Decay Boost → Length Norm → Hard Min Score → MMR Diversity
  108. - BM25 keyword preservation (score ≥ 0.75 bypasses semantic filter — protects API keys, ticket numbers)
  109. - 4 reranker providers: Jina, SiliconFlow, Voyage AI, Pinecone
  110. ### Memory Lifecycle (Weibull Decay)
  111. - 3 tiers: Core (β=0.8, floor=0.9) / Working (β=1.0, floor=0.7) / Peripheral (β=1.3, floor=0.5)
  112. - Promotion/demotion rules based on access count, composite score, importance, age
  113. - Composite score: Recency 40% + Frequency 30% + Intrinsic 30%
  114. - Access reinforcement: frequently recalled memories decay more slowly
  115. ### Multi-Scope Isolation
  116. - Scope formats: `global`, `agent:<id>`, `custom:<name>`, `project:<id>`, `user:<id>`
  117. - `scopes.agentAccess` mapping for multi-scope agents
  118. - Disable memory entirely: `{ "plugins": { "slots": { "memory": "none" } } }`
  119. ### All 9 MCP Tools
  120. Core (auto-registered): `memory_recall`, `memory_store`, `memory_forget`, `memory_update`
  121. Management (opt-in): `memory_stats`, `memory_list`
  122. Self-improvement (opt-in): `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review`
  123. ### Self-Improvement Governance
  124. - `LEARNINGS.md` (IDs: `LRN-YYYYMMDD-XXX`) and `ERRORS.md` (IDs: `ERR-YYYYMMDD-XXX`)
  125. - Entry lifecycle: `pending → resolved → promoted_to_skill`
  126. - Skill scaffold generation from learning entries
  127. ### CLI Reference
  128. Full coverage of all `openclaw memory-pro` commands: `list`, `search`, `stats`, `delete`, `delete-bulk`, `export`, `import`, `reembed`, `upgrade`, `migrate`
  129. ### Ollama Local Deployment (Plan D)
  130. - Step-by-step model pull commands
  131. - Ollama health check and embedding endpoint verification
  132. - JSON output reliability notes per model
  133. - Remote Ollama host configuration
  134. - Fallback when Smart Extraction fails with local LLM
  135. ### Iron Rules & Slash Commands
  136. - 5 Iron Rules for AI agents (dual-layer storage, LanceDB hygiene, recall-before-retry, etc.)
  137. - `/lesson` and `/remember` custom slash command templates for `AGENTS.md`
  138. ---
  139. ## What's in `references/full-reference.md`
  140. Deep technical content loaded only when needed:
  141. - **Database schema**: LanceDB `memories` table fields and metadata keys
  142. - **Source file map**: All 31 source files with sizes and responsibilities
  143. - **Retrieval pipeline**: Full scoring formula chain with all 9 parameters and defaults
  144. - **Weibull decay formulas**: `recency = exp(-lambda × daysSince^beta)` with tier-specific parameters
  145. - **Embedding config interface**: All `EmbeddingConfig` options
  146. - **Document chunking**: 5-level splitting hierarchy, smart chunking math
  147. - **Smart metadata system**: Three-tier content fields, bounded array limits, normalization functions
  148. - **LLM client internals**: Temperature, response parsing, error recovery strategy
  149. - **Noise filter details**: 5 built-in noise categories, auto-learning prototypes (bank cap: 200)
  150. - **Adaptive retrieval full logic**: Skip/force conditions with CJK equivalents
  151. - **Access tracking & reinforcement**: Debounce timer, logarithmic reinforcement curve
  152. - **Reflection storage subsystem**: 4 storage types, importance weights, dedup threshold
  153. ---
  154. ## About memory-lancedb-pro
  155. The underlying plugin is maintained at [CortexReach/memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro).
  156. Key specs:
  157. - **Version**: 1.1.0-beta.8
  158. - **Storage**: LanceDB (embedded, no separate server)
  159. - **Retrieval**: Hybrid vector + BM25 with RRF fusion
  160. - **Node.js**: 22.16+ required, 24 recommended
  161. - **License**: MIT
  162. ---
  163. ## License
  164. MIT
  165. ---
  166. ## Buy Me a Coffee
  167. [!["Buy Me A Coffee"](https://storage.ko-fi.com/cdn/kofi2.png?v=3)](https://ko-fi.com/aila)
  168. ## Contact
  169. <img src="assets/wechat-qrcode.jpeg" width="200" alt="WeChat QR Code" />

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.