superlocalmemory 3.4.21 → 3.4.22

package/src/superlocalmemory/server/routes/brain.py

@@ -1,10 +1,10 @@
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.21 — LLD-04 §4.1 + §3
+# Part of SuperLocalMemory v3.4.22 — LLD-04 §4.1 + §3
 
 """``/api/v3/brain`` — unified Brain endpoint (LLD-04 v2).
 
-Merges the pre-3.4.21 Patterns / Learning / Behavioral dashboard tabs
+Merges the pre-3.4.22 Patterns / Learning / Behavioral dashboard tabs
 into one auth-gated, honestly-labelled JSON payload. Every metric has
 an ``is_real`` (numeric counters) or ``is_real_ml`` (ML-derived) flag
 and points at the real table it was computed from. No metric is
@@ -24,7 +24,7 @@ Design notes (LLD-04 §7 hard rules):
 * **U2** — every metric section carries ``is_real`` or ``is_real_ml``.
 * **U3** — ``learning.phase`` never returns ``3`` without an active
   model row AND passing SHA check. Both conditions computed here.
-* **U4** — response shape must not contain the three pre-3.4.21
+* **U4** — response shape must not contain the three pre-3.4.22
   fabricated metrics (24h hit-rate, avg age on hit, skill-evolution
   row counts). A static test greps this file to verify; therefore we
   never spell those names anywhere in this module.
@@ -64,7 +64,7 @@ router = APIRouter(prefix="/api/v3", tags=["brain"])
 # LLD-03 v2 stratum space = 4 query types × 3 entity bins × 4 time buckets.
 _STRATA_TOTAL: int = 48
 
-_VERSION: str = "3.4.21"
+_VERSION: str = "3.4.22"
 
 # Banned metric names (LLD-04 U4). Kept as a tuple for grep visibility;
 # the source-level test asserts we don't accidentally reintroduce them.
@@ -246,7 +246,7 @@ def _compute_learning_status(profile_id: str,
     """Section ``learning`` — LLD-02 §4.10 phase truth + counters."""
     signals_total = _safe_count(lrn_db, "learning_signals", profile_id)
     features_total = _safe_count(lrn_db, "learning_features", profile_id)
-    # Raw count of historic pre-v3.4.21 feedback rows (the source table)
+    # Raw count of historic pre-v3.4.22 feedback rows (the source table)
     legacy_feedback_rows = _safe_count(lrn_db, "learning_feedback", profile_id)
     # Count of rows actually copied forward into learning_signals by
     # legacy_migration.migrate_legacy_feedback (signal_type='legacy_feedback').
@@ -289,7 +289,7 @@ def _compute_learning_status(profile_id: str,
         "signals_last_hour": signals_last_hour,
         "features_total": features_total,
         "feature_count_expected": FEATURE_DIM,
-        # Honest split (v3.4.21+): raw historic table count vs rows
+        # Honest split (v3.4.22+): raw historic table count vs rows
         # actually copied forward via the migrate-legacy flow.
         "legacy_feedback_rows": legacy_feedback_rows,
         "legacy_migrated_count": legacy_migrated,
@@ -356,7 +356,7 @@ def _top_query_types(
     ``query_type_od`` (features.py FEATURE_NAMES). We aggregate by the
     active one-hot slot. Missing table or zero rows → empty list.
     """
-    # E.1 (v3.4.21 perf): push the query-type classification into SQL via
+    # E.1 (v3.4.22 perf): push the query-type classification into SQL via
     # json_extract so we don't drag 10k rows' worth of JSON through Python.
     # SQLite's json1 extension treats json_extract as an ordinary scalar
     # function, so the whole aggregation becomes a single COUNT(*)
@@ -601,7 +601,7 @@ def _compute_cross_platform() -> dict:
     reports ``active: false`` with ``reason: error:<ExcName>`` rather
     than crashing the whole Brain endpoint (LLD-04 §2 — "honest, never
     fake"). An unimportable adapter means the install is missing Wave 2C
-    components, which is legitimate for an older 3.4.20 → 3.4.21 upgrade
+    components, which is legitimate for an older 3.4.20 → 3.4.22 upgrade
     mid-migration.
     """
     out: dict = {}
@@ -871,7 +871,7 @@ def _action_outcomes_count(lrn_db: LearningDatabase,
                            profile_id: str) -> int:
     """Row count in ``action_outcomes`` for ``profile_id``.
 
-    ``action_outcomes`` ships in v3.4.21 (M006). While absent, returns 0.
+    ``action_outcomes`` ships in v3.4.22 (M006). While absent, returns 0.
     """
     try:
         conn = sqlite3.connect(lrn_db.path, timeout=5.0)
@@ -963,7 +963,7 @@ async def get_brain(profile_id: str = "default") -> dict:
         "outcomes_preview": {
             "action_outcomes_rows":
                 0 if isinstance(outcomes_rows, Exception) else outcomes_rows,
-            "ships_in": "3.4.21",
+            "ships_in": "3.4.22",
         },
         # S9-defer H-22: live tile data for the Reward / Shadow /
         # Evolution-Cost dashboard tiles. Each block is a honest-empty

package/src/superlocalmemory/server/routes/prewarm.py

@@ -1,6 +1,6 @@
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.21 — LLD-01 §4.4 / §4.5
+# Part of SuperLocalMemory v3.4.22 — LLD-01 §4.4 / §4.5
 
 """POST /internal/prewarm — populates the context cache for a session.
 

package/src/superlocalmemory/server/security_middleware.py

@@ -33,7 +33,7 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
         # Enable browser XSS filter (legacy, but doesn't hurt)
         response.headers["X-XSS-Protection"] = "1; mode=block"
 
-        # Content Security Policy (v3.4.21 — vendored assets, no CDN hosts).
+        # Content Security Policy (v3.4.22 — vendored assets, no CDN hosts).
         # All Bootstrap/D3/Sigma/graphology/Inter assets ship locally under
         # /static/vendor/, so we drop every CDN host from the allow-list.
         # 'unsafe-inline' stays on script-src/style-src for the legacy inline

package/src/superlocalmemory/server/unified_daemon.py

@@ -369,7 +369,7 @@ async def lifespan(application: FastAPI):
             )
 
         # S9-DASH-02: start the outcome-queue worker so recall →
-        # pending_outcomes is actually produced. Before v3.4.21 this
+        # pending_outcomes is actually produced. Before v3.4.22 this
         # producer had zero callers and the closed-loop pipeline was
         # dark. Worker drains at 250 ms cadence; one SQLite INSERT per
         # event via EngagementRewardModel.record_recall.
@@ -457,7 +457,7 @@ async def lifespan(application: FastAPI):
     if enable_legacy:
         asyncio.create_task(_start_legacy_redirect(_DEFAULT_PORT, _LEGACY_PORT))
 
-    # V3.4.21 LLD-02: signal-worker background drainer (S8-SK-01 fix).
+    # V3.4.22 LLD-02: signal-worker background drainer (S8-SK-01 fix).
     # Without this, ``signals.enqueue`` fills a bounded queue and drops
     # silently after ~250 recalls — learning_signals never populates,
     # Phase 3 never activates, the whole Living Brain stays cold.
@@ -473,7 +473,7 @@ async def lifespan(application: FastAPI):
             logger.warning("signal_worker failed to start: %s", exc)
             application.state.signal_worker_started = False
 
-    # V3.4.21 LLD-05: cross-platform adapter sync loop
+    # V3.4.22 LLD-05: cross-platform adapter sync loop
     if os.environ.get("SLM_CROSS_PLATFORM_SYNC_DISABLED", "").lower() not in ("1", "true"):
         try:
             from superlocalmemory.cli.context_commands import build_default_adapters
@@ -482,7 +482,7 @@ async def lifespan(application: FastAPI):
         except Exception as exc:  # pragma: no cover — defensive
             logger.warning("cross-platform sync loop failed to start: %s", exc)
 
-    # V3.4.21 LLD-03: bandit reward proxy settler + retention sweep loops
+    # V3.4.22 LLD-03: bandit reward proxy settler + retention sweep loops
     if os.environ.get("SLM_BANDIT_DISABLED", "0") != "1":
         try:
             from superlocalmemory.server.bandit_loops import (

package/src/superlocalmemory/skills/slm-build-graph/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: slm-build-graph
+description: Build or rebuild the knowledge graph from existing memories using TF-IDF entity extraction and Leiden clustering. Use when search results seem poor, after bulk imports, or to optimize performance. Automatically discovers relationships between memories and creates topic clusters.
+version: "3.4.22"
+license: AGPL-3.0-or-later
+compatibility: "Requires SuperLocalMemory V2 installed at ~/.claude-memory/, optional dependencies: python-igraph, leidenalg"
+attribution:
+  creator: Varun Pratap Bhardwaj
+  role: Solution Architect & Original Creator
+  project: SuperLocalMemory V2
+---
+
+# SuperLocalMemory: Build Knowledge Graph
+
+Build or rebuild the knowledge graph from existing memories to improve search quality and discover hidden relationships.
+
+## Usage
+
+```bash
+slm build-graph [--force] [--clustering]
+```
+
+## What It Does
+
+### 1. Entity Extraction (TF-IDF)
+- Scans all memories
+- Identifies important terms (entities)
+- Creates nodes in knowledge graph
+- Examples: "FastAPI", "JWT", "PostgreSQL", "React hooks"
+
+### 2. Relationship Discovery
+- Finds memories sharing entities
+- Calculates similarity scores
+- Creates edges between related nodes
+- Discovers indirect connections
+
+### 3. Topic Clustering (Optional)
+- Groups related memories into clusters
+- Uses Leiden algorithm (community detection)
+- Creates semantic topic groups
+- Examples: "Authentication cluster", "Database cluster"
+
+## Examples
+
+### Example 1: Basic Graph Build
+```bash
+$ slm build-graph
+```
+
+**Output:**
+```
+🔄 Building Knowledge Graph...
+
+Phase 1: Entity Extraction
+  Scanning 1,247 memories...
+  Extracted 892 unique entities
+  Created 892 graph nodes
+  ✓ Complete (3.2s)
+
+Phase 2: Relationship Discovery
+  Computing similarity scores...
+  Created 3,456 edges (relationships)
+  Avg edges per node: 3.9
+  ✓ Complete (5.1s)
+
+Phase 3: Optimization
+  Indexing graph structure...
+  Pruning weak edges (score < 0.3)...
+  Final edge count: 2,134
+  ✓ Complete (1.2s)
+
+✅ Knowledge graph built successfully!
+
+Graph Statistics:
+  Nodes: 892
+  Edges: 2,134
+  Density: 0.27%
+  Largest Component: 856 nodes (96%)
+
+Next: Use `slm recall` to see improved search results
+```
+
+### Example 2: Force Rebuild
+```bash
+$ slm build-graph --force
+```
+
+**Rebuilds from scratch** (deletes existing graph first)
+
+**Use when:**
+- Graph seems corrupted
+- Major bulk import completed
+- Want fresh start
+
+### Example 3: With Clustering
+```bash
+$ slm build-graph --clustering
+```
+
+**Requires optional dependencies:**
+```bash
+pip3 install python-igraph leidenalg
+```
+
+**Additional output:**
+```
+Phase 4: Topic Clustering (Leiden)
+  Detecting communities...
+  Found 47 clusters
+  Largest cluster: 89 memories
+  Smallest cluster: 3 memories
+  Modularity score: 0.82 (excellent)
+  ✓ Complete (2.3s)
+
+Discovered Clusters:
+  Cluster 1 (89 memories): "Authentication & Security"
+    Top entities: JWT, OAuth, tokens, auth, security
+
+  Cluster 2 (76 memories): "Database & PostgreSQL"
+    Top entities: PostgreSQL, database, SQL, queries, indexes
+
+  Cluster 3 (54 memories): "React & Frontend"
+    Top entities: React, hooks, components, state, props
+
+  ...
+```
+
+## Arguments
+
+| Argument | Description | When to Use |
+|----------|-------------|-------------|
+| `--force` | Delete existing graph and rebuild | Corruption, fresh start |
+| `--clustering` | Run topic clustering | Want to discover topic groups |
+| `--verbose` | Show detailed progress | Debugging, understanding process |
+| `--dry-run` | Preview without saving | Testing, analysis |
+
+## When to Run
+
+### Always Run After:
+1. **Bulk imports** - Added 50+ memories at once
+2. **Database restore** - Restored from backup
+3. **Major project milestone** - Sprint complete, project phase done
+
+### Run Periodically:
+4. **Monthly** - Keep graph optimized
+5. **After 500 new memories** - Maintain quality
+6. **When search feels slow** - Rebuild indexes
+
+### Run on Issues:
+7. **Poor search results** - Graph may be stale
+8. **Missing relationships** - Rebuild connections
+9. **Corrupted graph errors** - Force rebuild
+
+## What Gets Built
+
+### Graph Nodes
+**Entities extracted from memories:**
+- Technologies: "FastAPI", "PostgreSQL", "React"
+- Concepts: "authentication", "performance", "testing"
+- Patterns: "TDD", "async", "REST API"
+- Decisions: "prefer X over Y"
+
+**Node properties:**
+- Entity text
+- Frequency (how many memories mention it)
+- Importance score
+- First seen / last seen
+
+### Graph Edges
+**Relationships between entities:**
+- **Similarity edge:** Memories share similar content
+- **Co-occurrence edge:** Entities appear together
+- **Sequential edge:** Memories created close in time
+
+**Edge properties:**
+- Similarity score (0.0 - 1.0)
+- Shared entities list
+- Edge type
+
+### Clusters (if --clustering)
+**Topic groups discovered:**
+- Cluster ID
+- Cluster name (auto-generated from top entities)
+- Member memories (which memories belong)
+- Top entities in cluster
+- Modularity score (how well-defined)
+
+## Performance
+
+| Memory Count | Build Time | Notes |
+|--------------|------------|-------|
+| 100 | ~1s | Instant |
+| 1,000 | ~10s | Fast |
+| 10,000 | ~2min | Acceptable |
+| 50,000+ | ~15min | Plan accordingly |
+
+**With clustering (add ~50%):**
+- 1,000 memories: ~15s
+- 10,000 memories: ~3min
+
+**Factors affecting speed:**
+- Memory content length
+- Vocabulary size (unique words)
+- Hardware (CPU, RAM)
+
+## Advanced Usage
+
+### Incremental Updates
+
+```bash
+# Add new memories
+slm remember "New content..." --tags new
+
+# Incremental graph update (fast)
+slm build-graph  # Only processes new memories
+
+# Force full rebuild (slower, thorough)
+slm build-graph --force
+```
+
+### Monitoring Quality
+
+```bash
+# Check graph stats before
+slm status | grep "Knowledge Graph"
+
+# Build graph
+slm build-graph --verbose
+
+# Check stats after
+slm status | grep "Knowledge Graph"
+```
+
+### Scripting & Automation
+
+**Weekly rebuild (cron job):**
+```bash
+#!/bin/bash
+# Every Sunday at 3 AM
+
+echo "$(date): Starting graph rebuild"
+slm build-graph --clustering >> /var/log/slm-build.log 2>&1
+echo "$(date): Graph rebuild complete"
+```
+
+**Post-import hook:**
+```bash
+#!/bin/bash
+# After bulk import
+
+memories_added=$1
+
+if [ "$memories_added" -gt 50 ]; then
+  echo "Large import detected, rebuilding graph..."
+  slm build-graph
+fi
+```
+
+### Clustering Analysis
+
+```bash
+# Build with clustering
+slm build-graph --clustering
+
+# Check discovered clusters
+slm status --verbose | grep -A 20 "Topic Clusters"
+
+# Search within specific cluster
+slm recall "FastAPI" --cluster "Backend & APIs"
+```
+
+## Troubleshooting
+
+### "Build failed: Memory error"
+
+**Cause:** Not enough RAM for large graph
+
+**Solution:**
+```bash
+# Build in chunks (process fewer memories at once)
+slm build-graph --chunk-size 1000
+
+# Or increase system memory
+# Or archive old memories
+```
+
+### "Clustering requires python-igraph"
+
+**Cause:** Optional dependencies not installed
+
+**Solution:**
+```bash
+pip3 install python-igraph leidenalg
+
+# Verify
+python3 -c "import igraph; import leidenalg"
+
+# Try again
+slm build-graph --clustering
+```
+
+### "Graph build slow"
+
+**Causes:**
+- Large database
+- Slow disk I/O
+- Complex memory content
+
+**Solutions:**
+```bash
+# Show progress
+slm build-graph --verbose
+
+# Skip clustering (faster)
+slm build-graph  # No --clustering flag
+
+# Check disk space
+df -h ~/.claude-memory/
+```
+
+### "Edges seem wrong"
+
+**Cause:** Stale graph or poor similarity threshold
+
+**Solution:**
+```bash
+# Force complete rebuild
+slm build-graph --force
+
+# Adjust similarity threshold (advanced)
+slm build-graph --min-similarity 0.4  # Default: 0.3
+```
+
+## Graph Metrics Explained
+
+### Node Count
+**Total unique entities found**
+- Good: > 100 for 1,000 memories
+- Poor: < 10 for 1,000 memories
+
+**Why matters:** More nodes = richer semantic understanding
+
+### Edge Count
+**Total relationships discovered**
+- Good: Edges/Nodes ratio > 2
+- Poor: Ratio < 1 (disconnected graph)
+
+**Why matters:** More edges = better search via relationships
+
+### Density
+**How connected the graph is**
+- Formula: (Edges / Possible Edges) × 100
+- Typical: 0.1% - 1%
+- Too low (<0.05%): Memories very disconnected
+- Too high (>5%): May indicate poor entity extraction
+
+### Largest Component
+**Size of biggest connected subgraph**
+- Good: >80% of nodes
+- Poor: <50% (fragmented knowledge)
+
+**Why matters:** Smaller component = isolated knowledge islands
+
+### Modularity (Clustering)
+**How well-defined clusters are**
+- Excellent: >0.7
+- Good: 0.5 - 0.7
+- Poor: <0.3
+
+**Why matters:** Higher = clearer topic separation
+
+## Impact on Other Commands
+
+### slm recall (Search)
+**Before graph build:**
+- Relies mainly on keyword matching
+- May miss related memories
+
+**After graph build:**
+- Discovers indirect relationships
+- Finds conceptually similar memories
+- Better ranked results
+
+**Example:**
+```
+Query: "authentication"
+
+Before:
+- Direct matches only (JWT, auth, login)
+
+After:
+- Direct matches (JWT, auth, login)
+- + Related concepts (security, tokens, OAuth)
+- + Connected memories (API design, user management)
+```
+
+### slm status
+Shows updated graph statistics
+
+### slm switch-profile
+Each profile has separate graph
+
+## Notes
+
+- **Non-destructive:** Original memories never modified
+- **Idempotent:** Can run multiple times safely
+- **Automatic:** Search uses graph automatically after build
+- **Privacy:** All processing local
+
+## Related Commands
+
+- `slm recall` - Search uses the graph
+- `slm status` - Check graph stats
+- `slm remember` - Add memories (triggers incremental update)
+
+---
+
+**Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
+**Project:** SuperLocalMemory V2
+**License:** MIT (see [LICENSE](../../LICENSE))
+**Repository:** https://github.com/varun369/SuperLocalMemoryV2
+
+*Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*