@cablate/memory-lancedb-mcp

Built on CortexReach/memory-lancedb-pro — original work by win4r and contributors. Refactored from OpenClaw plugin into a standalone MCP server.

English | 繁體中文

Why memory-lancedb-mcp?

Most AI agents forget everything the moment you start a new session. This MCP server gives any MCP-compatible client persistent, intelligent long-term memory — without manual management.

Quick Start

1. Install

npm install -g @cablate/memory-lancedb-mcp

2. Configure your MCP client

Add to your MCP client settings (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@cablate/memory-lancedb-mcp"],
      "env": {
        "EMBEDDING_API_KEY": "your-api-key",
        "EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}

3. Advanced configuration (optional)

For full control, create a config file and point to it:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@cablate/memory-lancedb-mcp"],
      "env": {
        "MEMORY_LANCEDB_CONFIG": "/path/to/config.json"
      }
    }
  }
}

See config.example.json for a full example.

MCP Tools

This server exposes the following tools to MCP clients:

Core Tools

Management Tools (opt-in)

Enable with "enableManagementTools": true in config.

Self-Improvement Tools (opt-in, disabled by default)

Enable with "enableSelfImprovementTools": true in config or MEMORY_ENABLE_SELF_IMPROVEMENT=true env var.

Architecture

┌─────────────────────────────────────────────────────────┐
│                  server.ts (MCP Server)                  │
│    Tool Registration · Config Loading · Request Routing  │
└────────┬──────────┬──────────┬──────────┬───────────────┘
         │          │          │          │
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
    │ store  │ │embedder│ │retriever│ │   scopes    │
    │ .ts    │ │ .ts    │ │ .ts    │ │    .ts      │
    └────────┘ └────────┘ └────────┘ └─────────────┘
         │                     │
    ┌────▼────────┐      ┌────▼──────────┐
    │smart-       │      │noise-filter.ts│
    │metadata.ts  │      │decay-engine.ts│
    └─────────────┘      └───────────────┘

Multi-Stage Scoring Pipeline

Query → embedQuery() ─┐
                       ├─→ RRF Fusion → Rerank → Lifecycle Decay → Length Norm → Filter
Query → BM25 FTS ─────┘

Configuration

Environment Variables

Config File

{
  "embedding": {
    "apiKey": "${EMBEDDING_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "./memory-data",
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "minScore": 0.3,
    "rerank": "cross-encoder",
    "rerankApiKey": "${JINA_API_KEY}",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankProvider": "jina",
    "candidatePoolSize": 20,
    "hardMinScore": 0.35,
    "filterNoise": true
  },
  "enableManagementTools": true,
  "enableSelfImprovementTools": false,
  "scopes": {
    "default": "global",
    "definitions": {
      "global": { "description": "Shared knowledge" },
      "agent:my-bot": { "description": "Private to my-bot" }
    },
    "agentAccess": {
      "my-bot": ["global", "agent:my-bot"]
    }
  },
  "decay": {
    "recencyHalfLifeDays": 30,
    "frequencyWeight": 0.3,
    "intrinsicWeight": 0.3
  }
}

Core Features

Hybrid Retrieval

• Vector Search — semantic similarity via LanceDB ANN (cosine distance)
• BM25 Full-Text Search — exact keyword matching via LanceDB FTS index
• Fusion — vector score as base, BM25 hits get a 15% boost

Cross-Encoder Reranking

• Supports Jina, TEI, SiliconFlow, Voyage AI, Pinecone, DashScope
• Hybrid scoring: 60% cross-encoder + 40% original fused score
• Graceful degradation on API failure

Multi-Scope Isolation

• Built-in scopes: global, agent:<id>, custom:<name>, project:<id>, user:<id>
• Agent-level access control via scopes.agentAccess

Noise Filtering

• Filters agent refusals, meta-questions, greetings, low-quality content
• CJK-aware thresholds (Chinese: 6 chars vs English: 15 chars)

Memory Lifecycle (Decay + Tiers)

• Weibull Decay: composite score = recency + frequency + intrinsic value
• Three-Tier Promotion: Peripheral ↔ Working ↔ Core
• Access Reinforcement: frequently recalled memories decay slower

Smart Metadata

• L0/L1/L2 layered storage for progressive detail retrieval
• Temporal versioning with supersede chains
• Fact key deduplication

Database Schema

LanceDB table memories:

Development

git clone https://github.com/cablate/memory-lancedb-mcp.git
cd memory-lancedb-mcp
npm install
npm test

Run the server locally:

EMBEDDING_API_KEY=your-key npx tsx server.ts

License

MIT — see LICENSE for details.