@prmichaelsen/remember-mcp 2.7.11 → 3.0.0

package/src/tools/search-space.ts

@@ -12,6 +12,7 @@ import { ensurePublicCollection, isValidSpaceId } from '../weaviate/space-schema
 import { SUPPORTED_SPACES } from '../types/space-memory.js';
 import { handleToolError } from '../utils/error-handler.js';
 import type { SearchFilters } from '../types/memory.js';
+import { createDebugLogger } from '../utils/debug.js';
 
 /**
  * Tool definition for remember_search_space
@@ -113,8 +114,18 @@ export async function handleSearchSpace(
   args: SearchSpaceArgs,
   userId: string  // May be used for private spaces in future
 ): Promise<string> {
+  const debug = createDebugLogger({
+    tool: 'remember_search_space',
+    userId,
+    operation: 'search_spaces',
+  });
+
   try {
+    debug.info('Tool invoked');
+    debug.trace('Arguments', { args });
+    
     // Validate all space IDs
+    debug.debug('Validating space IDs', { spaces: args.spaces });
     const invalidSpaces = args.spaces.filter(s => !isValidSpaceId(s));
     if (invalidSpaces.length > 0) {
       return JSON.stringify(
@@ -197,11 +208,24 @@ export async function handleSearchSpace(
 
     const whereFilter = filterList.length > 0 ? Filters.and(...filterList) : undefined;
 
-    // Execute hybrid search
-    const searchResults = await publicCollection.query.hybrid(args.query, {
+    debug.debug('Executing hybrid search', {
+      query: args.query,
+      filterCount: filterList.length,
       limit: args.limit || 10,
       offset: args.offset || 0,
-      ...(whereFilter && { where: whereFilter }),
+    });
+
+    // Execute hybrid search
+    const searchResults = await debug.time('Hybrid search query', async () => {
+      return await publicCollection.query.hybrid(args.query, {
+        limit: args.limit || 10,
+        offset: args.offset || 0,
+        ...(whereFilter && { where: whereFilter }),
+      });
+    });
+    
+    debug.debug('Search completed', {
+      resultCount: searchResults.objects.length,
     });
 
     // Format results
@@ -220,8 +244,17 @@ export async function handleSearchSpace(
       limit: args.limit || 10,
     };
 
+    debug.info('Tool completed successfully', {
+      resultCount: memories.length,
+      spaces: args.spaces,
+    });
+
     return JSON.stringify(result, null, 2);
   } catch (error) {
+    debug.error('Tool failed', {
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+    });
     return handleToolError(error, {
       toolName: 'remember_search_space',
       operation: 'search spaces',

package/src/tools/update-memory.ts

@@ -163,6 +163,14 @@ export async function handleUpdateMemory(
       throw new Error('Cannot update relationships using this tool. Use remember_update_relationship instead.');
     }
 
+    // Check if memory is deleted
+    if (existingMemory.properties.deleted_at) {
+      const deletedAt = typeof existingMemory.properties.deleted_at === 'string'
+        ? existingMemory.properties.deleted_at
+        : new Date(existingMemory.properties.deleted_at as any).toISOString();
+      throw new Error(`Cannot update deleted memory: ${args.memory_id}. Memory was deleted on ${deletedAt}.`);
+    }
+
     // Build update object with only provided fields
     const updates: Record<string, any> = {};
     const updatedFields: string[] = [];

package/src/types/memory.ts

@@ -196,6 +196,11 @@ export interface Memory {
   parent_id?: string | null; // ID of parent memory or comment (null for top-level)
   thread_root_id?: string | null; // Root memory ID for fetching entire thread (null for top-level)
   moderation_flags?: string[]; // Per-space moderation flags (format: "{space_id}:{flag_type}")
+
+  // Soft Delete Fields
+  deleted_at?: Date | null; // Timestamp when memory was soft-deleted (null = not deleted)
+  deleted_by?: string; // User ID who deleted the memory
+  deletion_reason?: string; // Optional reason for deletion
 }
 
 /**
@@ -259,6 +264,11 @@ export interface SearchFilters {
   has_relationships?: boolean;
 }
 
+/**
+ * Deleted filter type
+ */
+export type DeletedFilter = 'exclude' | 'include' | 'only';
+
 /**
  * Search options
  */
@@ -267,6 +277,7 @@ export interface SearchOptions {
   alpha?: number; // 0-1, balance between semantic (1.0) and keyword (0.0)
   filters?: SearchFilters;
   include_relationships?: boolean;
+  deleted_filter?: DeletedFilter;
   limit?: number;
   offset?: number;
 }

package/src/types/space-memory.ts

@@ -55,6 +55,11 @@ export interface SpaceMemory extends Omit<Memory, 'user_id' | 'doc_type'> {
    * Always 'space_memory' for space memories
    */
   doc_type: 'space_memory';
+
+  // Soft Delete Fields (inherited from Memory, but explicitly typed here)
+  deleted_at?: Date | null;
+  deleted_by?: string;
+  deletion_reason?: string;
 }
 
 /**

package/src/utils/debug.spec.ts

@@ -0,0 +1,257 @@
+/**
+ * Unit tests for debug utility
+ */
+
+import { createDebugLogger, DebugLogger } from './debug';
+import { DebugLevel } from '../config';
+import { logger } from './logger';
+
+// Mock logger
+jest.mock('./logger', () => ({
+  logger: {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+// Mock config
+jest.mock('../config', () => {
+  let mockLevel = 0; // NONE by default
+  
+  return {
+    DebugLevel: {
+      NONE: 0,
+      ERROR: 1,
+      WARN: 2,
+      INFO: 3,
+      DEBUG: 4,
+      TRACE: 5,
+    },
+    debugConfig: {
+      get level() {
+        return mockLevel;
+      },
+      set level(value: number) {
+        mockLevel = value;
+      },
+      enabled: (level: number) => mockLevel >= level,
+    },
+    // Re-export setMockDebugLevel for tests
+    __setMockDebugLevel: (level: number) => {
+      mockLevel = level;
+    },
+  };
+});
+
+const { __setMockDebugLevel } = require('../config');
+
+describe('DebugLogger', () => {
+  let debug: DebugLogger;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    __setMockDebugLevel(DebugLevel.NONE);
+    debug = createDebugLogger({
+      tool: 'test_tool',
+      userId: 'user123',
+      operation: 'test_operation',
+    });
+  });
+
+  describe('Debug Level Filtering', () => {
+    it('should not log anything when level is NONE', () => {
+      __setMockDebugLevel(DebugLevel.NONE);
+      
+      debug.trace('trace message');
+      debug.debug('debug message');
+      debug.info('info message');
+      debug.warn('warn message');
+      debug.error('error message');
+
+      expect(logger.debug).not.toHaveBeenCalled();
+      expect(logger.info).not.toHaveBeenCalled();
+      expect(logger.warn).not.toHaveBeenCalled();
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+
+    it('should only log errors when level is ERROR', () => {
+      __setMockDebugLevel(DebugLevel.ERROR);
+      
+      debug.trace('trace message');
+      debug.debug('debug message');
+      debug.info('info message');
+      debug.warn('warn message');
+      debug.error('error message');
+
+      expect(logger.debug).not.toHaveBeenCalled();
+      expect(logger.info).not.toHaveBeenCalled();
+      expect(logger.warn).not.toHaveBeenCalled();
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    });
+
+    it('should log warnings and errors when level is WARN', () => {
+      __setMockDebugLevel(DebugLevel.WARN);
+      
+      debug.trace('trace message');
+      debug.debug('debug message');
+      debug.info('info message');
+      debug.warn('warn message');
+      debug.error('error message');
+
+      expect(logger.debug).not.toHaveBeenCalled();
+      expect(logger.info).not.toHaveBeenCalled();
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    });
+
+    it('should log info, warnings, and errors when level is INFO', () => {
+      __setMockDebugLevel(DebugLevel.INFO);
+      
+      debug.trace('trace message');
+      debug.debug('debug message');
+      debug.info('info message');
+      debug.warn('warn message');
+      debug.error('error message');
+
+      expect(logger.debug).not.toHaveBeenCalled();
+      expect(logger.info).toHaveBeenCalledTimes(1);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    });
+
+    it('should log debug, info, warnings, and errors when level is DEBUG', () => {
+      __setMockDebugLevel(DebugLevel.DEBUG);
+      
+      debug.trace('trace message');
+      debug.debug('debug message');
+      debug.info('info message');
+      debug.warn('warn message');
+      debug.error('error message');
+
+      expect(logger.debug).toHaveBeenCalledTimes(1); // debug only
+      expect(logger.info).toHaveBeenCalledTimes(1);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    });
+
+    it('should log everything including trace when level is TRACE', () => {
+      __setMockDebugLevel(DebugLevel.TRACE);
+      
+      debug.trace('trace message');
+      debug.debug('debug message');
+      debug.info('info message');
+      debug.warn('warn message');
+      debug.error('error message');
+
+      expect(logger.debug).toHaveBeenCalledTimes(2); // trace + debug
+      expect(logger.info).toHaveBeenCalledTimes(1);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      expect(logger.error).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Context Propagation', () => {
+    it('should include context in all log calls', () => {
+      __setMockDebugLevel(DebugLevel.DEBUG);
+      
+      debug.debug('test message', { extra: 'data' });
+
+      expect(logger.debug).toHaveBeenCalledWith(
+        '[DEBUG] test message',
+        expect.objectContaining({
+          tool: 'test_tool',
+          userId: 'user123',
+          operation: 'test_operation',
+          extra: 'data',
+          debugLevel: 'DEBUG',
+        })
+      );
+    });
+  });
+
+  describe('dump()', () => {
+    it('should only dump objects at TRACE level', () => {
+      __setMockDebugLevel(DebugLevel.DEBUG);
+      
+      debug.dump('test object', { foo: 'bar' });
+      expect(logger.debug).not.toHaveBeenCalled();
+
+      __setMockDebugLevel(DebugLevel.TRACE);
+      debug.dump('test object', { foo: 'bar' });
+      
+      expect(logger.debug).toHaveBeenCalledWith(
+        '[DUMP] test object',
+        expect.objectContaining({
+          dump: expect.stringContaining('"foo": "bar"'),
+        })
+      );
+    });
+  });
+
+  describe('time()', () => {
+    it('should not add timing overhead when debug is disabled', async () => {
+      __setMockDebugLevel(DebugLevel.NONE);
+      
+      const result = await debug.time('test operation', async () => {
+        return 'result';
+      });
+
+      expect(result).toBe('result');
+      expect(logger.debug).not.toHaveBeenCalled();
+    });
+
+    it('should log timing when DEBUG level is enabled', async () => {
+      __setMockDebugLevel(DebugLevel.DEBUG);
+      
+      const result = await debug.time('test operation', async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        return 'result';
+      });
+
+      expect(result).toBe('result');
+      expect(logger.debug).toHaveBeenCalledWith(
+        '[DEBUG] test operation - Starting',
+        expect.any(Object)
+      );
+      expect(logger.debug).toHaveBeenCalledWith(
+        '[DEBUG] test operation - Completed',
+        expect.objectContaining({
+          durationMs: expect.any(Number),
+        })
+      );
+    });
+
+    it('should log errors with timing on failure', async () => {
+      __setMockDebugLevel(DebugLevel.DEBUG);
+      
+      const error = new Error('test error');
+      
+      await expect(
+        debug.time('test operation', async () => {
+          throw error;
+        })
+      ).rejects.toThrow('test error');
+
+      expect(logger.error).toHaveBeenCalledWith(
+        '[ERROR] test operation - Failed',
+        expect.objectContaining({
+          durationMs: expect.any(Number),
+          error: 'test error',
+        })
+      );
+    });
+  });
+
+  describe('createDebugLogger()', () => {
+    it('should create a DebugLogger instance with context', () => {
+      const logger = createDebugLogger({
+        tool: 'test_tool',
+        userId: 'user123',
+      });
+
+      expect(logger).toBeInstanceOf(DebugLogger);
+    });
+  });
+});

package/src/utils/debug.ts

@@ -0,0 +1,138 @@
+/**
+ * Debug logging utility for remember-mcp
+ * 
+ * Provides configurable debug logging via REMEMBER_MCP_DEBUG_LEVEL environment variable.
+ * Levels: NONE (default), ERROR, WARN, INFO, DEBUG, TRACE
+ */
+
+import { debugConfig, DebugLevel } from '../config.js';
+import { logger } from './logger.js';
+
+export interface DebugContext {
+  tool: string;
+  userId?: string;
+  operation?: string;
+  [key: string]: any;
+}
+
+export class DebugLogger {
+  private context: DebugContext;
+
+  constructor(context: DebugContext) {
+    this.context = context;
+  }
+
+  trace(message: string, data?: any): void {
+    if (debugConfig.enabled(DebugLevel.TRACE)) {
+      logger.debug(`[TRACE] ${message}`, {
+        ...this.context,
+        ...data,
+        debugLevel: 'TRACE',
+      });
+    }
+  }
+
+  debug(message: string, data?: any): void {
+    if (debugConfig.enabled(DebugLevel.DEBUG)) {
+      logger.debug(`[DEBUG] ${message}`, {
+        ...this.context,
+        ...data,
+        debugLevel: 'DEBUG',
+      });
+    }
+  }
+
+  info(message: string, data?: any): void {
+    if (debugConfig.enabled(DebugLevel.INFO)) {
+      logger.info(`[INFO] ${message}`, {
+        ...this.context,
+        ...data,
+        debugLevel: 'INFO',
+      });
+    }
+  }
+
+  warn(message: string, data?: any): void {
+    if (debugConfig.enabled(DebugLevel.WARN)) {
+      logger.warn(`[WARN] ${message}`, {
+        ...this.context,
+        ...data,
+        debugLevel: 'WARN',
+      });
+    }
+  }
+
+  error(message: string, data?: any): void {
+    if (debugConfig.enabled(DebugLevel.ERROR)) {
+      logger.error(`[ERROR] ${message}`, {
+        ...this.context,
+        ...data,
+        debugLevel: 'ERROR',
+      });
+    }
+  }
+
+  /**
+   * Dump full object (TRACE only)
+   * Use with caution - may expose sensitive data
+   */
+  dump(label: string, obj: any): void {
+    if (debugConfig.enabled(DebugLevel.TRACE)) {
+      logger.debug(`[DUMP] ${label}`, {
+        ...this.context,
+        dump: JSON.stringify(obj, null, 2),
+        debugLevel: 'TRACE',
+      });
+    }
+  }
+
+  /**
+   * Time an async operation (DEBUG and above)
+   * Logs start, completion, and duration
+   */
+  async time<T>(label: string, fn: () => Promise<T>): Promise<T> {
+    if (!debugConfig.enabled(DebugLevel.DEBUG)) {
+      return fn();
+    }
+
+    const start = Date.now();
+    this.debug(`${label} - Starting`);
+    
+    try {
+      const result = await fn();
+      const duration = Date.now() - start;
+      this.debug(`${label} - Completed`, { durationMs: duration });
+      return result;
+    } catch (error) {
+      const duration = Date.now() - start;
+      this.error(`${label} - Failed`, { 
+        durationMs: duration,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+}
+
+/**
+ * Create a debug logger with context
+ * 
+ * @param context - Context information (tool name, userId, operation, etc.)
+ * @returns DebugLogger instance
+ * 
+ * @example
+ * const debug = createDebugLogger({
+ *   tool: 'remember_create_memory',
+ *   userId: 'user123',
+ *   operation: 'create',
+ * });
+ * 
+ * debug.info('Tool invoked');
+ * debug.trace('Arguments', { args });
+ * const result = await debug.time('Database operation', async () => {
+ *   return await collection.insert(data);
+ * });
+ */
+export function createDebugLogger(context: DebugContext): DebugLogger {
+  return new DebugLogger(context);
+}

package/src/utils/weaviate-filters.ts

@@ -8,6 +8,11 @@
 import { Filters } from 'weaviate-client';
 import type { SearchFilters } from '../types/memory.js';
 
+/**
+ * Deleted filter options
+ */
+export type DeletedFilter = 'exclude' | 'include' | 'only';
+
 /**
  * Build filters for searching both memories and relationships
  * Uses OR logic: (doc_type=memory AND memory_filters) OR (doc_type=relationship AND relationship_filters)
@@ -165,7 +170,7 @@ export function buildRelationshipOnlyFilters(
  * @param filters - Array of filter objects
  * @returns Combined filter or undefined
  */
-function combineFiltersWithAnd(filters: any[]): any {
+export function combineFiltersWithAnd(filters: any[]): any {
   // Filter out any undefined/null values
   const validFilters = filters.filter(f => f !== undefined && f !== null);
   
@@ -207,3 +212,25 @@ function combineFiltersWithOr(filters: any[]): any {
 export function hasFilters(filter: any): boolean {
   return filter !== undefined && filter !== null;
 }
+
+/**
+ * Build filter for deleted_at field based on deleted_filter parameter
+ *
+ * @param collection - Weaviate collection instance
+ * @param deletedFilter - Filter mode: 'exclude' (default), 'include', or 'only'
+ * @returns Filter for deleted_at field, or null if no filter needed
+ */
+export function buildDeletedFilter(
+  collection: any,
+  deletedFilter: DeletedFilter = 'exclude'
+): any | null {
+  if (deletedFilter === 'exclude') {
+    // Exclude deleted: deleted_at is null or missing
+    return collection.filter.byProperty('deleted_at').isNull(true);
+  } else if (deletedFilter === 'only') {
+    // Only deleted: deleted_at is not null
+    return collection.filter.byProperty('deleted_at').isNull(false);
+  }
+  // 'include': no filter (show all)
+  return null;
+}

package/src/weaviate/client.ts

@@ -1,6 +1,7 @@
 import weaviate, { WeaviateClient } from 'weaviate-client';
 import { config } from '../config.js';
 import { logger } from '../utils/logger.js';
+import { createDebugLogger } from '../utils/debug.js';
 
 let client: WeaviateClient | null = null;
 
@@ -207,6 +208,21 @@ export const ALL_MEMORY_PROPERTIES = [
   'parent_id',
   'thread_root_id',
   'moderation_flags',
+  
+  // Space/publishing fields (for Memory_public collection)
+  'spaces',
+  'space_id',
+  'author_id',
+  'ghost_id',
+  'attribution',
+  'published_at',
+  'discovery_count',
+  'space_memory_id',
+  
+  // Soft delete fields
+  'deleted_at',
+  'deleted_by',
+  'deletion_reason',
 ] as const;
 
 /**
@@ -228,22 +244,50 @@ export async function fetchMemoryWithAllProperties(
   collection: any,
   memoryId: string
 ) {
+  const debug = createDebugLogger({
+    tool: 'weaviate-client',
+    operation: 'fetchMemoryWithAllProperties',
+  });
+
+  debug.debug('Fetching memory', {
+    memoryId,
+    collectionName: collection.name,
+    propertyCount: ALL_MEMORY_PROPERTIES.length,
+  });
+
   try {
     // Try to fetch with all properties specified
-    return await collection.query.fetchObjectById(memoryId, {
-      returnProperties: ALL_MEMORY_PROPERTIES,
+    const result = await debug.time('Fetch with all properties', async () => {
+      return await collection.query.fetchObjectById(memoryId, {
+        returnProperties: ALL_MEMORY_PROPERTIES,
+      });
     });
+    
+    debug.trace('Fetch result', {
+      found: !!result,
+      propertyCount: result?.properties ? Object.keys(result.properties).length : 0,
+      hasSpaces: !!result?.properties?.spaces,
+      hasAuthorId: !!result?.properties?.author_id,
+    });
+    
+    return result;
   } catch (error) {
     // If that fails (e.g., property doesn't exist on this record),
     // fetch without specifying properties - Weaviate will return
     // all properties that actually exist on the record
+    debug.warn('Fetch with all properties failed, falling back', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    
     logger.warn('Failed to fetch with all properties, falling back to unspecified fetch', {
       module: 'weaviate-client',
       memoryId,
       error: error instanceof Error ? error.message : String(error),
     });
     
-    return await collection.query.fetchObjectById(memoryId);
+    return await debug.time('Fetch without property specification', async () => {
+      return await collection.query.fetchObjectById(memoryId);
+    });
   }
 }
 

package/src/weaviate/schema.ts

@@ -268,6 +268,23 @@ export async function createMemoryCollection(userId: string): Promise<void> {
         dataType: 'text[]' as any,
         description: 'Per-space moderation flags (format: "{space_id}:{flag_type}")',
       },
+
+      // Soft delete fields
+      {
+        name: 'deleted_at',
+        dataType: 'date' as any,
+        description: 'Timestamp when memory was soft-deleted (null = not deleted)',
+      },
+      {
+        name: 'deleted_by',
+        dataType: 'text' as any,
+        description: 'User ID who deleted the memory',
+      },
+      {
+        name: 'deletion_reason',
+        dataType: 'text' as any,
+        description: 'Optional reason for deletion',
+      },
     ],
   });