@danielsimonjr/memory-mcp 12.5.2 → 12.7.0

package/dist/server/toolHandlers.js

@@ -8,7 +8,7 @@
  * @module server/toolHandlers
  */
 import path from 'node:path';
-import { formatToolResponse, formatTextResponse, formatRawResponse, validateWithSchema, validateFilePath, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, AddObservationsInputSchema, DeleteObservationsInputSchema, ArchiveCriteriaSchema, SavedSearchInputSchema, SavedSearchUpdateSchema, ImportFormatSchema, ExtendedExportFormatSchema, MergeStrategySchema, ExportFilterSchema, SearchQuerySchema, HybridSearchManager, QueryAnalyzer, QueryPlanner, ReflectionManager, ObservationNormalizer, RefIndex, AuditLog, GovernanceManager, FreshnessManager, ArtifactManager, CollaborativeSynthesis, FailureDistillation, CognitiveLoadAnalyzer, ConsolidationScheduler, DreamEngine, DistillationPipeline, DefaultDistillationPolicy, NoOpDistillationPolicy, computeEntropy, passesEntropyFilter, EntropyFilterStage, getRoleProfile, listRoleProfiles, QueryCostEstimator, ContradictionDetector, PiiRedactor, DecisionManager, RankedSearch, clearAllSearchCaches, getAllCacheStats, } from '@danielsimonjr/memoryjs';
+import { formatToolResponse, formatTextResponse, formatRawResponse, validateWithSchema, validateFilePath, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, AddObservationsInputSchema, DeleteObservationsInputSchema, ArchiveCriteriaSchema, SavedSearchInputSchema, SavedSearchUpdateSchema, ImportFormatSchema, ExtendedExportFormatSchema, MergeStrategySchema, ExportFilterSchema, SearchQuerySchema, HybridSearchManager, QueryAnalyzer, QueryPlanner, ReflectionManager, ObservationNormalizer, RefIndex, FreshnessManager, ArtifactManager, CollaborativeSynthesis, FailureDistillation, CognitiveLoadAnalyzer, ConsolidationScheduler, DreamEngine, DistillationPipeline, DefaultDistillationPolicy, NoOpDistillationPolicy, computeEntropy, passesEntropyFilter, EntropyFilterStage, getRoleProfile, listRoleProfiles, QueryCostEstimator, ContradictionDetector, PiiRedactor, DecisionManager, RankedSearch, RelationConsolidator, clearAllSearchCaches, getAllCacheStats, } from '@danielsimonjr/memoryjs';
 import { promises as fs } from 'node:fs';
 import { performance } from 'node:perf_hooks';
 import { z } from 'zod';
@@ -17,8 +17,6 @@ import { maybeCompressResponse } from './responseCompressor.js';
 // WeakMap-based singletons keyed on ManagerContext to avoid re-instantiation per request.
 // These managers are not on ManagerContext directly, so we wire them up once per ctx.
 const refIndexMap = new WeakMap();
-const auditLogMap = new WeakMap();
-const governanceMap = new WeakMap();
 const freshnessMap = new WeakMap();
 const artifactManagerMap = new WeakMap();
 const distillationPipelineMap = new WeakMap();
@@ -42,6 +40,14 @@ function getStorageFilePath(ctx) {
     const storage = ctx.storage;
     return storage.memoryFilePath ?? storage.filePath ?? 'memory.jsonl';
 }
+// Sidecar path for the serialized Cue–Tag–Content graph, following the
+// library's `<basename>-<suffix>` convention (memory.jsonl → memory-reconstructive.json).
+function reconstructiveSidecarPath(ctx) {
+    const storagePath = getStorageFilePath(ctx);
+    const ext = path.extname(storagePath);
+    const base = ext ? storagePath.slice(0, -ext.length) : storagePath;
+    return `${base}-reconstructive.json`;
+}
 function getRefIndex(ctx) {
     if (!refIndexMap.has(ctx)) {
         const storagePath = getStorageFilePath(ctx);
@@ -50,22 +56,6 @@ function getRefIndex(ctx) {
     }
     return refIndexMap.get(ctx);
 }
-function getAuditLog(ctx) {
-    if (!auditLogMap.has(ctx)) {
-        const storagePath = getStorageFilePath(ctx);
-        const dir = path.dirname(storagePath);
-        auditLogMap.set(ctx, new AuditLog(path.join(dir, 'memory-audit.jsonl')));
-    }
-    return auditLogMap.get(ctx);
-}
-function getGovernanceManager(ctx) {
-    if (!governanceMap.has(ctx)) {
-        // GovernanceManager constructor accepts GraphStorage; ctx.storage is GraphStorage
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        governanceMap.set(ctx, new GovernanceManager(ctx.storage, getAuditLog(ctx)));
-    }
-    return governanceMap.get(ctx);
-}
 function getFreshnessManager(ctx) {
     if (!freshnessMap.has(ctx)) {
         freshnessMap.set(ctx, new FreshnessManager(ctx.storage));
@@ -438,7 +428,33 @@ export const toolHandlers = {
         const limit = args.limit !== undefined
             ? validateWithSchema(args.limit, z.number().int().positive().max(200), 'Invalid limit')
             : 10;
-        const hybridSearch = new HybridSearchManager(ctx.semanticSearch, ctx.rankedSearch);
+        const graphWeight = args.graphWeight !== undefined
+            ? validateWithSchema(args.graphWeight, z.number().min(0).max(1), 'Invalid graphWeight')
+            : undefined;
+        const expandNeighborsArgs = args.expandNeighbors !== undefined
+            ? validateWithSchema(args.expandNeighbors, z.object({
+                topK: z.number().int().positive().max(100).optional(),
+                damping: z.number().min(0).max(1).optional(),
+            }).strict(), 'Invalid expandNeighbors')
+            : undefined;
+        // Only 1-hop expansion is supported by memoryjs, so `hops` is fixed here
+        // rather than exposed in the tool schema.
+        const expandNeighbors = expandNeighborsArgs !== undefined
+            ? { hops: 1, ...expandNeighborsArgs }
+            : undefined;
+        const explain = args.explain !== undefined
+            ? validateWithSchema(args.explain, z.boolean(), 'Invalid explain flag')
+            : undefined;
+        const lookFor = args.lookFor !== undefined
+            ? validateWithSchema(args.lookFor, z.string().min(1), 'Invalid lookFor')
+            : undefined;
+        // ctx.hybridSearchManager only attaches the GraphRankPrior when
+        // MEMORY_HYBRID_GRAPH_WEIGHT is set; per-call graph options need the prior
+        // wired explicitly or they would be silently inert.
+        const wantsGraphChannel = (graphWeight !== undefined && graphWeight > 0) || expandNeighbors !== undefined;
+        const hybridSearch = wantsGraphChannel
+            ? new HybridSearchManager(ctx.semanticSearch, ctx.rankedSearch, ctx.graphRankPrior)
+            : ctx.hybridSearchManager;
         const graph = await ctx.storage.loadGraph();
         const results = await hybridSearch.searchWithEntities(graph, query, {
             semanticWeight: weights?.semantic ?? 0.5,
@@ -456,6 +472,10 @@ export const toolHandlers = {
                 }
                 : undefined,
             limit,
+            graphWeight,
+            expandNeighbors,
+            explain,
+            lookFor,
         });
         return formatToolResponse({
             query,
@@ -463,6 +483,7 @@ export const toolHandlers = {
                 semantic: weights?.semantic ?? 0.5,
                 lexical: weights?.lexical ?? 0.3,
                 symbolic: weights?.symbolic ?? 0.2,
+                ...(graphWeight !== undefined ? { graph: graphWeight } : {}),
             },
             resultCount: results.length,
             results: results.map((r) => ({
@@ -472,6 +493,9 @@ export const toolHandlers = {
                 matchedLayers: r.matchedLayers,
                 observations: r.entity.observations.slice(0, 3),
                 tags: r.entity.tags,
+                ...(r.evidencePaths !== undefined ? { evidencePaths: r.evidencePaths } : {}),
+                ...(r.evidenceTruncated !== undefined ? { evidenceTruncated: r.evidenceTruncated } : {}),
+                ...(r.lookForScore !== undefined ? { lookForScore: r.lookForScore } : {}),
             })),
         });
     },
@@ -512,7 +536,7 @@ export const toolHandlers = {
             const planner = new QueryPlanner();
             plan = planner.createPlan(query, analysis);
         }
-        const hybridSearch = new HybridSearchManager(ctx.semanticSearch, ctx.rankedSearch);
+        const hybridSearch = ctx.hybridSearchManager;
         const reflection = new ReflectionManager(hybridSearch, analyzer);
         const graph = await ctx.storage.loadGraph();
         const result = await reflection.retrieveWithReflection(graph, query, {
@@ -1076,7 +1100,7 @@ export const toolHandlers = {
     },
     // ==================== GOVERNANCE HANDLERS ====================
     set_governance_policy: async (ctx, args) => {
-        const gm = getGovernanceManager(ctx);
+        const gm = ctx.governanceManager;
         // GovernancePolicy uses function callbacks; we translate boolean args into allow/deny functions
         const allowCreate = args.canCreate !== undefined
             ? validateWithSchema(args.canCreate, z.boolean(), 'Invalid canCreate')
@@ -1115,20 +1139,20 @@ export const toolHandlers = {
         const limit = args.limit !== undefined
             ? validateWithSchema(args.limit, z.number().int().min(1).max(1000), 'Invalid limit')
             : 50;
-        const al = getAuditLog(ctx);
+        const al = ctx.governanceManager.auditLog;
         let entries = await al.query(filter);
         entries = entries.slice(0, limit);
         return formatToolResponse({ entries, count: entries.length });
     },
     audit_history: async (ctx, args) => {
         const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
-        const al = getAuditLog(ctx);
+        const al = ctx.governanceManager.auditLog;
         const entries = await al.getHistory(entityName);
         return formatToolResponse({ entityName, entries, count: entries.length });
     },
     rollback_operation: async (ctx, args) => {
         const auditEntryId = validateWithSchema(args.auditEntryId, z.string().min(1), 'Invalid auditEntryId');
-        const gm = getGovernanceManager(ctx);
+        const gm = ctx.governanceManager;
         await gm.rollback(auditEntryId);
         return formatTextResponse(`Operation "${auditEntryId}" rolled back successfully`);
     },
@@ -2745,6 +2769,198 @@ export const toolHandlers = {
             inDegree: incoming.length,
         });
     },
+    // ==================== EVENT MEMORY HANDLERS (memoryjs v3.0.0) ====================
+    record_event: async (ctx, args) => {
+        const input = validateWithSchema(args, z.object({
+            action: z.string().min(1),
+            actor: z.string().min(1),
+            target: z.string().min(1).optional(),
+            context: z.string().min(1).optional(),
+            participants: z.array(z.string().min(1)).optional(),
+            occurredAt: z.string().min(1).optional(),
+            flowKey: z.string().min(1).optional(),
+            detail: z.array(z.string()).optional(),
+            importance: z.number().optional(),
+        }).strict(), 'Invalid event input');
+        const event = await ctx.eventManager.recordEvent(input);
+        return formatToolResponse({ event });
+    },
+    get_event: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid event name');
+        const event = await ctx.eventManager.getEvent(name);
+        if (!event) {
+            return formatTextResponse(`Event "${name}" not found`);
+        }
+        return formatToolResponse({ event });
+    },
+    query_events: async (ctx, args) => {
+        const filter = validateWithSchema(args, z.object({
+            actor: z.string().min(1).optional(),
+            target: z.string().min(1).optional(),
+            action: z.string().min(1).optional(),
+            flowKey: z.string().min(1).optional(),
+            timeRange: z.object({
+                start: z.string().min(1).optional(),
+                end: z.string().min(1).optional(),
+            }).strict().optional(),
+            limit: z.number().int().positive().max(1000).optional(),
+        }).strict(), 'Invalid event filter');
+        const events = await ctx.eventManager.queryEvents(filter);
+        return formatToolResponse({ events, count: events.length });
+    },
+    get_event_flow: async (ctx, args) => {
+        const flowKey = validateWithSchema(args.flowKey, z.string().min(1), 'Invalid flowKey');
+        const events = await ctx.eventManager.getFlow(flowKey);
+        return formatToolResponse({ flowKey, events, count: events.length });
+    },
+    who_did_what: async (ctx, args) => {
+        const filter = validateWithSchema(args, z.object({
+            target: z.string().min(1).optional(),
+            context: z.string().min(1).optional(),
+            timeRange: z.object({
+                start: z.string().min(1).optional(),
+                end: z.string().min(1).optional(),
+            }).strict().optional(),
+            limit: z.number().int().positive().max(1000).optional(),
+        }).strict(), 'Invalid filter');
+        const entries = await ctx.eventManager.whoDidWhat(filter);
+        return formatToolResponse({ entries, count: entries.length });
+    },
+    // ==================== RECONSTRUCTIVE MEMORY HANDLERS (memoryjs v3.0.0) ====================
+    ingest_dialogue: async (ctx, args) => {
+        const turns = validateWithSchema(args.turns, z.array(z.object({
+            id: z.string().min(1),
+            speaker: z.string().optional(),
+            text: z.string().min(1),
+            timestamp: z.string().optional(),
+        }).strict()).min(1), 'Invalid dialogue turns');
+        const rm = ctx.reconstructiveMemory();
+        const result = await rm.ingest(turns);
+        return formatToolResponse({
+            distillation: result,
+            persisted: rm.lastPersistResult,
+            stats: rm.stats(),
+        });
+    },
+    reconstruct_memory: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const options = validateWithSchema({
+            maxSteps: args.maxSteps,
+            perStepBudget: args.perStepBudget,
+            evidenceTarget: args.evidenceTarget,
+        }, z.object({
+            maxSteps: z.number().int().positive().max(32).optional(),
+            perStepBudget: z.number().int().positive().max(100).optional(),
+            evidenceTarget: z.number().int().positive().max(100).optional(),
+        }), 'Invalid reconstruction options');
+        const result = await ctx.reconstructiveMemory().reconstruct(query, options);
+        return formatToolResponse(result);
+    },
+    reconstructive_memory_stats: async (ctx) => {
+        return formatToolResponse(ctx.reconstructiveMemory().stats());
+    },
+    // ==================== RELATION CONSOLIDATION HANDLERS (memoryjs v3.0.0) ====================
+    analyze_relation_duplicates: async (ctx) => {
+        const consolidator = new RelationConsolidator(ctx.relationManager, ctx.entityManager, {
+            embedding: ctx.semanticSearch?.getEmbeddingService(),
+        });
+        const report = await consolidator.analyze();
+        return formatToolResponse(report);
+    },
+    consolidate_relations: async (ctx, args) => {
+        const apply = args.apply !== undefined
+            ? validateWithSchema(args.apply, z.boolean(), 'Invalid apply flag')
+            : false;
+        const consolidator = new RelationConsolidator(ctx.relationManager, ctx.entityManager, {
+            embedding: ctx.semanticSearch?.getEmbeddingService(),
+        });
+        const result = await consolidator.consolidate({ apply });
+        return formatToolResponse(result);
+    },
+    // ==================== AGENT REFLECTION HANDLERS (memoryjs v3.0.0) ====================
+    create_reflection: async (ctx, args) => {
+        const parsed = validateWithSchema(args, z.object({
+            scope: z.enum(['session', 'project', 'global']),
+            summary: z.string().min(1),
+            evidence: z.array(z.string().min(1)).min(1),
+            generalizationConfidence: z.number().min(0).max(1),
+            keyInsights: z.array(z.string().min(1)).max(5).optional(),
+            experienceType: z.string().min(1).optional(),
+            sourceSessionId: z.string().min(1).optional(),
+            sourceProjectId: z.string().min(1).optional(),
+            importance: z.number().optional(),
+            agentId: z.string().min(1).optional(),
+        }).strict(), 'Invalid reflection input');
+        const reflection = await ctx.reflectionManager.create({
+            scope: parsed.scope,
+            summary: parsed.summary,
+            evidence: parsed.evidence,
+            generalization_confidence: parsed.generalizationConfidence,
+            keyInsights: parsed.keyInsights,
+            experienceType: parsed.experienceType,
+            sourceSessionId: parsed.sourceSessionId,
+            sourceProjectId: parsed.sourceProjectId,
+        }, { importance: parsed.importance, agentId: parsed.agentId });
+        return formatToolResponse({ reflection });
+    },
+    list_reflections: async (ctx, args) => {
+        const options = validateWithSchema(args, z.object({
+            scope: z.enum(['session', 'project', 'global']).optional(),
+            sourceSessionId: z.string().min(1).optional(),
+            sourceProjectId: z.string().min(1).optional(),
+            minConfidence: z.number().min(0).max(1).optional(),
+            includeArchived: z.boolean().optional(),
+            limit: z.number().int().positive().max(1000).optional(),
+        }).strict(), 'Invalid list options');
+        const reflections = await ctx.reflectionManager.list(options);
+        return formatToolResponse({ reflections, count: reflections.length });
+    },
+    get_relevant_reflections: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const options = validateWithSchema({
+            sessionEntityNames: args.sessionEntityNames,
+            minConfidence: args.minConfidence,
+            limit: args.limit,
+        }, z.object({
+            sessionEntityNames: z.array(z.string().min(1)).optional(),
+            minConfidence: z.number().min(0).max(1).optional(),
+            limit: z.number().int().positive().max(1000).optional(),
+        }), 'Invalid relevance options');
+        const reflections = await ctx.reflectionManager.getRelevantForSession(sessionId, options);
+        return formatToolResponse({ sessionId, reflections, count: reflections.length });
+    },
+    archive_reflection: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid reflection id');
+        const result = await ctx.reflectionManager.archive(id);
+        return formatToolResponse(result);
+    },
+    // ==================== RECONSTRUCTIVE MEMORY PERSISTENCE HANDLERS (memoryjs v3.0.0) ====================
+    save_reconstructive_memory: async (ctx) => {
+        const rm = ctx.reconstructiveMemory();
+        const snapshot = rm.toSnapshot();
+        const sidecarPath = reconstructiveSidecarPath(ctx);
+        await fs.writeFile(sidecarPath, JSON.stringify(snapshot), 'utf-8');
+        return formatToolResponse({ path: sidecarPath, stats: rm.stats() });
+    },
+    load_reconstructive_memory: async (ctx) => {
+        const sidecarPath = reconstructiveSidecarPath(ctx);
+        let raw;
+        try {
+            raw = await fs.readFile(sidecarPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`No reconstructive memory snapshot at "${sidecarPath}" — run save_reconstructive_memory first`);
+        }
+        const snapshot = validateWithSchema(JSON.parse(raw), z.object({
+            cues: z.array(z.unknown()),
+            tags: z.array(z.unknown()),
+            contents: z.array(z.unknown()),
+            triples: z.array(z.unknown()),
+        }), `Invalid reconstructive memory snapshot at "${sidecarPath}"`);
+        const rm = ctx.reconstructiveMemory();
+        rm.loadSnapshot(snapshot);
+        return formatToolResponse({ path: sidecarPath, stats: rm.stats() });
+    },
 };
 /**
  * Handle a tool call by dispatching to the appropriate handler.

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Types Module - Barrel Export
+ *
+ * Central export point for all type definitions used throughout the
+ * Memory MCP Server. All types are consolidated in types.ts (Phase 5 cleanup).
+ *
+ * @example
+ * ```typescript
+ * import { Entity, Relation, KnowledgeGraph, SearchResult } from './types/index.js';
+ * ```
+ */
+export type { Entity, Relation, KnowledgeGraph, ReadonlyKnowledgeGraph, SearchResult, SavedSearch, BooleanQueryNode, DocumentVector, TFIDFIndex, FuzzyCacheKey, BooleanCacheEntry, PaginatedCacheEntry, TokenizedEntity, GraphStats, ValidationReport, ValidationIssue, ValidationWarning, CacheCompressionStats, ArchiveResultExtended, ExportFilter, ExportOptions, ExportResult, ImportResult, CompressionResult, BackupOptions, BackupResult, RestoreResult, BackupMetadataExtended, BackupInfoExtended, TagAlias, IGraphStorage, StorageConfig, LowercaseData, TraversalOptions, TraversalResult, PathResult, ConnectedComponentsResult, CentralityResult, WeightedRelation, EmbeddingService, SemanticSearchResult, IVectorStore, VectorSearchResult, EmbeddingConfig, SemanticIndexOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EAEV,MAAM,EACN,QAAQ,EACR,cAAc,EACd,sBAAsB,EAEtB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,UAAU,EAEV,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EAEf,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EAErB,qBAAqB,EAErB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EAEjB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAElB,QAAQ,EAER,aAAa,EACb,aAAa,EACb,aAAa,EAEb,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,yBAAyB,EACzB,gBAAgB,EAChB,gBAAgB,EAEhB,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,12 @@
+/**
+ * Types Module - Barrel Export
+ *
+ * Central export point for all type definitions used throughout the
+ * Memory MCP Server. All types are consolidated in types.ts (Phase 5 cleanup).
+ *
+ * @example
+ * ```typescript
+ * import { Entity, Relation, KnowledgeGraph, SearchResult } from './types/index.js';
+ * ```
+ */
+export {};