rag-memory-epf-mcp 3.5.2 → 3.6.0

package/README.md

@@ -134,9 +134,19 @@ storeDocument(id, content, metadata)
 |----------|---------|-------------|
 | `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.

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import { EmbeddingGate } from './src/embeddingGate.js';
+import type { EmbedPriority } from './src/embeddingGate.js';
+import { BackfillCoordinator } from './src/backfillCoordinator.js';
+export declare function compileFtsLiteralQuery(q: string): string | null;
 interface Entity {
     name: string;
     entityType: string;
@@ -44,15 +48,28 @@ interface DetailedContext {
 export declare class RAGKnowledgeGraphManager {
     private db;
     private encoding;
-    private embeddingModel;
-    private modelInitialized;
+    gate: EmbeddingGate;
+    embeddingsMode: 'lazy' | 'eager' | 'off';
+    currentProfileId: number;
+    grandfatherAllowed: boolean;
+    coordinator: BackfillCoordinator | null;
     private embeddingCache;
     private readonly EMBEDDING_CACHE_MAX;
     private dictionaryCache;
     initialize(opts?: {
         skipModel?: boolean;
+        gate?: EmbeddingGate;
     }): Promise<void>;
-    private initializeEmbeddingModel;
+    private ensureCurrentProfile;
+    private buildRealLoader;
+    startReconciliation(): Promise<void>;
+    hashWithBuilderVersion(text: string): string;
+    entityInputHash(entityId: string): string | null;
+    tryEmbedEntity(entityId: string, priority?: EmbedPriority): Promise<'embedded' | 'queued' | 'disabled'>;
+    private mutateEntityAndInvalidate;
+    invalidateEntityVector(entityId: string): void;
+    reembedChunkByRowid(rowid: number): Promise<boolean>;
+    shutdownAll(): Promise<void>;
     runMigrations(): Promise<{
         applied: number;
         currentVersion: number;
@@ -76,7 +93,14 @@ export declare class RAGKnowledgeGraphManager {
     deleteObservations(deletions: {
         entityName: string;
         observations: string[];
-    }[]): Promise<void>;
+    }[]): Promise<{
+        results: Array<{
+            entityName: string;
+            deleted: number;
+            embedding_status: 'embedded' | 'queued' | 'disabled' | 'n/a';
+        }>;
+        total_deleted: number;
+    }>;
     deleteRelations(relations: Relation[]): Promise<void>;
     updateRelations(updates: {
         from: string;
@@ -108,7 +132,17 @@ export declare class RAGKnowledgeGraphManager {
             path: string[];
         }>;
     }>;
-    searchNodes(query: string, limit?: number, since?: string, until?: string): Promise<KnowledgeGraph>;
+    searchNodes(query: string, limit?: number, since?: string, until?: string): Promise<KnowledgeGraph & {
+        search_mode?: string;
+        model_state?: string;
+        coverage?: {
+            entity_pct: number;
+        };
+        degradation_reason?: string;
+        warning?: string;
+    }>;
+    private searchNodesFts;
+    private relationsAmong;
     openNodes(names: string[]): Promise<KnowledgeGraph>;
     private generateEntityEmbeddingText;
     private buildEntityEmbeddingText;
@@ -267,7 +301,17 @@ export declare class RAGKnowledgeGraphManager {
             documents: number;
         };
     }>;
-    hybridSearch(query: string, limit?: number, useGraph?: boolean): Promise<EnhancedSearchResult[]>;
+    hybridSearch(query: string, limit?: number, useGraph?: boolean): Promise<{
+        results: EnhancedSearchResult[];
+        search_mode: 'hybrid' | 'hybrid-partial' | 'fts-only';
+        model_state: string;
+        coverage: {
+            chunk_pct: number;
+            graph_coverage_pct: number;
+        };
+        degradation_reason?: string;
+    }>;
+    degradationReason(): 'disabled' | 'model_not_ready' | 'reconciling' | 'reconciliation_failed' | undefined;
     getDetailedContext(chunkId: string, includeSurrounding?: boolean): Promise<DetailedContext>;
     getKnowledgeGraphStats(): Promise<any>;
     private _buildGraphologyGraph;