Step-by-step guide for upgrading from any previous version to SuperLocalMemory v2.7.0. Your existing memories, graph, and settings are fully preserved.

SuperLocalMemory v2.7 adds a personalized learning system that makes recall smarter over time. Instead of returning results based on text matching alone, v2.7 learns your preferences and re-ranks results so the most relevant memories appear first.

The learning system is implemented as a self-contained module with 11 files totaling 7,503 lines, backed by 229 passing unit tests.

# Update to v2.7.0
npm update -g superlocalmemory

# Or install the exact version
npm install -g superlocalmemory@2.7.0

What happens automatically:

• Downloads v2.7.0 from npm
• Copies updated files to ~/.claude-memory/
• Installs learning dependencies (lightgbm, scipy) if pip is available
• Creates src/learning/ module directory
• Preserves all existing data (memories, graph, patterns, events, agents)
• No restart of running IDE sessions needed (changes take effect on next operation)

# Navigate to your clone
cd superlocalmemory

# Pull latest
git pull origin main

# Re-run installer
./install.sh      # Mac/Linux
# or
.\install.ps1     # Windows

If you do not have SuperLocalMemory installed yet, follow the Installation guide. v2.7 includes everything from previous versions.

v2.7 introduces two optional Python dependencies for the ML-based ranking phase:

Both the npm postinstall script and install.sh attempt to install these automatically via:

pip install -r requirements-learning.txt

If automatic installation fails (restricted environments, no pip, etc.):

pip install lightgbm>=4.0.0 scipy>=1.9.0

Or:

pip install -r ~/.claude-memory/requirements-learning.txt

The system works fine without them. The learning system has three ranking phases:

Without lightgbm and scipy, the system caps at Phase 2 (rule-based boosting). This still provides personalized re-ranking — just without the ML model. There is no degradation of any feature that existed before v2.7.

v2.7 maintains full backward compatibility with all previous versions.

~/.claude-memory/
├── learning.db                              # NEW: Separate learning database
├── requirements-learning.txt                # NEW: Optional dependency list
└── src/
    └── learning/                            # NEW: Learning system module
        ├── __init__.py
        ├── learning_db.py                   # Separate SQLite database for behavioral data
        ├── cross_project_aggregator.py      # Layer 1: Tech preference tracking
        ├── project_context_manager.py       # Layer 2: Project detection
        ├── workflow_pattern_miner.py        # Layer 3: Workflow sequence mining
        ├── adaptive_ranker.py               # Three-phase adaptive ranking engine
        ├── feedback_collector.py            # Multi-channel feedback collection
        ├── feature_extractor.py             # Feature engineering for ML model
        ├── source_quality_scorer.py         # Per-source quality tracking
        ├── synthetic_bootstrap.py           # Day-1 synthetic model from existing data
        └── engagement_tracker.py            # Local engagement metrics

If any v2.7 component fails to load, the system falls back gracefully:

# How v2.7 modules are imported (safe pattern)
try:
    from src.learning import adaptive_ranker
    USE_LEARNING = True
except ImportError:
    USE_LEARNING = False
    # System continues with v2.6 behavior

This means:

• If src/learning/ is missing or corrupt: v2.6 behavior (pure text ranking)
• If learning.db is missing: created automatically on first use
• If learning.db is corrupt: deleted and recreated (memories unaffected)
• If lightgbm is not installed: Phase 2 (rule-based) only, no ML
• If scipy is not installed: Same as above

After upgrading, run these checks to confirm everything works.

slm status

Expected: Shows SuperLocalMemory v2.7.0 in the header.

slm learning status

Expected output:

Learning System Status
======================

Ranking Phase:     Baseline (Phase 1)
Feedback Signals:  0 / 50 needed for rule-based phase
Model Status:      Synthetic bootstrap ready

Layer 1 (Tech Preferences):  Active - 0 patterns learned
Layer 2 (Project Context):   Active - No project detected
Layer 3 (Workflow Patterns):  Active - 0 sequences detected

Learning DB Size:  12 KB
Last Updated:      just now

python3 -c "import lightgbm; print('LightGBM:', lightgbm.__version__)"
python3 -c "import scipy; print('SciPy:', scipy.__version__)"

If these fail, Phase 3 ML ranking will not be available, but everything else works.

# Save a memory (should work identically to before)
slm remember "Testing v2.7 upgrade" --tags test,upgrade

# Recall (should work, with learning features active in background)
slm recall "v2.7 upgrade"

# Mark as useful (new v2.7 feature)
slm useful <memory_id_from_recall>

# View patterns (new v2.7 feature)
slm patterns list

In Claude Desktop, Cursor, or Windsurf:

1. Start a new conversation
2. Ask: "What tools do you have access to?"
3. Verify you see memory_used, get_learned_patterns, and correct_pattern alongside existing tools
4. Test: "Remember that I prefer FastAPI for REST APIs"
5. Test: "What do I use for APIs?" (should recall and potentially trigger memory_used)

If you need to revert to a previous version for any reason:

# Install the specific previous version
npm install -g superlocalmemory@2.6.5

# Verify rollback
slm status

cd superlocalmemory

# Check out the v2.6.5 tag
git checkout v2.6.5

# Re-run installer
./install.sh

• Memories: Completely unaffected (memory.db is unchanged by v2.7)
• Learning data: learning.db remains on disk but is ignored by older versions
• New CLI commands: slm useful, slm patterns, slm learning, slm engagement will no longer be available
• New MCP tools: memory_used, get_learned_patterns, correct_pattern will no longer appear
• Recall behavior: Returns to pure text-relevance ranking (no personalization)

If you want to fully remove v2.7 artifacts after rolling back:

# Remove learning database (optional, does not affect memories)
rm ~/.claude-memory/learning.db

# Remove learning module (optional)
rm -rf ~/.claude-memory/src/learning/

# Remove learning requirements (optional)
rm ~/.claude-memory/requirements-learning.txt

None of these deletions affect your memories, graph, patterns, events, or any other existing data.

Direct upgrade. No special steps needed. Follow the standard upgrade procedure above.

Direct upgrade. The Event Bus, Agent Registry, and Trust Scoring features from v2.5 are fully preserved and enhanced by v2.7's learning system.

Direct upgrade. The installer handles all intermediate changes. Your memories, graph, and MACLA-based patterns are preserved.

Follow the Installation guide for a fresh install. Then use the migration tool:

python3 ~/.claude-memory/migrate_v1_to_v2.py

No. v2.7 does not alter memory.db in any way. It creates a separate learning.db file for all behavioral data.

Slightly. Phase 1 (baseline) creates a synthetic model from your existing memory patterns, so there may be minor re-ranking differences from day one. The changes are designed to be improvements — surfacing more relevant results. If results seem worse, you can disable learning (see Learning-System#disabling-the-learning-system).

Not strictly. Phase 1 works without any feedback. But the system gets significantly better with feedback. In MCP-connected IDEs, feedback happens automatically — no action needed on your part.

Yes. LightGBM is an open-source gradient boosting framework by Microsoft, widely used in production ML systems. It runs entirely locally and makes no network calls. v2.7 uses it for local model training only.

Typically under 5 MB after a year of use. See the Learning-System#troubleshooting section for details.

Yes. Set "learning": { "enabled": false } in config.json. Everything works exactly as v2.6.

• Learning-System - Complete guide to the learning system
• Learning-System - How v2.0 pattern detection works (enhanced by v2.7)
• Installation - Fresh installation guide
• CLI-Cheatsheet - Full command reference
• Performance-Benchmarks - Measured performance data

Created by Varun Pratap Bhardwaj Solution Architect - SuperLocalMemory

GitHub | Issues | Wiki