🧠 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).

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

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:

{
  "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:

{
  "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 by CortexReach — an enhanced LanceDB memory plugin for OpenClaw. All 29 source modules are included and loaded at runtime via jiti.

What this project adds:

• Standalone MCP server (no OpenClaw dependency)
• Claude Code hooks for true automation
• 14 MCP tools (vs 9 in original)
• Portable to any MCP-compatible AI client

License

MIT

Based on memory-lancedb-pro (MIT License, Copyright (c) 2026 win4r).