rag-memory-epf-mcp 3.5.2 → 4.0.0

package/dist/src/tools/graph-query-tools.js

@@ -563,7 +563,8 @@ Supports both merge (additive) and replace (clear + import) modes.
 - Replace mode provides clean import without conflicts
 - Handles partial imports (entities only, relations only, etc.)
 - Reports imported and skipped counts for verification
-- Supports full export format from exportGraph
+- Supports the full exportGraph format, including the v13 observation lifecycle tables
+  (revision history, provenance and events survive a round-trip)
 </features>
 
 <bestPractices>
@@ -587,12 +588,35 @@ Supports both merge (additive) and replace (clear + import) modes.
 - Full replace: {"data": {"entities": [...], "relations": [...], "documents": [...]}, "merge": false}
 - Entities only: {"data": {"entities": [{"id": "abc", "name": "Test", "entityType": "CONCEPT", "observations": ["fact1"]}]}}
 </examples>`;
+// dump 의 행은 객체다. z.any() 로 두면 광고 스키마에 type:'string' fallback 으로 나가
+// listTools 계약이 실제 입력과 어긋난다. z.record 는 "문자열 키를 가진 객체"로 광고되고
+// 비객체 입력을 거부한다(advisor beta r3 남은 P2).
+const dumpRow = () => z.record(z.any());
 const importGraphSchema = {
     data: z.object({
-        entities: z.array(z.any()).optional().describe('Array of entity objects to import'),
-        relations: z.array(z.any()).optional().describe('Array of relation objects to import'),
-        documents: z.array(z.any()).optional().describe('Array of document objects to import'),
-    }).describe('Object containing entities, relations, and/or documents arrays to import'),
+        entities: z.array(dumpRow()).optional().describe('Array of entity objects to import'),
+        relations: z.array(dumpRow()).optional().describe('Array of relation objects to import'),
+        documents: z.array(dumpRow()).optional().describe('Array of document objects to import'),
+        // v13: 이 네 배열이 스키마에 없으면 z.object().parse() 가 조용히 버린다. 그러면
+        // exportGraph 가 낸 완전한 dump 를 MCP 로 되돌릴 때 revision history·provenance·
+        // event log 가 전부 사라지고 legacy 관찰로 재생성된다 — 백업/복원이 조용히
+        // 손실 연산이 된다(advisor beta 발견 1, MCP 왕복으로 실측).
+        observation_roots: z.array(dumpRow()).optional()
+            .describe('Array of observation root rows (v13 lifecycle). Required to preserve history on restore'),
+        entity_observations: z.array(dumpRow()).optional()
+            .describe('Array of observation revision rows (v13 lifecycle)'),
+        observation_sources: z.array(dumpRow()).optional()
+            .describe('Array of observation provenance rows (v13 lifecycle)'),
+        observation_events: z.array(dumpRow()).optional()
+            .describe('Array of observation event rows (v13 lifecycle)'),
+        metadata: z.record(z.any()).optional()
+            .describe('Export metadata (exportedAt, version, counts). Ignored on import'),
+        // strict: dump 의 모든 정상 키를 위에 열거했으므로, 모르는 키는 **거부**한다.
+        // 기본 strip 은 모르는 테이블을 조용히 버리고(그게 lifecycle 4배열에서 실제로
+        // 일어난 일이다), passthrough 는 그것을 manager 까지 흘려보내 거기서 다시 조용히
+        // 무시된다 — 둘 다 같은 미래 데이터 손실 경로다. 지원하지 않는 dump 는 크게 실패해야
+        // 운영자가 엔진을 올린다(advisor beta r3).
+    }).strict().describe('A graph dump as produced by exportGraph, including the v13 observation lifecycle tables'),
     merge: z.boolean().optional().default(true).describe('If true (default), merge with existing data. If false, clear existing data first.'),
 };
 export const importGraphTool = {

package/dist/src/tools/knowledge-graph-tools.d.ts

@@ -6,6 +6,13 @@ export declare const hybridSearchTool: ToolDefinition;
 export declare const embedAllEntitiesTool: ToolDefinition;
 export declare const getDetailedContextTool: ToolDefinition;
 export declare const updateRelationsTool: ToolDefinition;
+export declare const retractObservationTool: ToolDefinition;
+export declare const restoreObservationTool: ToolDefinition;
+export declare const approveObservationTool: ToolDefinition;
+export declare const declineObservationTool: ToolDefinition;
+export declare const correctObservationTool: ToolDefinition;
+export declare const purgeObservationTool: ToolDefinition;
+export declare const getObservationHistoryTool: ToolDefinition;
 export declare const knowledgeGraphTools: {
     createEntities: ToolDefinition;
     createRelations: ToolDefinition;
@@ -14,4 +21,11 @@ export declare const knowledgeGraphTools: {
     hybridSearch: ToolDefinition;
     embedAllEntities: ToolDefinition;
     getDetailedContext: ToolDefinition;
+    correctObservation: ToolDefinition;
+    retractObservation: ToolDefinition;
+    restoreObservation: ToolDefinition;
+    approveObservation: ToolDefinition;
+    declineObservation: ToolDefinition;
+    purgeObservation: ToolDefinition;
+    getObservationHistory: ToolDefinition;
 };

package/dist/src/tools/knowledge-graph-tools.js

@@ -73,6 +73,15 @@ const createEntitiesSchema = {
         name: z.string().describe('The unique name/identifier of the entity'),
         entityType: z.string().describe('The category or type of the entity (e.g., PERSON, CONCEPT, TECHNOLOGY)'),
         observations: z.array(z.string()).describe('Array of contextual observations about the entity'),
+        // v13: 아래 두 필드는 addObservations 와 같은 의미다. 스키마에 없으면 전달되지 않는다.
+        status: z.enum(['active', 'provisional']).optional()
+            .describe("'provisional' hides the observations from search until approveObservation. Default 'active'"),
+        sources: z.array(z.object({
+            source_kind: z.enum(['document', 'conversation', 'decision', 'import'])
+                .describe('What kind of thing these observations came from'),
+            source_ref: z.string().describe('Identifier of the source'),
+            source_hash: z.string().optional().describe('Optional content hash of the source'),
+        })).optional().describe('Provenance. Omit if genuinely unknown - do not invent a source'),
     })).describe('Array of entities to create in the knowledge graph'),
 };
 export const createEntitiesTool = {
@@ -189,8 +198,10 @@ Observations provide the factual foundation that supports entity existence and p
 
 <importantNotes>
 - (!important!) **Entity must exist** - this tool only adds to existing entities
-- (!important!) Only new observations are added - duplicates are automatically filtered
-- (!important!) Observations are cumulative - they build the entity's knowledge base
+- (!important!) Duplicates are filtered - repeating existing text with a **new** sources entry
+  adds evidence to the existing revision and returns null for that position
+- (!important!) Observations are cumulative. **This tool never replaces anything** - use
+  correctObservation to supersede and retractObservation to withdraw
 - (!important!) **Be specific and factual** - observations should be verifiable statements
 </importantNotes>
 
@@ -200,21 +211,24 @@ Observations provide the factual foundation that supports entity existence and p
 - When updating entity knowledge from new sources
 - When refining and expanding entity descriptions
 - **Before making knowledge-based decisions** - ensure entities have sufficient context
-- When correcting or expanding incomplete entity information
+- When *expanding* incomplete entity information. **To correct a wrong observation use
+  correctObservation** - adding a second, contradicting observation leaves both in search
 </whenToUseThisTool>
 
 <features>
 - Batch addition of observations to multiple entities
 - Automatic duplicate filtering - no redundant observations
 - Supports rich textual observations with context
-- Maintains observation history and chronology
+- Stable observation ids returned in observation_ids, aligned 1:1 with contents
+- Real revision history: see correctObservation and getObservationHistory
 - Integrates with document processing workflows
 - Enables incremental knowledge building
 </features>
 
 <bestPractices>
 - Keep observations factual and specific rather than general
-- Include source context when possible ("According to paper X...")
+- Put provenance in the sources field, not in the text. A source written in prose cannot be
+  queried, deduplicated, or attached to a later revision
 - Use consistent terminology across observations
 - Add complementary observations that provide different perspectives
 - Include temporal information when relevant ("As of 2024...")
@@ -232,10 +246,22 @@ Observations provide the factual foundation that supports entity existence and p
 - Person details: {"observations": [{"entityName": "Marie Curie", "contents": ["First woman to win Nobel Prize", "Won Nobel Prizes in two different sciences"]}]}
 - Technology evolution: {"observations": [{"entityName": "React", "contents": ["React 18 introduced concurrent features", "Widely adopted for enterprise applications"]}]}
 </examples>`;
+// v13: provenance 와 status 는 스키마에 있어야 실제로 전달된다. validateToolArgs 가
+// z.object(...).parse() 로 검증하므로 스키마에 없는 키는 조용히 버려진다.
+const sourceInputSchema = z.object({
+    source_kind: z.enum(['document', 'conversation', 'decision', 'import'])
+        .describe('What kind of thing this observation came from'),
+    source_ref: z.string().describe('Identifier of the source (document id, decision id, ...)'),
+    source_hash: z.string().optional().describe('Optional content hash of the source'),
+}).describe('Where this observation came from');
 const addObservationsSchema = {
     observations: z.array(z.object({
         entityName: z.string().describe('Name of the existing entity to add observations to'),
         contents: z.array(z.string()).describe('Array of new observation strings to add'),
+        status: z.enum(['active', 'provisional']).optional()
+            .describe("'provisional' hides it from search until approveObservation. Default 'active'"),
+        sources: z.array(sourceInputSchema).optional()
+            .describe('Provenance. Omit if genuinely unknown - do not invent a source'),
     })).describe('Array of observation additions for specific entities'),
 };
 export const addObservationsTool = {
@@ -538,6 +564,211 @@ export const updateRelationsTool = {
     schema: updateRelationsSchema,
     annotations: { idempotentHint: true },
 };
+// === OBSERVATION LIFECYCLE TOOLS (v13, spec §6.1 / §6.2) ===
+// 상태 전이 4종은 인자와 형태가 같다. 같은 문장을 네 번 복사하면 한 곳만 고치는
+// drift 가 생기므로 팩토리로 만든다.
+const transitionTool = (a) => ({
+    capability: {
+        description: `${a.verb} an observation revision (${a.from} -> ${a.to})`,
+        parameters: {
+            type: 'object',
+            properties: {
+                observation_id: { type: 'string', description: 'The revision to transition' },
+                reason: { type: 'string', description: 'Why this transition happened' },
+            },
+            required: a.reasonRequired ? ['observation_id', 'reason'] : ['observation_id'],
+        },
+    },
+    description: () => `<description>
+${a.verb} an observation revision: status '${a.from}' becomes '${a.to}'.
+**This is a state change, not a deletion** - the revision and its text survive and stay
+visible through getObservationHistory.
+</description>
+
+<importantNotes>
+- (!important!) Only '${a.from}' revisions can be ${a.to === 'active' ? 'moved to active' : a.to}; the transition table rejects anything else
+- (!important!) 'superseded' is terminal - correct it into a new revision instead
+- (!important!) Ordinary search returns only 'active' revisions, so this changes what search sees
+- (!important!) ${a.extra}
+</importantNotes>
+
+<whenToUseThisTool>
+- ${a.extra}
+- When you need the record of the change to survive, not just the current text
+</whenToUseThisTool>
+
+<parameters>
+- observation_id: The revision id, from addObservations/createEntities or getObservationHistory (string, required)
+- reason: Why (string, ${a.reasonRequired ? 'required' : 'optional but strongly recommended'})
+</parameters>`,
+    schema: {
+        observation_id: z.string().describe('The observation revision id to transition'),
+        ...(a.reasonRequired
+            ? { reason: z.string().describe('Why this transition happened') }
+            : { reason: z.string().optional().describe('Why this transition happened') }),
+    },
+});
+export const retractObservationTool = transitionTool({
+    verb: 'Retract', from: 'active', to: 'retracted', reasonRequired: false,
+    extra: 'Use this when a fact turned out to be wrong or no longer holds and there is no replacement text',
+});
+export const restoreObservationTool = transitionTool({
+    verb: 'Restore', from: 'retracted', to: 'active', reasonRequired: false,
+    extra: 'Use this when a retraction itself was a mistake',
+});
+export const approveObservationTool = transitionTool({
+    verb: 'Approve', from: 'provisional', to: 'active', reasonRequired: false,
+    extra: 'Use this to accept a provisional observation so search starts returning it',
+});
+export const declineObservationTool = transitionTool({
+    verb: 'Decline', from: 'provisional', to: 'retracted', reasonRequired: true,
+    extra: 'Use this to reject a provisional observation while keeping the fact that it was proposed',
+});
+const correctObservationDescription = () => `<description>
+Replace the text of an observation while keeping the previous version as history.
+**This is the tool to use when a stored fact is wrong.** Overwriting loses the correction;
+this supersedes the old revision so both the mistake and the fix stay retrievable.
+</description>
+
+<importantNotes>
+- (!important!) The old revision becomes 'superseded' and the new one becomes 'active'
+- (!important!) The new revision keeps the old one's position in the entity's observation array
+- (!important!) Only an 'active' revision can be corrected
+- (!important!) Ordinary search returns only the new text; the old text is reachable through getObservationHistory
+</importantNotes>
+
+<whenToUseThisTool>
+- When an observation states something that is now known to be false (change_kind: 'correction')
+- When the world changed and the old statement was true at the time (change_kind: 'world_change')
+- **Instead of deleting and re-adding** - that loses the link between the two
+</whenToUseThisTool>
+
+<parameters>
+- observation_id: The active revision to correct (string, required)
+- content: The corrected text (string, required)
+- change_kind: 'correction' (it was wrong) or 'world_change' (it stopped being true). Default 'correction'
+- reason: Why (string, optional but strongly recommended)
+</parameters>
+
+<examples>
+- {"observation_id": "…", "content": "Uses FTS5 for keyword search", "change_kind": "correction", "reason": "verified in source"}
+</examples>`;
+export const correctObservationTool = {
+    capability: {
+        description: 'Supersede an observation revision with corrected text, keeping the old one as history',
+        parameters: {
+            type: 'object',
+            properties: {
+                observation_id: { type: 'string', description: 'The active revision to correct' },
+                content: { type: 'string', description: 'The corrected text' },
+                change_kind: { type: 'string', description: "'correction' or 'world_change'" },
+                reason: { type: 'string', description: 'Why this correction happened' },
+            },
+            required: ['observation_id', 'content'],
+        },
+    },
+    description: correctObservationDescription,
+    schema: {
+        observation_id: z.string().describe('The active observation revision to correct'),
+        content: z.string().describe('The corrected observation text'),
+        change_kind: z.enum(['correction', 'world_change']).optional()
+            .describe("'correction' = it was wrong; 'world_change' = it stopped being true. Default 'correction'"),
+        reason: z.string().optional().describe('Why this correction happened'),
+    },
+};
+const purgeObservationDescription = () => `<description>
+**DESTRUCTIVE.** Physically delete an observation revision and every later revision of the same
+root. History is gone afterwards - there is no undo.
+</description>
+
+<importantNotes>
+- (!important!) **retractObservation is almost always what you want.** It hides the fact from
+  search while keeping the record
+- (!important!) You must pass confirm='PURGE'; any other value refuses
+- (!important!) This is a **suffix purge**: purging revision 2 of a 3-revision chain removes 3 then 2
+- (!important!) The root row is kept so the observation's array position stays reserved
+- (!important!) Events for purged revisions are removed too
+</importantNotes>
+
+<whenToUseThisTool>
+- When content must be erased for legal or privacy reasons, not because it is wrong
+- **Never** as the normal way to remove an observation
+</whenToUseThisTool>
+
+<parameters>
+- observation_id: The revision to purge from (string, required)
+- confirm: Must be exactly 'PURGE' (string, required)
+</parameters>`;
+export const purgeObservationTool = {
+    capability: {
+        description: 'DESTRUCTIVE: physically delete an observation revision and its successors',
+        parameters: {
+            type: 'object',
+            properties: {
+                observation_id: { type: 'string', description: 'The revision to purge from' },
+                confirm: { type: 'string', description: "Must be exactly 'PURGE'" },
+            },
+            required: ['observation_id', 'confirm'],
+        },
+    },
+    description: purgeObservationDescription,
+    schema: {
+        observation_id: z.string().describe('The observation revision to purge from'),
+        confirm: z.literal('PURGE').describe("Must be exactly 'PURGE' - this destroys history"),
+    },
+    annotations: { destructiveHint: true },
+};
+const getObservationHistoryDescription = () => `<description>
+Return the full revision history of observations: every version, its status, its provenance, and
+the events that changed it.
+**Past versions come out here and nowhere else - ordinary search returns only 'active' revisions.**
+</description>
+
+<importantNotes>
+- (!important!) The response is always \`{ roots: [...] }\` - one root per logical observation
+- (!important!) Each root holds its revisions in order (revision_no ascending), oldest first
+- (!important!) Use this to answer "was this ever different?" or "where did this come from?"
+- (!important!) Exactly one selector is required
+</importantNotes>
+
+<whenToUseThisTool>
+- When you need to know whether a fact was corrected, and what it used to say
+- When you need the provenance (which document or decision) behind an observation
+- Before trusting a surprising fact - check whether it was already retracted or superseded
+- When auditing what changed in an entity's knowledge over time
+</whenToUseThisTool>
+
+<parameters>
+- entity_name: All observations of this entity (string, optional)
+- observation_id: The root that this revision belongs to (string, optional)
+- root_id: One specific logical observation (string, optional)
+</parameters>
+
+<examples>
+- {"entity_name": "claude-mem"}
+- {"observation_id": "…"}
+</examples>`;
+export const getObservationHistoryTool = {
+    capability: {
+        description: 'Full revision history of observations - the only surface for non-active revisions',
+        parameters: {
+            type: 'object',
+            properties: {
+                entity_name: { type: 'string', description: 'All observations of this entity' },
+                observation_id: { type: 'string', description: 'The root this revision belongs to' },
+                root_id: { type: 'string', description: 'One specific logical observation' },
+            },
+            required: [],
+        },
+    },
+    description: getObservationHistoryDescription,
+    schema: {
+        entity_name: z.string().optional().describe('All observations of this entity'),
+        observation_id: z.string().optional().describe('The root that this revision belongs to'),
+        root_id: z.string().optional().describe('One specific logical observation'),
+    },
+    annotations: { readOnlyHint: true },
+};
 // Export all knowledge graph tools
 export const knowledgeGraphTools = {
     createEntities: createEntitiesTool,
@@ -547,4 +778,12 @@ export const knowledgeGraphTools = {
     hybridSearch: hybridSearchTool,
     embedAllEntities: embedAllEntitiesTool,
     getDetailedContext: getDetailedContextTool,
+    // v13 observation lifecycle
+    correctObservation: correctObservationTool,
+    retractObservation: retractObservationTool,
+    restoreObservation: restoreObservationTool,
+    approveObservation: approveObservationTool,
+    declineObservation: declineObservationTool,
+    purgeObservation: purgeObservationTool,
+    getObservationHistory: getObservationHistoryTool,
 };

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

@@ -28,6 +28,13 @@ export declare const allTools: {
     hybridSearch: ToolDefinition;
     embedAllEntities: ToolDefinition;
     getDetailedContext: ToolDefinition;
+    correctObservation: ToolDefinition;
+    retractObservation: ToolDefinition;
+    restoreObservation: ToolDefinition;
+    approveObservation: ToolDefinition;
+    declineObservation: ToolDefinition;
+    purgeObservation: ToolDefinition;
+    getObservationHistory: ToolDefinition;
 };
 export declare const globalSettings: {
     version: string;

package/dist/src/tools/tool-registry.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { readFileSync } from 'node:fs';
 import { knowledgeGraphTools } from './knowledge-graph-tools.js';
 import { ragTools } from './rag-tools.js';
 import { graphQueryTools } from './graph-query-tools.js';
@@ -12,9 +13,12 @@ export const allTools = {
     ...graphAnalyticsTools,
     ...migrationTools,
 };
-// Global settings for tool descriptions
+// Global settings for tool descriptions.
+// version 은 package.json 이 정본이다. 하드코딩하면 릴리스마다 이 값만 옛 버전으로
+// 남아 도구 문서가 거짓을 말한다(실제로 3.1.0 에 멈춰 있었다 — advisor beta r3 남은 P2).
+const PKG = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
 export const globalSettings = {
-    version: '3.1.0',
+    version: PKG.version,
     systemName: 'RAG Knowledge Graph MCP Server',
     defaultTimeout: 60,
 };
@@ -41,6 +45,10 @@ export function convertToMCPTool(name, toolDef) {
             type: 'object',
             properties,
             required,
+            // validateToolArgs 가 최상위를 strict 로 검증한다. 광고 스키마가 그걸 말하지
+            // 않으면 클라이언트는 여분 필드가 허용된다고 읽고 서버에서 거부당한다
+            // (advisor beta r3: 계약 표현 불일치).
+            additionalProperties: false,
         },
         ...(toolDef.annotations && { annotations: toolDef.annotations }),
     };
@@ -90,6 +98,10 @@ function zodTypeToJsonSchema(zodType, fieldName) {
                     description: def.description || `${fieldName} object`,
                     properties: objectProperties,
                     required: objectRequired,
+                    // 런타임이 strict 면 광고도 strict 라고 말해야 한다. 안 그러면 클라이언트가
+                    // 여분 키를 허용된다고 읽고 서버에서 거부당한다 — importGraph.data 가
+                    // 정확히 그 상태였다(advisor beta r4 남은 P2).
+                    ...(def.unknownKeys === 'strict' && { additionalProperties: false }),
                 };
             case 'ZodRecord':
                 return {
@@ -97,6 +109,30 @@ function zodTypeToJsonSchema(zodType, fieldName) {
                     description: def.description || `${fieldName} record`,
                     additionalProperties: true,
                 };
+            // Enums and literals used to fall through to the string fallback, which dropped the
+            // allowed values from the advertised schema even though parse() still enforced them.
+            // A client that cannot see the values guesses, and the guess is rejected server-side.
+            case 'ZodEnum':
+                return {
+                    type: 'string',
+                    description: def.description || `${fieldName} parameter`,
+                    enum: [...def.values],
+                };
+            case 'ZodLiteral':
+                return {
+                    type: typeof def.value === 'number' ? 'number'
+                        : typeof def.value === 'boolean' ? 'boolean' : 'string',
+                    description: def.description || `${fieldName} parameter`,
+                    enum: [def.value],
+                };
+            // union 도 같은 fallback 함정이었다: deleteDocuments 의 documentIds 는
+            // string | string[] 인데 광고 스키마에 type:'string' 으로 나가 배열을 보내면
+            // 클라이언트가 계약 위반이라고 읽는다. anyOf 로 정직하게 노출한다.
+            case 'ZodUnion':
+                return {
+                    description: def.description || `${fieldName} parameter`,
+                    anyOf: def.options.map((o, i) => zodTypeToJsonSchema(o, `${fieldName} option ${i}`)),
+                };
             case 'ZodOptional':
                 const innerSchema = zodTypeToJsonSchema(def.innerType, fieldName);
                 return {
@@ -143,7 +179,11 @@ export function validateToolArgs(toolName, args) {
     if (!toolDef) {
         throw new Error(`Unknown tool: ${toolName}`);
     }
-    const schema = z.object(toolDef.schema);
+    // strict: 알 수 없는 최상위 인자는 거부한다. 기본 strip 은 오래된 호출자를
+    // **조용히** 통과시킨다 — v3.6 의 index 기반 관찰 지정(`{observation_id, index}`,
+    // `{observation_index}`)이 아무 오류 없이 무시되고, 호출자는 자기가 지정한
+    // revision 이 아닌 다른 것이 처리됐다는 사실을 모른다(spec T6, advisor beta 발견 4-1).
+    const schema = z.object(toolDef.schema).strict();
     return schema.parse(args);
 }
 /**

package/dist/src/tools/types.d.ts

@@ -36,6 +36,7 @@ export interface MCPTool {
         type: 'object';
         properties: Record<string, any>;
         required: string[];
+        additionalProperties?: boolean;
     };
     annotations?: ToolAnnotations;
 }