Tools

MCP Memory LanceDB Pro

Name: MCP Memory LanceDB Pro
Rating: 3.5 (1 reviews)
Author: bcornish1797

By bcornish1797 👁 4 views ▲ 0 votes

Full memory-lancedb-pro memory enhancement system for Claude Code via MCP protocol — hybrid retrieval, smart extraction, auto-capture, intelligent forgetting, multi-scope isolation. Feature parity with OpenClaw memory-lancedb-pro plugin.

GitHub

Install

npm install
```

Configuration Example

{
  "memory": {
    "command": "node",
    "args": ["~/.claude/mcp-servers/memory/server-full.mjs"],
    "env": {
      "JINA_API_KEY": "your-jina-api-key",
      "LLM_API_KEY": "your-llm-api-key",
      "LLM_BASE_URL": "https://api.openai.com/v1",
      "LLM_MODEL": "gpt-4o-mini",
      "RERANK_API_KEY": "your-reranker-key",
      "RERANK_PROVIDER": "jina",
      "RERANK_MODEL": "jina-reranker-v3",
      "RERANK_ENDPOINT": "https://api.jina.ai/v1/rerank"
    }
  }
}

README

<div align="center">

# 🧠 MCP-Memory-LanceDB-Pro

**Give your AI coding assistant a brain that actually remembers.**

*Full-featured long-term memory system for Claude Code via the Model Context Protocol (MCP).*

[![MCP Server](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![LanceDB](https://img.shields.io/badge/LanceDB-Vectorstore-orange)](https://lancedb.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-24+-339933)](https://nodejs.org)

</div>

---

## The Problem

Every time you start a new Claude Code session, your AI assistant forgets everything — your preferences, past decisions, project context, lessons learned. You end up repeating yourself, wasting time, and losing momentum.

## The Solution

**MCP-Memory-LanceDB-Pro** is a standalone MCP server that gives Claude Code persistent, intelligent long-term memory. It runs alongside Claude Code as an independent process, automatically capturing important information and recalling it when needed — across sessions, across projects, across time.

### Before & After

**Without memory** — every session starts from zero:
```
You: "Use tabs for indentation, always add error handling."
(next session)
You: "I already told you — tabs, not spaces!"
(next session)
You: "...seriously, tabs. And error handling. Again."
```

**With MCP-Memory-LanceDB-Pro** — your assistant learns and remembers:
```
You: "Use tabs for indentation, always add error handling."
(next session — assistant auto-recalls your preferences)
Assistant: (silently applies tabs + error handling)
You: "Why did we pick PostgreSQL over MongoDB last month?"
Assistant: "Based on our discussion on Feb 12, the main reasons were..."
```

---

## Features

| Feature | Description |
|---------|-------------|
| **Hybrid Retrieval** | Vector similarity + BM25 full-text search with RRF fusion |
| **Cross-Encoder Reranking** | Jina / SiliconFlow / Voyage / Pinecone rerankers |
| **Smart Extraction** | LLM-powered 6-category classification: preferences, decisions, facts, entities, events, patterns |
| **Intelligent Forgetting** | Weibull decay model — important memories stay, noise naturally fades |
| **Auto-Capture** | Claude Code hooks automatically store important info after each response |
| **Auto-Recall** | SessionStart hook automatically injects relevant context |
| **Multi-Scope Isolation** | Agent-private, global shared, and project-scoped boundaries |
| **Noise Filtering** | Embedding-based noise prototype bank + regex filters |
| **Reflection Pipeline** | Extract invariant rules and derived knowledge |
| **Self-Improvement** | Structured learning/error logging with skill extraction |
| **14 MCP Tools** | Complete memory management API |

---

## Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/bcornish1797/MCP-Memory-LanceDB-Pro.git \
  ~/.claude/mcp-servers/memory
cd ~/.claude/mcp-servers/memory
npm install
```

### 2. Configure Claude Code

Add to `~/.claude.json` under `projects.<your-project>.mcpServers`:

```json
{
  "memory": {
    "command": "node",
    "args": ["~/.claude/mcp-servers/memory/server-full.mjs"],
    "env": {
      "JINA_API_KEY": "your-jina-api-key",
      "LLM_API_KEY": "your-llm-api-key",
      "LLM_BASE_URL": "https://api.openai.com/v1",
      "LLM_MODEL": "gpt-4o-mini",
      "RERANK_API_KEY": "your-reranker-key",
      "RERANK_PROVIDER": "jina",
      "RERANK_MODEL": "jina-reranker-v3",
      "RERANK_ENDPOINT": "https://api.jina.ai/v1/rerank"
    }
  }
}
```

### 3. Set Up Automation Hooks (Optional)

Add to `~/.claude/settings.json` for fully automatic memory capture:

```json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "path/to/hooks/session-start.sh"}]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "path/to/hooks/auto-capture.sh"}]
    }],
    "PostCompact": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "path/to/hooks/post-compact.sh"}]
    }],
    "SessionEnd": [{
      "matcher": "",
      "hooks": [{"type": "command", "command": "path/to/hooks/session-end.sh"}]
    }]
  }
}
```

### 4. Restart Claude Code

The memory server loads automatically on next session.

---

## MCP Tools

### Core Memory

| Tool | Description |
|------|-------------|
| `memory_recall` | Hybrid search with vector + BM25 + cross-encoder reranking |
| `memory_store` | Store with auto-chunking, smart metadata, and auto-categorization |
| `memory_forget` | Delete by ID or search query |
| `memory_update` | Update text, importance, or category (triggers re-embedding) |
| `memory_stats` | Usage statistics by scope and category |
| `memory_list` | List recent memories with scope/category filters |

### Intelligent Processing

| Tool | Description |
|------|-------------|
| `memory_extract` | LLM-powered smart extraction from conversation text |
| `memory_decay` | Weibull intelligent forgetting — clean stale memories |
| `memory_reflect` | Reflection pipeline — extract invariant rules and derived knowledge |
| `memory_bulk_delete` | Bulk delete by scope, category, or age |
| `memory_migrate` | Legacy database migration |

### Self-Improvement

| Tool | Description |
|------|-------------|
| `self_improvement_log` | Log structured learnings or errors |
| `self_improvement_review` | Governance backlog summary |
| `self_improvement_extract_skill` | Transform learning entries into skill scaffolds |

---

## Architecture

```
┌─────────────────────────────────────────────────────┐
│              MCP Server (server-full.mjs)            │
│         stdio JSON-RPC  <-->  Claude Code            │
└────────┬──────────┬──────────┬──────────┬────────────┘
         |          |          |          |
    ┌────v───┐ ┌────v───┐ ┌───v────┐ ┌──v──────────┐
    | Store  | |Embedder| |Retriever| |   Scopes    |
    |LanceDB | | Jina   | |Hybrid  | | Isolation   |
    └────────┘ └────────┘ └────────┘ └─────────────┘
         |          |          |
    ┌────v───┐ ┌────v────┐ ┌──v──────────┐
    | Smart  | | Decay   | |  Noise      |
    |Extract | | Engine  | |  Filter     |
    | (LLM)  | |(Weibull)| |(Prototypes) |
    └────────┘ └─────────┘ └─────────────┘

    ┌─────────────────────────────────────┐
    |        Claude Code Hooks            |
    | SessionStart | Stop | PostCompact   |
    | (auto-recall)|(auto-|(re-inject)    |
    |              |capture)              |
    └─────────────────────────────────────┘
```

### Key Components

| Module | Files | Purpose |
|--------|-------|---------|
| **Storage** | `store.ts` | LanceDB vector storage with FTS/BM25 indexing |
| **Embedding** | `embedder.ts` | Jina/OpenAI-compatible embeddings with task-aware API |
| **Retrieval** | `retriever.ts` | Hybrid vector+BM25 with RRF fusion and 6-stage scoring pipeline |
| **Smart Extraction** | `smart-extractor.ts` | LLM-powered 6-category memory classification |
| **Decay** | `decay-engine.ts` | Weibull stretched-exponential decay with tier-based lifecycle |
| **Scopes** | `scopes.ts` | Multi-scope access control and isolation |
| **Noise Filter** | `noise-filter.ts`, `noise-prototypes.ts` | Regex + embedding-based noise rejection |
| **Reflection** | `reflection-*.ts` (8 modules) | Session reflection and knowledge distillation |
| **Self-Improvement** | `self-improvement-files.ts` | Structured learning/error governance |

---

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `JINA_API_KEY` | Yes | — | Jina AI API key for embeddings |
| `LLM_API_KEY` | No | — | LLM API key for smart extraction |
| `LLM_MODEL` | No | `gpt-4o-mini` | LLM model for extraction |
| `LLM_BASE_URL` | No | `https://api.openai.com/v1` | LLM API endpoint |
| `RERANK_API_KEY` | No | — | Reranker API key |
| `RERANK_PROVIDER` | No | `jina` | `jina` / `siliconflow` / `voyage` / `pinecone` |
| `RERANK_MODEL` | No | `jina-reranker-v3` | Reranker model name |
| `RERANK_ENDPOINT` | No | `https://api.jina.ai/v1/rerank` | Reranker API endpoint |
| `MEMORY_DB_PATH` | No | `~/.claude/memory-lancedb` | LanceDB database path |
| `MEMORY_DEFAULT_SCOPE` | No | `agent:primary` | Default memory scope |

### Supported Providers

**Embedding:**
| Provider | Model | Notes |
|----------|-------|-------|
| Jina AI | `jina-embeddings-v3` | Recommended, task-aware |
| OpenAI | `text-embedding-3-small` | Widely available |
| Ollama | `nomic-embed-text` | Free, local |

**Reranking:**
| Provider | Model | Notes |
|----------|-------|-------|
| Jina AI | `jina-reranker-v3` | High quality |
| SiliconFlow | `Qwen/Qwen3-Reranker-0.6B` | Free tier available |
| Voyage AI | `rerank-2` | Alternative |

**LLM (for smart extraction):**

Any OpenAI-compatible API — OpenAI, Anthropic, z.ai, MiniMax, Ollama, etc.

---

## Memory Scopes

| Scope | Purpose |
|-------|---------|
| `agent:primary` | Private to your primary agent |
| `agent:secondary` | Private to a secondary agent |
| `global` | Shared across all agents |
| `project:<name>` | Project-specific context |

---

## How Auto-Capture Works

The `Stop` hook runs after every Claude response:

1. Reads `last_assistant_message` from hook stdin
2. Filters through `shouldCapture()` (length, noise, CJK-aware)
3. Auto-categorizes via `detectCategory()`
4. Embeds via Jina API
5. Stores in LanceDB with scope and metadata

**This happens automatically** — no manual tool calls needed.

## Retrieval Pipeline

```
Query --> Embed --> Vector Search --+
                                    +--> RRF Fusion --> Rerank --> Recency
Query --> BM25 Full-Text Search ---+     --> Importance --> LengthNorm
                                         --> TimeDecay --> HardMin --> MMR
                                         --> Final Results
```

---

## Based On

Built on [memory-lancedb-pro](https://github.

... (truncated)

tools