superlocalmemory 3.4.16 → 3.4.18

package/docs/skill-evolution.md

@@ -1,256 +0,0 @@
-# Skill Evolution — SuperLocalMemory
-
-> Track, analyze, and evolve your AI agent skills automatically.
-
----
-
-## What Is Skill Evolution?
-
-Skill Evolution turns SuperLocalMemory from a passive memory system into an active learning engine that tracks how your skills perform and helps them improve over time.
-
-**The problem:** AI agent skills (SKILL.md files, slash commands, agent definitions) are static. A skill installed today works the same way 6 months from now — even if it failed 50 times, even if a better approach was discovered.
-
-**The solution:** SLM observes every skill invocation, builds execution traces, computes performance metrics, and surfaces insights so you (and eventually the system itself) can evolve skills based on real data.
-
----
-
-## How It Works
-
-```
-Your session
-  │
-  │ SLM hook captures every tool call (enriched: input, output, session, project)
-  ▼
-tool_events table (rich execution data)
-  │
-  │ SkillPerformanceMiner runs during consolidation
-  ▼
-Per-skill metrics + behavioral assertions + skill entities
-  │
-  │ Next session's soft prompts include skill routing recommendations
-  ▼
-Smarter skill selection, session by session
-```
-
-### Three Data Sources
-
-| Source | What It Captures | Cost |
-|--------|-----------------|------|
-| **SLM Hook** (primary) | Every tool call with input/output (500 chars), session ID, project path. Secret scrubbing built-in. | Zero — runs locally, no LLM calls |
-| **ECC Integration** (optional) | Rich observations from [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) via `slm ingest --source ecc` | Zero — reads existing ECC data |
-| **Consolidation Pipeline** | Mines tool_events for patterns, creates assertions, updates skill entities | Zero — statistical analysis only |
-
-### What Gets Tracked Per Skill
-
-| Metric | Description |
-|--------|-------------|
-| **Invocation count** | How many times the skill was used |
-| **Effective score** | Approximate success rate based on execution trace analysis |
-| **Session count** | How many sessions used this skill |
-| **Skill correlations** | Which skills are frequently used together |
-
-### Outcome Heuristic
-
-SLM uses a conservative, approximate heuristic to determine if a skill invocation was effective:
-
-| Signal | Type | What It Means |
-|--------|------|---------------|
-| Productive tools follow (Edit, Write, Bash success) | Positive | Skill likely helped |
-| Same skill re-invoked within 5 minutes | Negative | Likely retry = failure |
-| Bash errors in next 3 tool events | Negative | Something went wrong |
-| Session continues 10+ events | Weak positive | User stayed engaged |
-
-These signals are labeled as **approximate** everywhere. They inform soft prompt routing but do not trigger automatic changes without human review.
-
----
-
-## Dashboard: Skill Evolution Tab
-
-The dedicated **Skill Evolution** tab in the SLM dashboard shows:
-
-- **Overview cards** — Total skill events, unique skills, performance assertions, skill correlations
-- **Skill performance cards** — Per-skill effective score, invocation count, confidence level
-- **Evolution Engine status** — Backend detection, enable/disable toggle, run button
-- **Skill Lineage DAG** — Visual graph of evolved skill versions (parent → child relationships)
-- **Lineage table** — Clickable rows showing evolution type, status, verification result
-- **Skill correlations** — Which skills work well together
-
-Access: Open `http://localhost:8765` and navigate to the Skill Evolution tab in the sidebar.
-
----
-
-## IDE Compatibility
-
-| IDE | Status | How |
-|-----|--------|-----|
-| **Claude Code** | Supported | SLM hook auto-registered via `slm init` |
-| **Cursor** | Planned | Adapter needed |
-| **Windsurf** | Planned | Adapter needed |
-| **VS Code Copilot** | Planned | Extension events adapter needed |
-| **JetBrains** | Planned | Adapter needed |
-| **Any IDE** | API available | POST to `/api/v3/tool-event` directly |
-
-The backend (API, miner, database, dashboard) is fully IDE-agnostic. Any client that POSTs tool events to the `/api/v3/tool-event` endpoint gets full benefit. The hook that ships with SLM is currently optimized for Claude Code.
-
-### API Endpoint
-
-```bash
-POST http://localhost:8765/api/v3/tool-event
-Content-Type: application/json
-
-{
-  "tool_name": "Skill",
-  "event_type": "complete",
-  "input_summary": "{\"skill\": \"my-skill-name\", \"args\": \"...\"}",
-  "output_summary": "{\"success\": true}",
-  "session_id": "your-session-id",
-  "project_path": "/path/to/project"
-}
-```
-
-All fields except `tool_name` are optional. Existing integrations that send only `tool_name` + `event_type` continue to work.
-
----
-
-## ECC Integration
-
-[Everything Claude Code (ECC)](https://github.com/affaan-m/everything-claude-code) is a popular plugin for Claude Code that provides continuous learning, instinct-based pattern detection, and a rich observation pipeline.
-
-SLM's skill observation patterns were inspired by ECC's architecture. If you have ECC installed, you can enrich SLM's skill tracking with ECC's deeper observations:
-
-```bash
-# One-time import of existing ECC observations
-slm ingest --source ecc
-
-# Preview without writing (dry run)
-slm ingest --source ecc --dry-run
-```
-
-This reads ECC's observation files from `~/.claude/homunculus/projects/*/observations.jsonl` and imports them into SLM's `tool_events` table with full input/output preservation.
-
-**ECC is not required.** SLM is fully self-sufficient — its own hook captures all the data needed for skill tracking. ECC integration is an optional enhancement for users who want both systems working together.
-
----
-
-## Configuration
-
-### Skill Tracking (C1 — always on)
-
-Skill performance tracking is enabled by default when the SLM hook is registered. Zero-LLM, zero-cost. Runs as Step 10 in the consolidation pipeline.
-
-```bash
-slm status  # Shows hook registration status
-slm consolidate --cognitive  # Trigger manual consolidation
-```
-
-### Skill Evolution (C2 — off by default)
-
-The Skill Evolution Engine uses LLM calls to generate improved skill versions. **It is OFF by default** — end users must opt in.
-
-**Why off by default:** Evolution makes LLM calls (confirmation gate + mutation + blind verification). Even with budget caps, users should consciously enable this and configure their LLM backend.
-
-#### Enable via CLI
-
-```bash
-slm config set evolution.enabled true
-```
-
-#### Enable via Interactive Installer
-
-```bash
-slm setup  # Interactive wizard includes evolution opt-in
-```
-
-#### Enable via Dashboard
-
-Navigate to Settings → Skill Evolution → Enable.
-
-### LLM Backend — Auto-Detect
-
-Evolution uses a single auto-detect chain. No manual configuration needed for most users:
-
-```
-Priority 1: `claude` CLI available → spawn `claude --model haiku` (FREE, best quality)
-Priority 2: Ollama running         → use Ollama (FREE, local)
-Priority 3: API key set            → use Anthropic/OpenAI API (paid)
-Priority 4: Nothing available      → dashboard-only (show candidates, manual evolution)
-```
-
-This means:
-- **Claude Code users:** Evolution works for free — uses your existing Claude subscription
-- **Other IDE users with Ollama:** Evolution works for free — uses local Ollama
-- **Advanced users:** Can point at Anthropic/OpenAI API if preferred
-
-```bash
-# Override auto-detect (optional — most users never need this)
-slm config set evolution.backend claude
-slm config set evolution.backend ollama
-slm config set evolution.backend anthropic
-```
-
-### Full Evolution Config Reference
-
-| Key | Default | Description |
-|-----|---------|-------------|
-| `evolution.enabled` | `false` | Master switch — off by default, opt-in |
-| `evolution.backend` | `auto` | LLM backend: `auto`, `claude`, `ollama`, `anthropic`, `openai` |
-| `evolution.max_evolutions_per_cycle` | `3` | Budget cap per consolidation cycle |
-
-### Tracking Thresholds (C1)
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| MIN_INVOCATIONS | 5 | Minimum uses before creating assertions |
-| MIN_CONFIDENCE | 0.5 | Minimum confidence for soft prompt injection |
-| TRACE_WINDOW | 10 | Tool events to analyze after each Skill call |
-| RETRY_WINDOW | 300s | Same Skill within this window = potential retry |
-
-These are conservative by design — we'd rather miss a pattern than hallucinate one.
-
----
-
-## Research Foundations
-
-SLM's skill evolution system draws from:
-
-- **[EvoSkills](https://arxiv.org/abs/2604.01687)** (HKUDS, 2026) — Co-evolutionary verification with information isolation. +30pp improvement from blind verification.
-- **[OpenSpace](https://github.com/HKUDS/OpenSpace)** (HKUDS, MIT) — 3-trigger evolution system (post-analysis + tool degradation + metric monitor). Anti-loop guards. Version DAG model.
-- **[SkillsBench](https://arxiv.org/abs/2602.12670)** (2026) — 86-task benchmark showing self-generated skills provide zero benefit without verification. Focused 2-3 module skills outperform exhaustive docs.
-- **[SoK: Agent Skills](https://arxiv.org/abs/2602.12430)** (2026) — Four-axis taxonomy. Skills and MCP are orthogonal layers.
-
----
-
-## MCP Tools
-
-Three MCP tools are available for programmatic access:
-
-| Tool | Description |
-|------|-------------|
-| `evolve_skill` | Manually trigger evolution for a specific skill |
-| `skill_health` | Get health metrics (invocations, error rate, status) for skills |
-| `skill_lineage` | Get evolution lineage tree for a skill |
-
-These tools are registered automatically and available in all supported IDEs.
-
-## CLI Commands
-
-```bash
-slm config get evolution.enabled     # Check if evolution is enabled
-slm config set evolution.enabled true  # Enable evolution
-slm config set evolution.backend auto  # Set LLM backend
-```
-
-## What's Next
-
-- **IDE Adapters** — Cursor, Windsurf, VS Code Copilot, JetBrains support for skill tracking.
-- **Skill lineage visualization improvements** — Richer DAG with performance history overlay.
-
----
-
-## Links
-
-- [SLM GitHub](https://github.com/qualixar/superlocalmemory)
-- [Qualixar](https://qualixar.com)
-- [Everything Claude Code](https://github.com/affaan-m/everything-claude-code)
-- [OpenSpace](https://github.com/HKUDS/OpenSpace)
-- [EvoSkills Paper](https://arxiv.org/abs/2604.01687)

package/docs/troubleshooting.md

@@ -1,310 +0,0 @@
-# Troubleshooting
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-Solutions for common issues. If your problem is not listed here, run `slm status --verbose` and check the output for clues.
-
----
-
-## Installation Issues
-
-### "slm: command not found"
-
-The npm global bin directory is not in your shell's PATH.
-
-**Fix:**
-
-```bash
-# Find where npm puts global binaries
-npm root -g
-# Example output: /usr/local/lib/node_modules
-
-# The bin directory is one level up
-# Add to your shell profile (~/.zshrc, ~/.bashrc, or ~/.bash_profile):
-export PATH="$(npm prefix -g)/bin:$PATH"
-
-# Reload your shell
-source ~/.zshrc   # or source ~/.bashrc
-```
-
-**Alternative — use npx:**
-
-```bash
-npx superlocalmemory status
-```
-
-### "Python not found" during setup
-
-SLM V3 requires Python 3.10 or later for the math engine.
-
-```bash
-# Check Python version
-python3 --version
-
-# Install if missing
-# macOS:
-brew install python@3.12
-
-# Ubuntu/Debian:
-sudo apt install python3.12
-
-# Windows:
-winget install Python.Python.3.12
-```
-
-### "Permission denied" during install
-
-```bash
-# Option 1: Fix npm permissions (recommended)
-mkdir -p ~/.npm-global
-npm config set prefix '~/.npm-global'
-export PATH=~/.npm-global/bin:$PATH
-npm install -g superlocalmemory
-
-# Option 2: Use sudo (not recommended)
-sudo npm install -g superlocalmemory
-```
-
-## Recall Issues
-
-### "No memories found" when you know they exist
-
-**Check your active profile:**
-
-```bash
-slm profile list
-```
-
-Memories are profile-scoped. If you stored a memory in the `work` profile but are currently in `default`, it will not appear.
-
-```bash
-slm profile switch work
-slm recall "your query"
-```
-
-**Check your mode:**
-
-```bash
-slm mode
-```
-
-Mode A uses math-based retrieval. If you recently switched from Mode C, the retrieval behavior changes. Both modes search the same memories, but ranking differs.
-
-**Try a broader query:**
-
-```bash
-slm recall "database"          # Instead of "PostgreSQL 16 configuration on staging"
-slm list --limit 20            # Browse recent memories directly
-```
-
-### Recall returns irrelevant results
-
-**Lower your result count:**
-
-```bash
-slm recall "your query" --limit 3
-```
-
-Fewer results means only the highest-confidence matches are returned.
-
-**Use trace to debug:**
-
-```bash
-slm trace "your query"
-```
-
-This shows which channels contributed what. If BM25 is dominating with weak keyword matches, the query may need different terms.
-
-**Rebuild the graph:**
-
-```bash
-slm build_graph
-```
-
-If entity relationships seem wrong, rebuilding the graph can fix ranking issues.
-
-## Mode C Issues
-
-### "API key not set" or authentication errors
-
-```bash
-# Check your provider configuration
-slm provider
-
-# Reset your provider and key
-slm provider set openai
-# Enter your API key when prompted
-
-# Or set via environment variable
-export OPENAI_API_KEY="sk-..."
-```
-
-### "Connection timeout" or network errors
-
-```bash
-# Test connectivity to your provider
-slm status --verbose
-
-# Check if you're behind a proxy
-echo $HTTP_PROXY
-echo $HTTPS_PROXY
-```
-
-If behind a corporate proxy, set the proxy variables:
-
-```bash
-export HTTPS_PROXY="http://proxy.company.com:8080"
-```
-
-### Mode C is slow
-
-Cloud LLM calls add latency. If speed matters more than maximum recall quality:
-
-```bash
-slm mode b    # Local LLM (fast, no network)
-slm mode a    # Math-only (fastest)
-```
-
-## Migration Issues
-
-### Migration failed or was interrupted
-
-```bash
-# Check if backup exists
-ls ~/.superlocalmemory/backups/
-
-# Roll back to V2
-slm migrate --rollback
-
-# Try migration again
-slm migrate
-```
-
-### "Database is locked"
-
-Close all IDE sessions that might be accessing SLM, then retry:
-
-```bash
-# Check for processes using the database
-lsof ~/.superlocalmemory/memory.db
-
-# Close IDEs, then retry
-slm migrate
-```
-
-### Migration succeeded but recall quality seems worse
-
-After migration, the entity graph and BM25 index are rebuilt from existing data. This process is automatic but can take a moment for large databases.
-
-```bash
-# Force a full re-index
-slm build_graph
-slm compact
-```
-
-## IDE Connection Issues
-
-### IDE does not show SLM tools
-
-1. **Verify SLM is installed:**
-
-```bash
-npm list -g superlocalmemory
-```
-
-2. **Check the IDE config file has correct JSON:**
-
-```bash
-slm connect <your-ide>    # Regenerates the config
-```
-
-3. **Restart the IDE completely** (not just reload the window).
-
-4. **Test the MCP server directly:**
-
-```bash
-npx superlocalmemory mcp --test
-```
-
-### "Connection refused" in IDE
-
-The MCP server failed to start. Common causes:
-
-- Node.js version too old (need 18+)
-- Port conflict with another service
-- Corrupted installation
-
-```bash
-# Reinstall
-npm uninstall -g superlocalmemory
-npm install -g superlocalmemory
-
-# Verify
-slm status
-```
-
-### Multiple IDEs conflicting
-
-Each IDE has its own MCP config file. They do not conflict. All IDEs share the same underlying database. Concurrent access is safe (SQLite WAL mode handles this).
-
-## Database Issues
-
-### Database corruption
-
-Extremely rare with SQLite WAL mode, but if it happens:
-
-```bash
-# Check integrity
-slm status --verbose
-
-# Restore from automatic backup
-ls ~/.superlocalmemory/backups/
-cp ~/.superlocalmemory/backups/memory-2026-03-15.db ~/.superlocalmemory/memory.db
-```
-
-### Database is too large
-
-```bash
-# Check size
-slm memory_used
-
-# Compact (merges redundant memories, reclaims space)
-slm compact
-
-# Apply a retention policy to auto-delete old memories
-slm retention set custom --days 180
-```
-
-## Health Check
-
-Run a full diagnostic:
-
-```bash
-slm health
-```
-
-This reports the status of:
-
-| Component | What it checks |
-|-----------|---------------|
-| Database | Integrity, size, table counts |
-| Embedding model | Loaded, version, dimension |
-| Fisher-Rao | Similarity layer active |
-| Sheaf | Consistency layer active |
-| Langevin | Lifecycle layer active |
-| BM25 index | Token count, index health |
-| Entity graph | Node count, edge count |
-
-If any component shows an error, the output includes a suggested fix.
-
-## Getting Help
-
-If none of the above resolves your issue:
-
-1. Run `slm status --verbose` and note the output
-2. Check the [GitHub Issues](https://github.com/qualixar/superlocalmemory/issues)
-3. Open a new issue with your `slm status --verbose` output
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*