{"id":47613342,"url":"https://github.com/cablate/memory-lancedb-mcp","last_synced_at":"2026-04-08T03:02:09.058Z","repository":{"id":345229427,"uuid":"1184973714","full_name":"cablate/memory-lancedb-mcp","owner":"cablate","description":"MCP server for LanceDB-backed long-term memory with hybrid retrieval (Vector + BM25), cross-encoder rerank, multi-scope isolation, and memory lifecycle management","archived":false,"fork":false,"pushed_at":"2026-03-27T02:50:24.000Z","size":1143,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-02T04:15:42.808Z","etag":null,"topics":["ai-memory","hybrid-retrieval","lancedb","long-term-memory","mcp-server","model-context-protocol","semantic-search","typescript","vector-database"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cablate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-v1.1.0.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T05:34:37.000Z","updated_at":"2026-03-27T02:50:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cablate/memory-lancedb-mcp","commit_stats":null,"previous_names":["cablate/memory-lancedb-mcp"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/cablate/memory-lancedb-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmemory-lancedb-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmemory-lancedb-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmemory-lancedb-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmemory-lancedb-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cablate","download_url":"https://codeload.github.com/cablate/memory-lancedb-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cablate%2Fmemory-lancedb-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31537791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","hybrid-retrieval","lancedb","long-term-memory","mcp-server","model-context-protocol","semantic-search","typescript","vector-database"],"created_at":"2026-04-01T20:51:20.741Z","updated_at":"2026-04-08T03:02:09.052Z","avatar_url":"https://github.com/cablate.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/banner.png\" alt=\"memory-lancedb-mcp\" width=\"100%\" /\u003e\n\n**Persistent, intelligent long-term memory for any MCP-compatible AI agent.**\n\n[![npm version](https://img.shields.io/npm/v/@cablate/memory-lancedb-mcp)](https://www.npmjs.com/package/@cablate/memory-lancedb-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@cablate/memory-lancedb-mcp)](https://www.npmjs.com/package/@cablate/memory-lancedb-mcp)\n[![LanceDB](https://img.shields.io/badge/LanceDB-Vectorstore-orange)](https://lancedb.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n**English** | [繁體中文](README_ZH.md)\n\n\u003c/div\u003e\n\n---\n\n## Before / After\n\nWithout memory, every session starts from zero. With memory-lancedb-mcp, your agent accumulates knowledge across sessions — automatically.\n\n**Before** — agent has no context:\n```\nUser: \"Use the same animation style as last time\"\nAgent: \"I don't have any context about previous animations. Could you describe what you'd like?\"\n```\n\n**After** — agent recalls past decisions:\n```xml\n\u003cmemories\u003e\n1. Remotion spring animation: use duration \u003e= 20, damping 12-15 for smooth easing\n2. Video export preset: 1080p, 30fps for social, 60fps for demo\n\u003c/memories\u003e\n\u003crefs\u003e#1=6352a7d2 #2=bed148f0\u003c/refs\u003e\n```\n\nStore responses are minimal — no noise, just confirmation:\n```\nStored. [topic: remotion]\n```\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @cablate/memory-lancedb-mcp\n```\n\n### 2. Configure\n\nAdd to your MCP client settings (e.g. Claude Desktop `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cablate/memory-lancedb-mcp\"],\n      \"env\": {\n        \"EMBEDDING_API_KEY\": \"your-api-key\",\n        \"EMBEDDING_MODEL\": \"text-embedding-3-small\"\n      }\n    }\n  }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAdvanced: use a config file for full control\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cablate/memory-lancedb-mcp\"],\n      \"env\": {\n        \"MEMORY_LANCEDB_CONFIG\": \"/path/to/config.json\"\n      }\n    }\n  }\n}\n```\n\nSee [config.example.json](config.example.json) for all options.\n\n\u003c/details\u003e\n\n---\n\n## How It Works\n\n```\n          store                          recall\n            │                              │\n   ┌────────▼────────┐           ┌────────▼────────┐\n   │  Filter junk     │           │ Search by meaning │\n   │  Save + embed    │           │   AND keywords    │\n   │  Link related    │           │ Re-rank results   │\n   │  Flag conflicts  │           │ Fade stale ones   │\n   │  Tag topic       │           │ Pull in related   │\n   └────────┬────────┘           │ Merge duplicates  │\n            │                    └────────┬────────┘\n            ▼                             ▼\n   ┌─────────────────────────────────────────────┐\n   │          LanceDB (local, zero-config)        │\n   └─────────────────────────────────────────────┘\n```\n\nEvery `memory_store` saves to a local database, automatically links related memories, flags contradictions, and assigns topic labels — no extra API calls needed. Every `memory_recall` searches by both meaning and keywords, pulls in related memories the main search might miss, and includes maintenance hints so the agent can keep its own knowledge base clean.\n\n---\n\n## Features\n\n### Retrieval\n\n- **Finds the right memory even when you use different words** — searches by meaning and exact keywords simultaneously, then combines the best of both\n- **More precise results, not just surface matches** — an optional second pass re-ranks results by actual relevance (6 providers supported)\n- **Search multiple topics at once** — pass a `queries` array to search several keywords in one call; results are deduplicated and memories that match multiple queries rank higher\n- **Finding A automatically surfaces related B** — when a memory is found, its linked neighbors are pulled in too, even if they use completely different words\n- **Minimal token overhead** — responses use compact XML tags (`\u003cmemories\u003e`, `\u003chints\u003e`, `\u003crefs\u003e`) with short IDs, no category/scope noise\n\n### Storage\n\n- **Related memories link themselves** — when you store something new, it automatically creates bidirectional links to similar existing memories\n- **Conflicts get flagged** — if a new memory contradicts an existing one, you get a warning so nothing silently overwrites\n- **Topics assigned automatically** — each memory gets a topic label inferred from its content and neighbors; you can also set it explicitly\n- **Junk gets filtered out** — greetings, refusals, and meta-questions are rejected before they waste storage\n\n### Lifecycle\n\n- **Frequently used memories stay sharp, stale ones fade** — a decay model balances how recent, how often accessed, and how important each memory is\n- **Memories earn their keep** — three tiers (Peripheral → Working → Core); the more a memory gets used, the faster it promotes\n- **Full version history** — when you update a memory, the old version is preserved in a chain you can trace with `memory_history`\n\n### Maintenance\n\n- **The agent maintains itself** — recall results include inline hints about duplicates, dormant memories, and contradictions\n- **Health checks on demand** — `memory_lint` finds orphaned memories, stale entries, and missing links, then fixes what it can\n- **Merge duplicates** — `memory_merge` combines two redundant memories into one; originals are marked as superseded\n- **See your memory space** — `memory_visualize` generates an interactive HTML graph you can open in any browser\n\n---\n\n## Visualization\n\nRun `memory_visualize` to generate an interactive knowledge graph of your memory space:\n\n- Automatic clustering — related memories group together visually\n- Similarity edges, duplicate detection, importance sizing\n- Time filter, growth animation, cluster view\n- Self-contained HTML — open in any browser\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eScoring Pipeline (technical details)\u003c/strong\u003e\u003c/summary\u003e\n\n```\nQuery → embedQuery() ─┐\n                       ├─→ RRF Fusion → Rerank → Lifecycle Decay → Length Norm → Filter\nQuery → BM25 FTS ─────┘\n```\n\n| Stage | Effect |\n|-------|--------|\n| **RRF Fusion** | Combines semantic and exact-match recall |\n| **Cross-Encoder Rerank** | Promotes semantically precise hits |\n| **Lifecycle Decay** | Weibull freshness + access frequency + importance |\n| **Length Normalization** | Prevents long entries from dominating (anchor: 500 chars) |\n| **Hard Min Score** | Removes irrelevant results (default: 0.35) |\n| **MMR Diversity** | Cosine similarity \u003e 0.85 → demoted |\n\n\u003c/details\u003e\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `EMBEDDING_API_KEY` | Yes | API key for embedding provider |\n| `EMBEDDING_MODEL` | No | Model name (default: `text-embedding-3-small`) |\n| `EMBEDDING_BASE_URL` | No | Custom base URL for non-OpenAI providers |\n| `MEMORY_DB_PATH` | No | LanceDB storage directory |\n| `MEMORY_LANCEDB_CONFIG` | No | Path to JSON config file |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull configuration example\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"embedding\": {\n    \"apiKey\": \"${EMBEDDING_API_KEY}\",\n    \"model\": \"jina-embeddings-v5-text-small\",\n    \"baseURL\": \"https://api.jina.ai/v1\",\n    \"dimensions\": 1024,\n    \"taskQuery\": \"retrieval.query\",\n    \"taskPassage\": \"retrieval.passage\",\n    \"normalized\": true\n  },\n  \"dbPath\": \"./memory-data\",\n  \"retrieval\": {\n    \"mode\": \"hybrid\",\n    \"vectorWeight\": 0.7,\n    \"bm25Weight\": 0.3,\n    \"minScore\": 0.3,\n    \"rerank\": \"cross-encoder\",\n    \"rerankApiKey\": \"${JINA_API_KEY}\",\n    \"rerankModel\": \"jina-reranker-v3\",\n    \"rerankEndpoint\": \"https://api.jina.ai/v1/rerank\",\n    \"rerankProvider\": \"jina\",\n    \"candidatePoolSize\": 20,\n    \"hardMinScore\": 0.35,\n    \"filterNoise\": true\n  },\n  \"enableManagementTools\": true,\n  \"enableSelfImprovementTools\": false,\n  \"enableVisualizationTools\": true,\n  \"scopes\": {\n    \"default\": \"global\",\n    \"definitions\": {\n      \"global\": { \"description\": \"Shared knowledge\" },\n      \"agent:my-bot\": { \"description\": \"Private to my-bot\" }\n    },\n    \"agentAccess\": {\n      \"my-bot\": [\"global\", \"agent:my-bot\"]\n    }\n  },\n  \"decay\": {\n    \"recencyHalfLifeDays\": 30,\n    \"frequencyWeight\": 0.3,\n    \"intrinsicWeight\": 0.3\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEmbedding providers\u003c/strong\u003e\u003c/summary\u003e\n\nWorks with **any OpenAI-compatible embedding API**:\n\n| Provider | Model | Base URL | Dimensions |\n|----------|-------|----------|------------|\n| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 |\n| **Jina** | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 |\n| **DeepInfra** | `Qwen/Qwen3-Embedding-8B` | `https://api.deepinfra.com/v1/openai` | 1024 |\n| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 |\n| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | _varies_ |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRerank providers\u003c/strong\u003e\u003c/summary\u003e\n\n| Provider | `rerankProvider` | Endpoint | Example Model |\n|----------|-----------------|----------|---------------|\n| **Jina** | `jina` | `https://api.jina.ai/v1/rerank` | `jina-reranker-v3` |\n| **Hugging Face TEI** | `tei` | `http://host:8081/rerank` | `BAAI/bge-reranker-v2-m3` |\n| **SiliconFlow** | `siliconflow` | `https://api.siliconflow.com/v1/rerank` | `BAAI/bge-reranker-v2-m3` |\n| **Voyage AI** | `voyage` | `https://api.voyageai.com/v1/rerank` | `rerank-2.5` |\n| **Pinecone** | `pinecone` | `https://api.pinecone.io/rerank` | `bge-reranker-v2-m3` |\n| **DashScope** | `dashscope` | `https://dashscope.aliyuncs.com/api/v1/services/rerank` | `gte-rerank` |\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTools Reference\u003c/strong\u003e\u003c/summary\u003e\n\n### Core Tools\n\n| Tool | Description |\n|------|-------------|\n| `memory_recall` | Search memories — supports batch queries, relation expansion, topic filtering, and inline maintenance hints |\n| `memory_store` | Save a memory — auto-links related ones, flags contradictions, infers topic, filters junk |\n| `memory_forget` | Delete by ID or search query |\n| `memory_update` | Update a memory; the old version is preserved in a version chain |\n| `memory_merge` | Merge two memories into one |\n| `memory_history` | Trace version history through update/merge chains |\n\n### Management Tools (opt-in)\n\n| Tool | Description |\n|------|-------------|\n| `memory_stats` | Usage statistics by scope and category |\n| `memory_list` | List recent memories with filtering |\n| `memory_lint` | Health checks + auto-fix missing relations |\n\nEnable: `\"enableManagementTools\": true`\n\n### Self-Improvement Tools (opt-in)\n\n| Tool | Description |\n|------|-------------|\n| `self_improvement_log` | Log structured learning/error entries |\n| `self_improvement_extract_skill` | Create skill scaffolds from learnings |\n| `self_improvement_review` | Summarize governance backlog |\n\nEnable: `\"enableSelfImprovementTools\": true`\n\n### Visualization Tools (on by default)\n\n| Tool | Description |\n|------|-------------|\n| `memory_visualize` | Generate interactive HTML memory graph |\n\nParams: `output_path`, `scope`, `threshold` (default: 0.65), `max_neighbors` (default: 4)\n\nDisable: `\"enableVisualizationTools\": false`\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDatabase Schema\u003c/strong\u003e\u003c/summary\u003e\n\nLanceDB table `memories`:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string (UUID) | Primary key |\n| `text` | string | Memory text (FTS indexed) |\n| `vector` | float[] | Embedding vector |\n| `category` | string | `preference` / `fact` / `decision` / `entity` / `skill` / `lesson` / `other` |\n| `scope` | string | Scope identifier |\n| `importance` | float | Importance score 0-1 |\n| `timestamp` | int64 | Creation timestamp (ms) |\n| `metadata` | string (JSON) | Extended metadata (tier, access_count, relations, topic, etc.) |\n\n\u003c/details\u003e\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/cablate/memory-lancedb-mcp.git\ncd memory-lancedb-mcp\nnpm install\nnpm test\n```\n\nRun locally:\n\n```bash\nEMBEDDING_API_KEY=your-key npx tsx server.ts\n```\n\n---\n\n## Credits\n\nBuilt on [CortexReach/memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) — original work by [win4r](https://github.com/win4r) and contributors.\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcablate%2Fmemory-lancedb-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcablate%2Fmemory-lancedb-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcablate%2Fmemory-lancedb-mcp/lists"}