@prmichaelsen/remember-mcp 0.1.0 → 0.2.0

package/src/tools/query-memory.ts

@@ -0,0 +1,284 @@
+/**
+ * remember_query_memory tool
+ * RAG (Retrieval-Augmented Generation) queries with natural language
+ */
+
+import type { Memory, SearchFilters } from '../types/memory.js';
+import { getMemoryCollection } from '../weaviate/schema.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Tool definition for remember_query_memory
+ */
+export const queryMemoryTool = {
+  name: 'remember_query_memory',
+  description: `Query memories using natural language for RAG (Retrieval-Augmented Generation).
+  
+  This tool is optimized for LLM context retrieval. It returns relevant memories
+  with their full content and context, formatted for easy consumption by LLMs.
+  
+  Use this when you need to:
+  - Answer questions based on stored memories
+  - Provide context for conversations
+  - Retrieve information for decision-making
+  - Build responses using past knowledge
+  
+  Examples:
+  - "What do I know about camping?"
+  - "Tell me about the recipes I've saved"
+  - "What meetings did I have last week?"
+  - "What are my project goals?"
+  `,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Natural language query',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of memories to retrieve. Default: 5',
+        minimum: 1,
+        maximum: 50,
+        default: 5,
+      },
+      min_relevance: {
+        type: 'number',
+        description: 'Minimum relevance score (0-1). Default: 0.6',
+        minimum: 0,
+        maximum: 1,
+        default: 0.6,
+      },
+      filters: {
+        type: 'object',
+        description: 'Optional filters to narrow results',
+        properties: {
+          types: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Filter by content types',
+          },
+          tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Filter by tags',
+          },
+          weight_min: {
+            type: 'number',
+            description: 'Minimum weight (0-1)',
+          },
+          trust_min: {
+            type: 'number',
+            description: 'Minimum trust level (0-1)',
+          },
+          date_from: {
+            type: 'string',
+            description: 'Start date (ISO 8601)',
+          },
+          date_to: {
+            type: 'string',
+            description: 'End date (ISO 8601)',
+          },
+        },
+      },
+      include_context: {
+        type: 'boolean',
+        description: 'Include full context metadata. Default: true',
+        default: true,
+      },
+      format: {
+        type: 'string',
+        description: 'Output format: "detailed" (full objects) or "compact" (text summary). Default: detailed',
+        enum: ['detailed', 'compact'],
+        default: 'detailed',
+      },
+    },
+    required: ['query'],
+  },
+};
+
+/**
+ * Query memory arguments
+ */
+export interface QueryMemoryArgs {
+  query: string;
+  limit?: number;
+  min_relevance?: number;
+  filters?: SearchFilters;
+  include_context?: boolean;
+  format?: 'detailed' | 'compact';
+}
+
+/**
+ * Memory with relevance score
+ */
+export interface RelevantMemory extends Partial<Memory> {
+  relevance: number; // 0-1 relevance score
+}
+
+/**
+ * Query memory result
+ */
+export interface QueryMemoryResult {
+  query: string;
+  memories: RelevantMemory[] | string; // Array for detailed, string for compact
+  total: number;
+  min_relevance: number;
+  context_summary?: string;
+}
+
+/**
+ * Handle remember_query_memory tool
+ */
+export async function handleQueryMemory(
+  args: QueryMemoryArgs,
+  userId: string
+): Promise<string> {
+  try {
+    logger.info('Querying memories', { userId, query: args.query });
+
+    const collection = getMemoryCollection(userId);
+    const limit = args.limit ?? 5;
+    const minRelevance = args.min_relevance ?? 0.6;
+    const includeContext = args.include_context ?? true;
+    const format = args.format ?? 'detailed';
+
+    // Build where filter for memories only
+    const whereFilters: any[] = [
+      {
+        path: 'doc_type',
+        operator: 'Equal',
+        valueText: 'memory',
+      },
+    ];
+
+    // Add type filter
+    if (args.filters?.types && args.filters.types.length > 0) {
+      whereFilters.push({
+        path: 'type',
+        operator: 'ContainsAny',
+        valueTextArray: args.filters.types,
+      });
+    }
+
+    // Add weight filter
+    if (args.filters?.weight_min !== undefined) {
+      whereFilters.push({
+        path: 'weight',
+        operator: 'GreaterThanEqual',
+        valueNumber: args.filters.weight_min,
+      });
+    }
+
+    // Add trust filter
+    if (args.filters?.trust_min !== undefined) {
+      whereFilters.push({
+        path: 'trust',
+        operator: 'GreaterThanEqual',
+        valueNumber: args.filters.trust_min,
+      });
+    }
+
+    // Add date range filters
+    if (args.filters?.date_from) {
+      whereFilters.push({
+        path: 'created_at',
+        operator: 'GreaterThanEqual',
+        valueDate: new Date(args.filters.date_from),
+      });
+    }
+
+    if (args.filters?.date_to) {
+      whereFilters.push({
+        path: 'created_at',
+        operator: 'LessThanEqual',
+        valueDate: new Date(args.filters.date_to),
+      });
+    }
+
+    // Build search options
+    const searchOptions: any = {
+      limit: limit,
+      distance: 1 - minRelevance, // Convert relevance to distance
+      returnMetadata: ['distance'],
+    };
+
+    // Add filters if present
+    if (whereFilters.length > 0) {
+      searchOptions.filters = whereFilters.length > 1 ? {
+        operator: 'And' as const,
+        operands: whereFilters,
+      } : whereFilters[0];
+    }
+
+    // Perform semantic search using nearText
+    const results = await collection.query.nearText(args.query, searchOptions);
+
+    // Format memories with relevance scores
+    const relevantMemories: RelevantMemory[] = results.objects.map((obj: any) => {
+      const relevance = 1 - (obj.metadata?.distance ?? 0); // Convert distance to relevance
+      const memory: RelevantMemory = {
+        id: obj.uuid,
+        ...obj.properties,
+        relevance: Math.max(0, Math.min(1, relevance)), // Clamp to [0, 1]
+      };
+
+      // Remove context if not requested
+      if (!includeContext) {
+        delete memory.context;
+        delete memory.location;
+      }
+
+      return memory;
+    });
+
+    // Sort by relevance (highest first)
+    relevantMemories.sort((a, b) => (b.relevance ?? 0) - (a.relevance ?? 0));
+
+    logger.info('Query completed', {
+      userId,
+      query: args.query,
+      results: relevantMemories.length,
+    });
+
+    // Format output based on requested format
+    let formattedMemories: RelevantMemory[] | string;
+    let contextSummary: string | undefined;
+
+    if (format === 'compact') {
+      // Compact format: text summary for easy LLM consumption
+      const summaryParts = relevantMemories.map((mem, idx) => {
+        const title = mem.title ? `"${mem.title}"` : `Memory ${idx + 1}`;
+        const type = mem.type ? ` [${mem.type}]` : '';
+        const relevancePercent = Math.round((mem.relevance ?? 0) * 100);
+        const content = mem.content || '(no content)';
+        const tags = mem.tags && mem.tags.length > 0 ? `\nTags: ${mem.tags.join(', ')}` : '';
+        
+        return `${idx + 1}. ${title}${type} (${relevancePercent}% relevant)\n${content}${tags}`;
+      });
+
+      formattedMemories = summaryParts.join('\n\n---\n\n');
+      
+      contextSummary = `Found ${relevantMemories.length} relevant memories for query: "${args.query}"`;
+    } else {
+      // Detailed format: full objects
+      formattedMemories = relevantMemories;
+      
+      contextSummary = `Retrieved ${relevantMemories.length} memories with relevance >= ${Math.round(minRelevance * 100)}%`;
+    }
+
+    const result: QueryMemoryResult = {
+      query: args.query,
+      memories: formattedMemories,
+      total: relevantMemories.length,
+      min_relevance: minRelevance,
+      context_summary: contextSummary,
+    };
+
+    return JSON.stringify(result, null, 2);
+  } catch (error) {
+    logger.error('Failed to query memories:', error);
+    throw new Error(`Failed to query memories: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/src/tools/search-relationship.ts

@@ -0,0 +1,228 @@
+/**
+ * remember_search_relationship tool
+ * Search relationships by observation text or type
+ */
+
+import type { Relationship } from '../types/memory.js';
+import { getMemoryCollection } from '../weaviate/schema.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Tool definition for remember_search_relationship
+ */
+export const searchRelationshipTool = {
+  name: 'remember_search_relationship',
+  description: `Search relationships by observation text or relationship type.
+  
+  Uses semantic search on relationship observations to find connections.
+  Can filter by relationship type, strength, and tags.
+  Returns relationships with their connected memory IDs.
+  
+  Examples:
+  - "Find relationships about inspiration"
+  - "Search for contradicting relationships"
+  - "Show me all 'caused_by' relationships"
+  `,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search query (semantic search on observation field)',
+      },
+      relationship_types: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Filter by relationship types (e.g., ["inspired_by", "caused_by"])',
+      },
+      strength_min: {
+        type: 'number',
+        description: 'Minimum strength (0-1)',
+        minimum: 0,
+        maximum: 1,
+      },
+      confidence_min: {
+        type: 'number',
+        description: 'Minimum confidence (0-1)',
+        minimum: 0,
+        maximum: 1,
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Filter by tags',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results (default: 10)',
+        minimum: 1,
+        maximum: 100,
+      },
+      offset: {
+        type: 'number',
+        description: 'Offset for pagination (default: 0)',
+        minimum: 0,
+      },
+    },
+    required: ['query'],
+  },
+};
+
+/**
+ * Search relationship arguments
+ */
+export interface SearchRelationshipArgs {
+  query: string;
+  relationship_types?: string[];
+  strength_min?: number;
+  confidence_min?: number;
+  tags?: string[];
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Search relationship result
+ */
+export interface SearchRelationshipResult {
+  relationships: Relationship[];
+  total: number;
+  offset: number;
+  limit: number;
+  message: string;
+}
+
+/**
+ * Handle remember_search_relationship tool
+ */
+export async function handleSearchRelationship(
+  args: SearchRelationshipArgs,
+  userId: string
+): Promise<string> {
+  try {
+    logger.info('Searching relationships', { 
+      userId, 
+      query: args.query,
+      types: args.relationship_types 
+    });
+
+    const collection = getMemoryCollection(userId);
+    const limit = args.limit ?? 10;
+    const offset = args.offset ?? 0;
+
+    // Build where filter for doc_type and other filters
+    const whereFilters: any[] = [
+      {
+        path: 'doc_type',
+        operator: 'Equal',
+        valueText: 'relationship',
+      },
+    ];
+
+    // Add relationship type filter
+    if (args.relationship_types && args.relationship_types.length > 0) {
+      if (args.relationship_types.length === 1) {
+        whereFilters.push({
+          path: 'relationship_type',
+          operator: 'Equal',
+          valueText: args.relationship_types[0],
+        });
+      } else {
+        whereFilters.push({
+          operator: 'Or',
+          operands: args.relationship_types.map(type => ({
+            path: 'relationship_type',
+            operator: 'Equal',
+            valueText: type,
+          })),
+        });
+      }
+    }
+
+    // Add strength filter
+    if (args.strength_min !== undefined) {
+      whereFilters.push({
+        path: 'strength',
+        operator: 'GreaterThanEqual',
+        valueNumber: args.strength_min,
+      });
+    }
+
+    // Add confidence filter
+    if (args.confidence_min !== undefined) {
+      whereFilters.push({
+        path: 'confidence',
+        operator: 'GreaterThanEqual',
+        valueNumber: args.confidence_min,
+      });
+    }
+
+    // Add tags filter
+    if (args.tags && args.tags.length > 0) {
+      whereFilters.push({
+        path: 'tags',
+        operator: 'ContainsAny',
+        valueTextArray: args.tags,
+      });
+    }
+
+    // Build search options
+    const searchOptions: any = {
+      alpha: 1.0, // Pure semantic search for relationships
+      limit: limit + offset, // Get extra for offset
+    };
+
+    // Add filters if present
+    if (whereFilters.length > 0) {
+      searchOptions.filters = whereFilters.length > 1 ? {
+        operator: 'And' as const,
+        operands: whereFilters,
+      } : whereFilters[0];
+    }
+
+    // Perform hybrid search (semantic search on observation field)
+    const results = await collection.query.hybrid(args.query, searchOptions);
+
+    // Apply offset manually (Weaviate v4 doesn't have built-in offset for nearText)
+    const paginatedResults = results.objects.slice(offset, offset + limit);
+
+    // Map results to Relationship type
+    const relationships: Relationship[] = paginatedResults.map((obj: any) => ({
+      id: obj.uuid,
+      user_id: obj.properties.user_id,
+      doc_type: 'relationship',
+      memory_ids: obj.properties.memory_ids || [],
+      relationship_type: obj.properties.relationship_type,
+      observation: obj.properties.observation,
+      strength: obj.properties.strength,
+      confidence: obj.properties.confidence,
+      context: obj.properties.context || {
+        timestamp: obj.properties.created_at,
+        source: { type: 'api', platform: 'mcp' },
+      },
+      created_at: obj.properties.created_at,
+      updated_at: obj.properties.updated_at,
+      version: obj.properties.version,
+      tags: obj.properties.tags || [],
+    }));
+
+    logger.info('Relationship search completed', { 
+      userId, 
+      found: relationships.length,
+      total: results.objects.length
+    });
+
+    const result: SearchRelationshipResult = {
+      relationships,
+      total: results.objects.length,
+      offset,
+      limit,
+      message: `Found ${relationships.length} relationship(s) matching query "${args.query}"`,
+    };
+
+    return JSON.stringify(result, null, 2);
+  } catch (error) {
+    logger.error('Failed to search relationships:', error);
+    throw new Error(`Failed to search relationships: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}