@cartisien/engram-mcp 0.2.0 → 0.3.0

package/dist/tools/process_detect.js

@@ -0,0 +1,218 @@
+import { extractEntities } from '../analysis/entities.js';
+import { themeNames } from '../analysis/themes.js';
+import { scoreEmotion } from '../analysis/emotions.js';
+import { ok, fail } from '../response.js';
+import { defaultSession } from '../client.js';
+export async function toolProcessDetect(engram, input) {
+    const start = Date.now();
+    const sessionId = input.session_id ?? defaultSession();
+    const processType = input.process_type ?? 'all';
+    const minOccurrences = input.min_occurrences ?? 2;
+    try {
+        // Fetch a broad set of memories to detect patterns
+        const memories = await engram.recall(sessionId, input.entity_focus ?? undefined, {
+            limit: 100,
+            threshold: input.entity_focus ? 0.5 : 0,
+            tiers: ['working', 'long_term'],
+            after: input.time_range?.start ? new Date(input.time_range.start) : undefined,
+            before: input.time_range?.end ? new Date(input.time_range.end) : undefined,
+        });
+        if (memories.length < minOccurrences) {
+            return ok({ processes: [], insights: [], memory_count: memories.length }, sessionId, start, [
+                `Only ${memories.length} memories found — store more to enable pattern detection`,
+            ]);
+        }
+        const processes = [];
+        if (processType === 'decision' || processType === 'all') {
+            const decisions = detectDecisionPatterns(memories, minOccurrences);
+            processes.push(...decisions);
+        }
+        if (processType === 'planning' || processType === 'all') {
+            const planning = detectPlanningPatterns(memories, minOccurrences);
+            processes.push(...planning);
+        }
+        if (processType === 'learning' || processType === 'all') {
+            const learning = detectLearningPatterns(memories, minOccurrences);
+            processes.push(...learning);
+        }
+        if (processType === 'conflict' || processType === 'all') {
+            const conflicts = detectConflictPatterns(memories, minOccurrences);
+            processes.push(...conflicts);
+        }
+        // Generate insights
+        const insights = generateInsights(memories, processes);
+        return ok({
+            processes,
+            insights,
+            memory_count: memories.length,
+            time_range_analyzed: {
+                from: memories[memories.length - 1]?.timestamp.toISOString() ?? null,
+                to: memories[0]?.timestamp.toISOString() ?? null,
+            },
+        }, sessionId, start);
+    }
+    catch (err) {
+        return fail('PROCESS_DETECT_FAILED', String(err), sessionId, start);
+    }
+}
+const DECISION_KEYWORDS = ['decided', 'decision', 'chose', 'choice', 'option', 'will go with',
+    'going with', 'pick', 'select', 'prefer', 'instead', 'rather', 'pivot', 'switch to'];
+const PLANNING_KEYWORDS = ['plan', 'schedule', 'next step', 'todo', 'will do', 'need to',
+    'should', 'going to', 'agenda', 'roadmap', 'milestone', 'deadline', 'by end of'];
+const LEARNING_KEYWORDS = ['learned', 'realized', 'discovered', 'found out', 'understand',
+    'figured out', 'now know', 'insight', 'aha', 'interesting', 'turns out'];
+const CONFLICT_KEYWORDS = ['frustrated', 'problem', 'issue', 'conflict', 'disagree',
+    'not working', 'broken', 'stuck', 'blocked', 'challenge', 'difficulty'];
+function detectDecisionPatterns(memories, minOcc) {
+    const relevant = memories.filter(m => DECISION_KEYWORDS.some(kw => m.content.toLowerCase().includes(kw)));
+    if (relevant.length < minOcc)
+        return [];
+    const entities = topEntities(relevant);
+    const themes = topThemes(relevant);
+    const emotionalArc = buildEmotionalArcString(relevant);
+    return [{
+            id: `proc_decision_${Date.now()}`,
+            name: 'Decision-Making Loop',
+            type: 'decision',
+            occurrences: relevant.length,
+            entities_involved: entities,
+            common_themes: themes,
+            typical_emotional_arc: emotionalArc,
+            last_occurrence: relevant[0]?.timestamp.toISOString() ?? '',
+            related_memories: relevant.slice(0, 5).map(m => m.id),
+        }];
+}
+function detectPlanningPatterns(memories, minOcc) {
+    const relevant = memories.filter(m => PLANNING_KEYWORDS.some(kw => m.content.toLowerCase().includes(kw)));
+    if (relevant.length < minOcc)
+        return [];
+    return [{
+            id: `proc_planning_${Date.now()}`,
+            name: 'Planning Session',
+            type: 'planning',
+            occurrences: relevant.length,
+            entities_involved: topEntities(relevant),
+            common_themes: topThemes(relevant),
+            typical_emotional_arc: buildEmotionalArcString(relevant),
+            last_occurrence: relevant[0]?.timestamp.toISOString() ?? '',
+            related_memories: relevant.slice(0, 5).map(m => m.id),
+        }];
+}
+function detectLearningPatterns(memories, minOcc) {
+    const relevant = memories.filter(m => LEARNING_KEYWORDS.some(kw => m.content.toLowerCase().includes(kw)));
+    if (relevant.length < minOcc)
+        return [];
+    return [{
+            id: `proc_learning_${Date.now()}`,
+            name: 'Learning / Discovery',
+            type: 'learning',
+            occurrences: relevant.length,
+            entities_involved: topEntities(relevant),
+            common_themes: topThemes(relevant),
+            typical_emotional_arc: buildEmotionalArcString(relevant),
+            last_occurrence: relevant[0]?.timestamp.toISOString() ?? '',
+            related_memories: relevant.slice(0, 5).map(m => m.id),
+        }];
+}
+function detectConflictPatterns(memories, minOcc) {
+    const relevant = memories.filter(m => CONFLICT_KEYWORDS.some(kw => m.content.toLowerCase().includes(kw)));
+    if (relevant.length < minOcc)
+        return [];
+    return [{
+            id: `proc_conflict_${Date.now()}`,
+            name: 'Friction / Conflict Pattern',
+            type: 'conflict',
+            occurrences: relevant.length,
+            entities_involved: topEntities(relevant),
+            common_themes: topThemes(relevant),
+            typical_emotional_arc: buildEmotionalArcString(relevant),
+            last_occurrence: relevant[0]?.timestamp.toISOString() ?? '',
+            related_memories: relevant.slice(0, 5).map(m => m.id),
+        }];
+}
+function topEntities(memories) {
+    const counts = {};
+    for (const m of memories) {
+        for (const e of extractEntities(m.content)) {
+            const k = e.name.toLowerCase();
+            counts[k] = (counts[k] ?? 0) + 1;
+        }
+    }
+    return Object.entries(counts)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 5)
+        .map(([name]) => name);
+}
+function topThemes(memories) {
+    const counts = {};
+    for (const m of memories) {
+        for (const t of themeNames(m.content, 3)) {
+            counts[t] = (counts[t] ?? 0) + 1;
+        }
+    }
+    return Object.entries(counts)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 3)
+        .map(([t]) => t);
+}
+function buildEmotionalArcString(memories) {
+    if (memories.length === 0)
+        return 'unknown';
+    const sorted = [...memories].sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    const tones = sorted.map(m => scoreEmotion(m.content).tone);
+    // Deduplicate consecutive same tones
+    const deduped = [];
+    for (const t of tones) {
+        if (deduped[deduped.length - 1] !== t)
+            deduped.push(t);
+    }
+    return deduped.slice(0, 5).join(' → ');
+}
+function generateInsights(memories, processes) {
+    const insights = [];
+    if (processes.length === 0) {
+        insights.push('No recurring patterns detected yet — more memories needed');
+        return insights;
+    }
+    // Check for high decision frequency
+    const decisionProc = processes.find(p => p.type === 'decision');
+    if (decisionProc && decisionProc.occurrences > 5) {
+        insights.push(`High decision frequency (${decisionProc.occurrences} instances) — consider documenting decision criteria`);
+    }
+    // Check for conflict patterns without resolution
+    const conflictProc = processes.find(p => p.type === 'conflict');
+    const learningProc = processes.find(p => p.type === 'learning');
+    if (conflictProc && !learningProc) {
+        insights.push('Friction patterns detected without corresponding learning moments — consider reflection');
+    }
+    if (learningProc && learningProc.occurrences > 3) {
+        insights.push(`Active learning phase detected — ${learningProc.occurrences} discovery moments`);
+    }
+    // Most active entities
+    const allEntities = topEntities(memories);
+    if (allEntities.length > 0) {
+        insights.push(`Most referenced entity: '${allEntities[0]}' — appears central to current work`);
+    }
+    return insights;
+}
+export const PROCESS_DETECT_SCHEMA = {
+    name: 'process_detect',
+    description: 'Identify recurring conversation and behavior patterns: decision loops, planning sessions, learning moments, and conflict patterns.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            process_type: { type: 'string', enum: ['decision', 'learning', 'conflict', 'planning', 'all'], default: 'all' },
+            session_id: { type: 'string' },
+            entity_focus: { type: 'string', description: 'Focus pattern detection on a specific entity' },
+            min_occurrences: { type: 'number', default: 2, description: 'Minimum occurrences to consider a pattern' },
+            time_range: {
+                type: 'object',
+                properties: {
+                    start: { type: 'string' },
+                    end: { type: 'string' },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=process_detect.js.map

package/dist/tools/process_detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process_detect.js","sourceRoot":"","sources":["../../src/tools/process_detect.ts"],"names":[],"mappings":"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"}

package/dist/tools/recall.d.ts

@@ -0,0 +1,81 @@
+import type { Engram } from '@cartisien/engram';
+export interface RecallInput {
+    query: string;
+    session_id?: string;
+    limit?: number;
+    min_relevance?: number;
+    include_context?: boolean;
+    time_range?: {
+        start?: string;
+        end?: string;
+    };
+    entity_filter?: string[];
+    theme_filter?: string[];
+    tiers?: string[];
+}
+export declare function toolRecall(engram: Engram, input: RecallInput): Promise<import("../response.js").McpResponse<unknown>>;
+export declare const RECALL_SCHEMA: {
+    readonly name: "recall";
+    readonly description: "Retrieve relevant memories with entity, theme, and emotional context. Returns 360° relational intelligence around the query.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "What to search for";
+            };
+            readonly session_id: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly default: 5;
+                readonly description: "Max results (default: 5, max: 50)";
+            };
+            readonly min_relevance: {
+                readonly type: "number";
+                readonly default: 0.7;
+                readonly description: "Minimum relevance score 0-1";
+            };
+            readonly include_context: {
+                readonly type: "boolean";
+                readonly default: true;
+            };
+            readonly time_range: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly start: {
+                        readonly type: "string";
+                        readonly description: "ISO8601 start date";
+                    };
+                    readonly end: {
+                        readonly type: "string";
+                        readonly description: "ISO8601 end date";
+                    };
+                };
+            };
+            readonly entity_filter: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Only return memories mentioning these entities";
+            };
+            readonly theme_filter: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Only return memories matching these themes";
+            };
+            readonly tiers: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Memory tiers to search: working, long_term, archived";
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+};

package/dist/tools/recall.js

@@ -0,0 +1,134 @@
+import { extractEntities } from '../analysis/entities.js';
+import { themeNames } from '../analysis/themes.js';
+import { scoreEmotion, emotionalTrajectory } from '../analysis/emotions.js';
+import { ok, fail } from '../response.js';
+import { defaultSession } from '../client.js';
+export async function toolRecall(engram, input) {
+    const start = Date.now();
+    const sessionId = input.session_id ?? defaultSession();
+    if (!input.query?.trim()) {
+        return fail('INVALID_INPUT', 'query is required', sessionId, start);
+    }
+    const limit = Math.min(input.limit ?? 5, 50);
+    const threshold = input.min_relevance ?? 0.7;
+    const tiers = input.tiers ?? ['working', 'long_term'];
+    try {
+        const memories = await engram.recall(sessionId, input.query, {
+            limit: limit * 3, // over-fetch to allow post-filtering
+            threshold,
+            tiers,
+            after: input.time_range?.start ? new Date(input.time_range.start) : undefined,
+            before: input.time_range?.end ? new Date(input.time_range.end) : undefined,
+        });
+        // Post-filter by entity
+        let filtered = memories;
+        if (input.entity_filter?.length) {
+            const ef = input.entity_filter.map(e => e.toLowerCase());
+            filtered = memories.filter(m => {
+                const mLower = m.content.toLowerCase();
+                return ef.some(e => mLower.includes(e));
+            });
+        }
+        // Post-filter by theme
+        if (input.theme_filter?.length) {
+            const tf = new Set(input.theme_filter);
+            filtered = filtered.filter(m => {
+                const themes = themeNames(m.content, 5);
+                return themes.some(t => tf.has(t));
+            });
+        }
+        const results = filtered.slice(0, limit);
+        // Enrich each memory with context
+        const enriched = results.map(m => enrichMemory(m, input.query));
+        // Build summary
+        const allThemes = enriched.flatMap(m => m.themes);
+        const themeCounts = countItems(allThemes);
+        const dominantThemes = Object.entries(themeCounts)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, 3)
+            .map(([t]) => t);
+        const tones = enriched.map(m => m.emotional_tone);
+        const trajectory = emotionalTrajectory(tones.reverse()); // oldest first
+        const timeSpan = calcTimeSpanDays(results);
+        const suggestions = [];
+        if (filtered.length > limit) {
+            suggestions.push(`${filtered.length - limit} more results available — increase 'limit' or narrow filters`);
+        }
+        if (dominantThemes[0]) {
+            suggestions.push(`Try 'context' with target_type='theme' for '${dominantThemes[0]}'`);
+        }
+        return ok({
+            memories: enriched,
+            summary: {
+                total_found: memories.length,
+                returned: results.length,
+                time_span_days: timeSpan,
+                dominant_themes: dominantThemes,
+                emotional_trajectory: trajectory,
+            },
+        }, sessionId, start, suggestions);
+    }
+    catch (err) {
+        return fail('RECALL_FAILED', String(err), sessionId, start);
+    }
+}
+function enrichMemory(m, query) {
+    const entities = extractEntities(m.content).slice(0, 5);
+    const themes = themeNames(m.content, 3);
+    const emotion = scoreEmotion(m.content);
+    return {
+        id: m.id,
+        content: m.content,
+        relevance_score: m.similarity ?? 0,
+        retrieval_method: m.similarity && m.similarity > 0 ? 'hybrid' : 'fts',
+        timestamp: m.timestamp.toISOString(),
+        session_id: m.sessionId,
+        role: m.role,
+        tier: m.tier,
+        importance: m.importance,
+        entities: entities.map(e => ({ name: e.name, type: e.type, confidence: e.confidence })),
+        themes,
+        emotional_tone: emotion.tone,
+    };
+}
+function countItems(items) {
+    const counts = {};
+    for (const item of items) {
+        counts[item] = (counts[item] ?? 0) + 1;
+    }
+    return counts;
+}
+function calcTimeSpanDays(memories) {
+    if (memories.length < 2)
+        return 0;
+    const times = memories.map(m => m.timestamp.getTime());
+    const min = Math.min(...times);
+    const max = Math.max(...times);
+    return Math.round((max - min) / (1000 * 60 * 60 * 24));
+}
+export const RECALL_SCHEMA = {
+    name: 'recall',
+    description: 'Retrieve relevant memories with entity, theme, and emotional context. Returns 360° relational intelligence around the query.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'What to search for' },
+            session_id: { type: 'string' },
+            limit: { type: 'number', default: 5, description: 'Max results (default: 5, max: 50)' },
+            min_relevance: { type: 'number', default: 0.7, description: 'Minimum relevance score 0-1' },
+            include_context: { type: 'boolean', default: true },
+            time_range: {
+                type: 'object',
+                properties: {
+                    start: { type: 'string', description: 'ISO8601 start date' },
+                    end: { type: 'string', description: 'ISO8601 end date' },
+                },
+            },
+            entity_filter: { type: 'array', items: { type: 'string' }, description: 'Only return memories mentioning these entities' },
+            theme_filter: { type: 'array', items: { type: 'string' }, description: 'Only return memories matching these themes' },
+            tiers: { type: 'array', items: { type: 'string' }, description: 'Memory tiers to search: working, long_term, archived' },
+        },
+        required: ['query'],
+    },
+};
+//# sourceMappingURL=recall.js.map

package/dist/tools/recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.js","sourceRoot":"","sources":["../../src/tools/recall.ts"],"names":[],"mappings":"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"}

package/dist/tools/remember.d.ts

@@ -0,0 +1,47 @@
+import type { Engram } from '@cartisien/engram';
+export interface RememberInput {
+    content: string;
+    role?: string;
+    session_id?: string;
+    timestamp?: string;
+    metadata?: Record<string, unknown>;
+    extract_entities?: boolean;
+    link_to_session?: boolean;
+}
+export declare function toolRemember(engram: Engram, input: RememberInput): Promise<import("../response.js").McpResponse<unknown>>;
+export declare const REMEMBER_SCHEMA: {
+    readonly name: "remember";
+    readonly description: "Store a new memory with automatic entity extraction, theme detection, and relationship mapping.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The memory text to store";
+            };
+            readonly role: {
+                readonly type: "string";
+                readonly enum: readonly ["user", "assistant", "system"];
+                readonly default: "user";
+            };
+            readonly session_id: {
+                readonly type: "string";
+                readonly description: "Session identifier (defaults to ENGRAM_SESSION_ID)";
+            };
+            readonly timestamp: {
+                readonly type: "string";
+                readonly description: "ISO8601 timestamp (defaults to now)";
+            };
+            readonly metadata: {
+                readonly type: "object";
+                readonly description: "Arbitrary key-value metadata";
+            };
+            readonly extract_entities: {
+                readonly type: "boolean";
+                readonly default: true;
+                readonly description: "Auto-extract entities and store in graph";
+            };
+        };
+        readonly required: readonly ["content"];
+    };
+};

package/dist/tools/remember.js

@@ -0,0 +1,79 @@
+import { extractEntities, entityRelation } from '../analysis/entities.js';
+import { themeNames } from '../analysis/themes.js';
+import { scoreEmotion } from '../analysis/emotions.js';
+import { ok, fail } from '../response.js';
+import { defaultSession } from '../client.js';
+export async function toolRemember(engram, input) {
+    const start = Date.now();
+    const sessionId = input.session_id ?? defaultSession();
+    if (!input.content?.trim()) {
+        return fail('INVALID_INPUT', 'content is required', sessionId, start);
+    }
+    const role = (input.role ?? 'user');
+    const extractEntitiesFlag = input.extract_entities !== false;
+    const meta = { ...(input.metadata ?? {}) };
+    if (input.timestamp)
+        meta.original_timestamp = input.timestamp;
+    try {
+        const entry = await engram.remember(sessionId, input.content, role, meta);
+        // Entity extraction + graph storage
+        let extractedEntities = [];
+        if (extractEntitiesFlag) {
+            extractedEntities = extractEntities(input.content);
+            // Store additional semantic edges beyond what Engram's extractGraph does
+            const memoryEntity = `memory:${entry.id}`;
+            for (const entity of extractedEntities) {
+                const relation = entityRelation(entity.type);
+                await engram.storeEdge(sessionId, memoryEntity, relation, entity.name.toLowerCase(), entity.confidence, entry.id);
+                // Entity-to-entity: link co-occurring entities
+                for (const other of extractedEntities) {
+                    if (other.name !== entity.name) {
+                        await engram.storeEdge(sessionId, entity.name.toLowerCase(), 'co_occurs_with', other.name.toLowerCase(), 0.6, entry.id);
+                    }
+                }
+            }
+        }
+        // Theme + emotion analysis
+        const themes = themeNames(input.content);
+        const emotion = scoreEmotion(input.content);
+        // Find linked memories (recent from same session)
+        const linked = await engram.recall(sessionId, input.content, { limit: 3, threshold: 0.75 });
+        const linkedIds = linked
+            .filter(m => m.id !== entry.id)
+            .map(m => m.id)
+            .slice(0, 3);
+        const suggestions = [];
+        if (themes.length > 0)
+            suggestions.push(`Try 'recall' with theme_filter: [\"${themes[0]}\"]`);
+        if (extractedEntities.length > 0)
+            suggestions.push(`Try 'context' for entity \"${extractedEntities[0].name}\"`);
+        return ok({
+            memory_id: entry.id,
+            extracted_entities: extractedEntities.slice(0, 10),
+            linked_memories: linkedIds,
+            themes_detected: themes,
+            emotional_tone: emotion.tone,
+            tier: entry.tier,
+        }, sessionId, start, suggestions);
+    }
+    catch (err) {
+        return fail('STORE_FAILED', String(err), sessionId, start);
+    }
+}
+export const REMEMBER_SCHEMA = {
+    name: 'remember',
+    description: 'Store a new memory with automatic entity extraction, theme detection, and relationship mapping.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            content: { type: 'string', description: 'The memory text to store' },
+            role: { type: 'string', enum: ['user', 'assistant', 'system'], default: 'user' },
+            session_id: { type: 'string', description: 'Session identifier (defaults to ENGRAM_SESSION_ID)' },
+            timestamp: { type: 'string', description: 'ISO8601 timestamp (defaults to now)' },
+            metadata: { type: 'object', description: 'Arbitrary key-value metadata' },
+            extract_entities: { type: 'boolean', default: true, description: 'Auto-extract entities and store in graph' },
+        },
+        required: ['content'],
+    },
+};
+//# sourceMappingURL=remember.js.map

package/dist/tools/remember.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember.js","sourceRoot":"","sources":["../../src/tools/remember.ts"],"names":[],"mappings":"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"}