rag-memory-epf-mcp 3.3.6 → 3.5.0

package/README.md

@@ -13,7 +13,7 @@ A **project-local RAG memory** MCP server — knowledge graph + multilingual vec
 - **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
+- **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
@@ -36,7 +36,7 @@ A **project-local RAG memory** MCP server — knowledge graph + multilingual vec
 
 Place this `.mcp.json` in each project folder with its own `DB_FILE_PATH`. Each project maintains completely isolated memory.
 
-## Tools (30)
+## Tools (31)
 
 ### Knowledge Graph (7)
 | Tool | Description | Annotation |
@@ -49,7 +49,7 @@ Place this `.mcp.json` in each project folder with its own `DB_FILE_PATH`. Each
 | `deleteRelations` | Remove specific relationships | destructive |
 | `deleteObservations` | Remove specific observations | destructive |
 
-### Document Pipeline (8)
+### Document Pipeline (9)
 | Tool | Description | Annotation |
 |------|------------|------------|
 | `storeDocument` | Store documents with metadata | idempotent |
@@ -60,11 +60,12 @@ Place this `.mcp.json` in each project folder with its own `DB_FILE_PATH`. Each
 | `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) | readOnly |
+| `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 |
@@ -136,6 +137,14 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### 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.

package/dist/index.d.ts

@@ -1,2 +1,295 @@
 #!/usr/bin/env node
+interface Entity {
+    name: string;
+    entityType: string;
+    observations: string[];
+}
+interface Relation {
+    from: string;
+    to: string;
+    relationType: string;
+}
+interface KnowledgeGraph {
+    entities: Entity[];
+    relations: Relation[];
+}
+interface EnhancedSearchResult {
+    relevance_score: number;
+    key_highlight: string;
+    content_summary: string;
+    chunk_id: string;
+    document_title: string;
+    entities: string[];
+    vector_similarity: number;
+    graph_boost?: number;
+    fts_boost?: number;
+    full_context_available: boolean;
+    chunk_type: 'document' | 'entity' | 'relationship';
+    source_id?: string;
+    search_mode?: 'hybrid' | 'fts-only';
+}
+interface DetailedContext {
+    chunk_id: string;
+    document_id: string;
+    full_text: string;
+    document_title: string;
+    surrounding_chunks?: Array<{
+        chunk_id: string;
+        text: string;
+        position: 'before' | 'after';
+    }>;
+    entities: string[];
+    metadata: Record<string, any>;
+}
+export declare class RAGKnowledgeGraphManager {
+    private db;
+    private encoding;
+    private embeddingModel;
+    private modelInitialized;
+    private embeddingCache;
+    private readonly EMBEDDING_CACHE_MAX;
+    private dictionaryCache;
+    initialize(opts?: {
+        skipModel?: boolean;
+    }): Promise<void>;
+    private initializeEmbeddingModel;
+    runMigrations(): Promise<{
+        applied: number;
+        currentVersion: number;
+        appliedMigrations: Array<{
+            version: number;
+            description: string;
+        }>;
+    }>;
+    cleanup(): void;
+    private _timestampObservation;
+    createEntities(entities: Entity[]): Promise<Entity[]>;
+    createRelations(relations: Relation[]): Promise<Relation[]>;
+    addObservations(observations: {
+        entityName: string;
+        contents: string[];
+    }[]): Promise<{
+        entityName: string;
+        addedObservations: string[];
+    }[]>;
+    deleteEntities(entityNames: string[]): Promise<void>;
+    deleteObservations(deletions: {
+        entityName: string;
+        observations: string[];
+    }[]): Promise<void>;
+    deleteRelations(relations: Relation[]): Promise<void>;
+    updateRelations(updates: {
+        from: string;
+        to: string;
+        relationType: string;
+        confidence?: number;
+        metadata?: Record<string, any>;
+    }[]): Promise<{
+        updated: number;
+        notFound: number;
+    }>;
+    readGraph(): Promise<KnowledgeGraph>;
+    getNeighbors(entityNames: string[], depth?: number, relationType?: string): Promise<{
+        entities: Array<{
+            name: string;
+            entityType: string;
+            observations: string[];
+            depth: number;
+        }>;
+        relations: Array<{
+            from: string;
+            to: string;
+            relationType: string;
+            depth: number;
+        }>;
+        paths: Array<{
+            from: string;
+            to: string;
+            path: string[];
+        }>;
+    }>;
+    searchNodes(query: string, limit?: number, since?: string, until?: string): Promise<KnowledgeGraph>;
+    openNodes(names: string[]): Promise<KnowledgeGraph>;
+    private generateEntityEmbeddingText;
+    private splitIntoSentences;
+    private calculateSentenceSimilarities;
+    private cosineSimilarity;
+    private enhanceSimilarityWithContext;
+    private generateContentSummary;
+    private embedEntity;
+    embedAllEntities(): Promise<{
+        totalEntities: number;
+        embeddedEntities: number;
+    }>;
+    generateKnowledgeGraphChunks(): Promise<{
+        entityChunks: number;
+        relationshipChunks: number;
+    }>;
+    embedKnowledgeGraphChunks(): Promise<{
+        embeddedChunks: number;
+        totalChunks: number;
+        errors?: string[];
+    }>;
+    private generateEntityChunkText;
+    private generateRelationshipChunkText;
+    private cleanupKnowledgeGraphChunks;
+    private loadDictionary;
+    private hasKorean;
+    private isLikelyEnglish;
+    private normalizeQueryText;
+    private buildCrossLingualDictionary;
+    private translateQueryWithMap;
+    private buildCrossLingualVariants;
+    private extractTermsFromText;
+    private chunkText;
+    private generateEmbedding;
+    syncDocumentFromFile(filePath: string, documentId: string, options?: {
+        metadata?: Record<string, any>;
+        content?: string;
+        entityNames?: string[];
+        chunkParams?: {
+            maxTokens?: number;
+            overlap?: number;
+        };
+    }): Promise<{
+        documentId: string;
+        bytes: number;
+        chunks: number;
+        embeddedChunks: number;
+        linkedEntities: number;
+        explicitlyLinked?: number;
+        warning?: string;
+        skipped?: boolean;
+        reason?: string;
+    }>;
+    storeDocument(id: string, content: string, metadata?: Record<string, any>): Promise<{
+        id: string;
+        stored: boolean;
+    }>;
+    chunkDocument(documentId: string, options?: {
+        maxTokens?: number;
+        overlap?: number;
+    }): Promise<{
+        documentId: string;
+        chunks: Array<{
+            id: string;
+            text: string;
+            startPos: number | null;
+            endPos: number | null;
+            startToken: number | null;
+            endToken: number | null;
+        }>;
+    }>;
+    embedChunks(documentId: string): Promise<{
+        documentId: string;
+        embeddedChunks: number;
+        totalChunks: number;
+        linkedEntities?: number;
+        errors?: string[];
+    }>;
+    private hasCJK;
+    private buildEntityMatcher;
+    private autoLinkEntities;
+    extractTerms(documentId: string, options?: {
+        minLength?: number;
+        includeCapitalized?: boolean;
+        customPatterns?: string[];
+    }): Promise<{
+        documentId: string;
+        terms: string[];
+    }>;
+    linkEntitiesToDocument(documentId: string, entityNames: string[]): Promise<{
+        documentId: string;
+        linkedEntities: number;
+    }>;
+    private cleanupDocument;
+    deleteDocument(documentId: string): Promise<{
+        documentId: string;
+        deleted: boolean;
+    }>;
+    deleteMultipleDocuments(documentIds: string[]): Promise<{
+        results: Array<{
+            documentId: string;
+            deleted: boolean;
+        }>;
+        summary: {
+            deleted: number;
+            failed: number;
+            total: number;
+        };
+    }>;
+    deleteDocuments(documentIds: string | string[]): Promise<{
+        results: Array<{
+            documentId: string;
+            deleted: boolean;
+        }>;
+        summary: {
+            deleted: number;
+            failed: number;
+            total: number;
+        };
+    }>;
+    listDocuments(includeMetadata?: boolean): Promise<{
+        documents: Array<{
+            id: string;
+            metadata?: any;
+            created_at: string;
+        }>;
+    }>;
+    exportGraph(): Promise<{
+        entities: any[];
+        relations: any[];
+        documents: any[];
+        metadata: {
+            exportedAt: string;
+            version: string;
+            entityCount: number;
+            relationCount: number;
+            documentCount: number;
+        };
+    }>;
+    importGraph(data: {
+        entities?: any[];
+        relations?: any[];
+        documents?: any[];
+    }, options?: {
+        merge?: boolean;
+    }): Promise<{
+        imported: {
+            entities: number;
+            relations: number;
+            documents: number;
+        };
+        skipped: {
+            entities: number;
+            relations: number;
+            documents: number;
+        };
+    }>;
+    hybridSearch(query: string, limit?: number, useGraph?: boolean): Promise<EnhancedSearchResult[]>;
+    getDetailedContext(chunkId: string, includeSurrounding?: boolean): Promise<DetailedContext>;
+    getKnowledgeGraphStats(): Promise<any>;
+    private _buildGraphologyGraph;
+    getGraphMetrics(entityNames?: string[], metrics?: string[], limit?: number): Promise<any>;
+    detectCommunities(resolution?: number): Promise<any>;
+    analyzeGraphStructure(): Promise<any>;
+    getMigrationStatus(): Promise<{
+        currentVersion: number;
+        migrations: Array<{
+            version: number;
+            description: string;
+            applied: boolean;
+            applied_at?: string;
+        }>;
+        pendingCount: number;
+    }>;
+    rollbackMigration(targetVersion: number): Promise<{
+        rolledBack: number;
+        currentVersion: number;
+        rolledBackMigrations: Array<{
+            version: number;
+            description: string;
+        }>;
+    }>;
+}
 export {};

package/dist/index.js

@@ -56,7 +56,7 @@ function safeRowid(value) {
     return n;
 }
 // Enhanced RAG-enabled Knowledge Graph Manager
-class RAGKnowledgeGraphManager {
+export class RAGKnowledgeGraphManager {
     db = null;
     encoding = null;
     embeddingModel = null;
@@ -64,7 +64,7 @@ class RAGKnowledgeGraphManager {
     embeddingCache = new Map();
     EMBEDDING_CACHE_MAX = 500;
     dictionaryCache = null;
-    async initialize() {
+    async initialize(opts = {}) {
         console.error('🚀 Initializing RAG Knowledge Graph MCP Server...');
         // Initialize database
         this.db = new Database(DB_FILE_PATH);
@@ -80,8 +80,13 @@ class RAGKnowledgeGraphManager {
         this.db.pragma('foreign_keys = ON');
         // Initialize tiktoken
         this.encoding = get_encoding("cl100k_base");
-        // Initialize embedding model
-        await this.initializeEmbeddingModel();
+        // Initialize embedding model (skippable for tests / FTS-only environments)
+        if (!opts.skipModel) {
+            await this.initializeEmbeddingModel();
+        }
+        else {
+            console.error('⏭️  Skipping embedding model load (skipModel=true)');
+        }
         // Run database migrations
         await this.runMigrations();
         console.error('✅ RAG-enabled knowledge graph initialized');
@@ -1170,6 +1175,105 @@ class RAGKnowledgeGraphManager {
         throw new Error('Embedding model not initialized. The server may still be loading the model — retry in a few seconds.');
     }
     // === NEW SEPARATE TOOLS ===
+    async syncDocumentFromFile(filePath, documentId, options = {}) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        // 1. Resolve content: raw file verbatim (default) or explicit override.
+        //    Content is read on the server and never routed through the model context.
+        const content = options.content !== undefined
+            ? options.content
+            : fsSync.readFileSync(filePath, 'utf-8');
+        const bytes = Buffer.byteLength(content, 'utf-8');
+        // 2. Metadata: default source=path, updated=today, content_hash; caller can override.
+        const today = new Date().toISOString().slice(0, 10);
+        const contentHash = createHash('sha256').update(content).digest('hex');
+        const metadata = { source: filePath, updated: today, content_hash: contentHash, ...(options.metadata || {}) };
+        // 2b. Dedup gate: skip the full delete/store/chunk/embed pipeline when the
+        //     file is unchanged AND the existing document is fully embedded. The
+        //     completeness check avoids wrongly skipping a partial/failed prior sync.
+        const existingDoc = this.db.prepare(`SELECT metadata FROM documents WHERE id = ?`).get(documentId);
+        if (existingDoc) {
+            let existingHash;
+            try {
+                existingHash = JSON.parse(existingDoc.metadata)?.content_hash;
+            }
+            catch { /* ignore */ }
+            if (existingHash === contentHash) {
+                const cmCount = this.db.prepare(`SELECT count(*) AS n FROM chunk_metadata WHERE document_id = ?`).get(documentId).n;
+                const embCount = this.db.prepare(`
+          SELECT count(*) AS n FROM chunks c JOIN chunk_metadata m ON c.rowid = m.rowid WHERE m.document_id = ?
+        `).get(documentId).n;
+                if (cmCount > 0 && cmCount === embCount) {
+                    const linked = this.db.prepare(`
+            SELECT count(DISTINCT ce.entity_id) AS n FROM chunk_entities ce
+            JOIN chunk_metadata m ON ce.chunk_rowid = m.rowid WHERE m.document_id = ?
+          `).get(documentId).n;
+                    console.error(`⏭️  syncDocumentFromFile: ${documentId} unchanged (hash match, ${cmCount} chunks embedded) — skipped`);
+                    return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked, skipped: true, reason: 'unchanged' };
+                }
+            }
+        }
+        console.error(`🔄 syncDocumentFromFile: ${documentId} <- ${filePath} (${bytes} bytes)`);
+        // 3. Pre-compute chunks + embeddings BEFORE any DB mutation. If embedding
+        //    throws (model down), the existing document is left completely intact.
+        const { maxTokens = 800, overlap = 160 } = options.chunkParams || {};
+        const segments = this.chunkText(content, maxTokens, overlap);
+        const embedded = [];
+        for (const seg of segments) {
+            const embedding = await this.generateEmbedding(seg.text);
+            embedded.push({ seg, embedding });
+        }
+        // 4. Atomic swap: delete old -> insert doc -> insert chunks + embeddings,
+        //    all in a single synchronous better-sqlite3 transaction (all-or-nothing).
+        const applyTx = this.db.transaction(() => {
+            const db = this.db;
+            // 4a. cleanup old doc (inlined sync version of cleanupDocument).
+            const existing = db.prepare(`SELECT rowid FROM chunk_metadata WHERE document_id = ?`).all(documentId);
+            for (const ch of existing) {
+                db.prepare(`DELETE FROM chunk_entities WHERE chunk_rowid = ?`).run(ch.rowid);
+                db.exec(`DELETE FROM chunks WHERE rowid = ${safeRowid(ch.rowid)}`);
+            }
+            db.prepare(`DELETE FROM chunk_metadata WHERE document_id = ?`).run(documentId);
+            db.prepare(`DELETE FROM documents WHERE id = ?`).run(documentId);
+            // 4b. insert document.
+            db.prepare(`INSERT INTO documents (id, content, metadata) VALUES (?, ?, ?)`)
+                .run(documentId, content, JSON.stringify(metadata));
+            // 4c. insert chunk_metadata (FTS5 chunks_fts auto-filled by trigger) + embeddings.
+            for (const { seg, embedding } of embedded) {
+                const chunkId = `${documentId}_chunk_${seg.chunk_index}`;
+                const info = db.prepare(`
+          INSERT INTO chunk_metadata (chunk_id, document_id, chunk_index, text, start_pos, end_pos, start_token, end_token)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(chunkId, documentId, seg.chunk_index, seg.text, seg.start_pos, seg.end_pos, seg.start_token, seg.end_token);
+                const rowid = Number(info.lastInsertRowid);
+                db.prepare(`INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)`).run(Buffer.from(embedding.buffer));
+            }
+        });
+        applyTx();
+        const embeddedChunks = embedded.length;
+        // 5. Entity linking AFTER commit. Non-destructive + idempotent (INSERT OR
+        //    IGNORE), so a linking failure cannot corrupt the doc/embeddings.
+        const linkedEntities = await this.autoLinkEntities(documentId);
+        let explicitlyLinked;
+        if (options.entityNames && options.entityNames.length > 0) {
+            const linkResult = await this.linkEntitiesToDocument(documentId, options.entityNames);
+            explicitlyLinked = linkResult.linkedEntities;
+        }
+        // 6. Terse summary only (no chunk text / content echo) to keep caller context flat.
+        const result = {
+            documentId,
+            bytes,
+            chunks: segments.length,
+            embeddedChunks,
+            linkedEntities,
+            ...(explicitlyLinked !== undefined ? { explicitlyLinked } : {}),
+        };
+        if (linkedEntities === 0 && explicitlyLinked === undefined) {
+            result.warning = 'linkedEntities=0: ensure the file content contains entity-name literals (e.g. a wiki anchor line "RAG entity: ...") so term-matching can link entities.';
+        }
+        console.error(`✅ syncDocumentFromFile done: ${documentId} (${result.chunks} chunks, ${result.embeddedChunks} embedded, ${linkedEntities} linked)`);
+        return result;
+    }
     async storeDocument(id, content, metadata = {}) {
         if (!this.db)
             throw new Error('Database not initialized');
@@ -1676,7 +1780,8 @@ class RAGKnowledgeGraphManager {
         if (queryVariants.length > 1) {
             console.error(`🌐 Cross-lingual variants: ${queryVariants.slice(1).join(' | ')}`);
         }
-        const primaryQueryEmbedding = await this.generateEmbedding(queryVariants[0], 1024, true);
+        let vectorDegraded = false;
+        let primaryQueryEmbedding = null;
         // Vector search helper
         const searchChunks = (embedding, k) => {
             return this.db.prepare(`
@@ -1706,16 +1811,23 @@ class RAGKnowledgeGraphManager {
         };
         // Search original query plus cross-lingual expansions and keep best match per chunk.
         const resultMap = new Map();
-        for (const variant of queryVariants) {
-            const embedding = await this.generateEmbedding(variant, 1024, true);
-            const variantResults = searchChunks(embedding, limit * 3);
-            for (const r of variantResults) {
-                const existing = resultMap.get(r.chunk_id);
-                if (!existing || r.distance < existing.distance) {
-                    resultMap.set(r.chunk_id, r);
+        try {
+            primaryQueryEmbedding = await this.generateEmbedding(queryVariants[0], 1024, true);
+            for (const variant of queryVariants) {
+                const embedding = await this.generateEmbedding(variant, 1024, true);
+                const variantResults = searchChunks(embedding, limit * 3);
+                for (const r of variantResults) {
+                    const existing = resultMap.get(r.chunk_id);
+                    if (!existing || r.distance < existing.distance) {
+                        resultMap.set(r.chunk_id, r);
+                    }
                 }
             }
         }
+        catch (embErr) {
+            vectorDegraded = true;
+            console.error(`⚠️ Vector search unavailable (embedding model down) — degrading to FTS5-only:`, embErr instanceof Error ? embErr.message : embErr);
+        }
         const vectorResults = Array.from(resultMap.values()).sort((a, b) => a.distance - b.distance);
         // FTS5 full-text search as additional signal (Reciprocal Rank Fusion)
         const ftsBoostMap = new Map();
@@ -1803,7 +1915,7 @@ class RAGKnowledgeGraphManager {
         // Get entity information for graph enhancement via vector similarity
         let connectedEntities = new Set();
         let queryMatchedEntities = new Set();
-        if (useGraph) {
+        if (useGraph && !vectorDegraded) {
             // Vector search: find entities semantically similar to the query (dual search)
             try {
                 const searchEntities = (embedding) => {
@@ -1909,7 +2021,7 @@ class RAGKnowledgeGraphManager {
             }
             // Enhanced graph boost calculation with decay + cap
             let graphBoost = 0;
-            if (useGraph) {
+            if (useGraph && !vectorDegraded) {
                 const queryEntities = this.extractTermsFromText(query);
                 // Base boost for knowledge graph chunks
                 if (result.chunk_type === 'entity') {
@@ -1956,9 +2068,17 @@ class RAGKnowledgeGraphManager {
                 // Hard cap to prevent graph domination
                 graphBoost += Math.min(entityBoost, 0.4);
             }
-            // Generate semantic summary
-            const { summary, keyHighlight, relevanceScore } = await this.generateContentSummary(result.text, primaryQueryEmbedding, chunkEntities, result.chunk_type === 'relationship' ? 1 : 2 // Shorter summary for relationships
-            );
+            // Generate semantic summary (skip when degraded — no embeddings available).
+            let summary, keyHighlight, relevanceScore;
+            if (vectorDegraded || !primaryQueryEmbedding) {
+                keyHighlight = result.text.slice(0, 150);
+                summary = result.text.slice(0, 300);
+                relevanceScore = 0;
+            }
+            else {
+                ({ summary, keyHighlight, relevanceScore } = await this.generateContentSummary(result.text, primaryQueryEmbedding, chunkEntities, result.chunk_type === 'relationship' ? 1 : 2 // Shorter summary for relationships
+                ));
+            }
             const vectorSimilarity = Math.max(0, 1 - result.distance / 2);
             const ftsBoost = ftsBoostMap.get(result.chunk_id) || 0;
             const finalScore = Math.max(vectorSimilarity, relevanceScore) + graphBoost + ftsBoost;
@@ -1990,11 +2110,12 @@ class RAGKnowledgeGraphManager {
                 document_title: documentTitle,
                 entities: chunkEntities,
                 vector_similarity: vectorSimilarity,
-                graph_boost: useGraph ? graphBoost : undefined,
+                graph_boost: (useGraph && !vectorDegraded) ? graphBoost : undefined,
                 fts_boost: ftsBoost > 0 ? ftsBoost : undefined,
                 full_context_available: true,
                 chunk_type: result.chunk_type,
-                source_id: sourceId
+                source_id: sourceId,
+                search_mode: vectorDegraded ? 'fts-only' : 'hybrid'
             });
         }
         // Sort by relevance and return top results
@@ -2474,6 +2595,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.deleteDocuments(validatedArgs.documentIds), null, 2) }] };
             case "listDocuments":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.listDocuments(validatedArgs.includeMetadata !== false), null, 2) }] };
+            case "syncDocumentFromFile":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.syncDocumentFromFile(validatedArgs.path, validatedArgs.documentId, {
+                                metadata: validatedArgs.metadata,
+                                content: validatedArgs.content,
+                                entityNames: validatedArgs.entityNames,
+                                chunkParams: validatedArgs.chunkParams,
+                            }), null, 2) }] };
             // NEW: Entity embedding tools
             case "embedAllEntities":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.embedAllEntities(), null, 2) }] };
@@ -2532,8 +2660,12 @@ async function main() {
         process.exit(1);
     }
 }
-main().catch((error) => {
-    console.error("Fatal error in main():", error);
-    ragKgManager.cleanup();
-    process.exit(1);
-});
+// Only boot the server when run as the entry point — not when imported (tests).
+const isDirectRun = process.argv[1] === fileURLToPath(import.meta.url);
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error("Fatal error in main():", error);
+        ragKgManager.cleanup();
+        process.exit(1);
+    });
+}

package/dist/src/tools/rag-tools.d.ts

@@ -7,6 +7,7 @@ export declare const linkEntitiesToDocumentTool: ToolDefinition;
 export declare const getKnowledgeGraphStatsTool: ToolDefinition;
 export declare const deleteDocumentsTool: ToolDefinition;
 export declare const listDocumentsTool: ToolDefinition;
+export declare const syncDocumentFromFileTool: ToolDefinition;
 export declare const ragTools: {
     storeDocument: ToolDefinition;
     chunkDocument: ToolDefinition;
@@ -16,4 +17,5 @@ export declare const ragTools: {
     getKnowledgeGraphStats: ToolDefinition;
     deleteDocuments: ToolDefinition;
     listDocuments: ToolDefinition;
+    syncDocumentFromFile: ToolDefinition;
 };

package/dist/src/tools/rag-tools.js

@@ -516,6 +516,93 @@ export const listDocumentsTool = {
     schema: listDocumentsSchema,
     annotations: { readOnlyHint: true },
 };
+// === SYNC DOCUMENT FROM FILE TOOL ===
+const syncDocumentFromFileCapability = {
+    description: 'Read a file server-side and run the full document sync pipeline (delete, store, chunk, embed, link) in one call, returning only a terse summary',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute path of the file to sync. Content is read server-side and never routed through the model context.'
+            },
+            documentId: {
+                type: 'string',
+                description: 'RAG document ID to (re)create from the file'
+            },
+            metadata: {
+                type: 'object',
+                description: 'Metadata merged into the stored document (source defaults to path, updated defaults to today)',
+                additionalProperties: true,
+                optional: true
+            },
+            content: {
+                type: 'string',
+                description: 'Optional content override; if provided, this is stored instead of reading the file',
+                optional: true
+            },
+            entityNames: {
+                type: 'array',
+                description: 'Optional entities to explicitly link in addition to automatic term-matching',
+                items: { type: 'string' },
+                optional: true
+            },
+            chunkParams: {
+                type: 'object',
+                description: 'Optional chunking parameters { maxTokens, overlap }',
+                additionalProperties: true,
+                optional: true
+            }
+        },
+        required: ['path', 'documentId'],
+    },
+};
+const syncDocumentFromFileDescription = () => `<description>
+Read a file on the server and perform the entire document sync pipeline in a single call:
+deleteDocuments -> storeDocument -> chunkDocument -> embedChunks -> (optional) linkEntitiesToDocument.
+**The file content is read server-side and is NOT routed through the model context**, and only a
+terse summary is returned (no chunk text). This collapses the usual 5 tool calls per document into
+one and keeps the conversation context flat, which is the dominant cost of large /sync runs.
+</description>
+
+<importantNotes>
+- (!important!) **Content is read from \`path\` on the server** - it does not pass through the model context
+- (!important!) **Stores the raw file verbatim** by default (higher search fidelity); pass \`content\` to override
+- (!important!) **Idempotent** - the target documentId is fully re-synced (delete + recreate) each call
+- (!important!) **Returns terse counts only** - { documentId, bytes, chunks, embeddedChunks, linkedEntities }
+- (!important!) **Entity linking** happens automatically via term-matching during embedding; \`entityNames\` adds explicit links
+</importantNotes>
+
+<whenToUseThisTool>
+- During /sync to persist a Markdown/SSOT file into the RAG store without paying the context cost of reading it into the model
+- When re-syncing decision logs, current-focus, wiki pages, or any file-backed document
+- As a one-call replacement for the manual storeDocument + chunkDocument + embedChunks + linkEntitiesToDocument sequence
+</whenToUseThisTool>
+
+<bestPractices>
+- Use the document's canonical ID (e.g. \`current-focus\`, \`wiki-project-context\`)
+- Keep an entity-name literal (e.g. wiki anchor line "RAG entity: ...") in the file so term-matching can link entities; a warning is returned if linkedEntities is 0
+- Pass \`metadata.updated\` (YYYY-MM-DD) for change tracking
+</bestPractices>
+
+<examples>
+- Sync current-focus: {"path": "/abs/decisions/current-focus.md", "documentId": "current-focus", "metadata": {"updated": "2026-05-23"}}
+- With explicit links: {"path": "/abs/wiki/project-context.md", "documentId": "wiki-project-context", "entityNames": ["Ultimate AI Personal Assistant"]}
+</examples>`;
+const syncDocumentFromFileSchema = {
+    path: z.string().describe('Absolute path of the file to sync (read server-side)'),
+    documentId: z.string().describe('RAG document ID to (re)create from the file'),
+    metadata: z.record(z.any()).optional().describe('Metadata merged into the stored document'),
+    content: z.string().optional().describe('Optional content override; stored instead of reading the file'),
+    entityNames: z.array(z.string()).optional().describe('Optional entities to explicitly link'),
+    chunkParams: z.record(z.any()).optional().describe('Optional chunking parameters { maxTokens, overlap }'),
+};
+export const syncDocumentFromFileTool = {
+    capability: syncDocumentFromFileCapability,
+    description: syncDocumentFromFileDescription,
+    schema: syncDocumentFromFileSchema,
+    annotations: { idempotentHint: true },
+};
 // Export all RAG tools
 export const ragTools = {
     storeDocument: storeDocumentTool,
@@ -526,4 +613,5 @@ export const ragTools = {
     getKnowledgeGraphStats: getKnowledgeGraphStatsTool,
     deleteDocuments: deleteDocumentsTool,
     listDocuments: listDocumentsTool,
+    syncDocumentFromFile: syncDocumentFromFileTool,
 };

package/dist/src/tools/tool-registry.d.ts

@@ -20,6 +20,7 @@ export declare const allTools: {
     getKnowledgeGraphStats: ToolDefinition;
     deleteDocuments: ToolDefinition;
     listDocuments: ToolDefinition;
+    syncDocumentFromFile: ToolDefinition;
     createEntities: ToolDefinition;
     createRelations: ToolDefinition;
     addObservations: ToolDefinition;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-memory-epf-mcp",
-  "version": "3.3.6",
+  "version": "3.5.0",
   "description": "Project-local RAG memory MCP server — knowledge graph + multilingual vector + FTS5 in a single SQLite file. Per-project isolation, 30 MCP tools, codepoint-safe chunking (Korean/CJK/emoji).",
   "keywords": [
     "mcp",
@@ -41,8 +41,9 @@
     "prepare": "npm run build",
     "watch": "tsc --watch",
     "verify:invariants": "node test/chunk-invariants.test.mjs",
-    "test": "npm run build && npm run verify:invariants",
-    "prepublishOnly": "npm run build && npm run verify:invariants"
+    "verify:engine": "node test/engine-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs",
+    "test": "npm run build && npm run verify:invariants && npm run verify:engine",
+    "prepublishOnly": "npm run build && npm run verify:invariants && npm run verify:engine"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.5.1",