@getlore/cli 0.2.0

package/dist/mcp/handlers/research-agent.js

@@ -0,0 +1,369 @@
+/**
+ * Lore - Agentic Research using Claude Agent SDK
+ *
+ * This is the "real" agent that:
+ * 1. Takes a research task
+ * 2. Uses Lore's own tools iteratively (search, get_source, list_sources)
+ * 3. Follows leads, cross-references, refines queries
+ * 4. Synthesizes findings into a comprehensive research package
+ */
+import { query, tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { searchSources, getSourceById, getAllSources } from '../../core/vector-store.js';
+import { generateEmbedding } from '../../core/embedder.js';
+import { loadArchivedProjects } from './archive-project.js';
+// Agent will self-terminate when it has enough evidence
+// This is a safety limit to prevent runaway loops
+const MAX_TURNS = 50;
+/**
+ * Create the Lore tools MCP server for the research agent
+ */
+function createLoreToolsServer(dbPath, dataDir, archivedProjects) {
+    return createSdkMcpServer({
+        name: 'lore-tools',
+        version: '1.0.0',
+        tools: [
+            // Search tool - semantic search across sources
+            tool('search', 'Semantic search across all sources in the knowledge repository. Returns summaries with relevant quotes. Use this to find information related to a topic.', {
+                query: z.string().describe('Semantic search query - describe what you\'re looking for'),
+                source_type: z
+                    .enum(['granola', 'claude-code', 'claude-desktop', 'chatgpt', 'markdown', 'document'])
+                    .optional()
+                    .describe('Filter by source type (e.g., "granola" for meeting transcripts)'),
+                content_type: z
+                    .enum(['interview', 'meeting', 'conversation', 'document', 'note', 'analysis'])
+                    .optional()
+                    .describe('Filter by content type (e.g., "interview" for user interviews)'),
+                project: z.string().optional().describe('Filter to specific project'),
+                limit: z.number().optional().describe('Max results (default 10)'),
+            }, async (args) => {
+                try {
+                    const queryVector = await generateEmbedding(args.query);
+                    const results = await searchSources(dbPath, queryVector, {
+                        limit: args.limit || 10,
+                        project: args.project,
+                        source_type: args.source_type,
+                        content_type: args.content_type,
+                    });
+                    // Filter out archived projects
+                    const filtered = results.filter((r) => {
+                        return !r.projects.some((p) => archivedProjects.includes(p.toLowerCase()));
+                    });
+                    if (filtered.length === 0) {
+                        return {
+                            content: [{ type: 'text', text: 'No results found for this query.' }],
+                        };
+                    }
+                    const resultText = filtered
+                        .map((r, i) => {
+                        const quotes = r.quotes.slice(0, 3).map((q) => `  - "${q.text.substring(0, 150)}..."`).join('\n');
+                        return `${i + 1}. **${r.title}** (${r.source_type}, score: ${(r.score * 100).toFixed(0)}%)
+   ID: ${r.id}
+   Projects: ${r.projects.join(', ') || 'none'}
+   Summary: ${r.summary.substring(0, 200)}...
+   Key quotes:
+${quotes}`;
+                    })
+                        .join('\n\n');
+                    return {
+                        content: [{ type: 'text', text: `Found ${filtered.length} results:\n\n${resultText}` }],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: 'text', text: `Search error: ${error}` }],
+                    };
+                }
+            }),
+            // Get source - retrieve full details of a specific source
+            tool('get_source', 'Get full details of a specific source document including all quotes, themes, and summary. Use this to dive deeper into a specific source found via search.', {
+                source_id: z.string().describe('ID of the source document (from search results)'),
+            }, async (args) => {
+                try {
+                    const source = await getSourceById(dbPath, args.source_id);
+                    if (!source) {
+                        return {
+                            content: [{ type: 'text', text: `Source not found: ${args.source_id}` }],
+                        };
+                    }
+                    const themes = source.themes.map((t) => `- ${t.name}: ${t.evidence.length} pieces of evidence`).join('\n');
+                    const quotes = source.quotes
+                        .slice(0, 10)
+                        .map((q) => `- [${q.speaker || 'unknown'}] "${q.text}"`)
+                        .join('\n');
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `# ${source.title}
+
+**Type:** ${source.source_type} / ${source.content_type}
+**Created:** ${source.created_at}
+**Projects:** ${source.projects.join(', ') || 'none'}
+
+## Summary
+${source.summary}
+
+## Themes
+${themes || 'No themes extracted'}
+
+## Key Quotes
+${quotes || 'No quotes extracted'}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: 'text', text: `Error getting source: ${error}` }],
+                    };
+                }
+            }),
+            // List sources - browse available sources
+            tool('list_sources', 'List all sources in the repository. Use this to understand what knowledge is available before searching.', {
+                source_type: z
+                    .enum(['granola', 'claude-code', 'claude-desktop', 'chatgpt', 'markdown', 'document'])
+                    .optional()
+                    .describe('Filter by source type'),
+                project: z.string().optional().describe('Filter to specific project'),
+                limit: z.number().optional().describe('Max results (default 20)'),
+            }, async (args) => {
+                try {
+                    const sources = await getAllSources(dbPath, {
+                        source_type: args.source_type,
+                        project: args.project,
+                        limit: args.limit || 20,
+                    });
+                    // Filter out archived
+                    const filtered = sources.filter((s) => {
+                        return !s.projects.some((p) => archivedProjects.includes(p.toLowerCase()));
+                    });
+                    if (filtered.length === 0) {
+                        return {
+                            content: [{ type: 'text', text: 'No sources found matching criteria.' }],
+                        };
+                    }
+                    const listText = filtered
+                        .map((s, i) => {
+                        return `${i + 1}. **${s.title}** (${s.source_type})
+   ID: ${s.id}
+   Created: ${s.created_at}
+   Projects: ${s.projects.join(', ') || 'none'}`;
+                    })
+                        .join('\n\n');
+                    return {
+                        content: [{ type: 'text', text: `Found ${filtered.length} sources:\n\n${listText}` }],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: 'text', text: `Error listing sources: ${error}` }],
+                    };
+                }
+            }),
+        ],
+    });
+}
+/**
+ * Research agent system prompt
+ */
+function getResearchSystemPrompt(task, project) {
+    return `You are a research agent for Lore, a knowledge repository containing user interviews, meeting transcripts, AI conversations, and documents.
+
+Your task is to conduct comprehensive research and produce a well-cited research package.
+
+## Research Task
+${task}
+${project ? `\nFocus on project: ${project}` : ''}
+
+## Your Tools
+- **search**: Semantic search across all sources. Start broad, then refine.
+- **get_source**: Dive deep into a specific source for full context and quotes.
+- **list_sources**: See what knowledge is available.
+
+## Research Methodology
+
+1. **Explore First**: Start with broad searches to understand what's available.
+2. **Follow Leads**: When you find relevant sources, use get_source to read more and gather quotes.
+3. **Cross-Reference**: Look for patterns across multiple sources.
+4. **Identify Conflicts**: Note when sources disagree - prefer newer sources.
+5. **Synthesize When Ready**: When you feel you have sufficient evidence to answer the research task comprehensively, produce your findings.
+
+## Output Requirements
+
+When you have gathered sufficient evidence, provide your findings in this exact JSON format:
+
+\`\`\`json
+{
+  "summary": "A comprehensive 2-3 paragraph summary of findings",
+  "key_findings": ["Finding 1 with citation", "Finding 2 with citation", ...],
+  "conflicts_resolved": ["Description of any conflicts and how they were resolved"],
+  "supporting_quotes": [
+    {
+      "text": "The exact quote",
+      "speaker": "who said it",
+      "source_id": "source document ID",
+      "source_title": "title of the source"
+    }
+  ],
+  "sources_consulted": [
+    {
+      "id": "source ID",
+      "title": "source title",
+      "relevance": "why this was useful"
+    }
+  ],
+  "gaps_identified": ["What information is missing or unclear"],
+  "suggested_queries": ["Follow-up research questions"]
+}
+\`\`\`
+
+## Important Guidelines
+
+- ALWAYS cite your sources - every claim should reference a specific source
+- When sources conflict, note the conflict and prefer the more recent source
+- Be thorough - use multiple searches with different queries
+- Include direct quotes as evidence
+- Identify what you DIDN'T find (gaps)
+- Suggest follow-up questions
+
+Now begin your research. Use the tools iteratively until you have comprehensive findings.`;
+}
+/**
+ * Run the agentic research
+ */
+export async function runResearchAgent(dbPath, dataDir, args) {
+    const { task, project, include_sources = true } = args;
+    // Load archived projects to filter (extract just the project names)
+    const archivedProjectsData = await loadArchivedProjects(dataDir);
+    const archivedProjects = archivedProjectsData.map((p) => p.project.toLowerCase());
+    // Create the Lore tools server
+    const loreTools = createLoreToolsServer(dbPath, dataDir, archivedProjects);
+    // System prompt
+    const systemPrompt = getResearchSystemPrompt(task, project);
+    let finalResult = null;
+    let lastAssistantMessage = '';
+    try {
+        // Run the agent
+        for await (const message of query({
+            prompt: `Research task: ${task}${project ? ` (project: ${project})` : ''}`,
+            options: {
+                systemPrompt,
+                mcpServers: {
+                    'lore-tools': loreTools,
+                },
+                allowedTools: [
+                    'mcp__lore-tools__search',
+                    'mcp__lore-tools__get_source',
+                    'mcp__lore-tools__list_sources',
+                ],
+                maxTurns: MAX_TURNS,
+                permissionMode: 'acceptEdits', // Auto-approve tool calls
+            },
+        })) {
+            // Capture assistant messages (intermediate)
+            if (message.type === 'assistant') {
+                const msg = message;
+                if (msg.message?.content) {
+                    const content = msg.message.content;
+                    if (typeof content === 'string') {
+                        lastAssistantMessage = content;
+                    }
+                    else if (Array.isArray(content)) {
+                        const textBlocks = content.filter((b) => b.type === 'text');
+                        if (textBlocks.length > 0) {
+                            lastAssistantMessage = textBlocks.map((b) => b.text).join('\n');
+                        }
+                    }
+                }
+            }
+            // Capture the final result message
+            if (message.type === 'result') {
+                const msg = message;
+                if (msg.subtype === 'success' && msg.result) {
+                    lastAssistantMessage = msg.result;
+                    console.error(`[research-agent] Completed in ${msg.num_turns} turns`);
+                }
+                else if (msg.subtype?.startsWith('error')) {
+                    console.error(`[research-agent] Error: ${msg.subtype}`, msg.errors);
+                }
+            }
+            // Log tool usage for debugging
+            if (message.type === 'tool_use_summary') {
+                const msg = message;
+                console.error(`[research-agent] Tool: ${msg.tool_name || 'unknown'}`);
+            }
+        }
+        // Parse the final result from the agent's output
+        finalResult = parseResearchOutput(lastAssistantMessage, task, project);
+    }
+    catch (error) {
+        console.error('[research-agent] Error:', error);
+        // Return a minimal result on error
+        finalResult = {
+            query: task,
+            project,
+            generated_at: new Date().toISOString(),
+            summary: `Research failed: ${error}`,
+            key_findings: [],
+            supporting_quotes: [],
+            related_decisions: [],
+            sources_consulted: [],
+            gaps_identified: ['Research could not be completed due to an error'],
+        };
+    }
+    return finalResult;
+}
+/**
+ * Parse the agent's output into a ResearchPackage
+ */
+function parseResearchOutput(output, task, project) {
+    // Try to extract JSON from the output
+    const jsonMatch = output.match(/```json\s*([\s\S]*?)\s*```/);
+    if (jsonMatch) {
+        try {
+            const parsed = JSON.parse(jsonMatch[1]);
+            return {
+                query: task,
+                project,
+                generated_at: new Date().toISOString(),
+                summary: parsed.summary || '',
+                key_findings: parsed.key_findings || [],
+                conflicts_resolved: parsed.conflicts_resolved || [],
+                supporting_quotes: (parsed.supporting_quotes || []).map((q) => ({
+                    id: `quote_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+                    text: q.text,
+                    speaker: q.speaker,
+                    citation: {
+                        source_id: q.source_id,
+                        context: q.source_title,
+                    },
+                })),
+                related_decisions: [],
+                sources_consulted: (parsed.sources_consulted || []).map((s) => ({
+                    id: s.id,
+                    title: s.title,
+                    source_type: 'document',
+                    relevance: 0.8,
+                })),
+                gaps_identified: parsed.gaps_identified || [],
+                suggested_queries: parsed.suggested_queries || [],
+            };
+        }
+        catch (e) {
+            console.error('[research-agent] Failed to parse JSON output:', e);
+        }
+    }
+    // Fallback: return the raw output as summary
+    return {
+        query: task,
+        project,
+        generated_at: new Date().toISOString(),
+        summary: output || 'No research output generated',
+        key_findings: [],
+        supporting_quotes: [],
+        related_decisions: [],
+        sources_consulted: [],
+        gaps_identified: ['Could not parse structured output from research agent'],
+    };
+}

package/dist/mcp/handlers/research.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Research Handler - LLM-powered research synthesis
+ *
+ * Two modes:
+ * 1. AGENTIC (default): Uses Claude Agent SDK for iterative, thorough research
+ * 2. SIMPLE (fallback): Single-pass search + GPT-4o-mini synthesis
+ *
+ * Set LORE_RESEARCH_MODE=simple to use the fallback mode.
+ */
+import type { ResearchPackage } from '../../core/types.js';
+interface ResearchArgs {
+    task: string;
+    project?: string;
+    content_type?: string;
+    include_sources?: boolean;
+}
+export declare function handleResearch(dbPath: string, dataDir: string, args: ResearchArgs, options?: {
+    hookContext?: {
+        mode: 'mcp' | 'cli';
+    };
+}): Promise<ResearchPackage>;
+export {};

package/dist/mcp/handlers/research.js

@@ -0,0 +1,225 @@
+/**
+ * Research Handler - LLM-powered research synthesis
+ *
+ * Two modes:
+ * 1. AGENTIC (default): Uses Claude Agent SDK for iterative, thorough research
+ * 2. SIMPLE (fallback): Single-pass search + GPT-4o-mini synthesis
+ *
+ * Set LORE_RESEARCH_MODE=simple to use the fallback mode.
+ */
+import OpenAI from 'openai';
+import { searchSources } from '../../core/vector-store.js';
+import { generateEmbedding } from '../../core/embedder.js';
+import { loadArchivedProjects } from './archive-project.js';
+import { runResearchAgent } from './research-agent.js';
+import { getExtensionRegistry } from '../../extensions/registry.js';
+// Lazy initialization for OpenAI (only used in simple mode)
+let openaiClient = null;
+function getOpenAI() {
+    if (!openaiClient) {
+        openaiClient = new OpenAI();
+    }
+    return openaiClient;
+}
+/**
+ * Use LLM to synthesize research findings with conflict awareness
+ */
+async function synthesizeFindings(task, sources, quotes, decisions) {
+    // Sort sources by date for context (newest first in display)
+    const sortedSources = [...sources].sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+    const sourceSummaries = sortedSources
+        .map((s, i) => {
+        const date = new Date(s.created_at).toLocaleDateString();
+        return `[${i + 1}] "${s.title}" (${s.source_type}, ${date}): ${s.summary}`;
+    })
+        .join('\n\n');
+    const quoteTexts = quotes
+        .slice(0, 15)
+        .map((q, i) => {
+        const speaker = q.speaker === 'user' ? '[User]' : '[Participant]';
+        return `${i + 1}. ${speaker} "${q.text}"${q.theme ? ` (Theme: ${q.theme})` : ''}`;
+    })
+        .join('\n');
+    const decisionTexts = decisions
+        .map((d, i) => `${i + 1}. ${d.content}`)
+        .join('\n');
+    const prompt = `You are a research analyst synthesizing findings from user research and conversations.
+
+RESEARCH TASK: ${task}
+
+SOURCES FOUND (${sources.length}, sorted newest first):
+${sourceSummaries || 'No sources found.'}
+
+KEY QUOTES (${quotes.length} total, showing top 15):
+${quoteTexts || 'No quotes found.'}
+
+RELATED DECISIONS:
+${decisionTexts || 'No decisions found.'}
+
+Based on this evidence, provide a research synthesis in the following JSON format:
+{
+  "summary": "A 2-3 sentence executive summary answering the research task with the CURRENT understanding",
+  "key_findings": ["Finding 1 with evidence", "Finding 2 with evidence", "Finding 3 with evidence"],
+  "conflicts_resolved": ["Description of any conflicting info and how it was resolved, e.g., 'Earlier (Jan 5) the approach was X, but a later decision (Jan 15) changed to Y. Current approach: Y'"],
+  "gaps_identified": ["Gap or unanswered question 1", "Gap 2"],
+  "suggested_queries": ["Follow-up research query 1", "Query 2"]
+}
+
+CRITICAL GUIDELINES:
+- When sources contain CONFLICTING information, ALWAYS prefer the more recent source
+- If you detect a pivot, decision change, or evolution in thinking, note it in conflicts_resolved
+- The summary should reflect the CURRENT understanding, not historical positions
+- Key findings should reflect the latest thinking, while acknowledging evolution where relevant
+- If older sources contradict newer decisions, the newer decision takes precedence
+- Include dates when noting conflicts or changes (e.g., "As of Jan 15, the approach is X")
+- Be transparent about what changed and when - this helps users understand the lineage
+
+Respond with only the JSON object.`;
+    try {
+        const response = await getOpenAI().chat.completions.create({
+            model: 'gpt-4o-mini',
+            messages: [{ role: 'user', content: prompt }],
+            temperature: 0.3,
+            response_format: { type: 'json_object' },
+        });
+        const content = response.choices[0]?.message?.content;
+        if (!content) {
+            throw new Error('No response from LLM');
+        }
+        const result = JSON.parse(content);
+        return {
+            summary: result.summary || `Research on "${task}" found ${sources.length} sources.`,
+            key_findings: result.key_findings || [],
+            conflicts_resolved: result.conflicts_resolved || [],
+            gaps_identified: result.gaps_identified || [],
+            suggested_queries: result.suggested_queries || [],
+        };
+    }
+    catch (error) {
+        console.error('Error synthesizing findings:', error);
+        // Fallback to simple synthesis
+        return {
+            summary: `Research on "${task}" found ${sources.length} relevant sources with ${quotes.length} supporting quotes.`,
+            key_findings: sources.slice(0, 3).map((s) => s.summary),
+            conflicts_resolved: [],
+            gaps_identified: [],
+            suggested_queries: [],
+        };
+    }
+}
+export async function handleResearch(dbPath, dataDir, args, options = {}) {
+    const { task, project, include_sources = true } = args;
+    // Check if we should use agentic mode (default) or simple mode (fallback)
+    const useAgenticMode = process.env.LORE_RESEARCH_MODE !== 'simple';
+    if (useAgenticMode) {
+        console.error('[research] Using agentic mode (Claude Agent SDK)');
+        try {
+            const result = await runResearchAgent(dbPath, dataDir, args);
+            await runResearchCompletedHook(result, {
+                mode: options.hookContext?.mode || 'mcp',
+                dataDir,
+                dbPath,
+            });
+            return result;
+        }
+        catch (error) {
+            console.error('[research] Agentic mode failed, falling back to simple mode:', error);
+            // Fall through to simple mode
+        }
+    }
+    console.error('[research] Using simple mode (single-pass synthesis)');
+    const result = await handleResearchSimple(dbPath, dataDir, args);
+    await runResearchCompletedHook(result, {
+        mode: options.hookContext?.mode || 'mcp',
+        dataDir,
+        dbPath,
+    });
+    return result;
+}
+/**
+ * Simple research mode - single pass search + synthesis
+ * This is the fallback when agentic mode fails or is disabled
+ */
+async function handleResearchSimple(dbPath, dataDir, args) {
+    const { task, project, include_sources = true } = args;
+    // Use sensible defaults for simple mode
+    const sourceLimit = 10;
+    const quoteLimit = 25;
+    // Load archived projects to filter them out
+    const archivedProjects = await loadArchivedProjects(dataDir);
+    const archivedNames = new Set(archivedProjects.map((p) => p.project.toLowerCase()));
+    // Step 1: Search for relevant sources (fetch extra to account for archived filtering)
+    const queryVector = await generateEmbedding(task);
+    const rawSources = await searchSources(dbPath, queryVector, {
+        limit: sourceLimit * 2,
+        project,
+    });
+    // Filter out archived projects
+    const sources = rawSources
+        .filter((s) => !s.projects.some((p) => archivedNames.has(p.toLowerCase())))
+        .slice(0, sourceLimit);
+    // Step 2: Gather quotes from found sources (quotes are stored in source.quotes_json)
+    const allQuotes = [];
+    for (const source of sources) {
+        for (const quote of source.quotes) {
+            allQuotes.push({
+                ...quote,
+                citation: {
+                    source_id: source.id,
+                    context: source.title,
+                },
+            });
+        }
+    }
+    // Step 3: Synthesize findings with LLM (conflict-aware)
+    // Note: Decisions are now extracted at query time by the agentic research mode
+    const synthesis = await synthesizeFindings(task, sources.map((s) => ({
+        id: s.id,
+        title: s.title,
+        summary: s.summary,
+        source_type: s.source_type,
+        created_at: s.created_at,
+    })), allQuotes, [] // No pre-indexed decisions - agentic mode extracts them dynamically
+    );
+    const researchPackage = {
+        query: task,
+        project,
+        generated_at: new Date().toISOString(),
+        // LLM-synthesized findings
+        summary: synthesis.summary,
+        key_findings: synthesis.key_findings,
+        // Conflict resolution (shows evolution of thinking)
+        conflicts_resolved: synthesis.conflicts_resolved.length > 0 ? synthesis.conflicts_resolved : undefined,
+        // Evidence
+        supporting_quotes: allQuotes.slice(0, quoteLimit),
+        related_decisions: [],
+        // Sources
+        sources_consulted: include_sources
+            ? sources.map((s) => ({
+                id: s.id,
+                title: s.title,
+                source_type: s.source_type,
+                relevance: s.score,
+            }))
+            : [],
+        // LLM-identified gaps and suggestions
+        gaps_identified: synthesis.gaps_identified,
+        suggested_queries: synthesis.suggested_queries,
+    };
+    return researchPackage;
+}
+async function runResearchCompletedHook(result, context) {
+    try {
+        const registry = await getExtensionRegistry({
+            logger: (message) => console.error(message),
+        });
+        await registry.runHook('onResearchCompleted', result, {
+            mode: context.mode,
+            dataDir: context.dataDir,
+            dbPath: context.dbPath,
+        });
+    }
+    catch (error) {
+        console.error('[extensions] Failed to run onResearchCompleted hook:', error);
+    }
+}

package/dist/mcp/handlers/retain.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Retain Handler - Save insights, decisions, and notes
+ *
+ * This is the "push" mechanism for adding knowledge explicitly.
+ * Retained items are immediately added to the vector store for instant searchability.
+ * Auto-pushes to git remote if configured.
+ */
+interface RetainArgs {
+    content: string;
+    project: string;
+    type: 'insight' | 'decision' | 'requirement' | 'note';
+    source_context?: string;
+    tags?: string[];
+}
+export declare function handleRetain(dbPath: string, dataDir: string, args: RetainArgs, options?: {
+    autoPush?: boolean;
+}): Promise<unknown>;
+export {};