superlocalmemory 3.0.3 → 3.0.7

package/README.md

@@ -85,13 +85,35 @@ Query  ──►  Strategy Classifier  ──►  4 Parallel Channels:
 
 ---
 
+## Prerequisites
+
+| Requirement | Version | Why |
+|:-----------|:--------|:----|
+| **Node.js** | 14+ | npm package manager |
+| **Python** | 3.11+ | V3 engine runtime |
+| **pip** | Latest | Python dependency installer |
+
+> All Python dependencies are installed automatically during `npm install`. You don't need to run pip manually. If any dependency fails, the installer shows clear instructions.
+
+---
+
 ## Quick Start
 
-### Install via npm (recommended)
+### Install via npm (recommended — one command, everything included)
 
 ```bash
 npm install -g superlocalmemory
-slm setup
+```
+
+This single command:
+- Installs the V3 engine and CLI
+- Auto-installs all Python dependencies (numpy, scipy, networkx, sentence-transformers, etc.)
+- Creates the data directory at `~/.superlocalmemory/`
+- Detects and guides V2 migration if applicable
+
+Then configure:
+```bash
+slm setup    # Choose mode, configure provider
 ```
 
 ### Install via pip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.0.3",
+  "version": "3.0.7",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/scripts/postinstall.js

@@ -2,26 +2,26 @@
 /**
  * SuperLocalMemory V3 - NPM Postinstall Script
  *
+ * ONE COMMAND INSTALL. Everything the user needs.
+ * Python deps auto-installed. Embeddings auto-downloaded.
+ *
  * Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
  * Licensed under MIT License
- * Repository: https://github.com/qualixar/superlocalmemory
  */
 
+const { spawnSync } = require('child_process');
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
 
 console.log('\n════════════════════════════════════════════════════════════');
-console.log('  SuperLocalMemory V3 - Post-Installation');
+console.log('  SuperLocalMemory V3 — Post-Installation');
 console.log('  by Varun Pratap Bhardwaj / Qualixar');
 console.log('  https://github.com/qualixar/superlocalmemory');
 console.log('════════════════════════════════════════════════════════════\n');
 
-// V3 data directory
+// --- Step 1: Create data directory ---
 const SLM_HOME = path.join(os.homedir(), '.superlocalmemory');
-const V2_HOME = path.join(os.homedir(), '.claude-memory');
-
-// Ensure V3 data directory exists
 if (!fs.existsSync(SLM_HOME)) {
     fs.mkdirSync(SLM_HOME, { recursive: true });
     console.log('✓ Created data directory: ' + SLM_HOME);
@@ -29,7 +29,102 @@ if (!fs.existsSync(SLM_HOME)) {
     console.log('✓ Data directory exists: ' + SLM_HOME);
 }
 
-// Detect V2 installation
+// --- Step 2: Find Python 3 ---
+function findPython() {
+    const candidates = [
+        'python3', 'python',
+        '/opt/homebrew/bin/python3', '/usr/local/bin/python3', '/usr/bin/python3',
+    ];
+    if (os.platform() === 'win32') candidates.push('py -3');
+    for (const cmd of candidates) {
+        try {
+            const parts = cmd.split(' ');
+            const r = spawnSync(parts[0], [...parts.slice(1), '--version'], {
+                stdio: 'pipe', timeout: 5000,
+                env: { ...process.env, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || '') },
+            });
+            if (r.status === 0 && (r.stdout || '').toString().includes('3.')) return parts;
+        } catch (e) { /* next */ }
+    }
+    return null;
+}
+
+const pythonParts = findPython();
+if (!pythonParts) {
+    console.log('');
+    console.log('╔══════════════════════════════════════════════════════════╗');
+    console.log('║  ⚠  Python 3.11+ Required                              ║');
+    console.log('╚══════════════════════════════════════════════════════════╝');
+    console.log('');
+    console.log('  SuperLocalMemory V3 requires Python 3.11+');
+    console.log('  Install from: https://python.org/downloads/');
+    console.log('  After installing Python, run: slm setup');
+    console.log('');
+    process.exit(0); // Don't fail npm install
+}
+console.log('✓ Found Python: ' + pythonParts.join(' '));
+
+// --- Step 3: Install ALL Python dependencies ---
+console.log('\nInstalling Python dependencies (this may take 1-2 minutes)...\n');
+
+// Detect if --user or --break-system-packages is needed
+function pipInstall(packages, label) {
+    // Try normal install first
+    let result = spawnSync(pythonParts[0], [
+        ...pythonParts.slice(1), '-m', 'pip', 'install', '--quiet', '--disable-pip-version-check',
+        ...packages,
+    ], { stdio: 'pipe', timeout: 300000, env: { ...process.env, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || '') } });
+
+    if (result.status === 0) return true;
+
+    // If PEP 668 blocks it, try --user
+    const stderr = (result.stderr || '').toString();
+    if (stderr.includes('externally-managed') || stderr.includes('PEP 668')) {
+        result = spawnSync(pythonParts[0], [
+            ...pythonParts.slice(1), '-m', 'pip', 'install', '--quiet', '--disable-pip-version-check',
+            '--user', ...packages,
+        ], { stdio: 'pipe', timeout: 300000, env: { ...process.env, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || '') } });
+        if (result.status === 0) return true;
+
+        // Last resort: --break-system-packages
+        result = spawnSync(pythonParts[0], [
+            ...pythonParts.slice(1), '-m', 'pip', 'install', '--quiet', '--disable-pip-version-check',
+            '--break-system-packages', ...packages,
+        ], { stdio: 'pipe', timeout: 300000, env: { ...process.env, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || '') } });
+        return result.status === 0;
+    }
+
+    return false;
+}
+
+// Core dependencies (REQUIRED — product won't work without these)
+const coreDeps = [
+    'numpy>=1.26.0', 'scipy>=1.12.0', 'networkx>=3.0',
+    'httpx>=0.24.0', 'python-dateutil>=2.9.0',
+    'rank-bm25>=0.2.2', 'vaderSentiment>=3.3.2',
+];
+
+if (pipInstall(coreDeps, 'core')) {
+    console.log('✓ Core dependencies installed (math, search, NLP)');
+} else {
+    console.log('⚠ Core dependency installation failed.');
+    console.log('  Run manually: pip install ' + coreDeps.join(' '));
+}
+
+// Search dependencies (IMPORTANT — enables semantic search, 4-channel retrieval)
+const searchDeps = ['sentence-transformers>=2.5.0', 'geoopt>=0.5.0'];
+
+console.log('\nInstalling semantic search engine (downloads ~500MB on first use)...');
+if (pipInstall(searchDeps, 'search')) {
+    console.log('✓ Semantic search engine installed (sentence-transformers + Fisher-Rao)');
+} else {
+    console.log('⚠ Semantic search installation failed (BM25 keyword search still works).');
+    console.log('  For full 4-channel retrieval, run:');
+    console.log('  pip install sentence-transformers geoopt');
+}
+
+// --- Step 4: Detect V2 installation ---
+const V2_HOME = path.join(os.homedir(), '.claude-memory');
 if (fs.existsSync(V2_HOME) && fs.existsSync(path.join(V2_HOME, 'memory.db'))) {
     console.log('');
     console.log('╔══════════════════════════════════════════════════════════╗');
@@ -42,11 +137,9 @@ if (fs.existsSync(V2_HOME) && fs.existsSync(path.join(V2_HOME, 'memory.db'))) {
     console.log('  To migrate V2 data to V3, run:');
     console.log('    slm migrate');
     console.log('');
-    console.log('  Read the migration guide:');
-    console.log('    https://github.com/qualixar/superlocalmemory/wiki/Migration-from-V2');
-    console.log('');
 }
 
+// --- Done ---
 console.log('════════════════════════════════════════════════════════════');
 console.log('  ✓ SuperLocalMemory V3 installed successfully!');
 console.log('');
@@ -56,5 +149,10 @@ console.log('    slm status         # Check system status');
 console.log('    slm remember "..." # Store a memory');
 console.log('    slm recall "..."   # Search memories');
 console.log('');
-console.log('  Documentation: https://github.com/qualixar/superlocalmemory/wiki');
+console.log('  Prerequisites satisfied:');
+console.log('    ✓ Python 3.11+');
+console.log('    ✓ Core math & search libraries');
+console.log('    ✓ Data directory (~/.superlocalmemory/)');
+console.log('');
+console.log('  Docs: https://github.com/qualixar/superlocalmemory/wiki');
 console.log('════════════════════════════════════════════════════════════\n');

package/src/superlocalmemory/core/embeddings.py

@@ -56,6 +56,14 @@ class EmbeddingService:
         self._model: object | None = None
         self._lock = threading.Lock()
         self._loaded = False
+        self._available = True  # Set False if model can't load
+
+    @property
+    def is_available(self) -> bool:
+        """Check if embedding service has a usable model."""
+        if not self._loaded:
+            self._ensure_loaded()
+        return self._available and self._model is not None
 
     # ------------------------------------------------------------------
     # Public API
@@ -78,6 +86,9 @@ class EmbeddingService:
         """
         if not text or not text.strip():
             raise ValueError("Cannot embed empty text")
+        self._ensure_loaded()
+        if self._model is None:
+            return None
         vec = self._encode_single(text)
         self._validate_dimension(vec)
         return vec.tolist()
@@ -98,6 +109,9 @@ class EmbeddingService:
             if not t or not t.strip():
                 raise ValueError(f"Text at index {i} is empty")
 
+        self._ensure_loaded()
+        if self._model is None:
+            return [None] * len(texts)
         vectors = self._encode_batch(texts)
         for vec in vectors:
             self._validate_dimension(vec)
@@ -175,12 +189,16 @@ class EmbeddingService:
         try:
             from sentence_transformers import SentenceTransformer
         except ImportError:
-            raise ImportError(
-                "sentence-transformers required: "
-                "pip install sentence-transformers"
+            logger.warning(
+                "sentence-transformers not installed. Embeddings disabled. "
+                "Install with: pip install sentence-transformers"
             )
+            self._model = None
+            self._loaded = True
+            self._available = False
+            return
         model = SentenceTransformer(
-            self._config.model_name, trust_remote_code=False,
+            self._config.model_name, trust_remote_code=True,
         )
         actual_dim = model.get_sentence_embedding_dimension()
         if actual_dim != self._config.dimension:

package/src/superlocalmemory/core/engine.py

@@ -81,7 +81,12 @@ class MemoryEngine:
 
         self._db = DatabaseManager(self._config.db_path)
         self._db.initialize(schema)
-        self._embedder = EmbeddingService(self._config.embedding)
+        try:
+            emb = EmbeddingService(self._config.embedding)
+            self._embedder = emb if emb.is_available else None
+        except Exception as exc:
+            logger.warning("Embeddings unavailable (%s). BM25-only mode.", exc)
+            self._embedder = None
 
         if self._caps.llm_fact_extraction:
             self._llm = LLMBackbone(self._config.llm)

package/src/superlocalmemory/encoding/entropy_gate.py

@@ -68,24 +68,21 @@ class EntropyGate:
             logger.debug("Entropy gate: blocked (low-info pattern: '%s')", normalized)
             return False
 
-        # Stage 2: Similarity-based deduplication
-        if self._embedder is not None and self._recent_embeddings:
+        # Stage 2: Similarity-based deduplication (requires embeddings)
+        if self._embedder is not None:
             emb = self._embedder.embed(content)
-            for recent in self._recent_embeddings:
-                sim = _cosine(emb, recent)
-                if sim > self._threshold:
-                    logger.debug(
-                        "Entropy gate: blocked (near-duplicate, sim=%.3f)", sim
-                    )
-                    return False
-            # Add to window
-            self._recent_embeddings.append(emb)
-            if len(self._recent_embeddings) > self._window_size:
-                self._recent_embeddings.pop(0)
-        elif self._embedder is not None:
-            # First content — add to window, always pass
-            emb = self._embedder.embed(content)
-            self._recent_embeddings.append(emb)
+            if emb is not None:
+                if self._recent_embeddings:
+                    for recent in self._recent_embeddings:
+                        sim = _cosine(emb, recent)
+                        if sim > self._threshold:
+                            logger.debug(
+                                "Entropy gate: blocked (near-duplicate, sim=%.3f)", sim
+                            )
+                            return False
+                self._recent_embeddings.append(emb)
+                if len(self._recent_embeddings) > self._window_size:
+                    self._recent_embeddings.pop(0)
 
         return True
 

package/src/superlocalmemory/storage/v2_migrator.py

@@ -260,24 +260,77 @@ class V2Migrator:
             # Backfill V3 columns from V2 data
             conn.execute('UPDATE memories SET profile_id = COALESCE(profile, "default") WHERE profile_id IS NULL')
             conn.execute("UPDATE memories SET memory_id = 'v2_' || CAST(id AS TEXT) WHERE memory_id IS NULL")
+            # Create unique index on memory_id so V3 FKs work
+            try:
+                conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_memory_id ON memories (memory_id)")
+            except Exception:
+                pass
+            # Disable FK enforcement for migrated DBs (V2 schema is incompatible)
+            conn.execute("PRAGMA foreign_keys=OFF")
+
+            # Rename ALL tables with incompatible schemas (V2 + old alpha)
+            # User data is in 'memories' table (already upgraded above)
+            # Everything else is computed/derived and will be recreated by V3
+            all_existing = {r[0] for r in conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '_v2_bak_%'"
+            ).fetchall()}
+            # Keep only: memories (upgraded), profiles, schema_version, v3_config, sqlite_sequence
+            keep_tables = {"memories", "profiles", "schema_version", "v3_config", "sqlite_sequence"}
+            v2_conflicting = [t for t in all_existing if t not in keep_tables and not t.startswith("_")]
+            for table in v2_conflicting:
+                try:
+                    conn.execute(f'ALTER TABLE "{table}" RENAME TO "_v2_bak_{table}"')
+                except Exception:
+                    pass  # Table may not exist
+
             conn.commit()
 
-            for sql in V3_TABLES_SQL:
-                conn.execute(sql)
-            for sql in V3_INDEXES_SQL:
-                conn.execute(sql)
-            # Mark migration
-            conn.execute(
-                "INSERT OR REPLACE INTO v3_config (key, value, updated_at) VALUES (?, ?, ?)",
-                ("migration_date", datetime.now(UTC).isoformat(), datetime.now(UTC).isoformat()),
-            )
-            conn.execute(
-                "INSERT OR REPLACE INTO v3_config (key, value, updated_at) VALUES (?, ?, ?)",
-                ("migration_version", "3.0.0", datetime.now(UTC).isoformat()),
-            )
+            # Use the FULL V3 schema (not the partial V3_TABLES_SQL)
+            from superlocalmemory.storage import schema
+            schema.create_all_tables(conn)
             conn.commit()
+            # Mark migration in config table
+            try:
+                conn.execute(
+                    "INSERT OR REPLACE INTO config (key, value, updated_at) VALUES (?, ?, ?)",
+                    ("migration_date", datetime.now(UTC).isoformat(), datetime.now(UTC).isoformat()),
+                )
+                conn.execute(
+                    "INSERT OR REPLACE INTO config (key, value, updated_at) VALUES (?, ?, ?)",
+                    ("migration_version", "3.0.0", datetime.now(UTC).isoformat()),
+                )
+                conn.commit()
+            except Exception:
+                pass  # Schema handles this on engine init
+            # Step 4b: Convert V2 memories → V3 atomic_facts
+            try:
+                now = datetime.now(UTC).isoformat()
+                rows = conn.execute("SELECT memory_id, profile_id, content, created_at FROM memories").fetchall()
+                converted = 0
+                for row in rows:
+                    mid, pid, content, created = row[0], row[1], row[2], row[3]
+                    if not content or not content.strip():
+                        continue
+                    fid = f"v2_fact_{mid}"
+                    conn.execute(
+                        "INSERT OR IGNORE INTO atomic_facts "
+                        "(fact_id, memory_id, profile_id, content, fact_type, "
+                        " entities_json, canonical_entities_json, confidence, importance, "
+                        " evidence_count, access_count, source_turn_ids_json, session_id, "
+                        " lifecycle, emotional_valence, emotional_arousal, signal_type, created_at) "
+                        "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                        (fid, mid, pid or "default", content, "factual",
+                         "[]", "[]", 0.8, 0.5, 1, 0, "[]", "",
+                         "active", 0.0, 0.0, "factual", created or now),
+                    )
+                    converted += 1
+                conn.commit()
+                stats["steps"].append(f"Converted {converted} V2 memories to V3 facts")
+            except Exception as exc:
+                stats["steps"].append(f"V2 conversion partial: {exc}")
+
             conn.close()
-            stats["steps"].append(f"Extended schema ({len(V3_TABLES_SQL)} tables, {len(V3_INDEXES_SQL)} indexes)")
+            stats["steps"].append("Created V3 schema")
 
             # Step 5: Symlink (only if .claude-memory is not already a symlink)
             if not self._v2_base.is_symlink():