@prmichaelsen/remember-mcp 3.0.0 → 3.12.0

package/dist/weaviate/client.d.ts

@@ -18,11 +18,11 @@ export declare function getWeaviateClient(): WeaviateClient;
 export declare function testWeaviateConnection(): Promise<boolean>;
 /**
  * Sanitize user_id for collection name
- * Weaviate collection names must start with uppercase letter and contain only alphanumeric
+ * @deprecated v2 uses literal userId — no sanitization needed. Kept for migration script only.
  */
 export declare function sanitizeUserId(userId: string): string;
 /**
- * Get collection name for user's memories
+ * Get collection name for user's memories (v2 format)
  */
 export declare function getMemoryCollectionName(userId: string): string;
 /**
@@ -35,13 +35,10 @@ export declare function getTemplateCollectionName(userId: string): string;
 export declare function getAuditCollectionName(userId: string): string;
 /**
  * List of all memory properties to fetch
- * Centralized to ensure consistency across all tools
+ * Centralized to ensure consistency across all tools.
+ * Includes both v2 canonical names and v1 compat names.
  */
-/**
- * List of all memory properties to fetch
- * Matches the actual Weaviate schema properties exactly
- */
-export declare const ALL_MEMORY_PROPERTIES: readonly ["user_id", "doc_type", "content", "title", "summary", "type", "weight", "base_weight", "trust", "confidence", "computed_weight", "location_gps_lat", "location_gps_lng", "location_address", "location_city", "location_country", "location_source", "locale_language", "locale_timezone", "context_conversation_id", "context_summary", "context_timestamp", "relationships", "access_count", "last_accessed_at", "tags", "references", "created_at", "updated_at", "version", "template_id", "memory_ids", "relationship_type", "observation", "strength", "parent_id", "thread_root_id", "moderation_flags", "spaces", "space_id", "author_id", "ghost_id", "attribution", "published_at", "discovery_count", "space_memory_id", "deleted_at", "deleted_by", "deletion_reason"];
+export declare const ALL_MEMORY_PROPERTIES: readonly ["user_id", "doc_type", "content", "content_type", "title", "summary", "type", "weight", "base_weight", "trust_score", "trust", "confidence", "computed_weight", "location_name", "location_lat", "location_lon", "location_gps_lat", "location_gps_lng", "location_address", "location_city", "location_country", "location_source", "locale_language", "locale_timezone", "context_conversation_id", "context_summary", "context_timestamp", "context_app", "context_url", "relationship_ids", "related_memory_ids", "relationships", "memory_ids", "relationship_type", "observation", "strength", "access_count", "last_accessed_at", "tags", "references", "created_at", "updated_at", "version", "template_id", "space_ids", "group_ids", "parent_id", "thread_root_id", "moderation_flags", "spaces", "space_id", "author_id", "ghost_id", "attribution", "published_at", "discovery_count", "space_memory_id", "original_memory_id", "revised_at", "revision_count", "revision_history", "deleted_at", "deleted_by", "deletion_reason"];
 /**
  * Fetch a memory object by ID with all properties
  *

package/dist/weaviate/space-schema.d.ts

@@ -6,9 +6,9 @@
  */
 import { type WeaviateClient, type Collection } from 'weaviate-client';
 /**
- * Unified public collection name for all public spaces
+ * Unified public collection name for all public spaces (v2)
  */
-export declare const PUBLIC_COLLECTION_NAME = "Memory_public";
+export declare const PUBLIC_COLLECTION_NAME = "Memory_spaces_public";
 /**
  * Get collection name for a space
  *

package/docs/performance/v2-benchmarks.md

@@ -0,0 +1,80 @@
+# Memory Collection Pattern v2 — Performance Benchmarks
+
+## Overview
+
+This document defines performance targets and tracks benchmark results for
+Memory Collection Pattern v2 operations.
+
+## Running Benchmarks
+
+```bash
+# Pure performance tests (no Weaviate required)
+npm test -- --testPathPattern=test-data-generator
+
+# E2E performance tests (requires live Weaviate)
+WEAVIATE_URL=http://localhost:8080 npm run test:e2e -- --testPathPattern=v2-performance
+```
+
+## Performance Targets
+
+| Operation | Target | Notes |
+|-----------|--------|-------|
+| Single-space query (1K memories) | < 200ms | hybrid search |
+| Multi-space query (1K memories) | < 200ms | containsAny filter |
+| All-public query (1K memories) | < 200ms | no space_ids filter |
+| Group query (1K memories) | < 200ms | per-group collection |
+| Create memory | < 100ms | personal collection |
+| Update memory | < 100ms | replace operation |
+| Publish (single space) | < 100ms | insert to spaces_public |
+| Publish (multi-space/group) | < 200ms | parallel inserts |
+| Retract | < 100ms | delete + tracking update |
+| Revise published | < 200ms | update all copies |
+| Deduplication (1K results) | < 10ms | Set-based UUID dedup |
+
+## Optimizations Applied
+
+| Optimization | Impact | Commit |
+|-------------|--------|--------|
+| Set-based dedup in `addMultipleSpaceIds`/`addMultipleGroupIds` | O(n*m) → O(n+m) for bulk tracking array updates | v3.7.0 |
+| `indexNullState: true` on all collections | Enables efficient `deleted_at isNull` filter | v3.0.0 |
+| `space_ids.containsAny()` filter | Weaviate inverted index on text[] field | v3.5.0 |
+| Fetch limit pre-pagination | Single query per source, paginate in memory | v3.5.0 |
+
+## Benchmark Results
+
+> Results pending live Weaviate benchmarking session.
+> Run the E2E suite and record results here.
+
+### Query Performance
+
+| Scenario | Dataset | p50 | p95 | Target | Status |
+|----------|---------|-----|-----|--------|--------|
+| Single-space search | 1K | — | — | 200ms | Pending |
+| Multi-space search | 1K | — | — | 200ms | Pending |
+| All-public search | 1K | — | — | 200ms | Pending |
+| Group search | 1K | — | — | 200ms | Pending |
+
+### Write Performance
+
+| Operation | p50 | p95 | Target | Status |
+|-----------|-----|-----|--------|--------|
+| Create memory | — | — | 100ms | Pending |
+| Update memory | — | — | 100ms | Pending |
+| Publish (single) | — | — | 100ms | Pending |
+| Publish (multi) | — | — | 200ms | Pending |
+| Retract | — | — | 100ms | Pending |
+| Revise | — | — | 200ms | Pending |
+
+### Deduplication Performance (pure, no Weaviate)
+
+| Dataset | Elapsed | Target | Status |
+|---------|---------|--------|--------|
+| 1K objects (with 200 dupes) | < 1ms | 10ms | ✅ Passing |
+| 10K objects (50% dupes) | < 5ms | 50ms | ✅ Passing |
+
+## Notes
+
+- All query benchmarks use `search_type: "hybrid"` (default)
+- p95 is the primary SLO metric (not p50/avg)
+- Network latency to Weaviate (~1–5ms local) is included in measurements
+- Benchmarks should be rerun after schema changes or Weaviate upgrades

package/jest.e2e.config.js

@@ -1,9 +1,11 @@
-module.exports = {
-  preset: 'ts-jest',
+export default {
+  preset: 'ts-jest/presets/default-esm',
   testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
   testMatch: ['**/*.e2e.ts'],
-  testTimeout: 30000, // 30 seconds for real API calls
+  testTimeout: 60000, // 60 seconds for real API calls
   roots: ['<rootDir>/src'],
+  moduleFileExtensions: ['ts', 'js'],
   collectCoverageFrom: [
     'src/**/*.ts',
     '!src/**/*.spec.ts',
@@ -13,5 +15,14 @@ module.exports = {
   ],
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        useESM: true,
+      },
+    ],
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prmichaelsen/remember-mcp",
-  "version": "3.0.0",
+  "version": "3.12.0",
   "description": "Multi-tenant memory system MCP server with vector search and relationships",
   "main": "dist/server.js",
   "type": "module",

package/scripts/.collection-recreation-state.yaml

@@ -0,0 +1,16 @@
+migration:
+  id: recreate-collections-2026-02-25T21-34-24
+  started_at: 2026-02-25T21:34:24.770Z
+  updated_at: 2026-02-25T21:38:05.333Z
+  status: completed
+collections:
+  - name: Memory_MnOyIarhz5b8n06TsTovM582NSG2
+    status: completed
+    total_documents: 0
+    backed_up_documents: 0
+    restored_documents: 6577
+progress:
+  total_collections: 1
+  completed_collections: 4
+  percentage: 400
+errors: []

package/scripts/.gitkeep

@@ -0,0 +1,5 @@
+# Scripts
+
+Migration and utility scripts for remember-mcp.
+
+**Note**: Scripts have their own dependencies. See [scripts/README.md](scripts/README.md) for setup instructions.

package/scripts/README-collection-recreation.md

@@ -0,0 +1,224 @@
+# Collection Recreation Migration
+
+This script recreates Weaviate collections with updated schema configuration to fix the `indexNullState` bug introduced in v3.0.0.
+
+## Why This is Needed
+
+Version 3.0.0 added the soft delete system with a `deleted_at` field. The default filter uses `deleted_at IS NULL` to exclude deleted memories. However, the schema was missing `indexNullState: true` configuration, causing all searches to fail with:
+
+```
+WeaviateQueryError: Nullstate must be indexed to be filterable! 
+Add `indexNullState: true` to the invertedIndexConfig
+```
+
+**Version 3.0.1** fixes the schema, but existing collections must be recreated to apply the fix.
+
+## What This Script Does
+
+1. **Backs up** all documents from each collection (with vectors)
+2. **Deletes** the old collection
+3. **Recreates** the collection with `indexNullState: true`
+4. **Restores** all documents with original IDs and vectors
+5. **Verifies** document counts match
+
+## Prerequisites
+
+- remember-mcp v3.0.1 or later (with fixed schema)
+- Weaviate instance access
+- Sufficient disk space for backups
+
+## Quick Start
+
+### 1. Update to v3.0.1
+
+```bash
+npm install @prmichaelsen/remember-mcp@3.0.1
+```
+
+### 2. Run Migration
+
+```bash
+# Dry run first (test without changes)
+npx tsx scripts/migrate-recreate-collections.ts --dry-run
+
+# Run actual migration
+npx tsx scripts/migrate-recreate-collections.ts
+```
+
+## Usage Examples
+
+### Migrate All Collections
+
+```bash
+npx tsx scripts/migrate-recreate-collections.ts
+```
+
+### Migrate Specific Collections
+
+```bash
+npx tsx scripts/migrate-recreate-collections.ts \
+  --collections "Memory_user123,Memory_public"
+```
+
+### Dry Run (Test Mode)
+
+```bash
+npx tsx scripts/migrate-recreate-collections.ts --dry-run
+```
+
+### Custom Batch Size
+
+```bash
+npx tsx scripts/migrate-recreate-collections.ts --batch-size 500
+```
+
+## Configuration
+
+### Environment Variables
+
+Create `.env` file or set environment variables:
+
+```bash
+WEAVIATE_REST_URL=https://your-instance.weaviate.cloud
+WEAVIATE_API_KEY=your-api-key
+OPENAI_EMBEDDINGS_API_KEY=sk-...
+BATCH_SIZE=100
+```
+
+### CLI Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--weaviate-url` | Weaviate instance URL | `WEAVIATE_REST_URL` |
+| `--weaviate-key` | Weaviate API key | `WEAVIATE_API_KEY` |
+| `--openai-key` | OpenAI API key | `OPENAI_EMBEDDINGS_API_KEY` |
+| `--batch-size` | Documents per batch | 100 |
+| `--dry-run` | Test without changes | false |
+| `--collections` | Specific collections (comma-separated) | All Memory_* collections |
+| `--state-file` | State file path | `.collection-recreation-state.yaml` |
+
+## Safety Features
+
+- ✅ **Backups**: All data backed up before deletion
+- ✅ **State Management**: Progress tracked in YAML file
+- ✅ **Verification**: Document counts verified after restoration
+- ✅ **Dry Run**: Test mode to preview changes
+- ✅ **ID Preservation**: Original document IDs maintained
+- ✅ **Vector Preservation**: Original vectors maintained
+
+## Output Example
+
+```
+🚀 Collection Recreation Migration
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Configuration:
+  Weaviate URL: https://your-instance.weaviate.cloud
+  Batch Size: 100
+  Dry Run: false
+  Backup Directory: ./migration-backups
+
+🔍 Discovering collections...
+  Found 2 collections: Memory_user123, Memory_public
+
+📦 Migrating: Memory_user123
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  📥 Backing up Memory_user123...
+    Total documents: 1,234
+    Progress: 100.0% (1,234/1,234)
+    ✓ Backup complete
+    ✓ Saved backup: ./migration-backups/Memory_user123-2026-02-25-203000.json
+  🗑️  Deleting Memory_user123...
+    ✓ Deleted
+  🔨 Recreating Memory_user123 with updated schema...
+    ✓ Recreated with indexNullState: true
+  📤 Restoring 1,234 documents...
+    Progress: 100.0% (1,234/1,234)
+    ✓ Restore complete
+  ✓ Verified: 1,234 documents restored
+  ✅ Migration complete
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Migration Summary:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Total Collections: 2
+  Successful: 2
+  Failed: 0
+  Dry Run: false
+
+✨ Migration completed successfully!
+```
+
+## Troubleshooting
+
+### "Cannot connect to Weaviate"
+
+**Solution**: Verify `WEAVIATE_REST_URL` and `WEAVIATE_API_KEY` are correct.
+
+### "Document count mismatch"
+
+**Solution**: Check the state file for errors. The backup file is preserved in `./migration-backups/` for manual recovery.
+
+### Migration interrupted
+
+**Solution**: The script automatically resumes from the last successful step. Just run it again.
+
+### Out of disk space
+
+**Solution**: Backups are saved to `./migration-backups/`. Ensure sufficient disk space or use a smaller batch size.
+
+## Backup Files
+
+Backups are saved to `./migration-backups/` with format:
+```
+{collection_name}-{timestamp}.json
+```
+
+**Example**:
+```
+./migration-backups/Memory_user123-2026-02-25-203000.json
+```
+
+These files contain:
+- Collection schema
+- All documents with properties
+- All vectors
+- Document IDs
+
+**Keep these files** until you verify the migration succeeded.
+
+## State File
+
+Progress is tracked in `.collection-recreation-state.yaml`:
+
+```yaml
+migration:
+  id: recreate-collections-2026-02-25-203000
+  started_at: 2026-02-25T20:30:00Z
+  status: in_progress
+
+collections:
+  - name: Memory_user123
+    status: completed
+    total_documents: 1234
+    backed_up_documents: 1234
+    restored_documents: 1234
+    backup_file: ./migration-backups/Memory_user123-2026-02-25-203000.json
+
+progress:
+  total_collections: 2
+  completed_collections: 1
+  percentage: 50.0
+```
+
+## Security
+
+- Never commit backup files to version control
+- Never commit state files to version control
+- Backup files may contain sensitive user data
+- Delete backups after successful migration
+
+## Related Documentation
+
+- [Task 76: Fix indexNullState Schema Bug](../agent/tasks/task-76-fix-indexnullstate-schema-bug.md)
+- [CHANGELOG v3.0.1](../CHANGELOG.md)

package/scripts/README.md

@@ -0,0 +1,51 @@
+# Scripts Directory
+
+Migration and utility scripts for remember-mcp maintenance.
+
+## Setup
+
+Install script dependencies:
+
+```bash
+cd scripts
+npm install
+```
+
+## Available Scripts
+
+### Collection Recreation Migration
+
+Recreates Weaviate collections with updated schema configuration (v3.0.1 fix).
+
+**Required after**: Upgrading from v3.0.0 to v3.0.1
+
+**Documentation**: [README-collection-recreation.md](README-collection-recreation.md)
+
+**Usage**:
+```bash
+cd scripts
+npm run migrate:recreate:dry-run  # Test first
+npm run migrate:recreate           # Run migration
+```
+
+## Dependencies
+
+Scripts have their own `package.json` to avoid polluting the main project dependencies:
+
+- `weaviate-client` - Weaviate SDK
+- `yaml` - YAML parsing for state files
+- `dotenv` - Environment configuration
+- `tsx` - TypeScript execution
+
+## Environment Configuration
+
+Create `.env` file in scripts directory:
+
+```bash
+WEAVIATE_REST_URL=https://your-instance.weaviate.cloud
+WEAVIATE_API_KEY=your-api-key
+OPENAI_EMBEDDINGS_API_KEY=sk-...
+BATCH_SIZE=100
+```
+
+Or use environment variables from parent directory.