rag-memory-epf-mcp 6.4.0 → 6.4.1

package/README.md

@@ -154,6 +154,48 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### v6.4.1 (2026-10-16)
+
+- **Changed — new opt-in manager method `generateRelationEvidenceChunks(items, { formatVersion: 'evidence-v1' })`.**
+  `items` is the whole set of relationships that should have a relationship chunk: on success every relationship KG
+  chunk is replaced by evidence-backed chunks for that set, built from verified quotes (document chunk codepoint
+  ranges) and current active observations; relationships outside the set get no chunk, and entity chunks and
+  relationship rows are untouched. Caps: 1–8 evidence entries per item, ≤ 4,000 codepoints per quote, ≤ 8,000
+  codepoints of final body — over-cap input rejects the whole call without writes, never truncated. Not exposed over
+  MCP and does not change search defaults. The no-argument generator `generateKnowledgeGraphChunks()` keeps the
+  previous entity/triplet bodies, IDs, metadata and counts (the lifecycle and atomicity fixes below still apply);
+  calling it replaces existing evidence relationship chunks with triplet chunks. "Evidence-backed" means
+  caller-selected evidence whose references the engine verified exist verbatim, not an independent proof.
+- **Changed — stale KG chunks leave search immediately.** Deleting a relationship, or changing or removing a cited
+  observation or document, removes the KG chunk (vector, FTS row) in the same transaction. No automatic evidence
+  regeneration is scheduled; the chunk stays absent until the caller explicitly generates again. A confidence-only
+  update refreshes the copied metadata without re-embedding.
+- **Changed — `getDetailedContext` resolves KG chunks.** Entity chunks return the entity and its active observations;
+  relationship chunks return the relationship plus `evidence_status` (`claim_only` / `refs_available` /
+  `refs_unavailable`) and per-reference `available` / `missing` / `mismatch`, with `document_id: null` and
+  `document_title: null` in this branch only. Document detail and all `hybridSearch` fields are unchanged, except that
+  `full_context_available` is now `false` for a KG chunk whose entity or relationship row is gone.
+- **Changed — a failed KG replacement leaves the previous snapshot intact; no partial replacement is published. A KG
+  embedding computed for an input that changed meanwhile (text, evidence fingerprint or profile) is dropped,** on the
+  dedicated path and in background backfill. A profile change before inference starts embeds under the new profile.
+  An evidence row whose reference list is empty or malformed is never written back.
+- **Changed — `importGraph` requires string ids for documents and observation sources.** A `documents[i].id` or an
+  `observation_sources[i].observation_id` that is not a string (a number, `null`, or missing) rejects the whole import
+  before anything is written. Previously such a value was bound as-is: a number such as `7.5` could replace the
+  document whose TEXT id is `'7.5'` while the evidence chunks citing it stayed in search.
+- **Fixed — `deleteEntities` refreshes cached coverage** after at least one entity was deleted, so the coverage figures
+  and `search_mode` reported by `hybridSearch` and stats reflect the deletion without waiting for another write.
+- **Changed — oversize blocks split faster.** An oversize block that reaches the fallback split is split using a
+  verified token-window estimate, with the previous linear scan kept when no candidate verifies (C6 numbers: framework
+  receipts `raw/measurements/2026-10-16-kg-relation-evidence/C6-BENCH.md`, one synthetic input per size on one Mac,
+  Node 24.12.0 — not a guarantee for every input). Inputs that never reach this fallback keep their previous
+  boundaries. The chunking signature now says `fallback=cp-window-N`; documents stamped `cp-exact-N` stay current
+  format. A signature change alone does not re-chunk an unchanged document that still has chunk metadata (missing
+  vectors are re-queued without re-chunking; if no chunks remain, the normal path runs).
+- **Documented — `limit` sets both the maximum result count and the retrieval depth** (each query variant requests up
+  to `limit × 3` vector and up to `limit × 3` FTS candidates, then merged), so results for different limits can
+  differ. No algorithm change.
+
 ### v6.4.0 (2026-10-03)
 
 - (Published first as `6.4.0-rc.1` on the `next` dist-tag; promoted to `latest` after a canary of the published

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type SourceInput } from './src/observations/lifecycle.js';
+import { EVIDENCE_FORMAT, type EvidenceItemInput, type EvidenceStatus, type EvidenceRefStatus, type EvidenceChunkMetadataV1 } from './src/kg/relation-evidence.js';
 import { EmbeddingGate } from './src/embeddingGate.js';
 import type { EmbedPriority } from './src/embeddingGate.js';
 import { BackfillCoordinator } from './src/backfillCoordinator.js';
@@ -40,7 +41,7 @@ interface EnhancedSearchResult {
     source_id?: string;
     search_mode?: 'hybrid' | 'fts-only';
 }
-interface DetailedContext {
+interface DocumentDetailedContext {
     chunk_id: string;
     document_id: string;
     full_text: string;
@@ -53,11 +54,49 @@ interface DetailedContext {
     entities: string[];
     metadata: Record<string, any>;
 }
+interface KgDetailedContextBase {
+    chunk_id: string;
+    document_id: null;
+    document_title: null;
+    source_kind: 'entity' | 'relationship';
+    source_id: string;
+    full_text: string;
+    entities: string[];
+    metadata: Record<string, any>;
+}
+interface EntityDetailedContext extends KgDetailedContextBase {
+    source_kind: 'entity';
+    entity: {
+        name: string;
+        entityType: string;
+        observations: Array<{
+            observation_id: string;
+            revision_no: number;
+            content: string;
+        }>;
+    };
+}
+interface RelationshipDetailedContext extends KgDetailedContextBase {
+    source_kind: 'relationship';
+    relationship: {
+        id: string;
+        source: string;
+        target: string;
+        relationType: string;
+        confidence: number;
+    };
+    evidence_status: EvidenceStatus;
+    evidence_refs: EvidenceRefStatus[];
+    support: EvidenceChunkMetadataV1['support'] | null;
+}
+type KgDetailedContext = EntityDetailedContext | RelationshipDetailedContext;
+type DetailedContext = DocumentDetailedContext | KgDetailedContext;
 export declare class SyncCasConflictError extends Error {
     constructor(documentId: string);
 }
 export declare function isIoError(e: unknown): boolean;
 export declare function setSyncFaultPoint(point: string | null, fn: (() => void) | null): void;
+export declare function setKgFaultPoint(point: string | null, fn: (() => void) | null): void;
 export interface ReuseCandidate {
     rowid: number;
     text: string;
@@ -98,6 +137,7 @@ export declare class RAGKnowledgeGraphManager {
     private mutateEntityAndInvalidate;
     private invalidateDerivedForEntity;
     invalidateEntityVector(entityId: string): void;
+    private writeKgVectorIfCurrent;
     reembedChunkByRowid(rowid: number): Promise<boolean>;
     shutdownAll(): Promise<void>;
     runMigrations(): Promise<{
@@ -244,11 +284,19 @@ export declare class RAGKnowledgeGraphManager {
     embedKnowledgeGraphChunks(): Promise<{
         embeddedChunks: number;
         totalChunks: number;
+        discardedChunks?: number;
         errors?: string[];
     }>;
+    generateRelationEvidenceChunks(items: EvidenceItemInput[], options: {
+        formatVersion: typeof EVIDENCE_FORMAT;
+    }): Promise<{
+        relationshipChunks: number;
+        removedRelationshipChunks: number;
+        formatVersion: typeof EVIDENCE_FORMAT;
+    }>;
     private generateEntityChunkText;
     private generateRelationshipChunkText;
-    private cleanupKnowledgeGraphChunks;
+    private deleteAllKgChunks;
     private loadDictionary;
     private hasKorean;
     private isLikelyEnglish;
@@ -462,6 +510,7 @@ export declare class RAGKnowledgeGraphManager {
     }>;
     degradationReason(): 'disabled' | 'model_not_ready' | 'reconciling' | 'reconciliation_failed' | undefined;
     getDetailedContext(chunkId: string, includeSurrounding?: boolean): Promise<DetailedContext>;
+    private getKgDetailedContext;
     getKnowledgeGraphStats(): Promise<any>;
     private _buildGraphologyGraph;
     getGraphMetrics(entityNames?: string[], metrics?: string[], limit?: number): Promise<any>;