rag-memory-epf-mcp

rag-memory-epf-mcp

A project-local RAG memory MCP server — knowledge graph + multilingual vector search + FTS5 full-text search, all in a single SQLite file per project.

Key Features

• Project-local isolation — each project gets its own .memory/rag-memory.db. Multiple projects run simultaneously without interference.
• 3-signal hybrid search — vector similarity (bge-m3, 1024-dim) + FTS5 BM25 keyword matching + knowledge graph re-ranking, combined via Reciprocal Rank Fusion
• 100+ languages — Korean, Chinese, Japanese, Arabic, and more. Cross-lingual search works out of the box.
• Graph-aware scoring — per-entity geometric decay (0.5^i) with hard cap prevents any single document from dominating results
• 31 MCP tools — knowledge graph CRUD, document pipeline, hybrid search, multi-hop traversal, graph analytics (centrality / community detection / structure), export/import, temporal queries
• Codepoint-safe chunking — chunk offsets are Unicode codepoints, language-neutral across SQL substr, Python slicing, and JS [...str] iteration. Korean/CJK/emoji documents stay aligned. Verified by a publish-time invariant test.
• SQLite optimized — WAL mode, 32MB cache, 256MB mmap, FTS5 triggers, 7 indexes
• MCP SDK 1.27.1 — Tool Annotations (readOnly/destructive/idempotent), latest protocol 2025-11-25

Quick Start

{
  "mcpServers": {
    "rag-memory": {
      "command": "npx",
      "args": ["-y", "rag-memory-epf-mcp@latest"],
      "env": {
        "DB_FILE_PATH": "/path/to/your-project/.memory/rag-memory.db"
      }
    }
  }
}

Place this .mcp.json in each project folder with its own DB_FILE_PATH. Each project maintains completely isolated memory.

Tools (31)

Knowledge Graph (7)

Tool	Description	Annotation
createEntities	Create entities with observations and types (upsert)	idempotent
createRelations	Establish relationships between entities	idempotent
addObservations	Add contextual information to entities (dedup)	idempotent
updateRelations	Update relationship confidence and metadata	idempotent
deleteEntities	Remove entities and relationships	destructive
deleteRelations	Remove specific relationships	destructive
deleteObservations	Remove specific observations	destructive

Document Pipeline (9)

Tool	Description	Annotation
storeDocument	Store documents with metadata	idempotent
chunkDocument	Create text chunks with configurable parameters	—
embedChunks	Generate 1024-dim embeddings + auto-link entities	idempotent
embedAllEntities	Batch embed all entities (32 parallel)	idempotent
extractTerms	Extract potential entity terms	—
linkEntitiesToDocument	Link entities to chunks where they actually appear (text-matched)	idempotent
deleteDocuments	Remove documents and associated data	destructive
listDocuments	View all stored documents	readOnly
syncDocumentFromFile	One-call server-side sync: reads file + delete/store/chunk/embed/link, content stays off model context. Atomic (embed-first transaction swap) + content_hash dedup (skips unchanged files)	idempotent

Search & Retrieval (9)

Tool	Description	Annotation
hybridSearch	Vector + FTS5 BM25 + graph traversal (3-signal). Degrades to FTS5-only (search_mode) when the embedding model is down	readOnly
searchNodes	Semantic entity search with since/until temporal filtering	readOnly
openNodes	Retrieve specific entities by name	readOnly
readGraph	Get complete knowledge graph	readOnly
getNeighbors	Multi-hop graph traversal (depth 1-5, cycle detection)	readOnly
getDetailedContext	Get full context for a chunk	readOnly
exportGraph	Export full graph as JSON (backup)	readOnly
importGraph	Import graph from JSON (merge or replace)	destructive
getKnowledgeGraphStats	Knowledge base statistics	readOnly

Migration (3)

Tool	Description	Annotation
getMigrationStatus	Check database schema version	readOnly
runMigrations	Apply pending migrations	idempotent
rollbackMigration	Revert to a previous schema version	destructive

Graph Analytics (3)

Tool	Description	Annotation
getGraphMetrics	Per-entity centrality (degree, betweenness, closeness, pagerank)	readOnly
detectCommunities	Louvain community detection + modularity score	readOnly
analyzeGraphStructure	Density, connected components, clustering coefficient	readOnly

Document Processing Pipeline

storeDocument(id, content, metadata)
  → chunkDocument(documentId, maxTokens, overlap)
    → embedChunks(documentId)
       ├── generates vector embeddings for each chunk
       ├── auto-links entities to chunks (word boundary + CJK aware)
       └── returns { embeddedChunks, linkedEntities }

Architecture

┌─────────────────────────────────────────────┐
│  MCP Client (Claude Code, Gemini CLI, etc)  │
└──────────────────┬──────────────────────────┘
                   │ stdio (MCP SDK 1.27.1)
┌──────────────────▼──────────────────────────┐
│  rag-memory-epf-mcp                         │
│  ┌────────────┐ ┌─────────────┐ ┌────────┐  │
│  │ Knowledge  │ │ RAG Document│ │ Search │  │
│  │ Graph CRUD │ │ Pipeline    │ │ Engine │  │
│  └─────┬──────┘ └──────┬──────┘ └───┬────┘  │
│        │               │            │        │
│  ┌─────▼───────────────▼────────────▼─────┐  │
│  │  SQLite (WAL mode, per-project file)   │  │
│  │  ├── entities + relationships          │  │
│  │  ├── documents + chunk_metadata        │  │
│  │  ├── chunks (sqlite-vec, 1024-dim)     │  │
│  │  ├── entity_embeddings (sqlite-vec)    │  │
│  │  ├── entities_fts + chunks_fts (FTS5)  │  │
│  │  └── 11 migrations (auto-applied)      │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  bge-m3 (ONNX, 100+ langs)                   │
└──────────────────────────────────────────────┘

Environment Variables

Variable	Default	Description
DB_FILE_PATH	rag-memory.db (server dir)	Path to project-local SQLite database
EMBEDDING_MODEL	Xenova/bge-m3	HuggingFace model ID for embeddings
RAG_MEMORY_EMBEDDINGS	lazy	Boot mode: lazy (connect instantly, model loads in background), eager (wait for model + reconciliation, pre-3.6 behavior), off (never load the model — FTS5-only, zero download)
RAG_MEMORY_MODEL_CACHE_DIR	OS user cache	Version-independent model cache location (see docs/UPDATING.md)
RAG_MEMORY_TRUST_LEGACY_VECTORS	unset	Set 1 to grandfather pre-existing vectors under a custom EMBEDDING_MODEL (default model configs grandfather automatically)

Changelog

v3.6.0

• Lite install / lazy boot: the MCP server connects immediately — FTS5 search, knowledge graph and CRUD work from the first second, while the bge-m3 model (~1.2GB) loads or downloads in the background. Hybrid search switches on automatically. Requires Node >= 24.
• Version-independent model cache with a cross-process download lock: engine version bumps no longer re-download the model, and concurrent servers on one machine never corrupt a download. Cleaning the npx cache no longer deletes the model.
• Embedding provenance + automatic backfill: every vector records its input hash and model profile; anything missing or stale (including rows written while the model was unavailable) is re-embedded automatically with a per-target retry cap. Fixes a long-standing defect where deleteObservations left stale entity vectors behind.
• Search state transparency: responses report search_mode (hybrid / hybrid-partial / fts-only), model state, provenance coverage and a degradation_reason; searchNodes gains a lexical FTS fallback so entities never disappear from search while embeddings catch up. getKnowledgeGraphStats gains a server block (version, node, states, coverage) for update-reliability checks.
• BREAKING: (1) hybridSearch now returns an envelope {results, search_mode, model_state, coverage, degradation_reason?} instead of a bare array (per-item search_mode removed). (2) deleteObservations returns {results: [{entityName, deleted, embedding_status}], total_deleted} instead of a success string. Error responses now set isError: true. Migration/rollback and fleet-rollout guidance: docs/UPDATING.md.

v3.5.0

• Atomic syncDocumentFromFile: embeddings are computed before any DB write, then applied in a single synchronous transaction, so a failed embedding (e.g. model still loading) leaves the existing document fully intact instead of a half-deleted or partially-embedded state.
• content_hash dedup: unchanged files short-circuit the delete/chunk/embed pipeline (skipped: true), with a completeness gate that still re-processes a partially-embedded document.
• FTS5-only graceful degradation: when the embedding model is unavailable, hybridSearch returns BM25 (full-text) results tagged search_mode: 'fts-only' instead of failing the whole query.

v3.4.0

• syncDocumentFromFile: one-call server-side document sync - reads a file on the server and runs the full pipeline (deleteDocuments → storeDocument → chunkDocument → embedChunks → linkEntitiesToDocument) in a single call, returning only a terse summary { documentId, bytes, chunks, embeddedChunks, linkedEntities, warning? }. File content is read server-side and never routed through the model context, collapsing the usual 5 tool calls per document into one and keeping conversation context flat (the dominant cost of large sync runs). 30 → 31 tools.

v3.3.6

• Publish-time invariant test — npm run verify:invariants (wired as prepublishOnly) catches chunkText offset regressions before they ship. Tests ASCII / Korean / emoji-heavy / mixed CJK + supplementary plane / pure supplementary inputs against the codepoint-slice contract.
• chunkText extracted to src/chunkText.ts — algorithm now testable in isolation. The class method is a thin wrapper. No user-facing API change.
• README accuracy — tool count corrected to 30, migration count to 11, Graph Analytics tools surfaced.

v3.3.5

• Fix: chunk offsets stored as JS UTF-16 units instead of Unicode codepoints — Korean/CJK/emoji documents had start_pos/end_pos that disagreed with SQL substr and Python slicing for any chunk crossing a supplementary character. chunkText now maintains parallel UTF-16 + codepoint cursors and reports codepoint offsets.
• Migration v11 — converts existing chunk_metadata.start_pos/end_pos from UTF-16 units to codepoints by re-locating each chunk via indexOf and counting codepoints.

v3.3.4

• Migration version 9 → 10 jump + ALTER TABLE idempotency guards — some databases from early v3.x experiments (Ollama dimension swap) had recorded a migration at version 9, causing the new v9 migration to silently no-op. Bumped to version 10 and added PRAGMA table_info guards so the column-add is safe to re-run.

v3.3.3

• Separate token-space and char-space offsets in chunk_metadata — added start_token/end_token columns. Existing start_pos/end_pos are reinterpreted as character offsets into documents.content. Backfill migration recomputes char offsets via indexOf with a per-document cursor; misses leave NULL so callers can re-chunk to repair.

v3.3.0

• Graph analytics (graphology) — three new MCP tools: getGraphMetrics (degree / betweenness / closeness / pagerank), detectCommunities (Louvain + modularity), analyzeGraphStructure (density / components / clustering). 27 → 30 tools.

v3.2.1

• Fix: autoLinkEntities silent failure — was JOINing a non-existent observations table (observations are stored as JSON array column in entities). Changed to direct column select + JSON.parse().

v3.2.0

• Chunk-level entity linking in linkEntitiesToDocument — entities are now linked only to chunks where they actually appear (using buildEntityMatcher word-boundary/CJK matching), instead of blanket-linking to all chunks. Fixes search result domination by heavily-linked documents.
• Graph boost decay + hard cap — per-entity scores are sorted descending and decayed geometrically (0.5^i): 1st entity 100%, 2nd 50%, 3rd 25%, etc. Hard cap at 0.4 prevents graph signal from overwhelming vector similarity.

v3.0.0

• Back to self-contained embeddings — reverted from Ollama dependency (v2.x) to built-in @huggingface/transformers with bge-m3 (1024-dim). No external services required.
• Cross-lingual search — auto-detects non-English queries and performs dual-language search
• External dictionary — optional .memory/dictionary.json for custom translation pairs
• Modular tool system — tools extracted into src/tools/ with structured registry
• Migration system — extracted into src/migrations/ with versioned schema upgrades
• Dynamic version reporting — MCP server version now reads from package.json
• MIT LICENSE file — included in published package

v1.9.0

• Multi-hop graph traversal — getNeighbors tool with WITH RECURSIVE CTE, depth 1-5, cycle detection, bidirectional
• Embedding LRU cache — 500-entry in-memory cache, skips redundant re-computation
• Configurable model — EMBEDDING_MODEL env var to use alternative embedding models
• 27 tools total at this version (30 as of v3.3.0+)

v1.8.0

• MCP SDK 1.27.1 — protocol 2025-11-25, security fix GHSA-345p-7cg4-v4c7 (CVSS 7.1)
• Tool Annotations — all tools annotated (readOnlyHint, destructiveHint, idempotentHint)
• SIGTERM graceful shutdown — clean exit without ONNX mutex crash

v1.7.0

• SQLite optimization — WAL mode, 32MB cache, 256MB mmap, busy_timeout
• FTS5 full-text search — BM25 keyword matching + Reciprocal Rank Fusion with vector search
• updateRelations — update confidence scores and metadata without delete+recreate
• exportGraph / importGraph — JSON backup and restore (merge or replace)
• Batch embedding — embedAllEntities processes 32 entities in parallel
• Temporal filtering — searchNodes with since/until ISO 8601 date filters
• better-sqlite3 12.x — SQLite 3.51.3 with query planner improvements
• sqlite-vec 0.1.7 — DELETE space reclaim, KNN distance constraints
• DB indexes — entityType, relationType, chunk lookups
• SQL safety — safeRowid() validation for vec0 operations

v1.6.0

• Entity upsert — merges new observations into existing entities instead of ignoring duplicates
• Observation timestamps — auto [YYYY-MM-DD] prefix for staleness tracking
• Dedup by content — date-stripped comparison prevents duplicate observations

v1.5.0

• Chunk-level entity linking — precision linking to specific chunks, not all chunks
• Word boundary + CJK matching — Latin word boundaries, CJK substring matching
• Observation-derived aliases — file paths from observations matched against chunks

v1.4.x

• Switched to bge-m3 (1024-dim, 100+ languages)
• fp16 quantization, instruction prefix optimization

Development

git clone https://github.com/bripin123/rag-memory-epf-mcp.git
cd rag-memory-epf-mcp
npm install
npm run build
npm test                  # build + invariant verification
npm run verify:invariants # standalone invariant test (assumes dist/ built)

npm publish automatically runs prepublishOnly (build + verify:invariants); a chunk-offset regression blocks the publish at the source.

License

MIT License. See LICENSE.

Third-Party Model Licenses

Component	License	Details
bge-m3	MIT	Model card
@huggingface/transformers	Apache 2.0	JS inference runtime

Model weights are downloaded at runtime and not bundled in this package.

---

Built with: TypeScript, SQLite (WAL + FTS5 + sqlite-vec), bge-m3, MCP SDK 1.27.1