superlocalmemory 3.4.17 → 3.4.19

package/docs/profiles.md

@@ -1,173 +0,0 @@
-# Profiles
-> SuperLocalMemory V3 Documentation
-> https://superlocalmemory.com | Part of Qualixar
-
-Profiles let you maintain completely isolated memory contexts. Work memories never mix with personal memories. Client A never sees Client B's data.
-
----
-
-## What Profiles Are
-
-A profile is an isolated memory namespace. Each profile has its own:
-
-- Memories and knowledge graph
-- Learned patterns and behavioral data
-- Trust scores and provenance records
-- Retention policies
-- Audit trail
-
-There is zero data leakage between profiles. Searching in one profile never returns results from another.
-
-## Default Profile
-
-After installation, you have one profile called `default`. All memories go here unless you create and switch to another profile.
-
-## Managing Profiles
-
-### List profiles
-
-```bash
-slm profile list
-```
-
-Output:
-
-```
-Profiles:
-  * default     (142 memories, active)
-    work        (89 memories)
-    personal    (34 memories)
-    client-acme (67 memories)
-```
-
-The `*` marks the active profile.
-
-### Create a profile
-
-```bash
-slm profile create work
-slm profile create client-acme
-slm profile create personal
-```
-
-### Switch profiles
-
-```bash
-slm profile switch work
-```
-
-All subsequent `remember`, `recall`, and auto-memory operations use this profile until you switch again.
-
-### Delete a profile
-
-```bash
-slm profile delete old-project
-```
-
-This permanently deletes all memories in that profile. You will be prompted for confirmation.
-
-### Export a profile
-
-```bash
-slm profile export work > work-backup.json
-```
-
-### Import a profile
-
-```bash
-slm profile import < work-backup.json
-```
-
-## Use Cases
-
-### Work vs Personal
-
-```bash
-# Morning: switch to work
-slm profile switch work
-# Work memories are captured and recalled all day
-
-# Evening: switch to personal
-slm profile switch personal
-# Personal project memories are now active
-```
-
-### Per-Client Isolation
-
-For consultants and agencies working across multiple clients:
-
-```bash
-slm profile create client-alpha
-slm profile create client-beta
-
-# Working on Alpha's project
-slm profile switch client-alpha
-# Only Alpha's architecture, decisions, and context are available
-
-# Switch to Beta
-slm profile switch client-beta
-# Alpha's data is completely invisible
-```
-
-### Per-Project Isolation
-
-```bash
-slm profile create mobile-app
-slm profile create backend-api
-slm profile create infrastructure
-```
-
-### Temporary Profiles
-
-For experiments or short-term work:
-
-```bash
-slm profile create experiment-graphql
-slm profile switch experiment-graphql
-# ... do your experiment ...
-
-# Done — delete it
-slm profile switch default
-slm profile delete experiment-graphql
-```
-
-## Profile-Specific Settings
-
-Each profile can have its own retention policy:
-
-```bash
-slm profile switch client-acme
-slm retention set gdpr-30d        # GDPR compliance for this client
-
-slm profile switch internal
-slm retention set indefinite       # Keep internal memories forever
-```
-
-## Using Profiles With CLI Commands
-
-Most commands operate on the active profile. You can override this per-command:
-
-```bash
-# Recall from a specific profile without switching
-slm recall "database config" --profile client-acme
-
-# Store to a specific profile without switching
-slm remember "Acme uses Aurora PostgreSQL" --profile client-acme
-```
-
-## How Profiles Work Internally
-
-Each profile stores memories in the same SQLite database but with a profile identifier on every row. Queries are filtered by profile at the database level, ensuring complete isolation.
-
-The entity graph, BM25 index, and all math layer state are also per-profile. Building the graph for one profile does not affect another.
-
-## Limits
-
-- No hard limit on the number of profiles
-- Each profile adds minimal overhead (a few KB for metadata)
-- Performance is determined by per-profile memory count, not total profiles
-- Switching profiles is instant (no data loading required)
-
----
-
-*SuperLocalMemory V3 — Copyright 2026 Varun Pratap Bhardwaj. Elastic License 2.0. Part of Qualixar.*

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)