@feelingmindful/thinking-graph 1.4.0 → 1.5.0

package/dist/index.js

@@ -9,6 +9,7 @@ import { relateSchema, relateHandler } from './tools/relate.js';
 import { recallSchema, recallHandler } from './tools/recall.js';
 import { learnSchema, learnHandler } from './tools/learn.js';
 import { exportSchema, exportHandler } from './tools/export.js';
+import { researchSchema, researchHandler } from './tools/research.js';
 // Legacy compat shim removed — use `think` tool directly
 // ─── Storage setup ───────────────────────────────────────
 const memoryOnly = process.env.THINKING_GRAPH_MEMORY_ONLY === 'true';
@@ -30,6 +31,7 @@ server.tool('relate', 'Create a typed, directional relationship between two node
 server.tool('recall', 'Query the thinking graph — search by text, filter by type, traverse relationships, or search across projects.', recallSchema.shape, async (input) => recallHandler(graph, input));
 server.tool('learn', 'Store durable knowledge — code facts, tech debt, insights, principles. Deduplicates similar content.', learnSchema.shape, async (input) => learnHandler(graph, input));
 server.tool('export', 'Export the thinking graph as JSON or a human-readable markdown summary.', exportSchema.shape, async (input) => exportHandler(graph, input));
+server.tool('research', 'Research a topic using Perplexity/Firecrawl, then ingest findings into the graph. Two-phase: call once to get an action plan, then again with findings to store them.', researchSchema.shape, async (input) => researchHandler(graph, input));
 // ─── Startup ─────────────────────────────────────────────
 async function main() {
     await storage.initialize();

package/dist/tools/learn.d.ts

@@ -30,13 +30,13 @@ export declare const learnSchema: z.ZodObject<{
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
+    filePath?: string | undefined;
+    lineRange?: [number, number] | undefined;
     relates?: {
         type: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by";
         targetId: string;
         reasoning?: string | undefined;
     }[] | undefined;
-    filePath?: string | undefined;
-    lineRange?: [number, number] | undefined;
     effort?: string | undefined;
     impact?: string | undefined;
     violatedBy?: string[] | undefined;
@@ -46,13 +46,13 @@ export declare const learnSchema: z.ZodObject<{
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
+    filePath?: string | undefined;
+    lineRange?: [number, number] | undefined;
     relates?: {
         type: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by";
         targetId: string;
         reasoning?: string | undefined;
     }[] | undefined;
-    filePath?: string | undefined;
-    lineRange?: [number, number] | undefined;
     effort?: string | undefined;
     impact?: string | undefined;
     violatedBy?: string[] | undefined;

package/dist/tools/research.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import type { ThinkingGraph } from '../engine/graph.js';
+export declare const researchSchema: z.ZodObject<{
+    query: z.ZodString;
+    intent: z.ZodDefault<z.ZodEnum<["fact_check", "explore", "compare", "how_to", "current_state"]>>;
+    context: z.ZodOptional<z.ZodString>;
+    researchId: z.ZodOptional<z.ZodString>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        source: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }, {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }>, "many">>;
+    projectId: z.ZodOptional<z.ZodString>;
+    scrapeUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    recencyFilter: z.ZodOptional<z.ZodEnum<["hour", "day", "week", "month", "year"]>>;
+    domainFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    intent: "fact_check" | "explore" | "compare" | "how_to" | "current_state";
+    projectId?: string | undefined;
+    context?: string | undefined;
+    researchId?: string | undefined;
+    findings?: {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }[] | undefined;
+    scrapeUrls?: string[] | undefined;
+    recencyFilter?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    domainFilter?: string[] | undefined;
+}, {
+    query: string;
+    projectId?: string | undefined;
+    intent?: "fact_check" | "explore" | "compare" | "how_to" | "current_state" | undefined;
+    context?: string | undefined;
+    researchId?: string | undefined;
+    findings?: {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }[] | undefined;
+    scrapeUrls?: string[] | undefined;
+    recencyFilter?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    domainFilter?: string[] | undefined;
+}>;
+export type ResearchInput = z.infer<typeof researchSchema>;
+export declare function researchHandler(graph: ThinkingGraph, input: ResearchInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/research.js

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
+const RESEARCH_INTENTS = [
+    'fact_check', // Verify a claim or assumption
+    'explore', // Open-ended exploration of a topic
+    'compare', // Compare options, libraries, approaches
+    'how_to', // Find implementation guidance
+    'current_state', // Get current state of something (version, status, etc.)
+];
+const findingSchema = z.object({
+    content: z.string().describe('What was found'),
+    source: z.string().optional().describe('URL or citation'),
+    confidence: z.enum(['high', 'medium', 'low']).optional(),
+});
+export const researchSchema = z.object({
+    // Phase 1: initiate research
+    query: z.string().describe('What to research'),
+    intent: z.enum(RESEARCH_INTENTS).default('explore').describe('Research intent — guides tool selection'),
+    context: z.string().optional().describe('Why this research matters to the current task'),
+    // Phase 2: ingest findings (provide researchId from phase 1)
+    researchId: z.string().optional().describe('Node ID from phase 1 — triggers ingestion mode'),
+    findings: z.array(findingSchema).optional().describe('Results to store (phase 2)'),
+    // Options
+    projectId: z.string().optional(),
+    scrapeUrls: z.array(z.string()).optional().describe('Specific URLs to scrape with Firecrawl'),
+    recencyFilter: z.enum(['hour', 'day', 'week', 'month', 'year']).optional().describe('How recent results should be'),
+    domainFilter: z.array(z.string()).optional().describe('Restrict to these domains'),
+});
+function buildActionPlan(input) {
+    const steps = [];
+    const query = input.query;
+    // Choose Perplexity tool based on intent
+    switch (input.intent) {
+        case 'fact_check':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_ask',
+                description: 'Quick fact check with citations',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_context_size: 'medium',
+                    ...(input.recencyFilter && { search_recency_filter: input.recencyFilter }),
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+        case 'compare':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_reason',
+                description: 'Step-by-step comparison with web grounding',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_context_size: 'high',
+                    ...(input.recencyFilter && { search_recency_filter: input.recencyFilter }),
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+        case 'explore':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_research',
+                description: 'Deep multi-source research (30s+)',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    reasoning_effort: 'medium',
+                },
+            });
+            break;
+        case 'how_to':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_ask',
+                description: 'Find implementation guidance',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_context_size: 'high',
+                    ...(input.recencyFilter && { search_recency_filter: input.recencyFilter }),
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+        case 'current_state':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_ask',
+                description: 'Get current state with recency filter',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_recency_filter: input.recencyFilter ?? 'week',
+                    search_context_size: 'medium',
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+    }
+    // If specific URLs provided, add Firecrawl scrape steps
+    if (input.scrapeUrls?.length) {
+        for (const url of input.scrapeUrls) {
+            steps.push({
+                tool: 'mcp__firecrawl__firecrawl_scrape',
+                description: `Scrape ${url}`,
+                args: {
+                    url,
+                    formats: ['markdown'],
+                    onlyMainContent: true,
+                },
+            });
+        }
+    }
+    // For explore/compare, also suggest a Firecrawl search for additional sources
+    if (input.intent === 'explore' || input.intent === 'compare') {
+        steps.push({
+            tool: 'mcp__firecrawl__firecrawl_search',
+            description: 'Search for additional sources',
+            args: {
+                query,
+                limit: 5,
+                sources: [{ type: 'web' }],
+            },
+        });
+    }
+    return steps;
+}
+export async function researchHandler(graph, input) {
+    // ── Phase 2: ingest findings ──────────────────────────
+    if (input.researchId && input.findings?.length) {
+        const researchNode = await graph.getNode(input.researchId);
+        if (!researchNode) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `Research node ${input.researchId} not found` }),
+                    }],
+            };
+        }
+        const session = await graph.getCurrentSession();
+        const storedNodes = [];
+        for (const finding of input.findings) {
+            // Check for duplicates
+            const existing = await graph.findSimilar(finding.content, 'research', input.projectId);
+            if (existing) {
+                storedNodes.push(existing.id);
+                continue;
+            }
+            const node = await graph.addNode({
+                type: 'research',
+                content: finding.content,
+                sessionId: session.id,
+                projectId: input.projectId,
+                metadata: {
+                    source: finding.source,
+                    confidence: finding.confidence,
+                    researchQuery: researchNode.content,
+                },
+            });
+            // Relate finding back to the research query node
+            await graph.addEdge({
+                sourceId: node.id,
+                targetId: input.researchId,
+                type: 'supports',
+                reasoning: 'Finding from research query',
+            });
+            storedNodes.push(node.id);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        phase: 'ingest',
+                        researchId: input.researchId,
+                        storedCount: storedNodes.length,
+                        nodeIds: storedNodes,
+                        suggestions: [
+                            {
+                                tool: 'relate',
+                                when: 'Connect these findings to the thoughts/decisions they inform',
+                                example: {
+                                    sourceId: '<thought nodeId>',
+                                    targetId: storedNodes[0] ?? '<finding nodeId>',
+                                    type: 'depends_on',
+                                    reasoning: 'Decision informed by research',
+                                },
+                            },
+                            {
+                                tool: 'learn',
+                                when: 'Promote a key finding to a durable insight that persists cross-project',
+                                example: {
+                                    content: '<key takeaway>',
+                                    type: 'insight',
+                                    relates: [{ type: 'refines', targetId: input.researchId }],
+                                },
+                            },
+                        ],
+                    }),
+                }],
+        };
+    }
+    // ── Phase 1: initiate research ────────────────────────
+    const session = await graph.getCurrentSession();
+    const node = await graph.addNode({
+        type: 'research',
+        content: input.query,
+        sessionId: session.id,
+        projectId: input.projectId,
+        metadata: {
+            intent: input.intent,
+            context: input.context,
+            status: 'pending',
+        },
+    });
+    const actionPlan = buildActionPlan(input);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    phase: 'initiate',
+                    researchId: node.id,
+                    query: input.query,
+                    intent: input.intent,
+                    actionPlan,
+                    ingestStep: {
+                        tool: 'research',
+                        description: 'After executing the action plan, pipe findings back here',
+                        args: {
+                            query: input.query,
+                            researchId: node.id,
+                            findings: [
+                                {
+                                    content: '<summarize what you found>',
+                                    source: '<url or citation>',
+                                    confidence: 'high',
+                                },
+                            ],
+                        },
+                    },
+                }),
+            }],
+    };
+}

package/dist/tools/think.js

@@ -1,6 +1,79 @@
 import { z } from 'zod';
-import { NODE_TYPES, EDGE_TYPES } from '../engine/types.js';
+import { NODE_TYPES, EDGE_TYPES, GLOBAL_NODE_TYPES } from '../engine/types.js';
 const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
+function buildSuggestions(type, thoughtNumber, relatedCount, stats) {
+    const suggestions = [];
+    // First thought in session — suggest recall to check prior knowledge
+    if (thoughtNumber === 1 && stats.totalNodes > 1) {
+        suggestions.push({
+            tool: 'recall',
+            when: 'Check what the graph already knows before reasoning from scratch',
+            example: { query: '<topic>', crossProject: true },
+        });
+    }
+    // Decision nodes with no relationships — suggest relate
+    if (type === 'decision' && relatedCount === 0) {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Connect this decision to what it depends on or what it supersedes',
+            example: { sourceId: '<this nodeId>', targetId: '?<search term>', type: 'depends_on' },
+        });
+    }
+    // Assumption nodes — suggest relate and research to verify
+    if (type === 'assumption') {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Link this assumption to the decision or design it supports',
+            example: { sourceId: '<this nodeId>', targetId: '?<decision>', type: 'supports' },
+        });
+        suggestions.push({
+            tool: 'research',
+            when: 'Verify this assumption with external sources before building on it',
+            example: { query: '<the assumption to verify>', intent: 'fact_check' },
+        });
+    }
+    // Detection or tech_debt — suggest relate to violated principle
+    if (type === 'detection' || type === 'tech_debt') {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Link to the principle this violates (pre-seeded: SRP, DRY, YAGNI, etc.)',
+            example: { sourceId: '<this nodeId>', targetId: '?<principle name>', type: 'violates' },
+        });
+    }
+    // Insight, pattern, or principle — suggest learn to persist cross-project
+    if (GLOBAL_NODE_TYPES.includes(type)) {
+        suggestions.push({
+            tool: 'learn',
+            when: 'Persist this so it carries across sessions and projects',
+            example: { content: '<the insight>', type },
+        });
+    }
+    // Code fact — suggest learn with file metadata
+    if (type === 'code_fact') {
+        suggestions.push({
+            tool: 'learn',
+            when: 'Store this code fact with its file location for future recall',
+            example: { content: '<fact>', type: 'code_fact', filePath: '<path>', lineRange: [0, 0] },
+        });
+    }
+    // Research node via think — redirect to the full research tool
+    if (type === 'research') {
+        suggestions.push({
+            tool: 'research',
+            when: 'Use the research tool instead — it generates an action plan with Perplexity/Firecrawl calls and handles ingestion',
+            example: { query: '<what to research>', intent: 'explore' },
+        });
+    }
+    // Generic: if the node has no relationships and there are other nodes, nudge relate
+    if (relatedCount === 0 && stats.totalNodes > 2 && type === 'thought') {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Connect this thought to related nodes (use "?<search>" to find by content)',
+            example: { sourceId: '<this nodeId>', targetId: '?<search term>', type: 'supports' },
+        });
+    }
+    return suggestions;
+}
 export const thinkSchema = z.object({
     thought: z.string().describe('The reasoning content'),
     type: z.enum(NODE_TYPES).default('thought').describe('Node type'),
@@ -53,6 +126,7 @@ export async function thinkHandler(graph, input) {
         }
     }
     const stats = await graph.storage.getStats();
+    const suggestions = buildSuggestions(input.type ?? 'thought', input.thoughtNumber, relatedCount, stats);
     return {
         content: [{
                 type: 'text',
@@ -64,6 +138,7 @@ export async function thinkHandler(graph, input) {
                     branches: [],
                     thoughtHistoryLength: stats.totalNodes,
                     relatedNodes: relatedCount,
+                    ...(suggestions.length > 0 && { suggestions }),
                 }),
             }],
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelingmindful/thinking-graph",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Persistent graph-based MCP thinking server for the feeling-mindful plugin marketplace",
   "type": "module",
   "main": "dist/index.js",