@danielsimonjr/memory-mcp 12.5.2 → 12.7.0

package/dist/search/VectorStore.js

@@ -0,0 +1,311 @@
+/**
+ * Vector Store
+ *
+ * Phase 4 Sprint 11: Vector storage and retrieval for semantic search.
+ * Provides in-memory and SQLite-backed implementations.
+ *
+ * @module search/VectorStore
+ */
+/**
+ * Calculate cosine similarity between two vectors.
+ *
+ * Uses an optimized inner loop without array methods for maximum performance.
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Cosine similarity score (0.0 to 1.0)
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimensions mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dotProduct = 0;
+    let magnitudeA = 0;
+    let magnitudeB = 0;
+    // Optimized single-pass loop
+    for (let i = 0; i < a.length; i++) {
+        const ai = a[i];
+        const bi = b[i];
+        dotProduct += ai * bi;
+        magnitudeA += ai * ai;
+        magnitudeB += bi * bi;
+    }
+    const magnitude = Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB);
+    if (magnitude === 0) {
+        return 0;
+    }
+    // Clamp to [-1, 1] to handle floating point errors
+    const similarity = dotProduct / magnitude;
+    return Math.max(-1, Math.min(1, similarity));
+}
+/**
+ * In-Memory Vector Store
+ *
+ * Stores vectors in memory using a Map for O(1) add/remove operations.
+ * Search uses brute-force cosine similarity which is O(n) but fast for
+ * small to medium graphs (<10K entities).
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryVectorStore();
+ * store.add("entity1", [0.1, 0.2, 0.3]);
+ * store.add("entity2", [0.4, 0.5, 0.6]);
+ * const results = store.search([0.1, 0.2, 0.3], 5);
+ * console.log(results); // [{ name: "entity1", score: 1.0 }, ...]
+ * ```
+ */
+export class InMemoryVectorStore {
+    /** Map of entity name to embedding vector */
+    vectors = new Map();
+    /**
+     * Add a vector for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @param vector - Embedding vector
+     */
+    add(entityName, vector) {
+        this.vectors.set(entityName, vector);
+    }
+    /**
+     * Search for similar vectors using cosine similarity.
+     *
+     * @param queryVector - Query embedding vector
+     * @param k - Number of results to return
+     * @returns Array of results with entity name and similarity score
+     */
+    search(queryVector, k) {
+        if (this.vectors.size === 0) {
+            return [];
+        }
+        // Calculate similarity for all vectors
+        const results = [];
+        for (const [name, vector] of this.vectors) {
+            try {
+                const score = cosineSimilarity(queryVector, vector);
+                results.push({ name, score });
+            }
+            catch {
+                // Skip vectors with dimension mismatch
+                continue;
+            }
+        }
+        // Sort by score descending and take top k
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, k);
+    }
+    /**
+     * Remove a vector by entity name.
+     *
+     * @param entityName - Name of the entity to remove
+     * @returns True if found and removed
+     */
+    remove(entityName) {
+        return this.vectors.delete(entityName);
+    }
+    /**
+     * Get the number of vectors stored.
+     *
+     * @returns Number of vectors
+     */
+    size() {
+        return this.vectors.size;
+    }
+    /**
+     * Clear all vectors from the store.
+     */
+    clear() {
+        this.vectors.clear();
+    }
+    /**
+     * Check if a vector exists for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @returns True if vector exists
+     */
+    has(entityName) {
+        return this.vectors.has(entityName);
+    }
+    /**
+     * Get the vector for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @returns Vector if found, undefined otherwise
+     */
+    get(entityName) {
+        return this.vectors.get(entityName);
+    }
+    /**
+     * Get all entity names with stored vectors.
+     *
+     * @returns Array of entity names
+     */
+    getEntityNames() {
+        return Array.from(this.vectors.keys());
+    }
+    /**
+     * Load vectors from an iterable source.
+     *
+     * @param entries - Iterable of [entityName, vector] pairs
+     */
+    loadFrom(entries) {
+        for (const [name, vector] of entries) {
+            this.vectors.set(name, vector);
+        }
+    }
+}
+/**
+ * SQLite Vector Store
+ *
+ * Persists vectors to SQLite storage while maintaining an in-memory cache
+ * for fast search operations. Combines persistence with performance.
+ *
+ * Uses SQLiteStorage's embedding storage methods for persistence.
+ *
+ * @example
+ * ```typescript
+ * const store = new SQLiteVectorStore(sqliteStorage);
+ * await store.initialize();
+ * store.add("entity1", [0.1, 0.2, 0.3]);
+ * const results = store.search([0.1, 0.2, 0.3], 5);
+ * ```
+ */
+export class SQLiteVectorStore {
+    /** In-memory cache for fast search */
+    memoryStore = new InMemoryVectorStore();
+    /** SQLite storage reference for persistence */
+    storage = null;
+    /** Whether the store has been initialized */
+    initialized = false;
+    /** Model name used for embeddings */
+    embeddingModel = '';
+    /**
+     * Create a SQLite vector store.
+     *
+     * @param storage - SQLite storage instance with embedding support
+     * @param embeddingModel - Model name used for embeddings
+     */
+    constructor(storage, embeddingModel = 'unknown') {
+        this.storage = storage || null;
+        this.embeddingModel = embeddingModel;
+    }
+    /**
+     * Initialize the store by loading vectors from SQLite.
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (this.storage) {
+            // Load all embeddings from SQLite
+            const embeddings = await this.storage.loadAllEmbeddings();
+            this.memoryStore.loadFrom(embeddings);
+        }
+        this.initialized = true;
+    }
+    /**
+     * Add a vector for an entity.
+     * Stores in both memory and SQLite for persistence.
+     *
+     * @param entityName - Name of the entity
+     * @param vector - Embedding vector
+     */
+    add(entityName, vector) {
+        // Add to in-memory cache
+        this.memoryStore.add(entityName, vector);
+        // Persist to SQLite if available
+        if (this.storage) {
+            this.storage.storeEmbedding(entityName, vector, this.embeddingModel);
+        }
+    }
+    /**
+     * Search for similar vectors using cosine similarity.
+     *
+     * @param queryVector - Query embedding vector
+     * @param k - Number of results to return
+     * @returns Array of results with entity name and similarity score
+     */
+    search(queryVector, k) {
+        return this.memoryStore.search(queryVector, k);
+    }
+    /**
+     * Remove a vector by entity name.
+     *
+     * @param entityName - Name of the entity to remove
+     * @returns True if found and removed
+     */
+    remove(entityName) {
+        const removed = this.memoryStore.remove(entityName);
+        // Remove from SQLite if available
+        if (this.storage && removed) {
+            this.storage.removeEmbedding(entityName);
+        }
+        return removed;
+    }
+    /**
+     * Get the number of vectors stored.
+     *
+     * @returns Number of vectors
+     */
+    size() {
+        return this.memoryStore.size();
+    }
+    /**
+     * Clear all vectors from the store.
+     */
+    clear() {
+        this.memoryStore.clear();
+        if (this.storage) {
+            this.storage.clearAllEmbeddings();
+        }
+    }
+    /**
+     * Check if a vector exists for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @returns True if vector exists
+     */
+    has(entityName) {
+        return this.memoryStore.has(entityName);
+    }
+    /**
+     * Get the vector for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @returns Vector if found, undefined otherwise
+     */
+    get(entityName) {
+        return this.memoryStore.get(entityName);
+    }
+    /**
+     * Set the SQLite storage reference.
+     *
+     * @param storage - SQLite storage instance
+     */
+    setStorage(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Set the embedding model name.
+     *
+     * @param model - Model name
+     */
+    setEmbeddingModel(model) {
+        this.embeddingModel = model;
+    }
+}
+/**
+ * Create a vector store based on storage type.
+ *
+ * @param storageType - Storage type: 'jsonl' or 'sqlite'
+ * @param storage - Optional SQLite storage reference for 'sqlite' type
+ * @param embeddingModel - Optional model name for embedding tracking
+ * @returns Vector store instance
+ */
+export function createVectorStore(storageType = 'jsonl', storage, embeddingModel) {
+    switch (storageType) {
+        case 'sqlite':
+            return new SQLiteVectorStore(storage, embeddingModel);
+        case 'jsonl':
+        default:
+            return new InMemoryVectorStore();
+    }
+}

package/dist/search/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Search Module Barrel Export
+ *
+ * Sprint 2: Added SearchFilterChain for centralized filter logic
+ * Phase 4 Sprint 10: Added EmbeddingService for semantic search
+ */
+export { BasicSearch } from './BasicSearch.js';
+export { RankedSearch } from './RankedSearch.js';
+export { BooleanSearch } from './BooleanSearch.js';
+export { FuzzySearch, type FuzzySearchOptions } from './FuzzySearch.js';
+export { SearchSuggestions } from './SearchSuggestions.js';
+export { SavedSearchManager } from './SavedSearchManager.js';
+export { SearchManager } from './SearchManager.js';
+export { SearchFilterChain, type SearchFilters, type ValidatedPagination } from './SearchFilterChain.js';
+export { OpenAIEmbeddingService, LocalEmbeddingService, MockEmbeddingService, createEmbeddingService, } from './EmbeddingService.js';
+export { InMemoryVectorStore, SQLiteVectorStore, createVectorStore, cosineSimilarity, type SQLiteStorageWithEmbeddings, } from './VectorStore.js';
+export { SemanticSearch, entityToText, } from './SemanticSearch.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAGzG,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,2BAA2B,GACjC,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,YAAY,GACb,MAAM,qBAAqB,CAAC"}

package/dist/search/index.js

@@ -0,0 +1,21 @@
+/**
+ * Search Module Barrel Export
+ *
+ * Sprint 2: Added SearchFilterChain for centralized filter logic
+ * Phase 4 Sprint 10: Added EmbeddingService for semantic search
+ */
+export { BasicSearch } from './BasicSearch.js';
+export { RankedSearch } from './RankedSearch.js';
+export { BooleanSearch } from './BooleanSearch.js';
+export { FuzzySearch } from './FuzzySearch.js';
+export { SearchSuggestions } from './SearchSuggestions.js';
+export { SavedSearchManager } from './SavedSearchManager.js';
+export { SearchManager } from './SearchManager.js';
+// Sprint 2: Search Filter Chain utilities
+export { SearchFilterChain } from './SearchFilterChain.js';
+// Phase 4 Sprint 10: Embedding Service for semantic search
+export { OpenAIEmbeddingService, LocalEmbeddingService, MockEmbeddingService, createEmbeddingService, } from './EmbeddingService.js';
+// Phase 4 Sprint 11: Vector Store for semantic search
+export { InMemoryVectorStore, SQLiteVectorStore, createVectorStore, cosineSimilarity, } from './VectorStore.js';
+// Phase 4 Sprint 12: Semantic Search Manager
+export { SemanticSearch, entityToText, } from './SemanticSearch.js';

package/dist/server/MCPServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MCPServer.d.ts","sourceRoot":"","sources":["../../src/server/MCPServer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAOtE;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAiB;gBAEhB,GAAG,EAAE,cAAc;IAiB/B,OAAO,CAAC,oBAAoB;IAetB,KAAK;CAKZ"}
+{"version":3,"file":"MCPServer.d.ts","sourceRoot":"","sources":["../../src/server/MCPServer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAOtE;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAiB;IAE5B,YAAY,GAAG,EAAE,cAAc,EAe9B;IAED,OAAO,CAAC,oBAAoB;IAetB,KAAK,kBAIV;CACF"}

package/dist/server/toolDefinitions.d.ts

@@ -2,7 +2,7 @@
  * MCP Tool Definitions
  *
  * Extracted from MCPServer.ts to reduce file size and improve maintainability.
- * Contains all 106 tool schemas for the Knowledge Graph MCP Server.
+ * Contains all 241 tool schemas for the Knowledge Graph MCP Server.
  *
  * @module server/toolDefinitions
  */

package/dist/server/toolDefinitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinitions.d.ts","sourceRoot":"","sources":["../../src/server/toolDefinitions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,EAm0G3C,CAAC"}
+{"version":3,"file":"toolDefinitions.d.ts","sourceRoot":"","sources":["../../src/server/toolDefinitions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,EAokH3C,CAAC"}

package/dist/server/toolDefinitions.js

@@ -2,7 +2,7 @@
  * MCP Tool Definitions
  *
  * Extracted from MCPServer.ts to reduce file size and improve maintainability.
- * Contains all 106 tool schemas for the Knowledge Graph MCP Server.
+ * Contains all 241 tool schemas for the Knowledge Graph MCP Server.
  *
  * @module server/toolDefinitions
  */
@@ -476,7 +476,7 @@ export const toolDefinitions = [
     // Phase 11 Sprint 2: Hybrid Search
     {
         name: 'hybrid_search',
-        description: 'Search using combined semantic, lexical, and metadata signals. Provides better recall than single-signal search by fusing multiple relevance signals.',
+        description: 'Search using combined semantic, lexical, and metadata signals. Provides better recall than single-signal search by fusing multiple relevance signals. v3 additive options: graphWeight adds a graph-connectivity (PageRank) channel, expandNeighbors appends one-hop neighbors of top results, explain annotates results with evidence paths from query anchors, lookFor ranks expansion neighbors by a free-text connection description.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -531,6 +531,27 @@ export const toolDefinitions = [
                     additionalProperties: false,
                 },
                 limit: { type: 'number', description: 'Maximum results to return (default: 10)' },
+                graphWeight: {
+                    type: 'number',
+                    description: 'Weight for the graph-connectivity channel (normalized PageRank). 0/omitted = channel disabled (default)',
+                },
+                expandNeighbors: {
+                    type: 'object',
+                    description: 'One-hop neighbor expansion: neighbors of the top-K results are appended with a damped score and re-sorted',
+                    properties: {
+                        topK: { type: 'number', description: 'Number of top-ranked results to expand from (default: 10)' },
+                        damping: { type: 'number', description: "Damping factor applied to the parent's combined score (default: 0.3)" },
+                    },
+                    additionalProperties: false,
+                },
+                explain: {
+                    type: 'boolean',
+                    description: 'Annotate each result with evidencePaths — graph paths connecting query anchor matches to the result (default: false)',
+                },
+                lookFor: {
+                    type: 'string',
+                    description: 'Free-text description of the desired connection; expansion neighbors are ranked by similarity to it (lookForScore)',
+                },
             },
             required: ['query'],
             additionalProperties: false,
@@ -3347,6 +3368,237 @@ export const toolDefinitions = [
             additionalProperties: false,
         },
     },
+    // ==================== EVENT MEMORY TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'record_event',
+        description: 'Record an n-ary event: the action becomes a first-class event hub entity with role-typed relations (actor_of/targeted/occurred_in/participant_in). Missing endpoints auto-create as concept stubs. Optional flowKey groups events into a named flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', description: 'The verb — what happened (e.g. "deployed", "approved")' },
+                actor: { type: 'string', description: 'Entity name of who performed the action' },
+                target: { type: 'string', description: 'Entity name the action was performed on' },
+                context: { type: 'string', description: 'Entity name of where/within-what the event occurred' },
+                participants: { type: 'array', items: { type: 'string' }, description: 'Additional participant entity names' },
+                occurredAt: { type: 'string', description: 'ISO 8601 timestamp of when the event occurred' },
+                flowKey: { type: 'string', description: 'Flow key grouping related events (case-insensitive)' },
+                detail: { type: 'array', items: { type: 'string' }, description: 'Free-text detail observations attached to the event' },
+                importance: { type: 'number', description: 'Importance score for the event entity' },
+            },
+            required: ['action', 'actor'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_event',
+        description: 'Load one recorded event by its entity name, joining the event hub with its role-typed relation endpoints (actor, target, context, participants).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Event entity name (as returned by record_event / query_events)' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'query_events',
+        description: 'Query recorded events by any combination of actor, target, action, flowKey, and inclusive time range. Results are chronologically ordered (occurredAt, falling back to createdAt). Uses relation/type indexes — never a full-graph scan.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                actor: { type: 'string', description: 'Filter by actor entity name' },
+                target: { type: 'string', description: 'Filter by target entity name' },
+                action: { type: 'string', description: 'Filter by action verb' },
+                flowKey: { type: 'string', description: 'Filter by flow key' },
+                timeRange: {
+                    type: 'object',
+                    properties: {
+                        start: { type: 'string', description: 'Inclusive lower bound (ISO 8601)' },
+                        end: { type: 'string', description: 'Inclusive upper bound (ISO 8601)' },
+                    },
+                    additionalProperties: false,
+                    description: 'Inclusive time range; either bound may be omitted',
+                },
+                limit: { type: 'number', description: 'Max events to return' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_event_flow',
+        description: 'All events sharing a flow key (flow:<key> tag), chronologically ordered — the full timeline of a named flow (e.g. a release, an incident).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                flowKey: { type: 'string', description: 'Flow key (case-insensitive)' },
+            },
+            required: ['flowKey'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'who_did_what',
+        description: 'Convenience join answering "who did what (to target / in context / within time range)?" over recorded events. Returns actor + action + event tuples; events without a resolvable actor are omitted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Filter by target entity name' },
+                context: { type: 'string', description: 'Filter by context entity name' },
+                timeRange: {
+                    type: 'object',
+                    properties: {
+                        start: { type: 'string', description: 'Inclusive lower bound (ISO 8601)' },
+                        end: { type: 'string', description: 'Inclusive upper bound (ISO 8601)' },
+                    },
+                    additionalProperties: false,
+                    description: 'Inclusive time range; either bound may be omitted',
+                },
+                limit: { type: 'number', description: 'Max entries to return' },
+            },
+            additionalProperties: false,
+        },
+    },
+    // ==================== RECONSTRUCTIVE MEMORY TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'ingest_dialogue',
+        description: 'Distill raw dialogue turns into the Cue–Tag–Content associative memory graph (MRAgent-style "memory is reconstructed, not retrieved"). Episodic/semantic/topic layers are also persisted into the live knowledge graph. Multiple calls accumulate.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                turns: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: 'Unique turn id' },
+                            speaker: { type: 'string', description: 'Speaker name' },
+                            text: { type: 'string', description: 'Turn text' },
+                            timestamp: { type: 'string', description: 'ISO 8601 timestamp' },
+                        },
+                        required: ['id', 'text'],
+                        additionalProperties: false,
+                    },
+                    description: 'Dialogue turns to distill and ingest',
+                },
+            },
+            required: ['turns'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reconstruct_memory',
+        description: 'Answer a query via active multi-step traversal of the reconstructive (Cue–Tag–Content) memory graph. Returns accumulated evidence, the step-by-step trajectory, and whether the loop stopped early on a satisfied condition vs. budget.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Query to reconstruct an answer for' },
+                maxSteps: { type: 'number', description: 'Max reasoning turns (default 8)' },
+                perStepBudget: { type: 'number', description: 'Max content nodes routed per step (default 10)' },
+                evidenceTarget: { type: 'number', description: 'Stop once this many distinct evidence items accumulate (default 12)' },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'reconstructive_memory_stats',
+        description: 'Size statistics of the reconstructive (Cue–Tag–Content) memory graph: cue / tag / content node counts and edge counts.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    // ==================== RELATION CONSOLIDATION TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'analyze_relation_duplicates',
+        description: 'Dry-run the three-tier relation janitor: tier 1 finds trivial relationType spelling variants (WorksAt/works-at/works_at) and redundant bidirectional mirrors; tier 2 (when an embedding provider is configured) finds semantically equivalent same-pair relations. Report-only — never mutates the graph.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'consolidate_relations',
+        description: 'Run relation-duplicate analysis and — when apply=true — merge tier 1+2 duplicate groups (delete variants, create the canonical survivor with summed confirmationCount). apply=false (default) is identical to analyze_relation_duplicates.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                apply: { type: 'boolean', description: 'Apply tier 1+2 merges (default false = dry-run)' },
+            },
+            additionalProperties: false,
+        },
+    },
+    // ==================== AGENT REFLECTION TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'create_reflection',
+        description: 'Persist an agent reflection — a generalized lesson distilled from experience, backed by evidence entities. Deduplicated by evidence hash; scoped to session, project, or global.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['session', 'project', 'global'], description: 'Generalization scope of the reflection' },
+                summary: { type: 'string', description: 'The reflection text (non-empty)' },
+                evidence: { type: 'array', items: { type: 'string' }, description: 'Entity names backing this reflection (non-empty)' },
+                generalizationConfidence: { type: 'number', description: 'Confidence in [0.0, 1.0] that the lesson generalizes' },
+                keyInsights: { type: 'array', items: { type: 'string' }, description: 'Top pattern strings (max 5)' },
+                experienceType: { type: 'string', description: 'Experience type label (e.g. "success", "failure")' },
+                sourceSessionId: { type: 'string', description: 'Session the reflection was distilled from' },
+                sourceProjectId: { type: 'string', description: 'Project the reflection was distilled from' },
+                importance: { type: 'number', description: 'Importance score for the reflection entity' },
+                agentId: { type: 'string', description: 'Agent that authored the reflection' },
+            },
+            required: ['scope', 'summary', 'evidence', 'generalizationConfidence'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'list_reflections',
+        description: 'List stored agent reflections, filterable by scope, source session/project, and minimum generalization confidence. Archived reflections are excluded unless includeArchived is set.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['session', 'project', 'global'], description: 'Filter by scope' },
+                sourceSessionId: { type: 'string', description: 'Filter by source session' },
+                sourceProjectId: { type: 'string', description: 'Filter by source project' },
+                minConfidence: { type: 'number', description: 'Minimum generalization_confidence (inclusive)' },
+                includeArchived: { type: 'boolean', description: 'Include archived reflections (default false)' },
+                limit: { type: 'number', description: 'Max reflections to return' },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'get_relevant_reflections',
+        description: 'Reflections relevant to a session: matches by sourceSessionId, plus evidence overlap with the supplied session entity names. Use at session start to surface applicable past lessons.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Session to find relevant reflections for' },
+                sessionEntityNames: { type: 'array', items: { type: 'string' }, description: 'Entity names from the session for evidence-overlap matching' },
+                minConfidence: { type: 'number', description: 'Minimum generalization_confidence (inclusive)' },
+                limit: { type: 'number', description: 'Max reflections to return (default 10)' },
+            },
+            required: ['sessionId'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'archive_reflection',
+        description: 'Archive a reflection by id so it no longer appears in default listings or relevance matches (soft delete — the record is retained).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Reflection id to archive' },
+            },
+            required: ['id'],
+            additionalProperties: false,
+        },
+    },
+    // ==================== RECONSTRUCTIVE MEMORY PERSISTENCE TOOLS (memoryjs v3.0.0) ====================
+    {
+        name: 'save_reconstructive_memory',
+        description: 'Serialize the in-memory Cue–Tag–Content reconstructive graph to a JSON sidecar next to the storage file (<basename>-reconstructive.json). The CTC graph is process-local; save before shutdown to survive restarts.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'load_reconstructive_memory',
+        description: 'Restore the Cue–Tag–Content reconstructive graph from the <basename>-reconstructive.json sidecar written by save_reconstructive_memory, replacing the current in-memory graph. Errors if no sidecar exists.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
 ];
 // Tool categories are documented in CLAUDE.md for reference:
 // - Entity Operations: create_entities, delete_entities, read_graph, open_nodes

package/dist/server/toolHandlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlers.d.ts","sourceRoot":"","sources":["../../src/server/toolHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,kBAAkB,EA6ClB,KAAK,cAAc,EAkBpB,MAAM,yBAAyB,CAAC;AA2BjC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAE7E;AA2ED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,YAAY,CAAC,CAAC;AAiF3B,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAo8FpD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC,CAiBvB"}
+{"version":3,"file":"toolHandlers.d.ts","sourceRoot":"","sources":["../../src/server/toolHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,kBAAkB,EA2ClB,KAAK,cAAc,EAyBpB,MAAM,yBAAyB,CAAC;AAyBjC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAE7E;AAkED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,YAAY,CAAC,CAAC;AAiF3B,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAouGpD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC,CAiBvB"}