@prmichaelsen/remember-mcp 3.0.0 → 3.13.0

package/src/utils/test-data-generator.spec.ts

@@ -0,0 +1,317 @@
+/**
+ * Unit tests for test-data-generator utilities
+ *
+ * Tests cover:
+ * - generateMemory: correct shape, determinism, field ranges
+ * - generateMemories: count, seeded reproducibility
+ * - filterBySpace / filterByGroup: correctness
+ * - getDatasetStats: accuracy
+ * - measureMs / benchmark: timing utilities
+ */
+
+import {
+  generateMemory,
+  generateMemories,
+  filterBySpace,
+  filterByGroup,
+  getDatasetStats,
+  measureMs,
+  benchmark,
+  type GenerateOptions,
+} from './test-data-generator.js';
+
+// ---------------------------------------------------------------------------
+// generateMemory
+// ---------------------------------------------------------------------------
+
+function makeRng(seed = 42) {
+  let state = seed;
+  return {
+    next(): number {
+      state = (state * 1664525 + 1013904223) & 0xffffffff;
+      return (state >>> 0) / 0xffffffff;
+    },
+    nextInt(min: number, max: number): number {
+      return Math.floor(this.next() * (max - min + 1)) + min;
+    },
+    pick<T>(arr: T[]): T {
+      return arr[this.nextInt(0, arr.length - 1)];
+    },
+    shuffle<T>(arr: T[]): T[] {
+      const copy = [...arr];
+      for (let i = copy.length - 1; i > 0; i--) {
+        const j = this.nextInt(0, i);
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+      }
+      return copy;
+    },
+  };
+}
+
+describe('generateMemory', () => {
+  const opts: GenerateOptions = {
+    count: 1,
+    userId: 'test-user',
+    spaces: ['the_void', 'dogs'],
+    groups: ['grp-1'],
+    publishProbability: 1.0, // ensure fields are set
+  };
+
+  it('returns correct doc_type', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.doc_type).toBe('memory');
+  });
+
+  it('uses userId from options', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.user_id).toBe('test-user');
+  });
+
+  it('has non-empty content', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.content.length).toBeGreaterThan(0);
+  });
+
+  it('has weight in [0, 1] range', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.weight).toBeGreaterThanOrEqual(0);
+    expect(mem.weight).toBeLessThanOrEqual(1);
+  });
+
+  it('has trust in [0, 1] range', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.trust).toBeGreaterThanOrEqual(0);
+    expect(mem.trust).toBeLessThanOrEqual(1);
+  });
+
+  it('always initializes deleted_at to null', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.deleted_at).toBeNull();
+  });
+
+  it('assigns space_ids from provided spaces when publishProbability is 1', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.space_ids).toEqual(expect.arrayContaining(['the_void', 'dogs']));
+  });
+
+  it('assigns group_ids from provided groups when publishProbability is 1', () => {
+    const mem = generateMemory(0, opts, makeRng());
+    expect(mem.group_ids).toContain('grp-1');
+  });
+
+  it('assigns empty space_ids when publishProbability is 0', () => {
+    const zeroOpts = { ...opts, publishProbability: 0 };
+    const mem = generateMemory(0, zeroOpts, makeRng());
+    expect(mem.space_ids).toEqual([]);
+  });
+
+  it('assigns empty group_ids when publishProbability is 0', () => {
+    const zeroOpts = { ...opts, publishProbability: 0 };
+    const mem = generateMemory(0, zeroOpts, makeRng());
+    expect(mem.group_ids).toEqual([]);
+  });
+
+  it('includes index in id', () => {
+    const mem = generateMemory(7, opts, makeRng());
+    expect(mem.id).toContain('00000007');
+  });
+
+  it('produces different created_at per index (1 minute apart)', () => {
+    const mem0 = generateMemory(0, opts, makeRng());
+    const mem1 = generateMemory(1, opts, makeRng());
+    const diff = new Date(mem1.created_at).getTime() - new Date(mem0.created_at).getTime();
+    expect(diff).toBe(60_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generateMemories
+// ---------------------------------------------------------------------------
+
+describe('generateMemories', () => {
+  it('returns exactly count memories', () => {
+    const memories = generateMemories({ count: 100 });
+    expect(memories).toHaveLength(100);
+  });
+
+  it('returns empty array for count 0', () => {
+    const memories = generateMemories({ count: 0 });
+    expect(memories).toHaveLength(0);
+  });
+
+  it('is deterministic with same seed', () => {
+    const a = generateMemories({ count: 50 }, 99);
+    const b = generateMemories({ count: 50 }, 99);
+    expect(a[0].id).toBe(b[0].id);
+    expect(a[0].content).toBe(b[0].content);
+    expect(a[49].weight).toBe(b[49].weight);
+  });
+
+  it('produces different results with different seeds', () => {
+    const a = generateMemories({ count: 10 }, 1);
+    const b = generateMemories({ count: 10 }, 2);
+    // At least one memory should differ
+    const differ = a.some((m, i) => m.content !== b[i].content || m.weight !== b[i].weight);
+    expect(differ).toBe(true);
+  });
+
+  it('all memories have correct user_id', () => {
+    const memories = generateMemories({ count: 20, userId: 'bench-user' });
+    expect(memories.every(m => m.user_id === 'bench-user')).toBe(true);
+  });
+
+  it('all memories have doc_type memory', () => {
+    const memories = generateMemories({ count: 20 });
+    expect(memories.every(m => m.doc_type === 'memory')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// filterBySpace / filterByGroup
+// ---------------------------------------------------------------------------
+
+describe('filterBySpace', () => {
+  const memories = generateMemories({
+    count: 200,
+    spaces: ['the_void', 'dogs'],
+    publishProbability: 0.5,
+  });
+
+  it('returns only memories with the specified space_id', () => {
+    const filtered = filterBySpace(memories, 'the_void');
+    expect(filtered.every(m => m.space_ids.includes('the_void'))).toBe(true);
+  });
+
+  it('returns empty array for non-existent space', () => {
+    const filtered = filterBySpace(memories, 'non-existent-space');
+    expect(filtered).toHaveLength(0);
+  });
+
+  it('returns subset of total memories', () => {
+    const filtered = filterBySpace(memories, 'the_void');
+    expect(filtered.length).toBeLessThanOrEqual(memories.length);
+    expect(filtered.length).toBeGreaterThan(0);
+  });
+});
+
+describe('filterByGroup', () => {
+  const memories = generateMemories({
+    count: 200,
+    groups: ['grp-a', 'grp-b'],
+    publishProbability: 0.5,
+  });
+
+  it('returns only memories with the specified group_id', () => {
+    const filtered = filterByGroup(memories, 'grp-a');
+    expect(filtered.every(m => m.group_ids.includes('grp-a'))).toBe(true);
+  });
+
+  it('returns empty array for non-existent group', () => {
+    const filtered = filterByGroup(memories, 'grp-z');
+    expect(filtered).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getDatasetStats
+// ---------------------------------------------------------------------------
+
+describe('getDatasetStats', () => {
+  it('returns total equal to memories.length', () => {
+    const memories = generateMemories({ count: 100 });
+    const stats = getDatasetStats(memories);
+    expect(stats.total).toBe(100);
+  });
+
+  it('unpublished + publishedToAnySpace/Group accounting is internally consistent', () => {
+    const memories = generateMemories({
+      count: 200,
+      spaces: ['the_void'],
+      groups: ['grp-1'],
+      publishProbability: 0.5,
+    });
+    const stats = getDatasetStats(memories);
+    expect(stats.publishedToAnySpace + stats.publishedToAnyGroup + stats.unpublished).toBeGreaterThanOrEqual(stats.total);
+    expect(stats.total).toBe(200);
+  });
+
+  it('bySpace counts match filterBySpace counts', () => {
+    const memories = generateMemories({
+      count: 100,
+      spaces: ['the_void', 'dogs'],
+      publishProbability: 0.5,
+    });
+    const stats = getDatasetStats(memories);
+    const filteredCount = filterBySpace(memories, 'the_void').length;
+    expect(stats.bySpace['the_void'] ?? 0).toBe(filteredCount);
+  });
+
+  it('avgTagsPerMemory is a reasonable number between 0 and 3', () => {
+    const memories = generateMemories({ count: 100 });
+    const stats = getDatasetStats(memories);
+    expect(stats.avgTagsPerMemory).toBeGreaterThanOrEqual(0);
+    expect(stats.avgTagsPerMemory).toBeLessThanOrEqual(3);
+  });
+
+  it('returns all zeros for empty dataset', () => {
+    const stats = getDatasetStats([]);
+    expect(stats.total).toBe(0);
+    expect(stats.publishedToAnySpace).toBe(0);
+    expect(stats.unpublished).toBe(0);
+    expect(stats.avgTagsPerMemory).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// measureMs
+// ---------------------------------------------------------------------------
+
+describe('measureMs', () => {
+  it('returns result from the async function', async () => {
+    const { result } = await measureMs(async () => 42);
+    expect(result).toBe(42);
+  });
+
+  it('returns elapsedMs as a non-negative number', async () => {
+    const { elapsedMs } = await measureMs(async () => {});
+    expect(elapsedMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it('captures time for delayed operations', async () => {
+    const { elapsedMs } = await measureMs(async () => {
+      await new Promise(resolve => setTimeout(resolve, 20));
+    });
+    expect(elapsedMs).toBeGreaterThanOrEqual(15);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// benchmark
+// ---------------------------------------------------------------------------
+
+describe('benchmark', () => {
+  it('runs exactly iterations times', async () => {
+    let count = 0;
+    await benchmark(async () => { count++; }, 5);
+    expect(count).toBe(5);
+  });
+
+  it('returns results array of correct length', async () => {
+    const { results } = await benchmark(async () => 'x', 3);
+    expect(results).toHaveLength(3);
+  });
+
+  it('min <= avg <= max', async () => {
+    const { min, avg, max } = await benchmark(async () => {
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }, 4);
+    expect(min).toBeLessThanOrEqual(avg);
+    expect(avg).toBeLessThanOrEqual(max);
+  });
+
+  it('p95 is between min and max', async () => {
+    const { min, max, p95 } = await benchmark(async () => {}, 10);
+    expect(p95).toBeGreaterThanOrEqual(min);
+    expect(p95).toBeLessThanOrEqual(max);
+  });
+});

package/src/utils/test-data-generator.ts

@@ -0,0 +1,292 @@
+/**
+ * Test Data Generator for Memory Collection Pattern v2 Performance Tests
+ *
+ * Generates synthetic memory objects at scale for benchmarking.
+ * All functions are pure (no Weaviate dependency) — usable in unit tests.
+ */
+
+import { SUPPORTED_SPACES } from '../types/space-memory.js';
+
+/**
+ * Minimal memory object shape used for performance test generation.
+ * Mirrors the fields written to Weaviate during create/publish.
+ */
+export interface SyntheticMemory {
+  id: string;
+  user_id: string;
+  doc_type: 'memory';
+  content: string;
+  title: string;
+  type: string;
+  weight: number;
+  trust: number;
+  confidence: number;
+  tags: string[];
+  space_ids: string[];
+  group_ids: string[];
+  created_at: string;
+  updated_at: string;
+  version: number;
+  access_count: number;
+  deleted_at: null;
+}
+
+/**
+ * Options for generating synthetic memories
+ */
+export interface GenerateOptions {
+  /** Number of memories to generate */
+  count: number;
+  /** User ID to assign (default: 'perf-test-user') */
+  userId?: string;
+  /** Spaces to randomly assign (default: subset of SUPPORTED_SPACES) */
+  spaces?: string[];
+  /** Group IDs to randomly assign */
+  groups?: string[];
+  /** Probability (0-1) that a memory has been published to a space */
+  publishProbability?: number;
+  /** Base ISO date string for created_at (default: current time) */
+  baseDate?: string;
+}
+
+/**
+ * A fast, deterministic pseudo-random number generator (LCG).
+ * Avoids Math.random() so tests are reproducible.
+ */
+function createRng(seed: number) {
+  let state = seed;
+  return {
+    next(): number {
+      state = (state * 1664525 + 1013904223) & 0xffffffff;
+      return (state >>> 0) / 0xffffffff;
+    },
+    nextInt(min: number, max: number): number {
+      return Math.floor(this.next() * (max - min + 1)) + min;
+    },
+    pick<T>(arr: T[]): T {
+      return arr[this.nextInt(0, arr.length - 1)];
+    },
+    shuffle<T>(arr: T[]): T[] {
+      const copy = [...arr];
+      for (let i = copy.length - 1; i > 0; i--) {
+        const j = this.nextInt(0, i);
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+      }
+      return copy;
+    },
+  };
+}
+
+const CONTENT_TEMPLATES = [
+  'Remember that {} is important for the project.',
+  'Note: {} should be completed by next week.',
+  'Meeting with {} to discuss the roadmap.',
+  'Recipe for {}: combine ingredients and bake.',
+  'Bookmark: {} — useful reference for later.',
+  'Idea: {} could improve performance significantly.',
+  'Quote from {}: "Knowledge is power."',
+  'Event: {} on the calendar for this month.',
+  'Todo: {} needs to be done before launch.',
+  'Research notes on {}: several key findings.',
+];
+
+const WORDS = [
+  'alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta', 'eta', 'theta',
+  'project', 'memory', 'design', 'system', 'module', 'feature', 'release',
+  'task', 'goal', 'metric', 'api', 'schema', 'service', 'client', 'server',
+];
+
+const CONTENT_TYPES = ['note', 'todo', 'bookmark', 'idea', 'recipe', 'event', 'reference'];
+
+const TAG_POOL = [
+  'important', 'work', 'personal', 'cooking', 'tech', 'health',
+  'books', 'travel', 'family', 'finance', 'learning', 'creative',
+];
+
+/**
+ * Generate a single synthetic memory
+ */
+export function generateMemory(index: number, options: GenerateOptions, rng: ReturnType<typeof createRng>): SyntheticMemory {
+  const userId = options.userId ?? 'perf-test-user';
+  const spaces = options.spaces ?? SUPPORTED_SPACES.slice(0, 3);
+  const groups = options.groups ?? [];
+  const publishProb = options.publishProbability ?? 0.3;
+  const baseDate = options.baseDate ?? '2026-01-01T00:00:00Z';
+
+  const baseTime = new Date(baseDate).getTime();
+  const createdAt = new Date(baseTime + index * 60_000).toISOString(); // 1 minute apart
+
+  const word = rng.pick(WORDS);
+  const template = rng.pick(CONTENT_TEMPLATES);
+  const content = template.replace('{}', word);
+
+  const tagCount = rng.nextInt(0, 3);
+  const shuffledTags = rng.shuffle(TAG_POOL);
+  const tags = shuffledTags.slice(0, tagCount);
+
+  // Randomly assign to spaces based on publishProbability
+  const assignedSpaceIds: string[] = [];
+  for (const spaceId of spaces) {
+    if (rng.next() < publishProb) {
+      assignedSpaceIds.push(spaceId);
+    }
+  }
+
+  // Randomly assign to groups
+  const assignedGroupIds: string[] = [];
+  for (const groupId of groups) {
+    if (rng.next() < publishProb) {
+      assignedGroupIds.push(groupId);
+    }
+  }
+
+  return {
+    id: `${userId}-mem-${String(index).padStart(8, '0')}`,
+    user_id: userId,
+    doc_type: 'memory',
+    content,
+    title: `Memory ${index}: ${word}`,
+    type: rng.pick(CONTENT_TYPES),
+    weight: Math.round(rng.next() * 100) / 100,
+    trust: Math.round(rng.next() * 100) / 100,
+    confidence: 1.0,
+    tags,
+    space_ids: assignedSpaceIds,
+    group_ids: assignedGroupIds,
+    created_at: createdAt,
+    updated_at: createdAt,
+    version: 1,
+    access_count: 0,
+    deleted_at: null,
+  };
+}
+
+/**
+ * Generate a batch of synthetic memories.
+ *
+ * Uses a seeded RNG for reproducible results across test runs.
+ *
+ * @param options - Generation options
+ * @param seed - RNG seed (default: 42)
+ * @returns Array of synthetic memory objects
+ *
+ * @example
+ * // Generate 1K memories for a single user
+ * const memories = generateMemories({ count: 1000 });
+ *
+ * // Generate 10K with custom spaces
+ * const memories = generateMemories({
+ *   count: 10_000,
+ *   userId: 'user-123',
+ *   spaces: ['the_void', 'dogs'],
+ *   publishProbability: 0.5,
+ * });
+ */
+export function generateMemories(options: GenerateOptions, seed = 42): SyntheticMemory[] {
+  const rng = createRng(seed);
+  const memories: SyntheticMemory[] = [];
+
+  for (let i = 0; i < options.count; i++) {
+    memories.push(generateMemory(i, options, rng));
+  }
+
+  return memories;
+}
+
+/**
+ * Filter generated memories to only those published to a given space.
+ * Mirrors the Weaviate containsAny filter used in search-space.
+ */
+export function filterBySpace(memories: SyntheticMemory[], spaceId: string): SyntheticMemory[] {
+  return memories.filter(m => m.space_ids.includes(spaceId));
+}
+
+/**
+ * Filter generated memories to only those published to a given group.
+ */
+export function filterByGroup(memories: SyntheticMemory[], groupId: string): SyntheticMemory[] {
+  return memories.filter(m => m.group_ids.includes(groupId));
+}
+
+/**
+ * Get publication statistics for a generated dataset.
+ * Useful for understanding expected query result counts before running benchmarks.
+ */
+export function getDatasetStats(memories: SyntheticMemory[]): {
+  total: number;
+  publishedToAnySpace: number;
+  publishedToAnyGroup: number;
+  unpublished: number;
+  bySpace: Record<string, number>;
+  byGroup: Record<string, number>;
+  avgTagsPerMemory: number;
+} {
+  const bySpace: Record<string, number> = {};
+  const byGroup: Record<string, number> = {};
+  let publishedToAnySpace = 0;
+  let publishedToAnyGroup = 0;
+  let totalTags = 0;
+
+  for (const mem of memories) {
+    if (mem.space_ids.length > 0) publishedToAnySpace++;
+    if (mem.group_ids.length > 0) publishedToAnyGroup++;
+    totalTags += mem.tags.length;
+
+    for (const spaceId of mem.space_ids) {
+      bySpace[spaceId] = (bySpace[spaceId] ?? 0) + 1;
+    }
+    for (const groupId of mem.group_ids) {
+      byGroup[groupId] = (byGroup[groupId] ?? 0) + 1;
+    }
+  }
+
+  return {
+    total: memories.length,
+    publishedToAnySpace,
+    publishedToAnyGroup,
+    unpublished: memories.filter(m => m.space_ids.length === 0 && m.group_ids.length === 0).length,
+    bySpace,
+    byGroup,
+    avgTagsPerMemory: memories.length > 0 ? Math.round((totalTags / memories.length) * 100) / 100 : 0,
+  };
+}
+
+/**
+ * Timing utility for measuring operation duration.
+ * Returns elapsed milliseconds.
+ */
+export async function measureMs<T>(fn: () => Promise<T>): Promise<{ result: T; elapsedMs: number }> {
+  const start = performance.now();
+  const result = await fn();
+  const elapsedMs = Math.round((performance.now() - start) * 100) / 100;
+  return { result, elapsedMs };
+}
+
+/**
+ * Run a function N times and return timing statistics.
+ */
+export async function benchmark<T>(
+  fn: () => Promise<T>,
+  iterations: number
+): Promise<{ min: number; max: number; avg: number; p95: number; results: T[] }> {
+  const times: number[] = [];
+  const results: T[] = [];
+
+  for (let i = 0; i < iterations; i++) {
+    const { result, elapsedMs } = await measureMs(fn);
+    times.push(elapsedMs);
+    results.push(result);
+  }
+
+  times.sort((a, b) => a - b);
+  const avg = times.reduce((s, t) => s + t, 0) / times.length;
+  const p95Index = Math.floor(times.length * 0.95);
+
+  return {
+    min: times[0],
+    max: times[times.length - 1],
+    avg: Math.round(avg * 100) / 100,
+    p95: times[p95Index],
+    results,
+  };
+}

package/src/utils/weaviate-filters.ts

@@ -68,11 +68,11 @@ function buildDocTypeFilters(
   if (docType === 'memory' && filters?.types && filters.types.length > 0) {
     if (filters.types.length === 1) {
       filterList.push(
-        collection.filter.byProperty('type').equal(filters.types[0])
+        collection.filter.byProperty('content_type').equal(filters.types[0])
       );
     } else {
       filterList.push(
-        collection.filter.byProperty('type').containsAny(filters.types)
+        collection.filter.byProperty('content_type').containsAny(filters.types)
       );
     }
   }
@@ -94,14 +94,14 @@ function buildDocTypeFilters(
   // Trust filter (minimum) - applies to both
   if (filters?.trust_min !== undefined) {
     filterList.push(
-      collection.filter.byProperty('trust').greaterThanOrEqual(filters.trust_min)
+      collection.filter.byProperty('trust_score').greaterThanOrEqual(filters.trust_min)
     );
   }
 
   // Trust filter (maximum)
   if (filters?.trust_max !== undefined) {
     filterList.push(
-      collection.filter.byProperty('trust').lessThanOrEqual(filters.trust_max)
+      collection.filter.byProperty('trust_score').lessThanOrEqual(filters.trust_max)
     );
   }