memory-lancedb-pro-openclaw

What this skill does

# memory-lancedb-pro OpenClaw Plugin

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`memory-lancedb-pro` is a production-grade long-term memory plugin for [OpenClaw](https://github.com/openclaw/openclaw) agents. It stores preferences, decisions, and project context in a local [LanceDB](https://lancedb.com) vector database and automatically recalls relevant memories before each agent reply. Key features: hybrid retrieval (vector + BM25 full-text), cross-encoder reranking, LLM-powered smart extraction (6 categories), Weibull decay-based forgetting, multi-scope isolation (agent/user/project), and a full management CLI.

---

## Installation

### Option A: One-Click Setup Script (Recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
bash setup-memory.sh
```

Flags:
```bash
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 changes
```

The 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

```bash
openclaw plugins install memory-lancedb-pro@beta
```

### Option C: npm

```bash
npm i memory-lancedb-pro@beta
```

> **Critical:** 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`)

```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

```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",
            "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):**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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:

```bash
openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | grep "memory-lancedb-pro"
```

Expected startup log output:
```
memory-lancedb-pro: smart extraction enabled
[email protected]: plugin registered
```

### Memory Management CLI

```bash
# 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-pro
```

---

## MCP 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.

```typescript
// 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.

```typescript
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 mem