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

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

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