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
• 30 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 (30)

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 (8)

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

Search & Retrieval (9)

Tool	Description	Annotation
hybridSearch	Vector + FTS5 BM25 + graph traversal (3-signal)	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

Changelog

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