superlocalmemory 3.2.0 → 3.2.2

package/CHANGELOG.md

@@ -16,6 +16,40 @@ SuperLocalMemory V3 - Intelligent local memory system for AI coding assistants.
 
 ---
 
+## [3.2.2] - 2026-03-30
+
+### Added
+- Performance improvements for retrieval pipeline
+- New memory management capabilities with configurable lifecycle controls
+- Enhanced dashboard with 3 additional monitoring tabs
+- 9 new API endpoints for configuration and status
+- 5 new MCP tools for proactive memory operations
+- 5 new CLI commands for configuration management
+
+### Changed
+- Internal retrieval architecture optimized with additional search channel
+- Schema extensions for improved data management (9 new tables)
+- Memory surfacing engine with multi-signal scoring
+
+### Performance
+- Significant latency reduction in recall operations (vector-indexed retrieval)
+- Idle-time memory optimization for large stores
+- Reduced memory footprint for long-running sessions
+
+---
+
+## [3.2.1] - 2026-03-26
+
+### Fixed
+- **Windows `slm --version` / `slm -v`** — `.bat` and `.cmd` wrappers now intercept `--version`/`-v` directly (fast path, no Python needed) and set `PYTHONPATH` to the npm package's `src/` directory before launching Python. Previously, Windows users hitting `slm.bat` instead of the Node.js wrapper got `unrecognized arguments: --version` because Python resolved an older pip-installed version without the flag.
+- **Unix bash wrapper** (`bin/slm`) — now sets `PYTHONPATH` and intercepts `--version`/`-v`, matching the Node.js wrapper's behavior. Previously relied on npm's shim always routing to `slm-npm`.
+- **`postinstall.js`** — now runs `pip install .` to install the `superlocalmemory` Python package itself (not just dependencies). Prevents stale pip-installed versions from shadowing the npm-distributed source. Falls back to `--user` for PEP 668 environments.
+- **`preuninstall.js`** — corrected version string from "V2" to "V3".
+- **Windows Python detection** — added `py -3` (Python Launcher for Windows) as a fallback candidate in `slm.bat`.
+- **Environment parity** — all three entry points (`slm-npm`, `slm`, `slm.bat`) now set identical PyTorch memory-prevention env vars (`PYTORCH_MPS_HIGH_WATERMARK_RATIO`, `TORCH_DEVICE`, etc.).
+
+---
+
 ## [3.2.0] - 2026-03-26
 
 ### Added
@@ -347,7 +381,7 @@ We use [Semantic Versioning](https://semver.org/):
 - **MINOR:** New features (backward compatible, e.g., 2.0.0 → 2.1.0)
 - **PATCH:** Bug fixes (backward compatible, e.g., 2.1.0 → 2.1.1)
 
-**Current Version:** v2.8.0
+**Current Version:** v3.2.2
 **Website:** [superlocalmemory.com](https://superlocalmemory.com)
 **npm:** `npm install -g superlocalmemory`
 

package/README.md

@@ -2,7 +2,7 @@
   <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
 </p>
 
-<h1 align="center">SuperLocalMemory V3</h1>
+<h1 align="center">SuperLocalMemory V3.2</h1>
 <p align="center"><strong>The first local-only AI memory to break 74% retrieval on LoCoMo.<br/>No cloud. No APIs. No data leaves your machine.</strong></p>
 
 <p align="center">
@@ -47,6 +47,66 @@ Mathematical layers contribute **+12.7 percentage points** on average across 6 c
 
 ---
 
+## What's New in V3.2 — The Living Brain
+
+> Your AI agent now remembers the way humans do: associatively, temporally, and with consolidation during idle time. V3.2 transforms SLM from a retrieval engine into a living memory system that surfaces what you need before you ask for it.
+
+### Headline Features
+
+**100x Faster Recall** — Retrieval latency drops from ~500ms to <10ms at 10K facts. Vector KNN search replaces full-table scan. You feel the difference on the first query.
+
+**Automatic Memory Surfacing** — Memories now come to you. A multi-signal scoring engine (similarity + recency + frequency + trust) proactively injects relevant context at session start and during conversations. No more "I forgot we decided that last week."
+
+**Associative Retrieval (5th Channel)** — V3 had 4 retrieval channels. V3.2 adds a 5th: multi-hop spreading activation across your knowledge graph. Ask about "deployment" and it surfaces the related database migration decision three hops away.
+
+**Temporal Intelligence** — Facts now carry time-awareness. Bi-temporal validity tracks when something was true vs. when it was recorded. Contradictions are detected automatically: "We use Postgres" + "We migrated to MySQL" triggers a conflict resolution flow.
+
+**Sleep-Time Consolidation** — During idle periods, SLM compresses, deduplicates, and reorganizes your memory store. Redundant facts merge. Clusters tighten. Important memories get promoted to Core Memory blocks that stay permanently in context (inspired by Letta's core memory, but fully local).
+
+**Core Memory Blocks** — Pin your most critical context (architecture decisions, team conventions, project constraints) into always-available working memory. These blocks are injected into every session automatically — your agent never starts cold.
+
+### By the Numbers
+
+| Metric | V3.0 | V3.2 | Change |
+|:-------|:----:|:----:|:------:|
+| Recall latency (10K facts) | ~500ms | <10ms | **100x faster** |
+| Retrieval channels | 4 | 5 | +spreading activation |
+| MCP tools | 24 | 29 | +5 new |
+| CLI commands | 16 | 21 | +5 new |
+| Dashboard tabs | 17 | 20 | +3 new |
+| API endpoints | — | 9 new | configuration & status |
+| DB tables | 9 | 18 | +9 for temporal, consolidation, core memory |
+
+### Enable V3.2 Features
+
+All new features default OFF. Zero breaking changes. Opt in when ready:
+
+```bash
+# Turn on automatic memory surfacing
+slm config set auto_invoke.enabled true
+
+# Turn on sleep-time consolidation
+slm config set consolidation.enabled true
+
+# Turn on temporal intelligence
+slm config set temporal.enabled true
+
+# Turn on associative retrieval (5th channel)
+slm config set retrieval.synapse.enabled true
+```
+
+Or enable everything at once:
+
+```bash
+slm config set v32_features.all true
+```
+
+**Fully backward compatible.** All 29 MCP tools, 21 CLI commands work the same. Existing data untouched. New features activate only when you flip the switch.
+
+> **V3.2 Paper** — Technical details, formal guarantees, and benchmark results in the upcoming companion paper. Watch the [arXiv page](https://arxiv.org/abs/2603.14588) for updates.
+
+---
+
 ## Quick Start
 
 ### Install via npm (recommended)

package/bin/slm

@@ -2,6 +2,19 @@
 # SuperLocalMemory V3 CLI
 # Part of Qualixar | https://superlocalmemory.com
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG_ROOT="$(dirname "$SCRIPT_DIR")"
+SRC_DIR="$PKG_ROOT/src"
+
+# Handle --version / -v directly (fast path)
+for arg in "$@"; do
+    if [ "$arg" = "--version" ] || [ "$arg" = "-v" ]; then
+        VER=$(grep '"version"' "$PKG_ROOT/package.json" 2>/dev/null | head -1 | sed 's/.*"\([0-9][0-9.]*\)".*/\1/')
+        echo "superlocalmemory ${VER:-unknown}"
+        exit 0
+    fi
+done
+
 # Find Python
 PYTHON=""
 for cmd in python3 python; do
@@ -12,9 +25,24 @@ for cmd in python3 python; do
 done
 
 if [ -z "$PYTHON" ]; then
-    echo "Error: Python 3 not found. Install Python 3.10+ from python.org"
+    echo "Error: Python 3 not found. Install Python 3.11+ from python.org"
     exit 1
 fi
 
+# Set PYTHONPATH so Python finds the npm package's src/ directory
+if [ -n "$PYTHONPATH" ]; then
+    export PYTHONPATH="$SRC_DIR:$PYTHONPATH"
+else
+    export PYTHONPATH="$SRC_DIR"
+fi
+
+# Prevent PyTorch Metal/MPS GPU memory reservation
+export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0
+export PYTORCH_MPS_MEM_LIMIT=0
+export PYTORCH_ENABLE_MPS_FALLBACK=1
+export TOKENIZERS_PARALLELISM=false
+export TORCH_DEVICE=cpu
+export CUDA_VISIBLE_DEVICES=""
+
 # Run V3 CLI
 exec "$PYTHON" -m superlocalmemory.cli.main "$@"

package/bin/slm.bat

@@ -6,22 +6,60 @@ REM Repository: https://github.com/qualixar/superlocalmemory
 
 setlocal enabledelayedexpansion
 
+REM Resolve the package src/ directory for PYTHONPATH
+set "SLM_PKG_DIR=%~dp0..\src"
+
+REM Handle --version / -v directly (fast path, no Python needed)
+if "%~1"=="--version" goto :show_version
+if "%~1"=="-v" goto :show_version
+
 REM Find Python 3
-where python3 >/dev/null 2>&1
+where python3 >nul 2>&1
 if %ERRORLEVEL% EQU 0 (
     set PYTHON_CMD=python3
     goto :run
 )
-where python >/dev/null 2>&1
+where python >nul 2>&1
 if %ERRORLEVEL% EQU 0 (
     set PYTHON_CMD=python
     goto :run
 )
+where py >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    set PYTHON_CMD=py -3
+    goto :run
+)
 
 echo Error: Python 3.11+ not found.
 echo Install from: https://python.org/downloads/
 exit /b 1
 
+:show_version
+REM Read version from package.json via findstr
+for /f "tokens=2 delims=:," %%a in ('findstr /C:"\"version\"" "%~dp0..\package.json"') do (
+    set "VER=%%~a"
+    set "VER=!VER: =!"
+    echo superlocalmemory !VER!
+    exit /b 0
+)
+echo superlocalmemory unknown
+exit /b 0
+
 :run
+REM Set PYTHONPATH so Python finds the npm package's src/ directory
+if defined PYTHONPATH (
+    set "PYTHONPATH=%SLM_PKG_DIR%;%PYTHONPATH%"
+) else (
+    set "PYTHONPATH=%SLM_PKG_DIR%"
+)
+
+REM Prevent PyTorch Metal/MPS GPU memory reservation
+set "PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0"
+set "PYTORCH_MPS_MEM_LIMIT=0"
+set "PYTORCH_ENABLE_MPS_FALLBACK=1"
+set "TOKENIZERS_PARALLELISM=false"
+set "TORCH_DEVICE=cpu"
+set "CUDA_VISIBLE_DEVICES="
+
 %PYTHON_CMD% -m superlocalmemory.cli.main %*
 exit /b %ERRORLEVEL%

package/bin/slm.cmd

@@ -1,5 +1,5 @@
 @echo off
 REM SuperLocalMemory V3 - Windows CLI (CMD variant)
-REM Calls slm.bat for compatibility
+REM Delegates to slm.bat which handles PYTHONPATH and --version
 call "%~dp0slm.bat" %*
 exit /b %ERRORLEVEL%

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "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/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.2.0"
+version = "3.2.2"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}
@@ -78,6 +78,31 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+
+[tool.coverage.run]
+source = ["superlocalmemory"]
+omit = [
+    "*/tests/*",
+    "*/ui/*",
+    "*/cli/*",
+    "*/__main__.py",
+]
+
+[tool.coverage.report]
+fail_under = 0
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ ==",
+    "@overload",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
 
 [tool.ruff]
 target-version = "py311"

package/scripts/postinstall.js

@@ -157,6 +157,39 @@ if (pipInstall(perfDeps, 'performance')) {
     console.log('⚠ Performance deps skipped (system works fine without them).');
 }
 
+// --- Step 3b: Install the superlocalmemory package itself ---
+// This ensures `python -m superlocalmemory.cli.main` always resolves the
+// correct version, even when invoked outside the Node.js wrapper (e.g.,
+// via slm.bat on Windows or direct Python invocation).
+console.log('\nInstalling superlocalmemory Python package...');
+const pkgRoot = path.join(__dirname, '..');
+const pipInstallPkg = spawnSync(pythonParts[0], [
+    ...pythonParts.slice(1), '-m', 'pip', 'install', '--quiet', '--disable-pip-version-check',
+    pkgRoot,
+], { stdio: 'pipe', timeout: 300000, env: { ...process.env, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || '') } });
+
+if (pipInstallPkg.status === 0) {
+    console.log('✓ SuperLocalMemory Python package installed');
+} else {
+    // Try with --user if PEP 668
+    const stderr = (pipInstallPkg.stderr || '').toString();
+    if (stderr.includes('externally-managed') || stderr.includes('PEP 668')) {
+        const retryResult = spawnSync(pythonParts[0], [
+            ...pythonParts.slice(1), '-m', 'pip', 'install', '--quiet', '--disable-pip-version-check',
+            '--user', pkgRoot,
+        ], { stdio: 'pipe', timeout: 300000, env: { ...process.env, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:' + (process.env.PATH || '') } });
+        if (retryResult.status === 0) {
+            console.log('✓ SuperLocalMemory Python package installed (--user)');
+        } else {
+            console.log('⚠ Could not pip install the package. The Node.js wrapper (slm-npm)');
+            console.log('  sets PYTHONPATH automatically, so CLI will still work.');
+        }
+    } else {
+        console.log('⚠ Could not pip install the package. The Node.js wrapper (slm-npm)');
+        console.log('  sets PYTHONPATH automatically, so CLI will still work.');
+    }
+}
+
 // --- 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'))) {

package/scripts/preuninstall.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * SuperLocalMemory V2 - NPM Preuninstall Script
+ * SuperLocalMemory V3 - NPM Preuninstall Script
  *
  * Copyright (c) 2026 Varun Pratap Bhardwaj
  * Solution Architect & Original Creator
@@ -16,7 +16,7 @@ const os = require('os');
 const fs = require('fs');
 
 console.log('\n════════════════════════════════════════════════════════════');
-console.log('  SuperLocalMemory V2 - Uninstalling');
+console.log('  SuperLocalMemory V3 - Uninstalling');
 console.log('════════════════════════════════════════════════════════════\n');
 
 const SLM_DIR = path.join(os.homedir(), '.superlocalmemory');

package/src/superlocalmemory/attribution/signer.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import hashlib
 import hmac
 import os
+import sys
 from datetime import datetime, timezone
 from typing import Dict
 
@@ -35,7 +36,11 @@ def _get_or_create_key() -> str:
         os.makedirs(os.path.dirname(key_path), exist_ok=True)
         with open(key_path, "w") as f:
             f.write(key)
-        os.chmod(key_path, 0o600)
+        # On POSIX, restrict the key file to owner-only read/write.
+        # On Windows, os.chmod only supports setting the read-only flag
+        # and cannot enforce Unix-style permissions, so we skip it.
+        if sys.platform != "win32":
+            os.chmod(key_path, 0o600)
         return key
 
 _DEFAULT_KEY: str = _get_or_create_key()

package/src/superlocalmemory/core/config.py

@@ -84,13 +84,14 @@ class LLMConfig:
 
 @dataclass
 class ChannelWeights:
-    """Retrieval channel weights — 4 channels, query-adaptive."""
+    """Retrieval channel weights — 5 channels, query-adaptive."""
 
     # Entity-linked facts are high-precision matches that rank above BM25.
     semantic: float = 1.2
     bm25: float = 1.0
     entity_graph: float = 1.3
     temporal: float = 1.0
+    spreading_activation: float = 1.0  # Phase 3: 5th channel (BC-08: default value)
 
     def as_dict(self) -> dict[str, float]:
         return {
@@ -98,6 +99,7 @@ class ChannelWeights:
             "bm25": self.bm25,
             "entity_graph": self.entity_graph,
             "temporal": self.temporal,
+            "spreading_activation": self.spreading_activation,
         }
 
 
@@ -207,6 +209,109 @@ class MathConfig:
     # Rate-Distortion (production only, disabled for benchmarks)
 
 
+# ---------------------------------------------------------------------------
+# Master Config
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ConsolidationConfig:
+    """Configuration for sleep-time consolidation (Phase 5).
+
+    Feature-flagged: starts enabled=False (Rule 12).
+    """
+
+    enabled: bool = False                   # Feature flag (Rule 12)
+    step_count_trigger: int = 50            # Lightweight consolidation every N stores (L7)
+    session_trigger: bool = True            # Run on session end
+    idle_timeout_seconds: int = 300         # 5 min inactivity
+    scheduled_sessions: int = 5             # Full consolidation every N sessions
+    core_memory_char_limit: int = 2000      # Total chars across all blocks
+    block_char_limit: int = 500             # Per-block character limit
+    compression_similarity: float = 0.85    # Dedup threshold for compression
+    promotion_min_access: int = 3           # Min access count for promotion
+    promotion_min_trust: float = 0.5        # Min trust for promotion
+    decay_days_threshold: int = 30          # Edge decay after N days
+
+
+@dataclass(frozen=True)
+class TemporalValidatorConfig:
+    """Configuration for temporal intelligence (Phase 4).
+
+    Feature-flagged: starts enabled=False (Rule 12).
+    """
+
+    enabled: bool = False
+    mode: str = "a"                              # "a" (sheaf), "b"/"c" (LLM)
+
+    # Sheaf contradiction threshold
+    contradiction_threshold: float = 0.45        # Mode A threshold (768d)
+
+    # LLM pre-filter threshold (lower to catch more candidates)
+    llm_prefilter_threshold: float = 0.30
+
+    # Max LLM checks per new fact (cost control)
+    max_llm_checks: int = 5
+
+    # Trust penalty for expired facts
+    expiration_trust_penalty: float = -0.2
+
+    # Include expired facts in historical queries
+    include_expired_in_history: bool = True
+
+
+@dataclass(frozen=True)
+class AutoInvokeConfig:
+    """Configuration for the Auto-Invoke Engine (Phase 2).
+
+    Feature-flagged: starts enabled=False, graduated to default on
+    after MRR validation passes (Rule 12).
+
+    References:
+      - SYNAPSE: FOK gating (fok_threshold = 0.12)
+      - ACT-R: base-level activation (act_r_decay = 0.5)
+      - Zep/Hindsight: multi-signal ranking consensus
+    """
+
+    enabled: bool = False                      # Feature flag (Rule 12)
+    profile_id: str = "default"
+
+    # Scoring weights (4-signal default) -- must sum to 1.0
+    weights: dict = field(default_factory=lambda: {
+        "similarity": 0.40,
+        "recency": 0.25,
+        "frequency": 0.20,
+        "trust": 0.15,
+    })
+
+    # ACT-R mode (3-signal alternative) -- must sum to 1.0
+    use_act_r: bool = False
+    act_r_weights: dict = field(default_factory=lambda: {
+        "similarity": 0.40,
+        "base_level": 0.35,
+        "trust": 0.25,
+    })
+    act_r_decay: float = 0.5                   # Power-law decay exponent
+
+    # FOK gating (Feeling-of-Knowing)
+    fok_threshold: float = 0.12                # SYNAPSE minimum score gate
+
+    # Retrieval limits
+    max_memories_injected: int = 10
+    candidate_multiplier: int = 3              # candidates = limit * multiplier
+
+    # Mode A degradation weights -- must sum to 1.0
+    mode_a_weights: dict = field(default_factory=lambda: {
+        "similarity": 0.00,
+        "recency": 0.40,
+        "frequency": 0.35,
+        "trust": 0.25,
+    })
+
+    # Behavioral
+    include_archived: bool = False
+    relevance_threshold: float = 0.3           # Legacy compat with AutoRecall
+
+
 # ---------------------------------------------------------------------------
 # Master Config
 # ---------------------------------------------------------------------------
@@ -229,6 +334,13 @@ class SLMConfig:
     encoding: EncodingConfig = field(default_factory=EncodingConfig)
     retrieval: RetrievalConfig = field(default_factory=RetrievalConfig)
     math: MathConfig = field(default_factory=MathConfig)
+    temporal_validator: TemporalValidatorConfig = field(
+        default_factory=TemporalValidatorConfig,
+    )
+    auto_invoke: AutoInvokeConfig = field(default_factory=AutoInvokeConfig)
+    consolidation: ConsolidationConfig = field(
+        default_factory=ConsolidationConfig,
+    )
 
     def __post_init__(self) -> None:
         if self.db_path is None:
@@ -395,6 +507,7 @@ class SLMConfig:
                 bm25=1.2,
                 entity_graph=1.3,
                 temporal=1.0,
+                spreading_activation=1.2,  # Phase 3: SA boost in Mode C
             ),
             retrieval=RetrievalConfig(
                 use_cross_encoder=True,