superlocalmemory 3.4.17 → 3.4.19

package/CHANGELOG.md

@@ -10,6 +10,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.4.19] - 2026-04-17
+
+### Fixed
+- Recall cold-start eliminated. Embedding + reranker workers stay warm for 30 minutes by default instead of 2 minutes, so bursts of recalls no longer pay a 30-60 second model-load tax on every other query.
+
+### New environment variables
+- `SLM_EMBED_IDLE_TIMEOUT` — seconds to keep the embedding worker warm (default 1800). Set to 120 to restore pre-v3.4.19 behavior.
+- `SLM_RERANKER_IDLE_TIMEOUT` — same, for the cross-encoder reranker (default 1800).
+
+---
+
+## [3.4.18] - 2026-04-17
+
+### Fixed
+- pip and npm installs now ship identical functionality. Semantic search and cross-encoder reranking work out of the box on pip (previously required `pip install superlocalmemory[search]`).
+- First pip run auto-installs Claude Code hooks when Claude Code is detected, matching the npm postinstall experience.
+
+---
+
 ## [3.4.17] - 2026-04-17
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.17",
+  "version": "3.4.19",
   "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",
@@ -65,8 +65,6 @@
     "src/",
     "ide/",
     "scripts/",
-    "ui/",
-    "docs/",
     "pyproject.toml",
     "README.md",
     "LICENSE",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.4.17"
+version = "3.4.19"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}
@@ -52,9 +52,18 @@ dependencies = [
     # V3.4.3: Unified Brain
     "psutil>=5.9.0",
     "structlog>=24.0.0,<27.0.0",
+    # V3.4.18: Semantic search + cross-encoder reranker (npm install parity).
+    # Previously under [search] extra — pip users silently lost 30pp of recall
+    # quality vs. npm users. Now ships by default for both install paths.
+    "sentence-transformers[onnx]>=5.0.0",
+    "torch>=2.2.0",
+    "scikit-learn>=1.3.0,<2.0.0",
 ]
 
 [project.optional-dependencies]
+# `search` is now a no-op alias kept for backwards compatibility; the deps
+# moved into core in v3.4.18. ``pip install superlocalmemory[search]`` still
+# works but installs nothing extra.
 search = [
     "sentence-transformers[onnx]>=5.0.0",
     "einops>=0.8.2",

package/src/superlocalmemory/cli/setup_wizard.py

@@ -621,6 +621,10 @@ def check_first_use(command: str) -> None:
 
     Called from main.py before dispatching any command.
     Skips for commands that don't need setup (setup, hook, --version, --help).
+
+    On first use, also auto-installs Claude Code hooks so pip installs have
+    the same "it just works" experience as npm installs (npm does this via
+    postinstall; pip has no postinstall, so we do it here).
     """
     # Commands that work without setup
     _SKIP_COMMANDS = {"setup", "init", "hook", "hooks", "reap", "mcp"}
@@ -641,6 +645,7 @@ def check_first_use(command: str) -> None:
             _mark_complete()
         except Exception:
             pass
+        _maybe_install_hooks_on_first_use()
         return
 
     # Interactive: run the full wizard
@@ -648,6 +653,31 @@ def check_first_use(command: str) -> None:
     print("  First time using SuperLocalMemory!")
     print("  Running setup wizard...\n")
     run_wizard()
+    _maybe_install_hooks_on_first_use()
+
+
+def _maybe_install_hooks_on_first_use() -> None:
+    """Install Claude Code hooks on first SLM run — matches npm postinstall.
+
+    Install/uninstall parity rules:
+      * Skip if the user explicitly opted out via ``slm hooks remove``
+        (creates ``~/.superlocalmemory/hooks/.hooks-disabled``).
+      * Skip if Claude Code isn't installed (no ``~/.claude/settings.json``
+        to merge into).
+      * Silent + best-effort: never fail a CLI command because of this.
+    """
+    try:
+        opt_out = _SLM_HOME / "hooks" / ".hooks-disabled"
+        if opt_out.exists():
+            return
+        claude_settings = Path.home() / ".claude" / "settings.json"
+        if not claude_settings.exists():
+            return  # Claude Code not installed — nothing to hook into.
+        from superlocalmemory.hooks.claude_code_hooks import install_hooks
+        install_hooks()
+    except Exception:
+        # Best-effort: parity-fallback, never block CLI.
+        pass
 
 
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/core/embeddings.py

@@ -140,8 +140,14 @@ def release_embedding_lock() -> None:
         _embedding_lock_fd = None
 
 
-_IDLE_TIMEOUT_SECONDS = 120  # 2 minutes — kill worker after idle
-# V3.3.12: Configurable via SLM_EMBED_IDLE_TIMEOUT env var (seconds)
+_IDLE_TIMEOUT_SECONDS = 1800  # 30 minutes — keep model warm across bursty use.
+# V3.3.12: Configurable via SLM_EMBED_IDLE_TIMEOUT env var (seconds).
+# V3.4.19: Bumped from 120 → 1800 to eliminate the 30-60s cold-start pain
+# when the embedding worker was killed too aggressively. Safety: the
+# per-embed RSS self-check (SLM_EMBED_WORKER_RSS_LIMIT_MB, 4GB default) and
+# the daemon memory watchdog (unified_daemon.py, 4GB/60s) still cap any
+# runaway. To restore the old aggressive policy without redeploying, set
+# ``SLM_EMBED_IDLE_TIMEOUT=120`` and ``slm restart``.
 _IDLE_TIMEOUT_SECONDS = int(os.environ.get("SLM_EMBED_IDLE_TIMEOUT", _IDLE_TIMEOUT_SECONDS))
 # V3.3.21: Configurable response timeout — 180s default, but batch ingestion
 # (2-turn chunks across 10 conversations) needs 600s+ to survive cold-start

package/src/superlocalmemory/retrieval/reranker.py

@@ -51,8 +51,10 @@ _live_rerankers: set[weakref.ref] = set()
 
 logger = logging.getLogger(__name__)
 
-_IDLE_TIMEOUT_SECONDS = 120  # 2 min → kill worker
-# V3.3.12: Configurable via SLM_RERANKER_IDLE_TIMEOUT env var
+_IDLE_TIMEOUT_SECONDS = 1800  # 30 min — keep cross-encoder warm for active sessions.
+# V3.3.12: Configurable via SLM_RERANKER_IDLE_TIMEOUT env var.
+# V3.4.19: Bumped from 120 → 1800 in lock-step with the embedding worker.
+# Set ``SLM_RERANKER_IDLE_TIMEOUT=120`` + ``slm restart`` to revert.
 _IDLE_TIMEOUT_SECONDS = int(os.environ.get("SLM_RERANKER_IDLE_TIMEOUT", _IDLE_TIMEOUT_SECONDS))
 _SUBPROCESS_RESPONSE_TIMEOUT = 180  # V3.3.12: 180s (was 120s) for stressed system respawns
 _WORKER_RECYCLE_AFTER = 500  # Recycle after N requests

package/src/superlocalmemory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.4.17
+Version: 3.4.19
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later
@@ -48,6 +48,9 @@ Requires-Dist: rustworkx<1,>=0.15
 Requires-Dist: watchdog<6,>=4.0
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: structlog<27.0.0,>=24.0.0
+Requires-Dist: sentence-transformers[onnx]>=5.0.0
+Requires-Dist: torch>=2.2.0
+Requires-Dist: scikit-learn<2.0.0,>=1.3.0
 Provides-Extra: search
 Requires-Dist: sentence-transformers[onnx]>=5.0.0; extra == "search"
 Requires-Dist: einops>=0.8.2; extra == "search"

package/src/superlocalmemory.egg-info/requires.txt

@@ -19,6 +19,9 @@ rustworkx<1,>=0.15
 watchdog<6,>=4.0
 psutil>=5.9.0
 structlog<27.0.0,>=24.0.0
+sentence-transformers[onnx]>=5.0.0
+torch>=2.2.0
+scikit-learn<2.0.0,>=1.3.0
 
 [dev]
 pytest>=8.0

package/docs/ARCHITECTURE.md

@@ -1,149 +0,0 @@
-# Architecture
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-A high-level overview of how SuperLocalMemory V3 stores, organizes, and retrieves your memories.
-
----
-
-## Design Principles
-
-1. **Local-first.** Your data stays on your machine by default. Cloud is opt-in.
-2. **Zero-configuration.** Install and forget. Memory capture and recall happen automatically.
-3. **Multi-channel retrieval.** No single search method is best for every query. V3 combines four channels and picks the best results.
-4. **Mathematically grounded.** Retrieval quality, consistency, and lifecycle management are backed by information geometry rather than heuristics.
-
-## System Overview
-
-```
-Your IDE (Claude, Cursor, VS Code, ...)
-       |
-       | MCP Protocol
-       v
-+------------------+
-| MCP Server       |  24 tools, 6 resources
-+------------------+
-       |
-       v
-+------------------+
-| Memory Engine    |  Ingestion + Retrieval + Lifecycle
-+------------------+
-       |
-       v
-+------------------+
-| SQLite Database  |  ~/.superlocalmemory/memory.db
-+------------------+
-```
-
-## How Memories Are Stored (Ingestion)
-
-When you store a memory (or one is auto-captured), it passes through an 11-step pipeline:
-
-| Step | What it does |
-|------|-------------|
-| 1. Metadata extraction | Timestamps, session context, source identification |
-| 2. Entity extraction | People, projects, technologies, organizations mentioned |
-| 3. Fact extraction | Discrete facts pulled from the text |
-| 4. Emotion detection | Sentiment and emotional tone (frustration, confidence, etc.) |
-| 5. Belief extraction | Opinions, preferences, and stated beliefs |
-| 6. Entity resolution | Links mentions to canonical entities (e.g., "React" and "ReactJS" become one) |
-| 7. Graph wiring | Connects entities and facts into a relationship graph |
-| 8. Foresight tagging | Predicts what future queries this memory might answer |
-| 9. Observation building | Creates structured observations for pattern learning |
-| 10. Entropy gating | Filters out redundant or low-value information |
-| 11. Storage | Writes to all indexes: semantic vectors, BM25 tokens, graph edges, temporal events |
-
-In Mode A, all steps run locally without any LLM calls. In Modes B and C, the LLM enhances entity extraction and fact decomposition.
-
-## How Memories Are Retrieved (Recall)
-
-Every recall query runs through four independent retrieval channels, then fuses the results:
-
-### The Four Channels
-
-| Channel | How it works | Best for |
-|---------|-------------|----------|
-| **Semantic** | Vector similarity using sentence embeddings, enhanced by Fisher-Rao geometry | "Queries that mean the same thing but use different words" |
-| **BM25** | Classic keyword matching with term frequency scoring | "Queries with specific names, codes, or exact terms" |
-| **Entity Graph** | Traverses the relationship graph via spreading activation | "Who works with Maria?" or "What connects service A to service B?" |
-| **Temporal** | Matches based on time references and event ordering | "What did we decide last Friday?" or "Changes since the sprint started" |
-
-### Fusion and Ranking
-
-1. Each channel returns its top candidates with scores
-2. **Reciprocal Rank Fusion** (RRF) combines the four ranked lists into one
-3. In Mode C, a **cross-encoder** reranks the top results for final precision
-4. The top results are returned to your AI assistant
-
-This multi-channel approach means V3 finds memories that any single search method would miss. A keyword search alone might miss paraphrased content. A vector search alone might miss exact names. The combination catches both.
-
-## Three Operating Modes
-
-| Mode | Retrieval | LLM Usage | Data Location |
-|------|-----------|-----------|---------------|
-| **A: Zero-Cloud** | 4-channel + math scoring | None | 100% local |
-| **B: Local LLM** | 4-channel + local LLM reranking | Ollama (local) | 100% local |
-| **C: Cloud LLM** | 4-channel + cross-encoder + agentic retrieval | Cloud provider | Queries sent to cloud |
-
-Mode A is the default. It delivers strong recall quality using mathematical scoring without any network calls.
-
-## Mathematical Foundations
-
-V3 uses three mathematical layers. These are not academic additions — they solve specific practical problems.
-
-### Fisher-Rao Similarity
-
-**Problem:** Standard vector similarity treats all memories equally, regardless of how much evidence backs them.
-
-**Solution:** Fisher-Rao geometry accounts for the statistical confidence of each memory's embedding. A memory accessed and confirmed many times gets a tighter confidence region. A memory stored once and never validated has wider uncertainty. Similarity scoring respects this difference.
-
-**Effect:** Frequently validated memories rank higher. Uncertain memories are flagged for verification.
-
-### Sheaf Consistency
-
-**Problem:** Over time, you store contradictory memories. "We use PostgreSQL" and later "We migrated to MySQL." Simple retrieval returns both without flagging the conflict.
-
-**Solution:** Sheaf cohomology detects when memories attached to the same entity or topic contradict each other. When a contradiction is found, the system marks the older memory as superseded and surfaces the newer one.
-
-**Effect:** Recall returns consistent information. Contradictions are flagged for your review.
-
-### Langevin Lifecycle
-
-**Problem:** Memory databases grow endlessly. Old memories dilute retrieval quality.
-
-**Solution:** Langevin dynamics models each memory's lifecycle — from Active (frequently accessed) through Warm, Cold, and eventually Archived. The transition is not based on simple time rules but on a self-organizing dynamic that balances recency, access frequency, and information value.
-
-**Effect:** Active memories stay prominent. Stale memories fade gracefully. Storage stays efficient.
-
-## EU AI Act Compliance
-
-Mode A satisfies data sovereignty requirements under the EU AI Act by design:
-
-- **No cloud dependency.** All memory operations run locally. No data leaves your machine.
-- **Right to erasure.** `slm forget` deletes data locally. No cloud logs to purge.
-- **Transparency.** The retrieval pipeline is auditable. No black-box LLM decisions in Mode A.
-- **Risk classification.** A local retrieval system with no AI decision-making qualifies as minimal risk.
-
-Mode C sends queries to a cloud LLM provider. In that mode, the cloud provider's compliance posture applies to those queries.
-
-## Database
-
-All data is stored in a single SQLite database:
-
-```
-~/.superlocalmemory/memory.db
-```
-
-The database uses WAL (Write-Ahead Logging) mode for safe concurrent access from multiple IDE connections.
-
-Key table groups:
-
-- **Core:** memories, sessions, profiles
-- **Knowledge:** semantic_facts, kg_nodes, memory_edges, canonical_entities
-- **Retrieval indexes:** bm25_tokens, memory_metadata, temporal_events
-- **Math layers:** fisher_state, sheaf_sections, langevin_state
-- **Compliance:** trust_scores, provenance, audit_trail, retention_policies
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

package/docs/api-reference.md

@@ -1,284 +0,0 @@
-# API Reference
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-Use SuperLocalMemory programmatically from Python. This is for developers building integrations, custom workflows, or framework adapters.
-
----
-
-## Installation
-
-```bash
-npm install -g superlocalmemory
-```
-
-Or, if you installed via npm, the Python package is available at:
-
-```python
-import sys
-sys.path.insert(0, "/path/to/superlocalmemory/python")
-```
-
-## Quick Start
-
-```python
-from superlocalmemory.core.engine import MemoryEngine
-from superlocalmemory.core.config import SLMConfig
-
-# Initialize with default config (Mode A, default profile)
-config = SLMConfig()
-engine = MemoryEngine(config)
-
-# Store a memory
-engine.store("The API uses OAuth 2.0 with PKCE for mobile clients")
-
-# Recall memories
-results = engine.recall("authentication method for mobile")
-for result in results:
-    print(f"[{result.score:.2f}] {result.content}")
-
-# Clean up
-engine.close()
-```
-
-## Configuration
-
-### SLMConfig
-
-```python
-from superlocalmemory.core.config import SLMConfig
-
-# Default configuration
-config = SLMConfig()
-
-# Custom configuration
-config = SLMConfig(
-    mode="a",                      # "a", "b", or "c"
-    profile="work",                # Active profile name
-    data_dir="~/.superlocalmemory",  # Database location
-    embedding_model="all-MiniLM-L6-v2",
-    max_results=10,
-)
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `mode` | str | `"a"` | Operating mode |
-| `profile` | str | `"default"` | Active profile |
-| `data_dir` | str | `"~/.superlocalmemory"` | Data directory |
-| `embedding_model` | str | `"all-MiniLM-L6-v2"` | Sentence transformer model |
-| `max_results` | int | `10` | Default max results for recall |
-
-## Core Operations
-
-### Store
-
-```python
-# Basic store
-memory_id = engine.store("React 19 uses the new compiler by default")
-
-# Store with tags
-memory_id = engine.store(
-    "Deploy to staging before 2pm on Fridays",
-    tags=["process", "deployment"]
-)
-
-# Store with metadata
-memory_id = engine.store(
-    "Maria approved the new database schema",
-    metadata={"source": "slack", "channel": "#backend"}
-)
-```
-
-**Returns:** `int` — the ID of the stored memory.
-
-### Recall
-
-```python
-# Basic recall
-results = engine.recall("database schema approval")
-
-# With limit
-results = engine.recall("deployment schedule", limit=5)
-```
-
-**Returns:** `list[RecallResult]`
-
-Each `RecallResult` has:
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `id` | int | Memory ID |
-| `content` | str | Memory text |
-| `score` | float | Relevance score (0.0 to 1.0) |
-| `timestamp` | datetime | When the memory was stored |
-| `tags` | list[str] | Tags attached to the memory |
-| `metadata` | dict | Additional metadata |
-
-### Recall with Trace
-
-```python
-# Get channel-by-channel breakdown
-results = engine.recall_trace("who approved the schema")
-
-for result in results:
-    print(f"[{result.score:.2f}] {result.content}")
-    print(f"  Semantic: {result.trace.semantic:.2f}")
-    print(f"  BM25:     {result.trace.bm25:.2f}")
-    print(f"  Entity:   {result.trace.entity:.2f}")
-    print(f"  Temporal:  {result.trace.temporal:.2f}")
-```
-
-### Delete
-
-```python
-# Delete by ID
-engine.delete(memory_id=42)
-
-# Delete by query (deletes best match)
-engine.delete(query="old staging credentials")
-```
-
-### List Recent
-
-```python
-memories = engine.list_recent(limit=20)
-for m in memories:
-    print(f"[{m.id}] {m.content[:80]}...")
-```
-
-## Profile Management
-
-```python
-# List profiles
-profiles = engine.list_profiles()
-
-# Switch profile
-engine.switch_profile("client-acme")
-
-# Create profile
-engine.create_profile("new-project")
-
-# Delete profile
-engine.delete_profile("old-project")
-```
-
-## Health and Diagnostics
-
-```python
-# System status
-status = engine.status()
-print(f"Mode: {status.mode}")
-print(f"Profile: {status.profile}")
-print(f"Memories: {status.memory_count}")
-
-# Health check
-health = engine.health()
-print(f"Fisher-Rao: {health.fisher}")
-print(f"Sheaf: {health.sheaf}")
-print(f"Langevin: {health.langevin}")
-
-# Consistency check
-contradictions = engine.consistency_check()
-for c in contradictions:
-    print(f"Conflict: '{c.memory_a}' vs '{c.memory_b}'")
-```
-
-## Framework Integrations
-
-### LangChain
-
-```python
-from superlocalmemory.integrations.langchain import SLMMemory
-
-memory = SLMMemory(mode="a", profile="langchain-app")
-
-# Use as LangChain memory
-from langchain.chains import ConversationChain
-from langchain.llms import OpenAI
-
-chain = ConversationChain(
-    llm=OpenAI(),
-    memory=memory,
-)
-```
-
-### LlamaIndex
-
-```python
-from superlocalmemory.integrations.llamaindex import SLMMemoryStore
-
-store = SLMMemoryStore(mode="a", profile="llamaindex-app")
-
-# Use as a LlamaIndex document store
-```
-
-### Direct MCP Integration
-
-If you are building an MCP-compatible tool and want to add SLM as a backend:
-
-```python
-from superlocalmemory.mcp import create_mcp_server
-
-server = create_mcp_server(
-    mode="a",
-    profile="my-tool",
-)
-
-# The server exposes all 24 tools and 6 resources
-server.run()
-```
-
-## Context Manager
-
-For scripts that need clean resource management:
-
-```python
-from superlocalmemory.core.engine import MemoryEngine
-from superlocalmemory.core.config import SLMConfig
-
-with MemoryEngine(SLMConfig()) as engine:
-    engine.store("Ephemeral context for this script run")
-    results = engine.recall("context")
-    # engine.close() called automatically
-```
-
-## Error Handling
-
-```python
-from superlocalmemory.core.exceptions import (
-    SLMError,            # Base exception
-    ProfileNotFoundError,
-    MemoryNotFoundError,
-    ConfigError,
-    DatabaseError,
-)
-
-try:
-    engine.switch_profile("nonexistent")
-except ProfileNotFoundError:
-    print("Profile does not exist. Create it first.")
-
-try:
-    engine.delete(memory_id=99999)
-except MemoryNotFoundError:
-    print("Memory not found.")
-```
-
-## Thread Safety
-
-The `MemoryEngine` uses SQLite WAL mode and is safe for concurrent reads from multiple threads. Writes are serialized at the database level.
-
-For multi-threaded applications, create one engine instance and share it:
-
-```python
-# Safe: one engine, multiple threads reading
-engine = MemoryEngine(SLMConfig())
-
-# Each thread can call engine.recall() concurrently
-# Writes (engine.store()) are automatically serialized
-```
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*