@prmichaelsen/remember-mcp 2.2.1 → 2.3.1

package/src/tools/search-space.ts

@@ -0,0 +1,189 @@
+/**
+ * remember_search_space tool
+ * 
+ * Search shared spaces to discover memories from other users.
+ * Similar to remember_search_memory but searches space collections.
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { Filters } from 'weaviate-client';
+import { getWeaviateClient } from '../weaviate/client.js';
+import { ensureSpaceCollection, isValidSpaceId } from '../weaviate/space-schema.js';
+import { SUPPORTED_SPACES } from '../types/space-memory.js';
+import { handleToolError } from '../utils/error-handler.js';
+import type { SearchFilters } from '../types/memory.js';
+
+/**
+ * Tool definition for remember_search_space
+ */
+export const searchSpaceTool: Tool = {
+  name: 'remember_search_space',
+  description: 'Search shared spaces to discover thoughts, ideas, and memories. Works like remember_search_memory but searches shared spaces instead of personal memories.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search query (semantic + keyword hybrid)',
+      },
+      space: {
+        type: 'string',
+        description: 'Which space to search',
+        enum: SUPPORTED_SPACES,
+        default: 'the_void',
+      },
+      content_type: {
+        type: 'string',
+        description: 'Filter by content type',
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Filter by tags (must have all specified tags)',
+      },
+      min_weight: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        description: 'Minimum weight/significance (0-1)',
+      },
+      max_weight: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        description: 'Maximum weight/significance (0-1)',
+      },
+      date_from: {
+        type: 'string',
+        description: 'Filter memories created after this date (ISO 8601)',
+      },
+      date_to: {
+        type: 'string',
+        description: 'Filter memories created before this date (ISO 8601)',
+      },
+      limit: {
+        type: 'number',
+        default: 10,
+        description: 'Maximum number of results',
+      },
+      offset: {
+        type: 'number',
+        default: 0,
+        description: 'Offset for pagination',
+      },
+    },
+    required: ['query', 'space'],
+  },
+};
+
+interface SearchSpaceArgs {
+  query: string;
+  space: string;
+  content_type?: string;
+  tags?: string[];
+  min_weight?: number;
+  max_weight?: number;
+  date_from?: string;
+  date_to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Handle remember_search_space tool execution
+ */
+export async function handleSearchSpace(
+  args: SearchSpaceArgs,
+  userId: string  // May be used for private spaces in future
+): Promise<string> {
+  try {
+    // Validate space ID
+    if (!isValidSpaceId(args.space)) {
+      return JSON.stringify(
+        {
+          success: false,
+          error: 'Invalid space ID',
+          message: `Space "${args.space}" is not supported. Supported spaces: ${SUPPORTED_SPACES.join(', ')}`,
+        },
+        null,
+        2
+      );
+    }
+
+    const weaviateClient = getWeaviateClient();
+    const spaceCollection = await ensureSpaceCollection(weaviateClient, args.space);
+
+    // Build filters for space search
+    const filterList: any[] = [];
+
+    // Filter by space_id
+    filterList.push(spaceCollection.filter.byProperty('space_id').equal(args.space));
+
+    // Filter by doc_type (space_memory)
+    filterList.push(spaceCollection.filter.byProperty('doc_type').equal('space_memory'));
+
+    // Apply content type filter
+    if (args.content_type) {
+      filterList.push(spaceCollection.filter.byProperty('type').equal(args.content_type));
+    }
+
+    // Apply tags filter
+    if (args.tags && args.tags.length > 0) {
+      args.tags.forEach(tag => {
+        filterList.push(spaceCollection.filter.byProperty('tags').containsAny([tag]));
+      });
+    }
+
+    // Apply weight filters
+    if (args.min_weight !== undefined) {
+      filterList.push(spaceCollection.filter.byProperty('weight').greaterOrEqual(args.min_weight));
+    }
+
+    if (args.max_weight !== undefined) {
+      filterList.push(spaceCollection.filter.byProperty('weight').lessOrEqual(args.max_weight));
+    }
+
+    // Apply date filters (convert ISO strings to Date objects)
+    if (args.date_from) {
+      filterList.push(spaceCollection.filter.byProperty('created_at').greaterOrEqual(new Date(args.date_from)));
+    }
+
+    if (args.date_to) {
+      filterList.push(spaceCollection.filter.byProperty('created_at').lessOrEqual(new Date(args.date_to)));
+    }
+
+    const whereFilter = filterList.length > 0 ? Filters.and(...filterList) : undefined;
+
+    // Execute hybrid search
+    const searchResults = await spaceCollection.query.hybrid(args.query, {
+      limit: args.limit || 10,
+      offset: args.offset || 0,
+      ...(whereFilter && { where: whereFilter }),
+    });
+
+    // Format results
+    const memories = searchResults.objects.map((obj) => ({
+      id: obj.uuid,
+      ...obj.properties,
+      _score: obj.metadata?.score,
+    }));
+
+    const result = {
+      space: args.space,
+      query: args.query,
+      memories,
+      total: memories.length,
+      offset: args.offset || 0,
+      limit: args.limit || 10,
+    };
+
+    return JSON.stringify(result, null, 2);
+  } catch (error) {
+    handleToolError(error, {
+      toolName: 'remember_search_space',
+      operation: 'search space',
+      space: args.space,
+      query: args.query,
+    });
+  }
+}

package/src/types/space-memory.ts

@@ -0,0 +1,94 @@
+/**
+ * Space Memory type definitions for remember-mcp
+ * 
+ * Space memories are memories published to shared collections
+ * where they can be discovered by other users.
+ */
+
+import type { Memory, SearchOptions, SearchResult } from './memory.js';
+
+/**
+ * Space memory - a memory published to a shared space
+ * 
+ * Extends Memory with additional fields for attribution and discovery
+ */
+export interface SpaceMemory extends Omit<Memory, 'user_id' | 'doc_type'> {
+  /**
+   * Space identifier (snake_case)
+   * Examples: 'the_void', 'public_space'
+   */
+  space_id: string;
+
+  /**
+   * Original author's user_id (for permissions)
+   * This is private and not shown publicly
+   */
+  author_id: string;
+
+  /**
+   * Optional ghost profile ID for pseudonymous publishing
+   * If present, memory is attributed to ghost instead of user
+   */
+  ghost_id?: string;
+
+  /**
+   * When the memory was published to the space
+   */
+  published_at: string;
+
+  /**
+   * How many times this memory has been discovered/viewed
+   */
+  discovery_count: number;
+
+  /**
+   * Attribution type
+   * - 'user': Published as the user (shows author_id)
+   * - 'ghost': Published as a ghost (shows ghost_id)
+   */
+  attribution: 'user' | 'ghost';
+
+  /**
+   * Document type discriminator
+   * Always 'space_memory' for space memories
+   */
+  doc_type: 'space_memory';
+}
+
+/**
+ * Search options for space memories
+ * Same as SearchOptions but for space collections
+ */
+export interface SpaceSearchOptions extends Omit<SearchOptions, 'include_relationships'> {
+  /**
+   * Space to search
+   */
+  space: string;
+}
+
+/**
+ * Search result for space memories
+ */
+export interface SpaceSearchResult extends Omit<SearchResult, 'memories' | 'relationships'> {
+  /**
+   * Found space memories
+   */
+  space_memories: SpaceMemory[];
+}
+
+/**
+ * Supported space IDs
+ */
+export type SpaceId = 'the_void';
+
+/**
+ * Space display names mapped to IDs
+ */
+export const SPACE_DISPLAY_NAMES: Record<SpaceId, string> = {
+  the_void: 'The Void',
+};
+
+/**
+ * Supported spaces constant
+ */
+export const SUPPORTED_SPACES: SpaceId[] = ['the_void'];

package/src/weaviate/space-schema.spec.ts

@@ -0,0 +1,131 @@
+/**
+ * Unit tests for Space Schema utilities
+ */
+
+import {
+  getSpaceCollectionName,
+  sanitizeSpaceId,
+  getSpaceDisplayName,
+  isValidSpaceId,
+  ensureSpaceCollection,
+} from './space-schema';
+import type { WeaviateClient } from 'weaviate-client';
+
+// Mock Weaviate client
+const mockWeaviateClient = {
+  collections: {
+    exists: jest.fn(),
+    create: jest.fn(),
+    get: jest.fn(),
+  },
+} as unknown as WeaviateClient;
+
+describe('Space Schema Utilities', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getSpaceCollectionName', () => {
+    it('should return collection name with Memory_ prefix', () => {
+      expect(getSpaceCollectionName('the_void')).toBe('Memory_the_void');
+      expect(getSpaceCollectionName('public_space')).toBe('Memory_public_space');
+    });
+  });
+
+  describe('sanitizeSpaceId', () => {
+    it('should convert display name to snake_case', () => {
+      expect(sanitizeSpaceId('The Void')).toBe('the_void');
+      expect(sanitizeSpaceId('Public Space')).toBe('public_space');
+      expect(sanitizeSpaceId('MY SPACE')).toBe('my_space');
+    });
+
+    it('should handle multiple spaces', () => {
+      expect(sanitizeSpaceId('The  Void  Space')).toBe('the_void_space');
+    });
+
+    it('should handle already lowercase', () => {
+      expect(sanitizeSpaceId('the_void')).toBe('the_void');
+    });
+  });
+
+  describe('getSpaceDisplayName', () => {
+    it('should return display name for known space IDs', () => {
+      expect(getSpaceDisplayName('the_void')).toBe('The Void');
+    });
+
+    it('should return space ID if not found in map', () => {
+      expect(getSpaceDisplayName('unknown_space')).toBe('unknown_space');
+    });
+  });
+
+  describe('isValidSpaceId', () => {
+    it('should return true for supported spaces', () => {
+      expect(isValidSpaceId('the_void')).toBe(true);
+    });
+
+    it('should return false for unsupported spaces', () => {
+      expect(isValidSpaceId('unknown_space')).toBe(false);
+      expect(isValidSpaceId('public_space')).toBe(false); // Not yet supported
+    });
+  });
+
+  describe('ensureSpaceCollection', () => {
+    it('should return existing collection if it exists', async () => {
+      const mockCollection = { name: 'Memory_the_void' };
+      (mockWeaviateClient.collections.exists as jest.Mock).mockResolvedValue(true);
+      (mockWeaviateClient.collections.get as jest.Mock).mockReturnValue(mockCollection);
+
+      const result = await ensureSpaceCollection(mockWeaviateClient, 'the_void');
+
+      expect(result).toBe(mockCollection);
+      expect(mockWeaviateClient.collections.exists).toHaveBeenCalledWith('Memory_the_void');
+      expect(mockWeaviateClient.collections.get).toHaveBeenCalledWith('Memory_the_void');
+      expect(mockWeaviateClient.collections.create).not.toHaveBeenCalled();
+    });
+
+    it('should create collection if it does not exist', async () => {
+      const mockCollection = { name: 'Memory_the_void' };
+      (mockWeaviateClient.collections.exists as jest.Mock).mockResolvedValue(false);
+      (mockWeaviateClient.collections.create as jest.Mock).mockResolvedValue(undefined);
+      (mockWeaviateClient.collections.get as jest.Mock).mockReturnValue(mockCollection);
+
+      const result = await ensureSpaceCollection(mockWeaviateClient, 'the_void');
+
+      expect(result).toBe(mockCollection);
+      expect(mockWeaviateClient.collections.exists).toHaveBeenCalledWith('Memory_the_void');
+      expect(mockWeaviateClient.collections.create).toHaveBeenCalled();
+      expect(mockWeaviateClient.collections.get).toHaveBeenCalledWith('Memory_the_void');
+    });
+
+    it('should throw error for invalid space ID', async () => {
+      await expect(
+        ensureSpaceCollection(mockWeaviateClient, 'invalid_space')
+      ).rejects.toThrow('Invalid space ID: invalid_space');
+
+      expect(mockWeaviateClient.collections.exists).not.toHaveBeenCalled();
+    });
+
+    it('should create collection with correct schema', async () => {
+      (mockWeaviateClient.collections.exists as jest.Mock).mockResolvedValue(false);
+      (mockWeaviateClient.collections.create as jest.Mock).mockResolvedValue(undefined);
+      (mockWeaviateClient.collections.get as jest.Mock).mockReturnValue({});
+
+      await ensureSpaceCollection(mockWeaviateClient, 'the_void');
+
+      const createCall = (mockWeaviateClient.collections.create as jest.Mock).mock.calls[0][0];
+      expect(createCall.name).toBe('Memory_the_void');
+      expect(createCall.vectorizers).toBeDefined();
+      expect(createCall.properties).toBeDefined();
+      expect(createCall.properties.length).toBeGreaterThan(20); // Should have many properties
+      
+      // Check for space-specific properties
+      const propertyNames = createCall.properties.map((p: any) => p.name);
+      expect(propertyNames).toContain('space_id');
+      expect(propertyNames).toContain('author_id');
+      expect(propertyNames).toContain('ghost_id');
+      expect(propertyNames).toContain('published_at');
+      expect(propertyNames).toContain('discovery_count');
+      expect(propertyNames).toContain('attribution');
+    });
+  });
+});

package/src/weaviate/space-schema.ts

@@ -0,0 +1,275 @@
+/**
+ * Weaviate space collection schema and utilities
+ * 
+ * Manages shared space collections where users can publish memories
+ * for discovery by other users.
+ */
+
+import weaviate, { type WeaviateClient, type Collection } from 'weaviate-client';
+import { config } from '../config.js';
+import { SUPPORTED_SPACES, type SpaceId } from '../types/space-memory.js';
+
+/**
+ * Get collection name for a space
+ * 
+ * @param spaceId - Space identifier (snake_case)
+ * @returns Collection name in format Memory_{space_id}
+ * 
+ * @example
+ * getSpaceCollectionName('the_void') // Returns 'Memory_the_void'
+ */
+export function getSpaceCollectionName(spaceId: string): string {
+  return `Memory_${spaceId}`;
+}
+
+/**
+ * Sanitize display name to space ID
+ * 
+ * Converts display names like "The Void" to snake_case IDs like "the_void"
+ * 
+ * @param displayName - Display name with spaces and mixed case
+ * @returns snake_case space ID
+ * 
+ * @example
+ * sanitizeSpaceId('The Void') // Returns 'the_void'
+ * sanitizeSpaceId('Public Space') // Returns 'public_space'
+ */
+export function sanitizeSpaceId(displayName: string): string {
+  return displayName.toLowerCase().replace(/\s+/g, '_');
+}
+
+/**
+ * Get display name for a space ID
+ * 
+ * @param spaceId - Space identifier
+ * @returns Display name or the space ID if not found
+ * 
+ * @example
+ * getSpaceDisplayName('the_void') // Returns 'The Void'
+ */
+export function getSpaceDisplayName(spaceId: string): string {
+  const { SPACE_DISPLAY_NAMES } = require('../types/space-memory.js');
+  return SPACE_DISPLAY_NAMES[spaceId as SpaceId] || spaceId;
+}
+
+/**
+ * Validate space ID
+ * 
+ * @param spaceId - Space identifier to validate
+ * @returns True if valid, false otherwise
+ */
+export function isValidSpaceId(spaceId: string): boolean {
+  return SUPPORTED_SPACES.includes(spaceId as SpaceId);
+}
+
+/**
+ * Create a space collection with schema
+ * 
+ * @param client - Weaviate client
+ * @param spaceId - Space identifier
+ */
+async function createSpaceCollection(
+  client: WeaviateClient,
+  spaceId: string
+): Promise<void> {
+  const collectionName = getSpaceCollectionName(spaceId);
+
+  console.log(`[Weaviate] Creating space collection ${collectionName}...`);
+
+  // Create collection with schema (same as Memory schema but for spaces)
+  await client.collections.create({
+    name: collectionName,
+
+    // Vectorizer configuration
+    vectorizers: weaviate.configure.vectorizer.text2VecOpenAI({
+      model: 'text-embedding-3-small',
+      // Vectorize content for semantic search
+      sourceProperties: ['content', 'observation'],
+    }),
+
+    properties: [
+      // Discriminator
+      {
+        name: 'doc_type',
+        dataType: 'text' as any,
+        description: 'Document type: "space_memory"',
+      },
+
+      // Space identity
+      {
+        name: 'space_id',
+        dataType: 'text' as any,
+        description: 'Space identifier (e.g., "the_void")',
+      },
+      {
+        name: 'author_id',
+        dataType: 'text' as any,
+        description: 'Original author user_id (for permissions)',
+      },
+      {
+        name: 'ghost_id',
+        dataType: 'text' as any,
+        description: 'Optional ghost profile ID for pseudonymous publishing',
+      },
+      {
+        name: 'attribution',
+        dataType: 'text' as any,
+        description: 'Attribution type: "user" or "ghost"',
+      },
+
+      // Discovery metadata
+      {
+        name: 'published_at',
+        dataType: 'text' as any,
+        description: 'When published to space (ISO 8601)',
+      },
+      {
+        name: 'discovery_count',
+        dataType: 'number' as any,
+        description: 'How many times discovered',
+      },
+
+      // Memory fields (same as personal memories)
+      {
+        name: 'content',
+        dataType: 'text' as any,
+        description: 'Main memory content (vectorized)',
+      },
+      {
+        name: 'title',
+        dataType: 'text' as any,
+        description: 'Optional short title',
+      },
+      {
+        name: 'summary',
+        dataType: 'text' as any,
+        description: 'Optional brief summary',
+      },
+      {
+        name: 'type',
+        dataType: 'text' as any,
+        description: 'Content type (note, event, person, etc.)',
+      },
+
+      // Scoring fields
+      {
+        name: 'weight',
+        dataType: 'number' as any,
+        description: 'Significance/priority (0-1)',
+      },
+      {
+        name: 'trust',
+        dataType: 'number' as any,
+        description: 'Access control level (0-1)',
+      },
+      {
+        name: 'confidence',
+        dataType: 'number' as any,
+        description: 'System confidence in accuracy (0-1)',
+      },
+
+      // Location fields (flattened)
+      {
+        name: 'location_gps_latitude',
+        dataType: 'number' as any,
+        description: 'GPS latitude',
+      },
+      {
+        name: 'location_gps_longitude',
+        dataType: 'number' as any,
+        description: 'GPS longitude',
+      },
+      {
+        name: 'location_address_formatted',
+        dataType: 'text' as any,
+        description: 'Formatted address',
+      },
+      {
+        name: 'location_address_city',
+        dataType: 'text' as any,
+        description: 'City',
+      },
+      {
+        name: 'location_address_country',
+        dataType: 'text' as any,
+        description: 'Country',
+      },
+
+      // Context fields (flattened)
+      {
+        name: 'context_conversation_id',
+        dataType: 'text' as any,
+        description: 'Conversation ID',
+      },
+      {
+        name: 'context_platform',
+        dataType: 'text' as any,
+        description: 'Platform where created',
+      },
+
+      // Tags and relationships
+      {
+        name: 'tags',
+        dataType: 'text[]' as any,
+        description: 'Tags for categorization',
+      },
+      {
+        name: 'related_memory_ids',
+        dataType: 'text[]' as any,
+        description: 'IDs of related memories',
+      },
+
+      // Timestamps
+      {
+        name: 'created_at',
+        dataType: 'text' as any,
+        description: 'Original creation timestamp (ISO 8601)',
+      },
+      {
+        name: 'updated_at',
+        dataType: 'text' as any,
+        description: 'Last update timestamp (ISO 8601)',
+      },
+
+      // Versioning
+      {
+        name: 'version',
+        dataType: 'number' as any,
+        description: 'Version number (increments on update)',
+      },
+    ],
+  });
+
+  console.log(`[Weaviate] Space collection ${collectionName} created successfully`);
+}
+
+/**
+ * Ensure a space collection exists, creating it if needed
+ * 
+ * @param client - Weaviate client
+ * @param spaceId - Space identifier
+ * @returns Collection reference
+ * 
+ * @example
+ * const collection = await ensureSpaceCollection(client, 'the_void');
+ */
+export async function ensureSpaceCollection(
+  client: WeaviateClient,
+  spaceId: string
+): Promise<Collection<any>> {
+  // Validate space ID
+  if (!isValidSpaceId(spaceId)) {
+    throw new Error(`Invalid space ID: ${spaceId}. Supported spaces: ${SUPPORTED_SPACES.join(', ')}`);
+  }
+
+  const collectionName = getSpaceCollectionName(spaceId);
+
+  // Check if collection exists
+  const exists = await client.collections.exists(collectionName);
+  
+  if (!exists) {
+    await createSpaceCollection(client, spaceId);
+  }
+
+  return client.collections.get(collectionName);
+}