@danielsimonjr/memory-mcp 12.2.3 → 12.7.0

package/dist/server/toolHandlers.js

@@ -8,15 +8,15 @@
  * @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, } 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';
 import { maybeCompressResponse } from './responseCompressor.js';
 // ==================== SINGLETON INFRASTRUCTURE ====================
 // 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();
@@ -24,9 +24,29 @@ const failureDistillationMap = new WeakMap();
 const consolidationSchedulerMap = new WeakMap();
 const dreamEngineMap = new WeakMap();
 const queryCostEstimatorMap = new WeakMap();
+// Active project scope (Phase 13 deferred item; ctx.defaultProjectId is readonly,
+// so we keep mutable scope state in a WeakMap keyed on the context. Set via the
+// `set_project_scope` tool; handlers may consult `getActiveProjectScope(ctx)`
+// when they want to auto-apply the scope.
+const projectScopeMap = new WeakMap();
+export function getActiveProjectScope(ctx) {
+    return projectScopeMap.get(ctx);
+}
 function getStorageFilePath(ctx) {
-    // GraphStorage exposes filePath publicly; fall back to cwd-relative default
-    return ctx.storage.filePath ?? 'memory.jsonl';
+    // GraphStorage stores the path on `memoryFilePath` (private but reachable via
+    // type-cast). Older versions of this helper looked for `filePath` and
+    // silently fell back to 'memory.jsonl' — which made diag / size / reindex
+    // reports point at the wrong file. Try both field names defensively.
+    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)) {
@@ -36,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));
@@ -125,11 +129,43 @@ async function withCompression(handler) {
  * Filtered/limited search tools (search_nodes_ranked, fuzzy_search, etc.) are not
  * wrapped because their results are bounded by query specificity or limit params.
  */
+/**
+ * v2.1.0 — Parse `find_duplicate_observations` / `find_jaccard_duplicate_observations`
+ * filter args into the manager's `ObservationDedupFilter` shape. Validates each
+ * field independently so a stray garbage value falls back to the manager default
+ * rather than throwing — REST-like leniency since these are diagnostic tools.
+ */
+function parseObservationDedupFilter(args) {
+    const out = {};
+    if (typeof args.entityType === 'string') {
+        out.entityType = args.entityType;
+    }
+    else if (Array.isArray(args.entityType) && args.entityType.every((s) => typeof s === 'string')) {
+        out.entityType = args.entityType;
+    }
+    if (typeof args.projectId === 'string')
+        out.projectId = args.projectId;
+    if (typeof args.sessionId === 'string')
+        out.sessionId = args.sessionId;
+    if (typeof args.minOccurrences === 'number' && Number.isFinite(args.minOccurrences) && args.minOccurrences >= 2) {
+        out.minOccurrences = args.minOccurrences;
+    }
+    if (typeof args.maxGroups === 'number' && Number.isFinite(args.maxGroups) && args.maxGroups >= 1) {
+        out.maxGroups = args.maxGroups;
+    }
+    return out;
+}
 export const toolHandlers = {
     // ==================== ENTITY HANDLERS ====================
     create_entities: async (ctx, args) => {
         const entities = validateWithSchema(args.entities, BatchCreateEntitiesSchema, 'Invalid entities data');
-        return formatToolResponse(await ctx.entityManager.createEntities(entities));
+        // Phase 13 (v12.4.0): auto-stamp active project scope on entities lacking
+        // an explicit projectId. Set via set_project_scope; explicit projectId wins.
+        const activeScope = getActiveProjectScope(ctx);
+        const scoped = activeScope
+            ? entities.map((e) => (e.projectId === undefined ? { ...e, projectId: activeScope } : e))
+            : entities;
+        return formatToolResponse(await ctx.entityManager.createEntities(scoped));
     },
     delete_entities: async (ctx, args) => {
         const entityNames = validateWithSchema(args.entityNames, EntityNamesSchema, 'Invalid entity names');
@@ -148,6 +184,19 @@ export const toolHandlers = {
         const projects = await ctx.entityManager.listProjects();
         return formatToolResponse({ projects, count: projects.length });
     },
+    set_project_scope: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string(), 'Invalid projectId');
+        if (projectId === '') {
+            projectScopeMap.delete(ctx);
+            return formatToolResponse({ projectId: null });
+        }
+        projectScopeMap.set(ctx, projectId);
+        return formatToolResponse({ projectId });
+    },
+    get_project_scope: async (ctx, _args) => {
+        const projectId = projectScopeMap.get(ctx) ?? null;
+        return formatToolResponse({ projectId });
+    },
     get_entity_versions: async (ctx, args) => {
         const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
         const latest = await ctx.entityManager.getLatestVersion(entityName);
@@ -242,10 +291,20 @@ export const toolHandlers = {
         const entityName = args.entityName !== undefined
             ? validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name')
             : undefined;
-        const options = args.options ?? {};
+        const options = args.options !== undefined
+            ? validateWithSchema(args.options, z.object({
+                resolveCoreferences: z.boolean().optional(),
+                anchorTimestamps: z.boolean().optional(),
+                extractKeywords: z.boolean().optional(),
+            }).strict(), 'Invalid options')
+            : {};
         const persist = args.persist === true;
         const normalizer = new ObservationNormalizer();
-        const graph = await ctx.storage.loadGraph();
+        // Use getGraphForMutation() to acquire the storage write lock — prevents
+        // concurrent calls from overwriting each other's persisted normalizations.
+        const graph = persist
+            ? await ctx.storage.getGraphForMutation()
+            : await ctx.storage.loadGraph();
         const entities = entityName
             ? graph.entities.filter(e => e.name === entityName)
             : graph.entities;
@@ -350,12 +409,52 @@ export const toolHandlers = {
     // Phase 11 Sprint 2: Hybrid search
     hybrid_search: async (ctx, args) => {
         const query = validateWithSchema(args.query, SearchQuerySchema, 'Invalid search query');
-        const weights = args.weights;
-        const filters = args.filters;
+        const weights = args.weights !== undefined
+            ? validateWithSchema(args.weights, z.object({
+                semantic: z.number().optional(),
+                lexical: z.number().optional(),
+                symbolic: z.number().optional(),
+            }).strict(), 'Invalid weights')
+            : undefined;
+        const filters = args.filters !== undefined
+            ? validateWithSchema(args.filters, z.object({
+                tags: z.array(z.string()).optional(),
+                entityTypes: z.array(z.string()).optional(),
+                dateRange: z.object({ start: z.string(), end: z.string() }).strict().optional(),
+                minImportance: z.number().optional(),
+                maxImportance: z.number().optional(),
+            }).strict(), 'Invalid filters')
+            : undefined;
         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,
@@ -373,6 +472,10 @@ export const toolHandlers = {
                 }
                 : undefined,
             limit,
+            graphWeight,
+            expandNeighbors,
+            explain,
+            lookFor,
         });
         return formatToolResponse({
             query,
@@ -380,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) => ({
@@ -389,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 } : {}),
             })),
         });
     },
@@ -429,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, {
@@ -863,7 +970,7 @@ export const toolHandlers = {
         const entityName = args.entityName !== undefined
             ? validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName')
             : undefined;
-        const refs = await getRefIndex(ctx).listRefs(entityName ? { entityName } : undefined);
+        const refs = await getRefIndex(ctx).listRefs(entityName);
         return formatToolResponse({ refs, count: refs.length });
     },
     // ==================== ARTIFACT HANDLERS ====================
@@ -993,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')
@@ -1032,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`);
     },
@@ -1274,7 +1381,9 @@ export const toolHandlers = {
         const distillFailures = args.distillFailures !== undefined
             ? validateWithSchema(args.distillFailures, z.boolean(), 'Invalid distillFailures')
             : true;
-        const graph = await ctx.storage.loadGraph();
+        // Use getGraphForMutation() to acquire the storage write lock — prevents
+        // concurrent end_session calls from clobbering each other's outcome writes.
+        const graph = await ctx.storage.getGraphForMutation();
         const sessionEntity = graph.entities.find(e => e.name === sessionId);
         if (!sessionEntity) {
             return formatTextResponse(`Session "${sessionId}" not found`);
@@ -1718,7 +1827,7 @@ export const toolHandlers = {
     // ==================== η.5.5.c OCC HANDLER ====================
     update_entity: async (ctx, args) => {
         const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
-        const updates = validateWithSchema(args.updates, z.record(z.unknown()), 'Invalid updates');
+        const updates = validateWithSchema(args.updates, z.record(z.string(), z.unknown()), 'Invalid updates');
         const expectedVersion = args.expectedVersion !== undefined
             ? validateWithSchema(args.expectedVersion, z.number().int().positive(), 'Invalid expectedVersion')
             : undefined;
@@ -1897,6 +2006,961 @@ export const toolHandlers = {
         const chains = await ctx.worldModelManager.predictOutcome(action, candidates);
         return formatToolResponse({ action, candidates, chains, count: chains.length });
     },
+    // ==================== v2.1.0 TOOL AFFORDANCE ====================
+    record_tool_outcome: async (ctx, args) => {
+        const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');
+        const outcome = validateWithSchema(args.outcome, z.enum(['success', 'failure', 'partial']), 'Invalid outcome');
+        const errorMessage = args.errorMessage === undefined
+            ? undefined
+            : validateWithSchema(args.errorMessage, z.string(), 'Invalid errorMessage');
+        const durationMs = args.durationMs === undefined
+            ? undefined
+            : validateWithSchema(args.durationMs, z.number().min(0), 'Invalid durationMs');
+        const record = await ctx.toolAffordanceManager.recordOutcome(toolName, {
+            outcome,
+            errorMessage,
+            durationMs,
+        });
+        return formatToolResponse({ record });
+    },
+    get_tool_affordance_stats: async (ctx, args) => {
+        const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');
+        const stats = ctx.toolAffordanceManager.rollingStats(toolName);
+        return formatToolResponse({ toolName, stats: stats ?? null });
+    },
+    suggest_tool: async (ctx, args) => {
+        const taskHint = validateWithSchema(args.taskHint, z.string().min(1), 'Invalid taskHint');
+        const limit = args.limit === undefined
+            ? undefined
+            : validateWithSchema(args.limit, z.number().int().min(1), 'Invalid limit');
+        const minScore = args.minScore === undefined
+            ? undefined
+            : validateWithSchema(args.minScore, z.number().min(0).max(1), 'Invalid minScore');
+        const suggestions = await ctx.toolAffordanceManager.suggestTool(taskHint, { limit, minScore });
+        return formatToolResponse({ taskHint, suggestions, count: suggestions.length });
+    },
+    list_tool_affordances: async (ctx) => {
+        const records = await ctx.toolAffordanceManager.list();
+        return formatToolResponse({ records, count: records.length });
+    },
+    remove_tool_affordance: async (ctx, args) => {
+        const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');
+        const removed = await ctx.toolAffordanceManager.remove(toolName);
+        return formatToolResponse({ toolName, removed });
+    },
+    observe_tool_start: (ctx, args) => {
+        const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');
+        const argsField = args.args === undefined
+            ? undefined
+            : validateWithSchema(args.args, z.record(z.string(), z.unknown()), 'Invalid args (must be an object)');
+        const callId = ctx.toolCallObserver.observeStart(toolName, argsField);
+        return Promise.resolve(formatToolResponse({ callId, toolName }));
+    },
+    observe_tool_complete: async (ctx, args) => {
+        const callId = validateWithSchema(args.callId, z.string().min(1), 'Invalid callId');
+        const result = args.result === undefined
+            ? undefined
+            : validateWithSchema(args.result, z.string(), 'Invalid result');
+        await ctx.toolCallObserver.observeComplete(callId, result === undefined ? undefined : { result });
+        return formatToolResponse({ callId, recorded: 'success' });
+    },
+    observe_tool_error: async (ctx, args) => {
+        const callId = validateWithSchema(args.callId, z.string().min(1), 'Invalid callId');
+        const errorMessage = validateWithSchema(args.errorMessage, z.string().min(1), 'Invalid errorMessage');
+        await ctx.toolCallObserver.observeError(callId, errorMessage);
+        return formatToolResponse({ callId, recorded: 'failure', errorMessage });
+    },
+    observe_tool_partial: async (ctx, args) => {
+        const callId = validateWithSchema(args.callId, z.string().min(1), 'Invalid callId');
+        const reason = validateWithSchema(args.reason, z.string().min(1), 'Invalid reason');
+        await ctx.toolCallObserver.observePartial(callId, reason);
+        return formatToolResponse({ callId, recorded: 'partial', reason });
+    },
+    observe_tool_cancel: (ctx, args) => {
+        const callId = validateWithSchema(args.callId, z.string().min(1), 'Invalid callId');
+        ctx.toolCallObserver.cancel(callId);
+        return Promise.resolve(formatToolResponse({ callId, cancelled: true }));
+    },
+    tool_observer_in_flight_count: (ctx) => {
+        const count = ctx.toolCallObserver.inFlightCount();
+        return Promise.resolve(formatToolResponse({ inFlightCount: count }));
+    },
+    // ==================== v2.1.0 HEURISTIC GUIDELINES ====================
+    add_heuristic: async (ctx, args) => {
+        const condition = validateWithSchema(args.condition, z.string().min(1), 'Invalid condition');
+        const action = validateWithSchema(args.action, z.string().min(1), 'Invalid action');
+        const priority = args.priority === undefined
+            ? undefined
+            : validateWithSchema(args.priority, z.number(), 'Invalid priority');
+        const initialConfidence = args.initialConfidence === undefined
+            ? undefined
+            : validateWithSchema(args.initialConfidence, z.number().min(0).max(1), 'Invalid initialConfidence');
+        const importance = args.importance === undefined
+            ? undefined
+            : validateWithSchema(args.importance, z.number().min(0).max(10), 'Invalid importance');
+        const agentId = args.agentId === undefined
+            ? undefined
+            : validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const id = args.id === undefined
+            ? undefined
+            : validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const heuristicId = await ctx.heuristicManager.add({
+            condition,
+            action,
+            priority,
+            initialConfidence,
+            importance,
+            agentId,
+            id: id,
+        });
+        return formatToolResponse({ id: heuristicId });
+    },
+    get_heuristic: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const heuristic = ctx.heuristicManager.get(id);
+        return formatToolResponse({ id, heuristic: heuristic ?? null });
+    },
+    list_heuristics: async (ctx) => {
+        const heuristics = await ctx.heuristicManager.list();
+        return formatToolResponse({ heuristics, count: heuristics.length });
+    },
+    heuristic_count: async (ctx) => {
+        const size = await ctx.heuristicManager.size();
+        return formatToolResponse({ count: size });
+    },
+    match_heuristics: async (ctx, args) => {
+        const input = validateWithSchema(args.input, z.string().min(1), 'Invalid input');
+        const limit = args.limit === undefined
+            ? undefined
+            : validateWithSchema(args.limit, z.number().int().min(1), 'Invalid limit');
+        const minScore = args.minScore === undefined
+            ? undefined
+            : validateWithSchema(args.minScore, z.number().min(0).max(1), 'Invalid minScore');
+        const matches = await ctx.heuristicManager.match(input, { limit, minScore });
+        return formatToolResponse({ input, matches, count: matches.length });
+    },
+    reinforce_heuristic: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const result = await ctx.heuristicManager.reinforce(id);
+        return formatToolResponse({ id, result });
+    },
+    record_heuristic_contradiction: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const result = await ctx.heuristicManager.recordContradiction(id);
+        return formatToolResponse({ id, result });
+    },
+    detect_heuristic_conflicts: async (ctx) => {
+        const conflicts = await ctx.heuristicManager.detectConflicts();
+        return formatToolResponse({ conflicts, count: conflicts.length });
+    },
+    remove_heuristic: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const removed = await ctx.heuristicManager.remove(id);
+        return formatToolResponse({ id, removed });
+    },
+    clear_heuristics: async (ctx) => {
+        await ctx.heuristicManager.clear();
+        return formatToolResponse({ cleared: true });
+    },
+    // ==================== v2.1.0 PROJECT CONTEXT ====================
+    upsert_project_context: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const facts = args.facts === undefined
+            ? undefined
+            : validateWithSchema(args.facts, z.array(z.string()), 'Invalid facts');
+        const conventions = args.conventions === undefined
+            ? undefined
+            : validateWithSchema(args.conventions, z.array(z.string()), 'Invalid conventions');
+        const commands = args.commands === undefined
+            ? undefined
+            : validateWithSchema(args.commands, z.array(z.object({
+                name: z.string().min(1),
+                command: z.string().min(1),
+                purpose: z.string().min(1),
+            })), 'Invalid commands');
+        const glossary = args.glossary === undefined
+            ? undefined
+            : validateWithSchema(args.glossary, z.array(z.object({
+                term: z.string().min(1),
+                definition: z.string().min(1),
+            })), 'Invalid glossary');
+        const record = await ctx.projectContextManager.upsert(projectId, {
+            facts, conventions, commands, glossary,
+        });
+        return formatToolResponse({ record });
+    },
+    get_project_context: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const record = ctx.projectContextManager.get(projectId);
+        return formatToolResponse({ projectId, record: record ?? null });
+    },
+    append_project_fact: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const fact = validateWithSchema(args.fact, z.string().min(1), 'Invalid fact');
+        const record = await ctx.projectContextManager.appendFact(projectId, fact);
+        return formatToolResponse({ record });
+    },
+    append_project_convention: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const convention = validateWithSchema(args.convention, z.string().min(1), 'Invalid convention');
+        const record = await ctx.projectContextManager.appendConvention(projectId, convention);
+        return formatToolResponse({ record });
+    },
+    append_project_command: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const command = validateWithSchema(args.command, z.string().min(1), 'Invalid command');
+        const purpose = validateWithSchema(args.purpose, z.string().min(1), 'Invalid purpose');
+        const record = await ctx.projectContextManager.appendCommand(projectId, { name, command, purpose });
+        return formatToolResponse({ record });
+    },
+    append_project_glossary_term: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const term = validateWithSchema(args.term, z.string().min(1), 'Invalid term');
+        const definition = validateWithSchema(args.definition, z.string().min(1), 'Invalid definition');
+        const record = await ctx.projectContextManager.appendGlossaryTerm(projectId, { term, definition });
+        return formatToolResponse({ record });
+    },
+    remove_project_fact: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const fact = validateWithSchema(args.fact, z.string().min(1), 'Invalid fact');
+        const removed = await ctx.projectContextManager.removeFact(projectId, fact);
+        return formatToolResponse({ projectId, fact, removed });
+    },
+    remove_project_convention: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const convention = validateWithSchema(args.convention, z.string().min(1), 'Invalid convention');
+        const removed = await ctx.projectContextManager.removeConvention(projectId, convention);
+        return formatToolResponse({ projectId, convention, removed });
+    },
+    remove_project_command: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const commandName = validateWithSchema(args.commandName, z.string().min(1), 'Invalid commandName');
+        const removed = await ctx.projectContextManager.removeCommand(projectId, commandName);
+        return formatToolResponse({ projectId, commandName, removed });
+    },
+    remove_project_glossary_term: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const term = validateWithSchema(args.term, z.string().min(1), 'Invalid term');
+        const removed = await ctx.projectContextManager.removeGlossaryTerm(projectId, term);
+        return formatToolResponse({ projectId, term, removed });
+    },
+    clear_project_context: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const cleared = await ctx.projectContextManager.clear(projectId);
+        return formatToolResponse({ projectId, cleared });
+    },
+    format_project_context_for_llm: async (ctx, args) => {
+        const projectId = validateWithSchema(args.projectId, z.string().min(1), 'Invalid projectId');
+        const budgetChars = args.budgetChars === undefined
+            ? undefined
+            : validateWithSchema(args.budgetChars, z.number().int().min(1), 'Invalid budgetChars');
+        const prose = await ctx.projectContextManager.forContext(projectId, { budgetChars });
+        return formatTextResponse(prose);
+    },
+    // ==================== v2.1.0 DECISION RATIONALE ====================
+    propose_decision: async (ctx, args) => {
+        const context = validateWithSchema(args.context, z.string().min(1), 'Invalid context');
+        const decision = validateWithSchema(args.decision, z.string().min(1), 'Invalid decision');
+        const alternatives = args.alternatives === undefined
+            ? []
+            : validateWithSchema(args.alternatives, z.array(z.string()), 'Invalid alternatives');
+        const consequences = args.consequences === undefined
+            ? []
+            : validateWithSchema(args.consequences, z.array(z.string()), 'Invalid consequences');
+        const relatedFiles = args.relatedFiles === undefined
+            ? undefined
+            : validateWithSchema(args.relatedFiles, z.array(z.string()), 'Invalid relatedFiles');
+        const supersedes = args.supersedes === undefined
+            ? undefined
+            : validateWithSchema(args.supersedes, z.string().min(1), 'Invalid supersedes');
+        const sourceSessionId = args.sourceSessionId === undefined
+            ? undefined
+            : validateWithSchema(args.sourceSessionId, z.string().min(1), 'Invalid sourceSessionId');
+        const sourceProjectId = args.sourceProjectId === undefined
+            ? undefined
+            : validateWithSchema(args.sourceProjectId, z.string().min(1), 'Invalid sourceProjectId');
+        const importance = args.importance === undefined
+            ? undefined
+            : validateWithSchema(args.importance, z.number().min(0).max(10), 'Invalid importance');
+        const agentId = args.agentId === undefined
+            ? undefined
+            : validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        // `supersedes` is a branded DecisionId at the type level; the
+        // manager casts internally so a string is fine here.
+        const record = await ctx.decisionManager.propose({
+            context,
+            decision,
+            alternatives,
+            consequences,
+            relatedFiles,
+            supersedes: supersedes,
+            sourceSessionId,
+            sourceProjectId,
+        }, { importance, agentId });
+        return formatToolResponse({ record });
+    },
+    accept_decision: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const result = await ctx.decisionManager.accept(id);
+        return formatToolResponse({ id, result });
+    },
+    reject_decision: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const reason = validateWithSchema(args.reason, z.string().min(1), 'Invalid reason');
+        const result = await ctx.decisionManager.reject(id, reason);
+        return formatToolResponse({ id, reason, result });
+    },
+    supersede_decision: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const by = validateWithSchema(args.by, z.string().min(1), 'Invalid by');
+        const result = await ctx.decisionManager.supersede(id, by);
+        return formatToolResponse({ id, by, result });
+    },
+    find_decisions_by_context: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const records = await ctx.decisionManager.findByContext(query);
+        return formatToolResponse({ query, records, count: records.length });
+    },
+    get_decision_chain: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const chain = await ctx.decisionManager.getChain(id);
+        return formatToolResponse({ id, chain, length: chain.length });
+    },
+    list_decisions: async (ctx, args) => {
+        const status = args.status === undefined
+            ? undefined
+            : validateWithSchema(args.status, z.enum(['proposed', 'accepted', 'superseded', 'rejected']), 'Invalid status');
+        const sourceSessionId = args.sourceSessionId === undefined
+            ? undefined
+            : validateWithSchema(args.sourceSessionId, z.string().min(1), 'Invalid sourceSessionId');
+        const sourceProjectId = args.sourceProjectId === undefined
+            ? undefined
+            : validateWithSchema(args.sourceProjectId, z.string().min(1), 'Invalid sourceProjectId');
+        const limit = args.limit === undefined
+            ? undefined
+            : validateWithSchema(args.limit, z.number().int().min(1), 'Invalid limit');
+        const records = await ctx.decisionManager.list({ status, sourceSessionId, sourceProjectId, limit });
+        return formatToolResponse({ records, count: records.length });
+    },
+    get_decision: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const record = ctx.decisionManager.get(id);
+        return formatToolResponse({ id, record: record ?? null });
+    },
+    export_decision_as_adr_markdown: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const markdown = ctx.decisionManager.exportAsAdrMarkdown(id);
+        return formatTextResponse(markdown);
+    },
+    parse_adr_markdown: async (_ctx, args) => {
+        const text = validateWithSchema(args.text, z.string().min(1), 'Invalid text');
+        const parsed = DecisionManager.parseAdrMarkdown(text);
+        return formatToolResponse({ parsed });
+    },
+    // ==================== v2.1.0 do_not_remember (Exclusion) ====================
+    add_exclusion_rule: async (ctx, args) => {
+        const pattern = validateWithSchema(args.pattern, z.string().min(1), 'Invalid pattern');
+        const scope = args.scope === undefined
+            ? undefined
+            : validateWithSchema(args.scope, z.enum(['future-only', 'past-only', 'both']), 'Invalid scope');
+        const entityType = args.entityType === undefined
+            ? undefined
+            : validateWithSchema(args.entityType, z.string().min(1), 'Invalid entityType');
+        const reason = args.reason === undefined
+            ? undefined
+            : validateWithSchema(args.reason, z.string().min(1), 'Invalid reason');
+        const rule = await ctx.exclusionManager.add({ pattern, scope, entityType, reason });
+        return formatToolResponse({ rule });
+    },
+    list_exclusion_rules: async (ctx) => {
+        const rules = await ctx.exclusionManager.list();
+        return formatToolResponse({ rules, count: rules.length });
+    },
+    remove_exclusion_rule: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const removed = await ctx.exclusionManager.remove(id);
+        return formatToolResponse({ id, removed });
+    },
+    check_exclusion: async (ctx, args) => {
+        const content = validateWithSchema(args.content, z.string(), 'Invalid content');
+        const entityType = args.entityType === undefined
+            ? undefined
+            : validateWithSchema(args.entityType, z.string().min(1), 'Invalid entityType');
+        const verdict = await ctx.exclusionManager.check(content, entityType);
+        return formatToolResponse(verdict);
+    },
+    find_matching_memories_for_rule: async (ctx, args) => {
+        const pattern = validateWithSchema(args.pattern, z.string().min(1), 'Invalid pattern');
+        const entityType = args.entityType === undefined
+            ? undefined
+            : validateWithSchema(args.entityType, z.string().min(1), 'Invalid entityType');
+        const matches = await ctx.exclusionManager.findMatchingMemories({ pattern, entityType });
+        return formatToolResponse({
+            pattern,
+            entityType,
+            matches: matches.map((m) => ({ name: m.name, entityType: m.entityType })),
+            count: matches.length,
+        });
+    },
+    // ==================== v2.1.0 OBSERVATION DEDUP ====================
+    find_duplicate_observations: async (ctx, args) => {
+        const filter = parseObservationDedupFilter(args);
+        const groups = await ctx.observationDedupManager.findDuplicateObservations(filter);
+        return formatToolResponse({ filter, groups, count: groups.length });
+    },
+    find_jaccard_duplicate_observations: async (ctx, args) => {
+        const filter = parseObservationDedupFilter(args);
+        const groups = await ctx.observationDedupManager.findJaccardDuplicates(filter);
+        return formatToolResponse({ filter, groups, count: groups.length });
+    },
+    // ==================== v2.1.0 SPELL CORRECTION ====================
+    spell_suggest: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const limit = args.limit === undefined
+            ? undefined
+            : validateWithSchema(args.limit, z.number().int().min(1), 'Invalid limit');
+        const minScore = args.minScore === undefined
+            ? undefined
+            : validateWithSchema(args.minScore, z.number().min(0).max(1), 'Invalid minScore');
+        const maxDistance = args.maxDistance === undefined
+            ? undefined
+            : validateWithSchema(args.maxDistance, z.number().min(0), 'Invalid maxDistance');
+        const suggestions = await ctx.spellChecker.suggest(query, { limit, minScore, maxDistance });
+        return formatToolResponse({ query, suggestions, count: suggestions.length });
+    },
+    spell_rebuild_vocabulary: async (ctx) => {
+        await ctx.spellChecker.rebuild();
+        return formatToolResponse({ rebuilt: true, vocabularySize: ctx.spellChecker.vocabularySize() });
+    },
+    spell_vocabulary_size: async (ctx) => {
+        const size = ctx.spellChecker.vocabularySize();
+        return formatToolResponse({ vocabularySize: size });
+    },
+    // ==================== ENGINEERING / DIAGNOSTIC TOOLS (v12.5.0) ====================
+    // Parallel to the `memory diag` / `memory check` / etc. CLI surface in memoryjs v2.2+.
+    // Useful when the MCP server is up but the graph state is suspect.
+    diag: async (ctx) => {
+        const storagePath = getStorageFilePath(ctx);
+        let exists = false;
+        let sizeBytes = 0;
+        try {
+            const stat = await fs.stat(storagePath);
+            exists = true;
+            sizeBytes = stat.size;
+        }
+        catch { /* file may not exist yet */ }
+        const stats = await ctx.analyticsManager.getGraphStats();
+        return formatToolResponse({
+            runtime: { node: process.version, platform: process.platform, arch: process.arch, pid: process.pid },
+            storage: {
+                path: storagePath,
+                type: process.env.MEMORY_STORAGE_TYPE ?? 'jsonl',
+                exists,
+                sizeBytes,
+                entities: stats.totalEntities,
+                relations: stats.totalRelations,
+            },
+            loadedAt: new Date().toISOString(),
+        });
+    },
+    health: async (ctx) => {
+        const checks = [];
+        const t1 = performance.now();
+        let graph;
+        try {
+            graph = await ctx.storage.loadGraph();
+            checks.push({ name: 'storage:loadGraph', ok: true, durationMs: performance.now() - t1 });
+        }
+        catch (e) {
+            checks.push({
+                name: 'storage:loadGraph',
+                ok: false,
+                durationMs: performance.now() - t1,
+                detail: e instanceof Error ? e.message : String(e),
+            });
+            return formatToolResponse({ ok: false, failed: 1, totalChecks: 1, totalMs: performance.now() - t1, checks });
+        }
+        const t2 = performance.now();
+        const names = new Set();
+        const dupes = [];
+        for (const e of graph.entities) {
+            if (names.has(e.name))
+                dupes.push(e.name);
+            else
+                names.add(e.name);
+        }
+        checks.push({
+            name: 'entities:distinct-names',
+            ok: dupes.length === 0,
+            durationMs: performance.now() - t2,
+            detail: dupes.length === 0 ? undefined : `${dupes.length} duplicate(s)`,
+        });
+        const t3 = performance.now();
+        const orphans = [];
+        for (const r of graph.relations) {
+            if (!names.has(r.from) || !names.has(r.to)) {
+                orphans.push(`${r.from} → ${r.to}`);
+            }
+        }
+        checks.push({
+            name: 'relations:no-orphans',
+            ok: orphans.length === 0,
+            durationMs: performance.now() - t3,
+            detail: orphans.length === 0 ? undefined : `${orphans.length} orphan(s)`,
+        });
+        const t4 = performance.now();
+        const byName = new Map();
+        for (const e of graph.entities)
+            byName.set(e.name, e);
+        const cycleIssues = [];
+        for (const e of graph.entities) {
+            if (!e.parentId)
+                continue;
+            if (!byName.has(e.parentId)) {
+                cycleIssues.push(`${e.name}.parentId='${e.parentId}' missing`);
+                continue;
+            }
+            const visited = new Set();
+            let cur = byName.get(e.parentId);
+            while (cur && cur.parentId) {
+                if (visited.has(cur.name)) {
+                    cycleIssues.push(`cycle through ${cur.name}`);
+                    break;
+                }
+                visited.add(cur.name);
+                cur = byName.get(cur.parentId);
+            }
+        }
+        checks.push({
+            name: 'hierarchy:no-cycles-no-missing-parents',
+            ok: cycleIssues.length === 0,
+            durationMs: performance.now() - t4,
+            detail: cycleIssues.length === 0 ? undefined : cycleIssues.slice(0, 3).join('; '),
+        });
+        const failed = checks.filter((c) => !c.ok).length;
+        return formatToolResponse({
+            ok: failed === 0,
+            failed,
+            totalChecks: checks.length,
+            totalMs: Number(checks.reduce((a, c) => a + c.durationMs, 0).toFixed(2)),
+            checks,
+        });
+    },
+    check_graph: async (ctx, args) => {
+        const apply = args.apply === undefined
+            ? false
+            : validateWithSchema(args.apply, z.boolean(), 'Invalid apply');
+        const graph = await ctx.storage.loadGraph();
+        const names = new Set(graph.entities.map((e) => e.name));
+        const orphans = [];
+        for (const r of graph.relations) {
+            const fromMissing = !names.has(r.from);
+            const toMissing = !names.has(r.to);
+            if (fromMissing || toMissing) {
+                orphans.push({
+                    from: r.from, to: r.to, relationType: r.relationType,
+                    reason: fromMissing && toMissing ? 'both-missing' : fromMissing ? 'from-missing' : 'to-missing',
+                });
+            }
+        }
+        const byName = new Map();
+        for (const e of graph.entities)
+            byName.set(e.name, { name: e.name, parentId: e.parentId });
+        const missing = [];
+        const cycles = [];
+        for (const e of graph.entities) {
+            if (!e.parentId)
+                continue;
+            if (!byName.has(e.parentId)) {
+                missing.push({ entity: e.name, parentId: e.parentId });
+                continue;
+            }
+            const visited = new Set([e.name]);
+            let cur = byName.get(e.parentId);
+            while (cur && cur.parentId) {
+                if (visited.has(cur.name)) {
+                    cycles.push({ entityInCycle: e.name, cycleThrough: cur.name });
+                    break;
+                }
+                visited.add(cur.name);
+                cur = byName.get(cur.parentId);
+            }
+        }
+        const ok = orphans.length === 0 && missing.length === 0 && cycles.length === 0;
+        const result = {
+            ok, applied: apply, orphanRelations: orphans, missingParents: missing, hierarchyCycles: cycles,
+        };
+        if (apply && (orphans.length > 0 || missing.length > 0)) {
+            let deleted = 0;
+            let cleared = 0;
+            if (orphans.length > 0) {
+                await ctx.relationManager.deleteRelations(orphans.map((o) => ({ from: o.from, to: o.to, relationType: o.relationType })));
+                deleted = orphans.length;
+            }
+            for (const m of missing) {
+                try {
+                    await ctx.hierarchyManager.setEntityParent(m.entity, null);
+                    cleared += 1;
+                }
+                catch { /* skip; entity may have vanished */ }
+            }
+            result.actions = { orphanRelationsDeleted: deleted, missingParentsCleared: cleared };
+        }
+        return formatToolResponse(result);
+    },
+    reindex: async (ctx, args) => {
+        const ranked = args.ranked === undefined
+            ? true
+            : validateWithSchema(args.ranked, z.boolean(), 'Invalid ranked');
+        const spell = args.spell === undefined
+            ? true
+            : validateWithSchema(args.spell, z.boolean(), 'Invalid spell');
+        if (!ranked && !spell) {
+            return formatToolResponse({ ok: true, failed: 0, result: {} });
+        }
+        const result = {};
+        if (ranked) {
+            const t = performance.now();
+            try {
+                // Same workaround as the CLI: default ctx.rankedSearch is constructed
+                // without a storageDir so buildIndex() refuses. Construct an ad-hoc one
+                // alongside the JSONL.
+                const storageDir = path.dirname(getStorageFilePath(ctx));
+                const r = new RankedSearch(ctx.storage, storageDir);
+                await r.buildIndex();
+                result.ranked = { ok: true, durationMs: performance.now() - t };
+            }
+            catch (e) {
+                result.ranked = {
+                    ok: false,
+                    durationMs: performance.now() - t,
+                    detail: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }
+        if (spell) {
+            const t = performance.now();
+            try {
+                await ctx.spellChecker.rebuild();
+                result.spell = { ok: true, durationMs: performance.now() - t };
+            }
+            catch (e) {
+                result.spell = {
+                    ok: false,
+                    durationMs: performance.now() - t,
+                    detail: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }
+        const failed = Object.values(result).filter((r) => !r.ok).length;
+        return formatToolResponse({ ok: failed === 0, failed, result });
+    },
+    cache_stats: async (_ctx) => {
+        return formatToolResponse({ stats: getAllCacheStats() });
+    },
+    cache_clear: async (_ctx) => {
+        clearAllSearchCaches();
+        return formatToolResponse({ cleared: true, caches: ['basic', 'ranked', 'boolean', 'fuzzy'] });
+    },
+    graph_size: async (ctx) => {
+        const storagePath = getStorageFilePath(ctx);
+        const graph = await ctx.storage.loadGraph();
+        let observationCount = 0;
+        const tagSet = new Set();
+        for (const e of graph.entities) {
+            observationCount += e.observations.length;
+            if (e.tags)
+                for (const t of e.tags)
+                    tagSet.add(t);
+        }
+        let exists = false;
+        let sizeBytes = 0;
+        let lineCount = 0;
+        try {
+            const stat = await fs.stat(storagePath);
+            exists = true;
+            sizeBytes = stat.size;
+            if (sizeBytes > 0) {
+                const content = await fs.readFile(storagePath, 'utf8');
+                lineCount = content.split('\n').filter((l) => l.length > 0).length;
+            }
+        }
+        catch { /* file may not exist */ }
+        return formatToolResponse({
+            graph: {
+                entities: graph.entities.length,
+                relations: graph.relations.length,
+                observations: observationCount,
+                distinctTags: tagSet.size,
+                avgObservationsPerEntity: graph.entities.length === 0
+                    ? 0
+                    : Number((observationCount / graph.entities.length).toFixed(2)),
+            },
+            storage: { path: storagePath, exists, sizeBytes, lineCount },
+        });
+    },
+    inspect_entity: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        // getEntityByName reads an in-memory nameIndex hydrated by loadGraph.
+        const graph = await ctx.storage.loadGraph();
+        const entity = ctx.storage.getEntityByName(name);
+        if (!entity)
+            throw new Error(`entity not found: ${name}`);
+        const observations = await ctx.observationManager.getObservationsFor(name);
+        const outgoing = graph.relations
+            .filter((r) => r.from === name)
+            .map((r) => ({ to: r.to, type: r.relationType }));
+        const incoming = graph.relations
+            .filter((r) => r.to === name)
+            .map((r) => ({ from: r.from, type: r.relationType }));
+        const children = (await ctx.hierarchyManager.getChildren(name)).map((c) => c.name);
+        const ancestors = (await ctx.hierarchyManager.getAncestors(name)).map((a) => a.name);
+        return formatToolResponse({
+            name: entity.name,
+            entityType: entity.entityType,
+            observations,
+            tags: entity.tags,
+            importance: entity.importance,
+            createdAt: entity.createdAt,
+            lastModified: entity.lastModified,
+            parentId: entity.parentId,
+            children,
+            ancestors,
+            relations: { outgoing, incoming },
+        });
+    },
+    hierarchy_tree: async (ctx, args) => {
+        const root = args.root === undefined
+            ? undefined
+            : validateWithSchema(args.root, z.string().min(1), 'Invalid root');
+        await ctx.storage.loadGraph();
+        async function walk(n) {
+            const e = ctx.storage.getEntityByName(n);
+            const kids = await ctx.hierarchyManager.getChildren(n);
+            const childNodes = [];
+            for (const c of kids)
+                childNodes.push(await walk(c.name));
+            return { name: n, entityType: e?.entityType ?? 'unknown', children: childNodes };
+        }
+        if (root) {
+            const e = ctx.storage.getEntityByName(root);
+            if (!e)
+                throw new Error(`entity not found: ${root}`);
+            return formatToolResponse({ trees: [await walk(root)] });
+        }
+        const roots = await ctx.hierarchyManager.getRootEntities();
+        const trees = await Promise.all(roots.map((r) => walk(r.name)));
+        return formatToolResponse({ trees });
+    },
+    entity_neighbors: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const graph = await ctx.storage.loadGraph();
+        const entity = ctx.storage.getEntityByName(name);
+        if (!entity)
+            throw new Error(`entity not found: ${name}`);
+        const outgoing = graph.relations.filter((r) => r.from === name).map((r) => ({ to: r.to, type: r.relationType }));
+        const incoming = graph.relations.filter((r) => r.to === name).map((r) => ({ from: r.from, type: r.relationType }));
+        return formatToolResponse({
+            entity: name,
+            outgoing,
+            incoming,
+            outDegree: outgoing.length,
+            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.