@prmichaelsen/remember-mcp 0.1.0

package/src/types/memory.ts

@@ -0,0 +1,276 @@
+/**
+ * Memory type definitions for remember-mcp
+ */
+
+/**
+ * Content types for memories
+ * Based on agent/design/content-types-expansion.md
+ */
+export type ContentType =
+  // Core types
+  | 'code'
+  | 'note'
+  | 'documentation'
+  | 'reference'
+  // Task & Planning
+  | 'todo'
+  | 'checklist'
+  | 'project'
+  | 'goal'
+  | 'habit'
+  // Communication
+  | 'email'
+  | 'conversation'
+  | 'meeting'
+  | 'person'
+  // Content & Media
+  | 'article'
+  | 'webpage'
+  | 'social'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'transcript'
+  | 'presentation'
+  | 'spreadsheet'
+  | 'pdf'
+  // Creative
+  | 'screenplay'
+  | 'recipe'
+  | 'idea'
+  | 'quote'
+  // Personal
+  | 'journal'
+  | 'memory'
+  | 'event'
+  // Organizational
+  | 'bookmark'
+  | 'form'
+  | 'location'
+  // Business
+  | 'invoice'
+  | 'contract'
+  // System
+  | 'system'
+  | 'action'
+  | 'audit'
+  | 'history';
+
+/**
+ * GPS coordinates
+ */
+export interface GPSCoordinates {
+  latitude: number;
+  longitude: number;
+  accuracy?: number; // Accuracy in meters
+  altitude?: number;
+  timestamp: string; // ISO 8601 datetime
+}
+
+/**
+ * Address information
+ */
+export interface Address {
+  formatted: string; // Full formatted address
+  street?: string;
+  city?: string;
+  state?: string;
+  country?: string;
+  postal_code?: string;
+  timezone?: string;
+}
+
+/**
+ * Location information (from platform cookies)
+ */
+export interface Location {
+  gps: GPSCoordinates | null;
+  address: Address | null;
+  source: 'gps' | 'ip' | 'manual' | 'cached' | 'unavailable';
+  confidence: number; // 0-1
+  is_approximate: boolean;
+}
+
+/**
+ * Conversation participant
+ */
+export interface Participant {
+  user_id: string;
+  role: 'user' | 'assistant' | 'system';
+  name?: string;
+}
+
+/**
+ * Source information
+ */
+export interface Source {
+  type: 'conversation' | 'import' | 'inference' | 'manual' | 'api';
+  platform?: string; // web, mobile, api
+  client?: string;
+  version?: string;
+}
+
+/**
+ * Environment information
+ */
+export interface Environment {
+  location?: Location;
+  device?: string;
+  user_agent?: string;
+}
+
+/**
+ * Context information about how/when memory was created
+ */
+export interface MemoryContext {
+  conversation_id?: string;
+  conversation_title?: string;
+  turn_number?: number;
+  summary?: string; // Brief summary for quick retrieval
+  participants?: Participant[];
+  timestamp: string; // ISO 8601 datetime
+  timezone?: string;
+  source: Source;
+  environment?: Environment;
+  tags?: string[];
+  notes?: string;
+}
+
+/**
+ * Core Memory interface
+ * Based on agent/design/requirements-enhancements.md
+ */
+export interface Memory {
+  // Core Identity
+  id: string; // UUID from Weaviate
+  user_id: string;
+  doc_type: 'memory'; // Discriminator for unified collection
+
+  // Content
+  content: string; // Main memory content (vectorized)
+  title?: string;
+  summary?: string;
+  type: ContentType;
+
+  // Significance & Trust
+  weight: number; // 0-1, significance/priority
+  trust: number; // 0-1, access control level
+  confidence?: number; // 0-1, system confidence in accuracy
+
+  // Location (from platform)
+  location: Location;
+
+  // Context
+  context: MemoryContext;
+
+  // Relationships
+  relationships: string[]; // IDs of relationship documents
+
+  // Access Tracking (for weight calculation)
+  access_count: number;
+  last_accessed_at?: string; // ISO 8601 datetime
+  access_frequency?: number; // Accesses per day
+
+  // Metadata
+  created_at: string; // ISO 8601 datetime
+  updated_at: string; // ISO 8601 datetime
+  version: number;
+
+  // Organization
+  tags: string[];
+  category?: string;
+  references?: string[]; // Source URLs
+
+  // Template Integration (optional)
+  template_id?: string;
+  template_version?: string;
+  structured_content?: Record<string, any>;
+
+  // Computed Weight (for search ranking)
+  base_weight: number; // User-specified
+  computed_weight?: number; // Calculated with access multipliers
+}
+
+/**
+ * Relationship interface
+ * Stored in same collection as memories with doc_type: "relationship"
+ */
+export interface Relationship {
+  // Core Identity
+  id: string;
+  user_id: string;
+  doc_type: 'relationship'; // Discriminator
+
+  // Connection
+  memory_ids: string[]; // 2...N memory IDs
+  relationship_type: string; // Free-form: "causes", "contradicts", "inspired_by", etc.
+
+  // Observation
+  observation: string; // Description of the connection (vectorized)
+  strength: number; // 0-1
+  confidence: number; // 0-1
+
+  // Context
+  context: MemoryContext;
+
+  // Metadata
+  created_at: string;
+  updated_at: string;
+  version: number;
+  tags: string[];
+}
+
+/**
+ * Union type for documents in Memory collection
+ */
+export type MemoryDocument = Memory | Relationship;
+
+/**
+ * Partial memory for updates
+ */
+export type MemoryUpdate = Partial<Omit<Memory, 'id' | 'user_id' | 'doc_type' | 'created_at' | 'version'>>;
+
+/**
+ * Partial relationship for updates
+ */
+export type RelationshipUpdate = Partial<Omit<Relationship, 'id' | 'user_id' | 'doc_type' | 'created_at' | 'version'>>;
+
+/**
+ * Search filters
+ */
+export interface SearchFilters {
+  types?: ContentType[];
+  tags?: string[];
+  weight_min?: number;
+  weight_max?: number;
+  trust_min?: number;
+  trust_max?: number;
+  date_from?: string;
+  date_to?: string;
+  location_near?: GPSCoordinates;
+  location_radius_meters?: number;
+  has_relationships?: boolean;
+}
+
+/**
+ * Search options
+ */
+export interface SearchOptions {
+  query: string;
+  alpha?: number; // 0-1, balance between semantic (1.0) and keyword (0.0)
+  filters?: SearchFilters;
+  include_relationships?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Search result
+ */
+export interface SearchResult {
+  memories: Memory[];
+  relationships?: Relationship[];
+  total: number;
+  offset: number;
+  limit: number;
+}

package/src/utils/logger.ts

@@ -0,0 +1,42 @@
+import { config } from '../config.js';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const currentLevel = LOG_LEVELS[config.server.logLevel as LogLevel] ?? LOG_LEVELS.info;
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= currentLevel;
+}
+
+export const logger = {
+  debug: (message: string, ...args: any[]) => {
+    if (shouldLog('debug')) {
+      console.debug(`[DEBUG] ${message}`, ...args);
+    }
+  },
+
+  info: (message: string, ...args: any[]) => {
+    if (shouldLog('info')) {
+      console.info(`[INFO] ${message}`, ...args);
+    }
+  },
+
+  warn: (message: string, ...args: any[]) => {
+    if (shouldLog('warn')) {
+      console.warn(`[WARN] ${message}`, ...args);
+    }
+  },
+
+  error: (message: string, ...args: any[]) => {
+    if (shouldLog('error')) {
+      console.error(`[ERROR] ${message}`, ...args);
+    }
+  },
+};

package/src/weaviate/client.spec.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import {
+  initWeaviateClient,
+  testWeaviateConnection,
+  sanitizeUserId,
+  getMemoryCollectionName,
+  getTemplateCollectionName,
+  getAuditCollectionName,
+} from '../../src/weaviate/client.js';
+
+describe('Weaviate Client', () => {
+  describe('User ID Sanitization', () => {
+    it('should sanitize email addresses', () => {
+      expect(sanitizeUserId('user@example.com')).toBe('User_example_com');
+    });
+
+    it('should sanitize user IDs with hyphens', () => {
+      expect(sanitizeUserId('user-123')).toBe('User_123');
+    });
+
+    it('should handle IDs starting with numbers', () => {
+      expect(sanitizeUserId('123user')).toBe('_123user');
+    });
+
+    it('should handle special characters', () => {
+      expect(sanitizeUserId('user!@#$%123')).toBe('User_____123');
+    });
+  });
+
+  describe('Collection Name Generation', () => {
+    it('should generate memory collection names', () => {
+      expect(getMemoryCollectionName('user123')).toBe('Memory_User123');
+      expect(getMemoryCollectionName('user@test.com')).toBe('Memory_User_test_com');
+    });
+
+    it('should generate template collection names', () => {
+      expect(getTemplateCollectionName('user123')).toBe('Template_User123');
+      expect(getTemplateCollectionName('user@test.com')).toBe('Template_User_test_com');
+    });
+
+    it('should generate audit collection names', () => {
+      expect(getAuditCollectionName('user123')).toBe('Audit_User123');
+      expect(getAuditCollectionName('user@test.com')).toBe('Audit_User_test_com');
+    });
+  });
+
+  // Integration tests (require Weaviate instance)
+  describe.skip('Weaviate Connection', () => {
+    beforeAll(async () => {
+      await initWeaviateClient();
+    });
+
+    it('should initialize client', async () => {
+      const result = await testWeaviateConnection();
+      expect(result).toBe(true);
+    });
+  });
+});

package/src/weaviate/client.ts

@@ -0,0 +1,114 @@
+import weaviate, { WeaviateClient } from 'weaviate-client';
+import { config } from '../config.js';
+
+let client: WeaviateClient | null = null;
+
+/**
+ * Initialize Weaviate client
+ */
+export async function initWeaviateClient(): Promise<WeaviateClient> {
+  if (client) {
+    return client;
+  }
+
+  // Weaviate v3 client initialization
+  client = await weaviate.connectToWeaviateCloud(config.weaviate.url, {
+    authCredentials: config.weaviate.apiKey
+      ? new weaviate.ApiKey(config.weaviate.apiKey)
+      : undefined,
+    headers: config.openai.apiKey
+      ? { 'X-OpenAI-Api-Key': config.openai.apiKey }
+      : undefined,
+  });
+
+  console.log('[Weaviate] Client initialized');
+  return client;
+}
+
+/**
+ * Get Weaviate client instance
+ */
+export function getWeaviateClient(): WeaviateClient {
+  if (!client) {
+    throw new Error('Weaviate client not initialized. Call initWeaviateClient() first.');
+  }
+  return client;
+}
+
+/**
+ * Test Weaviate connection
+ */
+export async function testWeaviateConnection(): Promise<boolean> {
+  try {
+    const weaviateClient = getWeaviateClient();
+    const isReady = await weaviateClient.isReady();
+    console.log('[Weaviate] Connection successful, ready:', isReady);
+    return isReady;
+  } catch (error) {
+    console.error('[Weaviate] Connection failed:', error);
+    return false;
+  }
+}
+
+/**
+ * Sanitize user_id for collection name
+ * Weaviate collection names must start with uppercase letter and contain only alphanumeric
+ */
+export function sanitizeUserId(userId: string): string {
+  // Remove special characters, keep alphanumeric
+  let sanitized = userId.replace(/[^a-zA-Z0-9]/g, '_');
+  
+  // If starts with number, prepend underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = '_' + sanitized;
+  }
+  
+  // Ensure starts with uppercase letter
+  return sanitized.charAt(0).toUpperCase() + sanitized.slice(1);
+}
+
+/**
+ * Get collection name for user's memories
+ */
+export function getMemoryCollectionName(userId: string): string {
+  return `Memory_${sanitizeUserId(userId)}`;
+}
+
+/**
+ * Get collection name for user's templates
+ */
+export function getTemplateCollectionName(userId: string): string {
+  return `Template_${sanitizeUserId(userId)}`;
+}
+
+/**
+ * Get collection name for user's audit logs
+ */
+export function getAuditCollectionName(userId: string): string {
+  return `Audit_${sanitizeUserId(userId)}`;
+}
+
+/**
+ * Check if collection exists
+ */
+export async function collectionExists(collectionName: string): Promise<boolean> {
+  try {
+    const weaviateClient = getWeaviateClient();
+    const exists = await weaviateClient.collections.exists(collectionName);
+    return exists;
+  } catch (error) {
+    console.error(`[Weaviate] Error checking collection ${collectionName}:`, error);
+    return false;
+  }
+}
+
+/**
+ * Close Weaviate client connection
+ */
+export async function closeWeaviateClient(): Promise<void> {
+  if (client) {
+    // Weaviate client doesn't have explicit close method
+    client = null;
+    console.log('[Weaviate] Client closed');
+  }
+}