monomind 2.5.1 → 2.5.2

package/packages/@monomind/cli/dist/src/mcp-tools/memory-tools.js

@@ -1,9 +1,9 @@
 /**
  * Memory MCP Tools — Phase 6 of ADR-053
  *
- * Exposes Memory backend operations as MCP tools.
- * Provides direct access to ReasoningBank, CausalGraph, SkillLibrary,
- * AttestationLog, and bridge health through the MCP protocol.
+ * Exposes Memory backend operations as MCP tools: pattern store/search,
+ * usage-weighted feedback (EWMA), the conversation knowledge graph
+ * (memory_kg_*), session records, weight-aware GC, and bridge health.
  *
  * Security: All handlers validate input types, enforce length bounds,
  * and sanitize error messages before returning to MCP callers.
@@ -107,7 +107,7 @@ export const memoryControllers = {
 // ===== memory_pattern_store — Store via ReasoningBank =====
 export const memoryPatternStore = {
     name: 'memory_pattern-store',
-    description: 'Store a pattern directly via ReasoningBank controller',
+    description: 'Store a reusable pattern (embedded, semantically searchable) in the patterns namespace',
     inputSchema: {
         type: 'object',
         properties: {
@@ -149,7 +149,7 @@ export const memoryPatternStore = {
 // ===== memory_pattern_search — Search via ReasoningBank =====
 export const memoryPatternSearch = {
     name: 'memory_pattern-search',
-    description: 'Search patterns via ReasoningBank controller with BM25+semantic hybrid',
+    description: 'Search stored patterns — semantic when the local embedding model is available, keyword otherwise',
     inputSchema: {
         type: 'object',
         properties: {
@@ -193,13 +193,14 @@ export const memoryPatternSearch = {
 // ===== memory_feedback — Record task feedback =====
 export const memoryFeedback = {
     name: 'memory_feedback',
-    description: 'Record task feedback for learning via LearningSystem + ReasoningBank controllers',
+    description: 'Rate the usefulness of memory entries that produced an answer. Pass the entryIds returned by a prior search — their feedback_weight is EWMA-updated and blended into future ranking. Idempotent per taskId.',
     inputSchema: {
         type: 'object',
         properties: {
-            taskId: { type: 'string', description: 'Task identifier' },
+            taskId: { type: 'string', description: 'Task identifier (also the idempotency key — the same taskId never double-applies)' },
+            entryIds: { type: 'array', items: { type: 'string' }, description: 'Memory entry IDs (from search results) that were used for this task' },
             success: { type: 'boolean', description: 'Whether task succeeded' },
-            quality: { type: 'number', description: 'Quality score (0-1)' },
+            quality: { type: 'number', description: 'Quality score (0-1); defaults from success (0.9/0.2)' },
             agent: { type: 'string', description: 'Agent that performed the task' },
         },
         required: ['taskId'],
@@ -210,14 +211,28 @@ export const memoryFeedback = {
             if (!taskId)
                 return { success: false, error: 'taskId is required (non-empty string, max 500 chars)' };
             const bridge = await getBridge();
+            // Closed loop: apply the rating to the entries that were actually used.
+            const entryIds = Array.isArray(params.entryIds)
+                ? params.entryIds.filter((x) => typeof x === 'string' && x.length > 0 && x.length <= 500).slice(0, 100)
+                : [];
+            let weighting = null;
+            if (entryIds.length) {
+                const score = typeof params.quality === 'number' && Number.isFinite(params.quality)
+                    ? Math.max(0, Math.min(1, params.quality))
+                    : (params.success === true ? 0.9 : 0.2);
+                weighting = await bridge.bridgeApplyFeedback({ entryIds, score, ledgerKey: taskId });
+            }
+            // Keep the historical feedback-event record alongside the weighting.
             const result = await bridge.bridgeRecordFeedback({
                 taskType: validateString(params.agent, 'agent', 200) ?? 'task',
                 action: taskId,
                 outcome: params.success === true ? 'success' : 'failure',
                 confidence: validateScore(params.quality, 0.85),
-                metadata: { taskId },
+                metadata: { taskId, entryIds },
             });
-            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+            if (!result)
+                return { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+            return { ...result, weighting };
         }
         catch (error) {
             return { success: false, error: sanitizeError(error) };
@@ -227,14 +242,15 @@ export const memoryFeedback = {
 // ===== memory_causal_edge — Record causal relationships =====
 export const memoryCausalEdge = {
     name: 'memory_causal-edge',
-    description: 'Record a causal edge between two memory entries via CausalMemoryGraph',
+    description: 'Record a causal relationship between two named things as a real knowledge-graph edge (traversable via memory_kg_search)',
     inputSchema: {
         type: 'object',
         properties: {
-            sourceId: { type: 'string', description: 'Source entry ID' },
-            targetId: { type: 'string', description: 'Target entry ID' },
-            relation: { type: 'string', description: 'Relationship type (e.g., caused, preceded, succeeded)' },
+            sourceId: { type: 'string', description: 'Source entity name (or entry ID)' },
+            targetId: { type: 'string', description: 'Target entity name (or entry ID)' },
+            relation: { type: 'string', description: 'Relationship type (e.g., causes, preceded, fixed_by)' },
             weight: { type: 'number', description: 'Edge weight (0-1)' },
+            description: { type: 'string', description: 'One-sentence concrete fact for this edge' },
         },
         required: ['sourceId', 'targetId', 'relation'],
     },
@@ -249,14 +265,151 @@ export const memoryCausalEdge = {
                 return { success: false, error: 'targetId is required (non-empty string)' };
             if (!relation)
                 return { success: false, error: 'relation is required (non-empty string)' };
-            const bridge = await getBridge();
-            const result = await bridge.bridgeRecordCausalEdge({
-                sourceId,
-                targetId,
-                relation,
-                strength: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined,
+            const kg = await import('../memory/memory-kg.js');
+            const result = await kg.kgIngest({
+                nodes: [{ name: sourceId }, { name: targetId }],
+                edges: [{ source: sourceId, target: targetId, relation, description: validateString(params.description, 'description', 2000) ?? undefined }],
+                originRef: 'causal-edge-tool',
             });
-            return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
+            return result;
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+// ===== memory_kg_* — Conversation/org knowledge graph =====
+export const memoryKgIngest = {
+    name: 'memory_kg_ingest',
+    description: 'Merge extracted entities/relations (and optionally distilled rules) into the persistent knowledge graph. Same-name entities merge idempotently. Call with LLM-extracted nodes/edges — basic types ("Person", "Tool"), coreference-resolved fullest names, snake_case relations, one-sentence edge facts. Pass rawText instead to use the lower-trust regex extractor.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            nodes: { type: 'array', items: { type: 'object' }, description: 'Entities: [{name, type?, description?, nodeSet?}]' },
+            edges: { type: 'array', items: { type: 'object' }, description: 'Relations: [{source, target, relation, description?}]' },
+            rules: { type: 'array', items: { type: 'object' }, description: 'Distilled durable rules: [{rule, context?}] — deduped semantically against existing rules' },
+            rawText: { type: 'string', description: 'Fallback: raw text for regex-based extraction (no LLM)' },
+            originRef: { type: 'string', description: 'Provenance ref (session/run/doc id) — enables memory_kg_rollback' },
+        },
+        required: ['originRef'],
+    },
+    handler: async (params) => {
+        try {
+            const originRef = validateString(params.originRef, 'originRef', 500);
+            if (!originRef)
+                return { success: false, error: 'originRef is required' };
+            const kg = await import('../memory/memory-kg.js');
+            let nodes = Array.isArray(params.nodes) ? params.nodes : [];
+            let edges = Array.isArray(params.edges) ? params.edges : [];
+            if (!nodes.length && !edges.length && typeof params.rawText === 'string' && params.rawText.trim()) {
+                const extracted = kg.heuristicExtract(params.rawText, { sourceName: originRef });
+                nodes = extracted.nodes;
+                edges = extracted.edges;
+            }
+            const graph = (nodes.length || edges.length)
+                ? await kg.kgIngest({ nodes, edges, originRef })
+                : { success: true, nodesAdded: 0, nodesMerged: 0, edgesAdded: 0, edgesMerged: 0 };
+            const rules = Array.isArray(params.rules) && params.rules.length
+                ? await kg.kgIngestRules({ rules: params.rules, originRef })
+                : null;
+            return { ...graph, rules };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+export const memoryKgSearch = {
+    name: 'memory_kg_search',
+    description: 'Search the knowledge graph: vector-seeded entities expanded to ranked relationship triplets. Returns rendered context lines plus seed entry ids (rate them via memory_feedback).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Natural-language query' },
+            limit: { type: 'number', description: 'Max triplets (default 8)' },
+            nodeSet: { type: 'string', description: "Filter to a node set (e.g. 'rules')" },
+        },
+        required: ['query'],
+    },
+    handler: async (params) => {
+        try {
+            const query = validateString(params.query, 'query', 2000);
+            if (!query)
+                return { success: false, error: 'query is required' };
+            const kg = await import('../memory/memory-kg.js');
+            return await kg.kgSearch({
+                query,
+                limit: validatePositiveInt(params.limit, 8, 50),
+                nodeSet: validateString(params.nodeSet, 'nodeSet', 100) ?? undefined,
+            });
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+export const memoryKgRollback = {
+    name: 'memory_kg_rollback',
+    description: 'Delete all knowledge-graph nodes/edges/rules whose only provenance is the given originRef (bad-ingest recovery). Elements shared with other origins are retained.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            originRef: { type: 'string', description: 'The provenance ref to roll back (session/run/doc id)' },
+        },
+        required: ['originRef'],
+    },
+    handler: async (params) => {
+        try {
+            const originRef = validateString(params.originRef, 'originRef', 500);
+            if (!originRef)
+                return { success: false, error: 'originRef is required' };
+            const kg = await import('../memory/memory-kg.js');
+            return await kg.kgRollback({ originRef });
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+export const memoryKgConsolidate = {
+    name: 'memory_kg_consolidate',
+    description: 'List knowledge-graph entities whose descriptions lag their connectivity, with neighborhood facts. YOU do the consolidation: rewrite each candidate\'s description as one canonical paragraph merging the facts, then resubmit via memory_kg_ingest (richer descriptions win on merge).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            minEdges: { type: 'number', description: 'Minimum relations for a candidate (default 3)' },
+            limit: { type: 'number', description: 'Max candidates (default 10)' },
+        },
+    },
+    handler: async (params) => {
+        try {
+            const kg = await import('../memory/memory-kg.js');
+            const candidates = await kg.kgConsolidateCandidates({
+                minEdges: validatePositiveInt(params.minEdges, 3, 100),
+                limit: validatePositiveInt(params.limit, 10, 50),
+            });
+            return { success: true, candidates };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
+export const memoryKgStats = {
+    name: 'memory_kg_stats',
+    description: 'Knowledge graph size: node, edge, and rule counts (plus the entity glossary for extraction prompts)',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            glossary: { type: 'boolean', description: 'Include top entity names (default false)' },
+        },
+    },
+    handler: async (params) => {
+        try {
+            const kg = await import('../memory/memory-kg.js');
+            const stats = await kg.kgStats();
+            const glossary = params.glossary === true ? await kg.kgGlossary() : undefined;
+            return { success: true, ...stats, ...(glossary ? { glossary } : {}) };
         }
         catch (error) {
             return { success: false, error: sanitizeError(error) };
@@ -266,7 +419,7 @@ export const memoryCausalEdge = {
 // ===== memory_route — Route via SemanticRouter =====
 export const memoryRoute = {
     name: 'memory_route',
-    description: 'Route a task via SemanticRouter or LearningSystem recommendAlgorithm',
+    description: 'Suggest agent routing for a task by searching past routing patterns',
     inputSchema: {
         type: 'object',
         properties: {
@@ -292,7 +445,7 @@ export const memoryRoute = {
 // ===== memory_session_start — Session with ReflexionMemory =====
 export const memorySessionStart = {
     name: 'memory_session-start',
-    description: 'Start a session with ReflexionMemory episodic replay',
+    description: 'Record a session start in the sessions namespace',
     inputSchema: {
         type: 'object',
         properties: {
@@ -321,7 +474,7 @@ export const memorySessionStart = {
 // ===== memory_session_end — End session + NightlyLearner =====
 export const memorySessionEnd = {
     name: 'memory_session-end',
-    description: 'End session, persist to ReflexionMemory, trigger NightlyLearner consolidation',
+    description: 'Record session end with summary and metrics in the sessions namespace',
     inputSchema: {
         type: 'object',
         properties: {
@@ -352,7 +505,7 @@ export const memorySessionEnd = {
 // ===== memory_hierarchical_store — Store to hierarchical memory =====
 export const memoryHierarchicalStore = {
     name: 'memory_hierarchical-store',
-    description: 'Store to hierarchical memory with tier (working, episodic, semantic)',
+    description: 'Store into a tier-labeled namespace (tier_working/episodic/semantic). Note: tiers are labels, not automatic promotion',
     inputSchema: {
         type: 'object',
         properties: {
@@ -391,7 +544,7 @@ export const memoryHierarchicalStore = {
 // ===== memory_hierarchical_recall — Recall from hierarchical memory =====
 export const memoryHierarchicalRecall = {
     name: 'memory_hierarchical-recall',
-    description: 'Recall from hierarchical memory with optional tier filter',
+    description: 'Search tier-labeled namespaces (tier_working/episodic/semantic), or all when no tier given',
     inputSchema: {
         type: 'object',
         properties: {
@@ -426,12 +579,13 @@ export const memoryHierarchicalRecall = {
 // ===== memory_consolidate — Run memory consolidation =====
 export const memoryConsolidate = {
     name: 'memory_consolidate',
-    description: 'Run memory consolidation to promote entries across tiers and compress old data',
+    description: 'Garbage-collect stale, unused memory entries. Weight-aware: entries with high feedback_weight or repeated usage are never collected.',
     inputSchema: {
         type: 'object',
         properties: {
-            minAge: { type: 'number', description: 'Minimum age in hours since store (optional)' },
-            maxEntries: { type: 'number', description: 'Maximum entries to consolidate (optional)' },
+            minAge: { type: 'number', description: 'Minimum age in hours since last update (optional, default 168 = 7 days)' },
+            maxEntries: { type: 'number', description: 'Maximum entries to scan (optional)' },
+            namespace: { type: 'string', description: "Namespace to GC, or 'all' for every non-protected namespace (optional)" },
         },
     },
     handler: async (params) => {
@@ -440,14 +594,17 @@ export const memoryConsolidate = {
             // Reject NaN and Infinity. typeof === 'number' returns true for both.
             // NaN propagates through arithmetic and corrupts consolidation accounting;
             // Infinity makes `entry.age >= minAge` always false, silently no-op.
+            // The bridge expects MILLISECONDS; this param is documented in hours —
+            // convert here (previously passed through raw, so 720 hours became 720ms).
             const minAge = typeof params.minAge === 'number' && Number.isFinite(params.minAge)
-                ? Math.max(0, Math.min(params.minAge, 24 * 365 * 10))
+                ? Math.max(0, Math.min(params.minAge, 24 * 365 * 10)) * 3600 * 1000
                 : undefined;
             const result = await bridge.bridgeConsolidate({
                 minAge,
                 maxEntries: params.maxEntries !== undefined
                     ? validatePositiveInt(params.maxEntries, 1000, 10_000)
                     : undefined,
+                namespace: validateString(params.namespace, 'namespace', 128) ?? undefined,
             });
             return result ?? { success: false, error: 'Memory bridge not available. Use memory_store/memory_search instead.' };
         }
@@ -533,7 +690,7 @@ export const memoryBatch = {
 // ===== memory_context_synthesize — Synthesize context from memories =====
 export const memoryContextSynthesize = {
     name: 'memory_context-synthesize',
-    description: 'Synthesize context from stored memories for a given query',
+    description: 'Concatenate top matching memories into a context block for a query (no summarization)',
     inputSchema: {
         type: 'object',
         properties: {
@@ -601,6 +758,11 @@ export const memoryTools = [
     memoryPatternSearch,
     memoryFeedback,
     memoryCausalEdge,
+    memoryKgIngest,
+    memoryKgSearch,
+    memoryKgRollback,
+    memoryKgConsolidate,
+    memoryKgStats,
     memoryRoute,
     memorySessionStart,
     memorySessionEnd,

package/packages/@monomind/cli/dist/src/memory/memory-bridge.d.ts

@@ -26,6 +26,8 @@ export declare function bridgeStoreEntry(options: {
     ttl?: number;
     dbPath?: string;
     upsert?: boolean;
+    /** Structured metadata persisted on the entry (KG nodes/edges, weights, provenance). */
+    metadata?: Record<string, unknown>;
 }): Promise<{
     success: boolean;
     id: string;
@@ -77,6 +79,7 @@ export declare function bridgeListEntries(options: {
         updatedAt: string;
         hasEmbedding: boolean;
         tags: string[];
+        metadata: Record<string, unknown>;
     }[];
     total: number;
     error?: string;
@@ -99,6 +102,7 @@ export declare function bridgeGetEntry(options: {
         updatedAt: string;
         hasEmbedding: boolean;
         tags: string[];
+        metadata: Record<string, unknown>;
     };
     cacheHit?: boolean;
     error?: string;
@@ -199,6 +203,31 @@ export declare function bridgeSearchPatterns(options: {
     }[];
     error?: string;
 } | null>;
+/** Record that these entries were actually USED (returned to and consumed by a
+ *  caller) — increments frequency_weight, which feeds the ranking blend. */
+export declare function bridgeRecordUsage(options: {
+    entryIds: string[];
+    dbPath?: string;
+}): Promise<{
+    success: boolean;
+    updated: number;
+} | null>;
+/** Apply a usefulness rating to the entries that produced an answer:
+ *  EWMA feedback_weight' = w + alpha*(score - w), clipped [0,1] (cognee's
+ *  apply_feedback_weights). `ledgerKey` makes application idempotent — a
+ *  daemon retry or duplicate MCP call must never compound the update. */
+export declare function bridgeApplyFeedback(options: {
+    entryIds: string[];
+    score: number;
+    ledgerKey?: string;
+    alpha?: number;
+    dbPath?: string;
+}): Promise<{
+    success: boolean;
+    applied: number;
+    alreadyApplied?: boolean;
+    error?: string;
+} | null>;
 export declare function bridgeRecordFeedback(options: {
     taskType: string;
     action: string;
@@ -275,8 +304,12 @@ export declare function bridgeHierarchicalRecall(params: {
     topK?: number;
 }): Promise<any>;
 export declare function bridgeConsolidate(params: {
+    /** Minimum age in MILLISECONDS since last update (default 7 days). */
     minAge?: number;
     maxEntries?: number;
+    /** Namespace to GC; 'all' scans every non-protected namespace (default 'default'). */
+    namespace?: string;
+    dbPath?: string;
 }): Promise<any>;
 export declare function bridgeBatchOperation(params: {
     operation: string;