superlocalmemory 3.4.9 → 3.4.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -3
- package/docs/cloud-backup.md +174 -0
- package/docs/skill-evolution.md +256 -0
- package/ide/hooks/tool-event-hook.sh +101 -11
- package/package.json +1 -1
- package/pyproject.toml +3 -2
- package/src/superlocalmemory/cli/commands.py +359 -0
- package/src/superlocalmemory/cli/ingest_cmd.py +81 -29
- package/src/superlocalmemory/cli/main.py +32 -0
- package/src/superlocalmemory/cli/setup_wizard.py +54 -11
- package/src/superlocalmemory/core/config.py +35 -0
- package/src/superlocalmemory/core/consolidation_engine.py +138 -0
- package/src/superlocalmemory/core/embedding_worker.py +1 -1
- package/src/superlocalmemory/core/engine.py +19 -0
- package/src/superlocalmemory/core/fact_consolidator.py +425 -0
- package/src/superlocalmemory/core/graph_pruner.py +290 -0
- package/src/superlocalmemory/core/maintenance_scheduler.py +44 -3
- package/src/superlocalmemory/core/recall_pipeline.py +9 -0
- package/src/superlocalmemory/core/tier_manager.py +325 -0
- package/src/superlocalmemory/encoding/entity_resolver.py +96 -28
- package/src/superlocalmemory/evolution/__init__.py +29 -0
- package/src/superlocalmemory/evolution/blind_verifier.py +115 -0
- package/src/superlocalmemory/evolution/evolution_store.py +302 -0
- package/src/superlocalmemory/evolution/mutation_generator.py +181 -0
- package/src/superlocalmemory/evolution/skill_evolver.py +555 -0
- package/src/superlocalmemory/evolution/triggers.py +367 -0
- package/src/superlocalmemory/evolution/types.py +92 -0
- package/src/superlocalmemory/hooks/hook_handlers.py +13 -0
- package/src/superlocalmemory/infra/backup.py +63 -20
- package/src/superlocalmemory/infra/cloud_backup.py +703 -0
- package/src/superlocalmemory/learning/skill_performance_miner.py +422 -0
- package/src/superlocalmemory/mcp/server.py +4 -0
- package/src/superlocalmemory/mcp/tools_evolution.py +338 -0
- package/src/superlocalmemory/retrieval/engine.py +64 -4
- package/src/superlocalmemory/retrieval/forgetting_filter.py +22 -7
- package/src/superlocalmemory/retrieval/strategy.py +2 -2
- package/src/superlocalmemory/server/routes/backup.py +512 -8
- package/src/superlocalmemory/server/routes/behavioral.py +39 -17
- package/src/superlocalmemory/server/routes/evolution.py +213 -0
- package/src/superlocalmemory/server/routes/tiers.py +195 -0
- package/src/superlocalmemory/server/unified_daemon.py +36 -5
- package/src/superlocalmemory/storage/schema_v3410.py +159 -0
- package/src/superlocalmemory/storage/schema_v3411.py +149 -0
- package/src/superlocalmemory/ui/index.html +59 -3
- package/src/superlocalmemory/ui/js/core.js +3 -0
- package/src/superlocalmemory/ui/js/lifecycle.js +83 -0
- package/src/superlocalmemory/ui/js/ng-entities.js +27 -3
- package/src/superlocalmemory/ui/js/ng-shell.js +33 -0
- package/src/superlocalmemory/ui/js/ng-skills.js +611 -0
- package/src/superlocalmemory/ui/js/settings.js +311 -1
- package/src/superlocalmemory.egg-info/PKG-INFO +16 -1
- package/src/superlocalmemory.egg-info/SOURCES.txt +18 -0
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
<h1 align="center">SuperLocalMemory V3.4</h1>
|
|
6
6
|
<p align="center"><strong>Every other AI forgets. Yours won't.</strong><br/><em>Infinite memory for Claude Code, Cursor, Windsurf & 17+ AI tools.</em></p>
|
|
7
|
-
<p align="center"><code>v3.4.
|
|
7
|
+
<p align="center"><code>v3.4.11</code> — Install once. Every session remembers the last. Automatically.</p>
|
|
8
8
|
<p align="center"><strong>Backed by 3 peer-reviewed research papers</strong> · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
|
|
9
9
|
|
|
10
10
|
<p align="center">
|
|
@@ -378,6 +378,21 @@ Auto-capture hooks: `slm hooks install` + `slm observe` + `slm session-context`.
|
|
|
378
378
|
- Auto-learned soft prompts injected into agent context
|
|
379
379
|
- Behavioral pattern detection and outcome tracking
|
|
380
380
|
|
|
381
|
+
### Skill Evolution
|
|
382
|
+
- **Per-skill performance tracking** — tracks which skills succeed and fail across sessions (zero-LLM, always on)
|
|
383
|
+
- **Evolution engine** — 3-trigger system with blind verification. Off by default — enable via `slm config set evolution.enabled true`
|
|
384
|
+
- **MCP tools** — `evolve_skill`, `skill_health`, `skill_lineage` for programmatic access
|
|
385
|
+
- **Lineage DAG** — visual evolution history in the dashboard
|
|
386
|
+
- **CLI config** — `slm config get/set` for all evolution settings
|
|
387
|
+
- **Post-session triggers** — automatic analysis on session end via Stop hook
|
|
388
|
+
- **[ECC](https://github.com/affaan-m/everything-claude-code) integration** — optional enhanced observations via `slm ingest --source ecc`
|
|
389
|
+
|
|
390
|
+
### Tiered Storage & Scaling
|
|
391
|
+
- **4-tier lifecycle** — active, warm, cold, archived with automatic promotion/demotion
|
|
392
|
+
- **Deep recall** — archived facts searchable at reduced weight
|
|
393
|
+
- **Graph pruning** — automatic cleanup of orphan edges, self-loops, duplicates
|
|
394
|
+
- **Fact consolidation** — clusters related facts into consolidated summaries
|
|
395
|
+
|
|
381
396
|
### Trust & Security
|
|
382
397
|
- Bayesian Beta-distribution trust scoring (per-agent, per-fact)
|
|
383
398
|
- Trust gates (block low-trust agents from writing/deleting)
|
|
@@ -387,9 +402,9 @@ Auto-capture hooks: `slm hooks install` + `slm observe` + `slm session-context`.
|
|
|
387
402
|
### Infrastructure
|
|
388
403
|
- 23-tab web dashboard with real-time visualization
|
|
389
404
|
- 17+ IDE integrations (Claude, Cursor, Windsurf, VS Code, JetBrains, Zed, etc.)
|
|
390
|
-
-
|
|
405
|
+
- 38 MCP tools + 7 MCP resources
|
|
391
406
|
- Profile isolation (independent memory spaces)
|
|
392
|
-
-
|
|
407
|
+
- 2,900+ tests, AGPL v3, cross-platform (Mac/Linux/Windows)
|
|
393
408
|
- CPU-only — no GPU required
|
|
394
409
|
- Automatic orphaned process cleanup
|
|
395
410
|
|
|
@@ -508,6 +523,11 @@ Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar.
|
|
|
508
523
|
|
|
509
524
|
Part of [Qualixar](https://qualixar.com) · Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
|
|
510
525
|
|
|
526
|
+
### Acknowledgments
|
|
527
|
+
|
|
528
|
+
- **[Everything Claude Code (ECC)](https://github.com/affaan-m/everything-claude-code)** — SLM's skill observation patterns were inspired by ECC's continuous learning architecture. SLM supports direct ingestion of ECC observations via `slm ingest --source ecc`, giving ECC users richer skill performance tracking. We recommend ECC for Claude Code users who want the deepest learning experience alongside SLM.
|
|
529
|
+
- **[HKUDS/OpenSpace](https://github.com/HKUDS/OpenSpace)** — The skill evolution research in SLM draws from the EvoSkills co-evolutionary verification concepts (arXiv:2604.01687). We adopted their 3-trigger evolution system and anti-loop guard patterns.
|
|
530
|
+
|
|
511
531
|
---
|
|
512
532
|
|
|
513
533
|
<p align="center">
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Cloud Backup — Google Drive & GitHub
|
|
2
|
+
|
|
3
|
+
SuperLocalMemory v3.4.10+ can automatically back up your memory databases to **Google Drive** and **GitHub**. All credentials are stored in your OS keychain (macOS Keychain, Windows Credential Locker, or Linux Secret Service) — never in plaintext.
|
|
4
|
+
|
|
5
|
+
## GitHub Backup (Recommended)
|
|
6
|
+
|
|
7
|
+
GitHub backup works out of the box. No additional setup needed beyond a Personal Access Token.
|
|
8
|
+
|
|
9
|
+
### Setup (2 minutes)
|
|
10
|
+
|
|
11
|
+
1. Open the SLM Dashboard: `http://localhost:8765`
|
|
12
|
+
2. Click the **account widget** in the sidebar (bottom), then click the **GitHub icon**
|
|
13
|
+
3. You'll see the "Connect GitHub" form:
|
|
14
|
+
|
|
15
|
+
- **Personal Access Token**: Click [Create one here](https://github.com/settings/tokens/new?scopes=repo&description=SLM+Backup) — this opens GitHub with the `repo` scope pre-selected. Click "Generate token" and copy it.
|
|
16
|
+
- **Repository Name**: Default is `slm-backup`. Change if you want.
|
|
17
|
+
|
|
18
|
+
4. Click **Connect**
|
|
19
|
+
|
|
20
|
+
That's it. SLM will:
|
|
21
|
+
- Verify your token
|
|
22
|
+
- Create a **private** repository (always private — your data is never public)
|
|
23
|
+
- Initialize it with a README
|
|
24
|
+
- Show your GitHub avatar and username in the sidebar
|
|
25
|
+
|
|
26
|
+
### How It Works
|
|
27
|
+
|
|
28
|
+
- Each backup creates a **GitHub Release** with your database files as assets
|
|
29
|
+
- ALL databases are included: memory.db, learning.db, audit_chain.db, code_graph.db, pending.db
|
|
30
|
+
- Only the last **5 releases** are kept — older ones are automatically deleted to prevent storage bloat
|
|
31
|
+
- Backups run in the background — the dashboard never freezes
|
|
32
|
+
|
|
33
|
+
### Restoring from GitHub
|
|
34
|
+
|
|
35
|
+
1. Go to your `slm-backup` repo on GitHub
|
|
36
|
+
2. Click **Releases** in the sidebar
|
|
37
|
+
3. Download the `.db` files from the latest release
|
|
38
|
+
4. Copy them to `~/.superlocalmemory/`
|
|
39
|
+
5. Run `slm restart`
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Google Drive Backup
|
|
44
|
+
|
|
45
|
+
Google Drive backup requires a one-time OAuth client setup through Google Cloud Console. This is a Google requirement for any application that accesses Drive on behalf of users.
|
|
46
|
+
|
|
47
|
+
### Why Is This Needed?
|
|
48
|
+
|
|
49
|
+
Google requires every application to register an "OAuth client" before it can access your Drive. This is a security measure — it ensures you know exactly which application is accessing your data. For GitHub, a simple Personal Access Token is enough, but Google's security model is stricter.
|
|
50
|
+
|
|
51
|
+
### Setup (5 minutes)
|
|
52
|
+
|
|
53
|
+
#### Step 1: Create a Google Cloud Project
|
|
54
|
+
|
|
55
|
+
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
|
56
|
+
2. Click the project dropdown (top bar) → **New Project**
|
|
57
|
+
3. Name it anything (e.g., `slm-backup`) → **Create**
|
|
58
|
+
4. Select the new project from the dropdown
|
|
59
|
+
|
|
60
|
+
#### Step 2: Enable APIs
|
|
61
|
+
|
|
62
|
+
1. Go to **APIs & Services** → **Library**
|
|
63
|
+
2. Search for and enable:
|
|
64
|
+
- **Google Drive API**
|
|
65
|
+
- **People API** (for showing your email/name)
|
|
66
|
+
|
|
67
|
+
#### Step 3: Configure OAuth Consent Screen
|
|
68
|
+
|
|
69
|
+
1. Go to **APIs & Services** → **OAuth consent screen**
|
|
70
|
+
2. Select **External** → **Create**
|
|
71
|
+
3. Fill in:
|
|
72
|
+
- **App name**: `SuperLocalMemory` (or anything)
|
|
73
|
+
- **User support email**: your Gmail
|
|
74
|
+
- **Developer contact email**: your Gmail
|
|
75
|
+
4. Click **Save and Continue** through the remaining steps
|
|
76
|
+
5. Go to **Test users** → **Add users** → add your Gmail address
|
|
77
|
+
|
|
78
|
+
#### Step 4: Create OAuth Client
|
|
79
|
+
|
|
80
|
+
1. Go to **APIs & Services** → **Credentials**
|
|
81
|
+
2. Click **Create Credentials** → **OAuth client ID**
|
|
82
|
+
3. Application type: **Web application**
|
|
83
|
+
4. Name: `SLM Dashboard` (or anything)
|
|
84
|
+
5. Under **Authorized redirect URIs**, add:
|
|
85
|
+
```
|
|
86
|
+
http://localhost:8765/api/backup/oauth/google/callback
|
|
87
|
+
```
|
|
88
|
+
6. Click **Create**
|
|
89
|
+
7. Copy the **Client ID** and **Client Secret** (you'll need both)
|
|
90
|
+
|
|
91
|
+
#### Step 5: Connect in SLM
|
|
92
|
+
|
|
93
|
+
1. Open the SLM Dashboard: `http://localhost:8765`
|
|
94
|
+
2. Click the **Google icon** in the sidebar account widget
|
|
95
|
+
3. Paste your **Client ID** and **Client Secret**
|
|
96
|
+
4. Click **Save & Connect Google Drive**
|
|
97
|
+
5. Google's login page opens — sign in and click **Allow**
|
|
98
|
+
6. You'll see "Google Drive Connected!" — close the popup
|
|
99
|
+
|
|
100
|
+
### How It Works
|
|
101
|
+
|
|
102
|
+
- Backups are uploaded to a `SLM-Backup` folder in your Google Drive
|
|
103
|
+
- Files are **replaced in-place** (no duplicates, no storage bloat)
|
|
104
|
+
- ALL databases are backed up, not just memory.db
|
|
105
|
+
- Your OAuth credentials are stored in your OS keychain
|
|
106
|
+
- Backups run in the background
|
|
107
|
+
|
|
108
|
+
### Restoring from Google Drive
|
|
109
|
+
|
|
110
|
+
1. Open Google Drive → `SLM-Backup` folder
|
|
111
|
+
2. Download all `.db` files
|
|
112
|
+
3. Copy them to `~/.superlocalmemory/`
|
|
113
|
+
4. Run `slm restart`
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Sync & Schedule
|
|
118
|
+
|
|
119
|
+
### Manual Sync
|
|
120
|
+
|
|
121
|
+
Click **Sync Now** (cloud upload icon) in the sidebar account widget, or go to **Settings** → **Cloud Backup** → **Sync Now**.
|
|
122
|
+
|
|
123
|
+
### Auto-Backup
|
|
124
|
+
|
|
125
|
+
SLM automatically creates local backups on a schedule (default: weekly). When cloud destinations are connected, backups are also pushed to the cloud after each auto-backup.
|
|
126
|
+
|
|
127
|
+
Configure the schedule in **Settings** → **Backup Configuration**:
|
|
128
|
+
- **Interval**: Daily or Weekly
|
|
129
|
+
- **Max backups**: How many local backups to keep (default: 10)
|
|
130
|
+
|
|
131
|
+
### Export
|
|
132
|
+
|
|
133
|
+
Click the **download icon** in the sidebar to export a compressed `.gz` backup file you can store anywhere.
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## What Gets Backed Up
|
|
138
|
+
|
|
139
|
+
| Database | Contents | Typical Size |
|
|
140
|
+
|---|---|---|
|
|
141
|
+
| `memory.db` | Facts, entities, graph edges, embeddings, sessions | 50 MB — 2 GB |
|
|
142
|
+
| `learning.db` | Learning signals, behavioral patterns, ranker data | 0.5 — 5 MB |
|
|
143
|
+
| `audit_chain.db` | Audit trail, compliance provenance | 0.5 — 2 MB |
|
|
144
|
+
| `code_graph.db` | Code knowledge graph (if used) | 0.1 — 10 MB |
|
|
145
|
+
| `pending.db` | Pending operations queue | 0.1 — 1 MB |
|
|
146
|
+
|
|
147
|
+
All databases are backed up using SQLite's `sqlite3.backup()` API, which creates a consistent, atomic snapshot even while the daemon is running.
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Security
|
|
152
|
+
|
|
153
|
+
- **GitHub repos are always private** — hardcoded, cannot be changed
|
|
154
|
+
- **Credentials stored in OS keychain** — macOS Keychain, Windows Credential Locker, or Linux Secret Service
|
|
155
|
+
- **Fallback**: On systems without a keychain (headless Linux), credentials are stored in `~/.superlocalmemory/.credentials.json` with `chmod 0600` (owner-only)
|
|
156
|
+
- **Google OAuth tokens** are refresh tokens — they can be revoked from your [Google Account Security page](https://myaccount.google.com/permissions)
|
|
157
|
+
- **GitHub PATs** can be revoked from [GitHub Settings → Tokens](https://github.com/settings/tokens)
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Troubleshooting
|
|
162
|
+
|
|
163
|
+
### "Sync failed" in the sidebar
|
|
164
|
+
Check the destination status in **Settings** → **Cloud Backup**. Common causes:
|
|
165
|
+
- GitHub: PAT expired or revoked → reconnect with a new token
|
|
166
|
+
- Google: OAuth token expired → click "Connect Google Drive" again to re-authorize
|
|
167
|
+
|
|
168
|
+
### Google Drive shows "Connection Failed"
|
|
169
|
+
- Make sure you added yourself as a **test user** in the OAuth consent screen
|
|
170
|
+
- Verify the redirect URI matches exactly: `http://localhost:8765/api/backup/oauth/google/callback`
|
|
171
|
+
- Check that the SLM daemon is running on port 8765
|
|
172
|
+
|
|
173
|
+
### Dashboard freezes during sync
|
|
174
|
+
This was fixed in v3.4.10 — syncs now run in a background thread. If you're on an older version, update: `pip install -U superlocalmemory`
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# Skill Evolution — SuperLocalMemory
|
|
2
|
+
|
|
3
|
+
> Track, analyze, and evolve your AI agent skills automatically.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## What Is Skill Evolution?
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
**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.
|
|
12
|
+
|
|
13
|
+
**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.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## How It Works
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
Your session
|
|
21
|
+
│
|
|
22
|
+
│ SLM hook captures every tool call (enriched: input, output, session, project)
|
|
23
|
+
▼
|
|
24
|
+
tool_events table (rich execution data)
|
|
25
|
+
│
|
|
26
|
+
│ SkillPerformanceMiner runs during consolidation
|
|
27
|
+
▼
|
|
28
|
+
Per-skill metrics + behavioral assertions + skill entities
|
|
29
|
+
│
|
|
30
|
+
│ Next session's soft prompts include skill routing recommendations
|
|
31
|
+
▼
|
|
32
|
+
Smarter skill selection, session by session
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Three Data Sources
|
|
36
|
+
|
|
37
|
+
| Source | What It Captures | Cost |
|
|
38
|
+
|--------|-----------------|------|
|
|
39
|
+
| **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 |
|
|
40
|
+
| **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 |
|
|
41
|
+
| **Consolidation Pipeline** | Mines tool_events for patterns, creates assertions, updates skill entities | Zero — statistical analysis only |
|
|
42
|
+
|
|
43
|
+
### What Gets Tracked Per Skill
|
|
44
|
+
|
|
45
|
+
| Metric | Description |
|
|
46
|
+
|--------|-------------|
|
|
47
|
+
| **Invocation count** | How many times the skill was used |
|
|
48
|
+
| **Effective score** | Approximate success rate based on execution trace analysis |
|
|
49
|
+
| **Session count** | How many sessions used this skill |
|
|
50
|
+
| **Skill correlations** | Which skills are frequently used together |
|
|
51
|
+
|
|
52
|
+
### Outcome Heuristic
|
|
53
|
+
|
|
54
|
+
SLM uses a conservative, approximate heuristic to determine if a skill invocation was effective:
|
|
55
|
+
|
|
56
|
+
| Signal | Type | What It Means |
|
|
57
|
+
|--------|------|---------------|
|
|
58
|
+
| Productive tools follow (Edit, Write, Bash success) | Positive | Skill likely helped |
|
|
59
|
+
| Same skill re-invoked within 5 minutes | Negative | Likely retry = failure |
|
|
60
|
+
| Bash errors in next 3 tool events | Negative | Something went wrong |
|
|
61
|
+
| Session continues 10+ events | Weak positive | User stayed engaged |
|
|
62
|
+
|
|
63
|
+
These signals are labeled as **approximate** everywhere. They inform soft prompt routing but do not trigger automatic changes without human review.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Dashboard: Skill Evolution Tab
|
|
68
|
+
|
|
69
|
+
The dedicated **Skill Evolution** tab in the SLM dashboard shows:
|
|
70
|
+
|
|
71
|
+
- **Overview cards** — Total skill events, unique skills, performance assertions, skill correlations
|
|
72
|
+
- **Skill performance cards** — Per-skill effective score, invocation count, confidence level
|
|
73
|
+
- **Evolution Engine status** — Backend detection, enable/disable toggle, run button
|
|
74
|
+
- **Skill Lineage DAG** — Visual graph of evolved skill versions (parent → child relationships)
|
|
75
|
+
- **Lineage table** — Clickable rows showing evolution type, status, verification result
|
|
76
|
+
- **Skill correlations** — Which skills work well together
|
|
77
|
+
|
|
78
|
+
Access: Open `http://localhost:8765` and navigate to the Skill Evolution tab in the sidebar.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## IDE Compatibility
|
|
83
|
+
|
|
84
|
+
| IDE | Status | How |
|
|
85
|
+
|-----|--------|-----|
|
|
86
|
+
| **Claude Code** | Supported | SLM hook auto-registered via `slm init` |
|
|
87
|
+
| **Cursor** | Planned | Adapter needed |
|
|
88
|
+
| **Windsurf** | Planned | Adapter needed |
|
|
89
|
+
| **VS Code Copilot** | Planned | Extension events adapter needed |
|
|
90
|
+
| **JetBrains** | Planned | Adapter needed |
|
|
91
|
+
| **Any IDE** | API available | POST to `/api/v3/tool-event` directly |
|
|
92
|
+
|
|
93
|
+
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.
|
|
94
|
+
|
|
95
|
+
### API Endpoint
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
POST http://localhost:8765/api/v3/tool-event
|
|
99
|
+
Content-Type: application/json
|
|
100
|
+
|
|
101
|
+
{
|
|
102
|
+
"tool_name": "Skill",
|
|
103
|
+
"event_type": "complete",
|
|
104
|
+
"input_summary": "{\"skill\": \"my-skill-name\", \"args\": \"...\"}",
|
|
105
|
+
"output_summary": "{\"success\": true}",
|
|
106
|
+
"session_id": "your-session-id",
|
|
107
|
+
"project_path": "/path/to/project"
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
All fields except `tool_name` are optional. Existing integrations that send only `tool_name` + `event_type` continue to work.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## ECC Integration
|
|
116
|
+
|
|
117
|
+
[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.
|
|
118
|
+
|
|
119
|
+
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:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
# One-time import of existing ECC observations
|
|
123
|
+
slm ingest --source ecc
|
|
124
|
+
|
|
125
|
+
# Preview without writing (dry run)
|
|
126
|
+
slm ingest --source ecc --dry-run
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
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.
|
|
130
|
+
|
|
131
|
+
**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.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Configuration
|
|
136
|
+
|
|
137
|
+
### Skill Tracking (C1 — always on)
|
|
138
|
+
|
|
139
|
+
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.
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
slm status # Shows hook registration status
|
|
143
|
+
slm consolidate --cognitive # Trigger manual consolidation
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### Skill Evolution (C2 — off by default)
|
|
147
|
+
|
|
148
|
+
The Skill Evolution Engine uses LLM calls to generate improved skill versions. **It is OFF by default** — end users must opt in.
|
|
149
|
+
|
|
150
|
+
**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.
|
|
151
|
+
|
|
152
|
+
#### Enable via CLI
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
slm config set evolution.enabled true
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
#### Enable via Interactive Installer
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
slm setup # Interactive wizard includes evolution opt-in
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
#### Enable via Dashboard
|
|
165
|
+
|
|
166
|
+
Navigate to Settings → Skill Evolution → Enable.
|
|
167
|
+
|
|
168
|
+
### LLM Backend — Auto-Detect
|
|
169
|
+
|
|
170
|
+
Evolution uses a single auto-detect chain. No manual configuration needed for most users:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
Priority 1: `claude` CLI available → spawn `claude --model haiku` (FREE, best quality)
|
|
174
|
+
Priority 2: Ollama running → use Ollama (FREE, local)
|
|
175
|
+
Priority 3: API key set → use Anthropic/OpenAI API (paid)
|
|
176
|
+
Priority 4: Nothing available → dashboard-only (show candidates, manual evolution)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
This means:
|
|
180
|
+
- **Claude Code users:** Evolution works for free — uses your existing Claude subscription
|
|
181
|
+
- **Other IDE users with Ollama:** Evolution works for free — uses local Ollama
|
|
182
|
+
- **Advanced users:** Can point at Anthropic/OpenAI API if preferred
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
# Override auto-detect (optional — most users never need this)
|
|
186
|
+
slm config set evolution.backend claude
|
|
187
|
+
slm config set evolution.backend ollama
|
|
188
|
+
slm config set evolution.backend anthropic
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Full Evolution Config Reference
|
|
192
|
+
|
|
193
|
+
| Key | Default | Description |
|
|
194
|
+
|-----|---------|-------------|
|
|
195
|
+
| `evolution.enabled` | `false` | Master switch — off by default, opt-in |
|
|
196
|
+
| `evolution.backend` | `auto` | LLM backend: `auto`, `claude`, `ollama`, `anthropic`, `openai` |
|
|
197
|
+
| `evolution.max_evolutions_per_cycle` | `3` | Budget cap per consolidation cycle |
|
|
198
|
+
|
|
199
|
+
### Tracking Thresholds (C1)
|
|
200
|
+
|
|
201
|
+
| Parameter | Default | Description |
|
|
202
|
+
|-----------|---------|-------------|
|
|
203
|
+
| MIN_INVOCATIONS | 5 | Minimum uses before creating assertions |
|
|
204
|
+
| MIN_CONFIDENCE | 0.5 | Minimum confidence for soft prompt injection |
|
|
205
|
+
| TRACE_WINDOW | 10 | Tool events to analyze after each Skill call |
|
|
206
|
+
| RETRY_WINDOW | 300s | Same Skill within this window = potential retry |
|
|
207
|
+
|
|
208
|
+
These are conservative by design — we'd rather miss a pattern than hallucinate one.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## Research Foundations
|
|
213
|
+
|
|
214
|
+
SLM's skill evolution system draws from:
|
|
215
|
+
|
|
216
|
+
- **[EvoSkills](https://arxiv.org/abs/2604.01687)** (HKUDS, 2026) — Co-evolutionary verification with information isolation. +30pp improvement from blind verification.
|
|
217
|
+
- **[OpenSpace](https://github.com/HKUDS/OpenSpace)** (HKUDS, MIT) — 3-trigger evolution system (post-analysis + tool degradation + metric monitor). Anti-loop guards. Version DAG model.
|
|
218
|
+
- **[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.
|
|
219
|
+
- **[SoK: Agent Skills](https://arxiv.org/abs/2602.12430)** (2026) — Four-axis taxonomy. Skills and MCP are orthogonal layers.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## MCP Tools
|
|
224
|
+
|
|
225
|
+
Three MCP tools are available for programmatic access:
|
|
226
|
+
|
|
227
|
+
| Tool | Description |
|
|
228
|
+
|------|-------------|
|
|
229
|
+
| `evolve_skill` | Manually trigger evolution for a specific skill |
|
|
230
|
+
| `skill_health` | Get health metrics (invocations, error rate, status) for skills |
|
|
231
|
+
| `skill_lineage` | Get evolution lineage tree for a skill |
|
|
232
|
+
|
|
233
|
+
These tools are registered automatically and available in all supported IDEs.
|
|
234
|
+
|
|
235
|
+
## CLI Commands
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
slm config get evolution.enabled # Check if evolution is enabled
|
|
239
|
+
slm config set evolution.enabled true # Enable evolution
|
|
240
|
+
slm config set evolution.backend auto # Set LLM backend
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
## What's Next
|
|
244
|
+
|
|
245
|
+
- **IDE Adapters** — Cursor, Windsurf, VS Code Copilot, JetBrains support for skill tracking.
|
|
246
|
+
- **Skill lineage visualization improvements** — Richer DAG with performance history overlay.
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## Links
|
|
251
|
+
|
|
252
|
+
- [SLM GitHub](https://github.com/qualixar/superlocalmemory)
|
|
253
|
+
- [Qualixar](https://qualixar.com)
|
|
254
|
+
- [Everything Claude Code](https://github.com/affaan-m/everything-claude-code)
|
|
255
|
+
- [OpenSpace](https://github.com/HKUDS/OpenSpace)
|
|
256
|
+
- [EvoSkills Paper](https://arxiv.org/abs/2604.01687)
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env bash
|
|
2
|
-
# SuperLocalMemory V3.4.
|
|
2
|
+
# SuperLocalMemory V3.4.10 — Enriched Tool Event Learning Hook
|
|
3
3
|
# Copyright (c) 2026 Varun Pratap Bhardwaj
|
|
4
4
|
# Licensed under AGPL-3.0-or-later
|
|
5
5
|
#
|
|
6
|
-
# PostToolUse hook that logs tool events to SLM for behavioral learning.
|
|
7
|
-
#
|
|
8
|
-
#
|
|
6
|
+
# PostToolUse hook that logs RICH tool events to SLM for behavioral learning.
|
|
7
|
+
# Captures: tool_name, input_summary (500 chars), output_summary (500 chars),
|
|
8
|
+
# session_id, project_path. Scrubs secrets before storing.
|
|
9
|
+
#
|
|
10
|
+
# Modeled after ECC observe.sh patterns — SLM is self-sufficient for observation.
|
|
11
|
+
# An end user with only SLM (no ECC) gets full learning quality.
|
|
9
12
|
#
|
|
10
13
|
# Installation: slm init (auto-registers) or manually add to settings.json:
|
|
11
14
|
# { "type": "PostToolUse", "matcher": "*",
|
|
@@ -17,8 +20,26 @@ set -euo pipefail
|
|
|
17
20
|
# Read stdin (Claude Code passes JSON with tool_name, input, output)
|
|
18
21
|
INPUT=$(cat)
|
|
19
22
|
|
|
20
|
-
#
|
|
21
|
-
|
|
23
|
+
# Exit if no input
|
|
24
|
+
if [ -z "$INPUT" ]; then
|
|
25
|
+
exit 0
|
|
26
|
+
fi
|
|
27
|
+
|
|
28
|
+
# Extract tool name (lightweight — bash-only fallback if python unavailable)
|
|
29
|
+
TOOL_NAME=""
|
|
30
|
+
if command -v python3 >/dev/null 2>&1; then
|
|
31
|
+
PYTHON_CMD="python3"
|
|
32
|
+
elif command -v python >/dev/null 2>&1; then
|
|
33
|
+
PYTHON_CMD="python"
|
|
34
|
+
else
|
|
35
|
+
# No python — fallback to basic extraction
|
|
36
|
+
TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' 2>/dev/null || echo "unknown")
|
|
37
|
+
PYTHON_CMD=""
|
|
38
|
+
fi
|
|
39
|
+
|
|
40
|
+
# Skip logging for our own tools (avoid recursion)
|
|
41
|
+
if [ -n "$PYTHON_CMD" ]; then
|
|
42
|
+
TOOL_NAME=$(echo "$INPUT" | "$PYTHON_CMD" -c "
|
|
22
43
|
import sys, json
|
|
23
44
|
try:
|
|
24
45
|
d = json.load(sys.stdin)
|
|
@@ -26,10 +47,11 @@ try:
|
|
|
26
47
|
except:
|
|
27
48
|
print('unknown')
|
|
28
49
|
" 2>/dev/null || echo "unknown")
|
|
50
|
+
fi
|
|
29
51
|
|
|
30
|
-
# Skip logging for our own tools (avoid recursion)
|
|
31
52
|
case "$TOOL_NAME" in
|
|
32
|
-
log_tool_event|get_assertions|reinforce_assertion|contradict_assertion
|
|
53
|
+
log_tool_event|get_assertions|reinforce_assertion|contradict_assertion|\
|
|
54
|
+
mcp__superlocalmemory__*|session_init|recall|remember|observe|mesh_*)
|
|
33
55
|
exit 0
|
|
34
56
|
;;
|
|
35
57
|
esac
|
|
@@ -39,8 +61,76 @@ PORT=8765
|
|
|
39
61
|
PORT_FILE="$HOME/.superlocalmemory/daemon.port"
|
|
40
62
|
[ -f "$PORT_FILE" ] && PORT=$(cat "$PORT_FILE" 2>/dev/null || echo 8765)
|
|
41
63
|
|
|
42
|
-
#
|
|
43
|
-
|
|
64
|
+
# If no python, send basic event (backward compatible)
|
|
65
|
+
if [ -z "$PYTHON_CMD" ]; then
|
|
66
|
+
curl -s -m 2 -X POST "http://127.0.0.1:${PORT}/api/v3/tool-event" \
|
|
67
|
+
-H "Content-Type: application/json" \
|
|
68
|
+
-d "{\"tool_name\": \"${TOOL_NAME}\", \"event_type\": \"complete\"}" \
|
|
69
|
+
>/dev/null 2>&1 || true
|
|
70
|
+
exit 0
|
|
71
|
+
fi
|
|
72
|
+
|
|
73
|
+
# Parse full JSON and build enriched payload (with secret scrubbing)
|
|
74
|
+
ENRICHED=$(echo "$INPUT" | "$PYTHON_CMD" -c '
|
|
75
|
+
import json, sys, os, re
|
|
76
|
+
|
|
77
|
+
# Secret scrubbing pattern (adopted from ECC observe.sh)
|
|
78
|
+
_SECRET_RE = re.compile(
|
|
79
|
+
r"(?i)(api[_-]?key|[a-z_]*_key|token|secret|password|pass\b|authorization|credentials?|auth)"
|
|
80
|
+
r"""([\"'"'"'"'"'"'\s:=]+)"""
|
|
81
|
+
r"([A-Za-z]+\s+)?"
|
|
82
|
+
r"([A-Za-z0-9_\-/.+=]{8,})"
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
def scrub(val, max_len=500):
|
|
86
|
+
"""Scrub secrets first, then truncate."""
|
|
87
|
+
if val is None:
|
|
88
|
+
return ""
|
|
89
|
+
if isinstance(val, dict):
|
|
90
|
+
s = json.dumps(val, default=str)
|
|
91
|
+
elif isinstance(val, list):
|
|
92
|
+
s = json.dumps(val, default=str)
|
|
93
|
+
else:
|
|
94
|
+
s = str(val)
|
|
95
|
+
s = _SECRET_RE.sub(
|
|
96
|
+
lambda m: m.group(1) + m.group(2) + (m.group(3) or "") + "[REDACTED]", s
|
|
97
|
+
)
|
|
98
|
+
return s[:max_len]
|
|
99
|
+
|
|
100
|
+
try:
|
|
101
|
+
data = json.load(sys.stdin)
|
|
102
|
+
|
|
103
|
+
tool_name = data.get("tool_name", data.get("tool", "unknown"))
|
|
104
|
+
|
|
105
|
+
# Extract input — Claude Code uses tool_input or input
|
|
106
|
+
raw_input = data.get("tool_input", data.get("input", ""))
|
|
107
|
+
input_summary = scrub(raw_input, 500)
|
|
108
|
+
|
|
109
|
+
# Extract output — Claude Code uses tool_response, tool_output, or output
|
|
110
|
+
raw_output = data.get("tool_response")
|
|
111
|
+
if raw_output is None:
|
|
112
|
+
raw_output = data.get("tool_output", data.get("output", ""))
|
|
113
|
+
output_summary = scrub(raw_output, 500)
|
|
114
|
+
|
|
115
|
+
session_id = data.get("session_id", "")
|
|
116
|
+
project_path = data.get("cwd", "")
|
|
117
|
+
|
|
118
|
+
payload = {
|
|
119
|
+
"tool_name": tool_name,
|
|
120
|
+
"event_type": "complete",
|
|
121
|
+
"input_summary": input_summary,
|
|
122
|
+
"output_summary": output_summary,
|
|
123
|
+
"session_id": session_id,
|
|
124
|
+
"project_path": project_path,
|
|
125
|
+
}
|
|
126
|
+
print(json.dumps(payload))
|
|
127
|
+
except Exception:
|
|
128
|
+
# Fallback — send basic event
|
|
129
|
+
print(json.dumps({"tool_name": "unknown", "event_type": "complete"}))
|
|
130
|
+
' 2>/dev/null || echo '{"tool_name":"unknown","event_type":"complete"}')
|
|
131
|
+
|
|
132
|
+
# Send enriched event to SLM daemon (fire and forget, 2s timeout)
|
|
133
|
+
echo "$ENRICHED" | curl -s -m 2 -X POST "http://127.0.0.1:${PORT}/api/v3/tool-event" \
|
|
44
134
|
-H "Content-Type: application/json" \
|
|
45
|
-
-d
|
|
135
|
+
-d @- \
|
|
46
136
|
>/dev/null 2>&1 || true
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "superlocalmemory",
|
|
3
|
-
"version": "3.4.
|
|
3
|
+
"version": "3.4.11",
|
|
4
4
|
"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.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai-memory",
|
package/pyproject.toml
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "superlocalmemory"
|
|
3
|
-
version = "3.4.
|
|
3
|
+
version = "3.4.11"
|
|
4
4
|
description = "Information-geometric agent memory with mathematical guarantees"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = {text = "AGPL-3.0-or-later"}
|
|
@@ -112,8 +112,9 @@ superlocalmemory = ["ui/**/*"]
|
|
|
112
112
|
[tool.pytest.ini_options]
|
|
113
113
|
testpaths = ["tests"]
|
|
114
114
|
pythonpath = ["src"]
|
|
115
|
+
addopts = "-m 'not slow and not ollama'"
|
|
115
116
|
markers = [
|
|
116
|
-
"slow: marks tests as slow (
|
|
117
|
+
"slow: marks tests as slow — real engine/model loading (run with: pytest -m slow)",
|
|
117
118
|
"ollama: marks tests that require a running Ollama instance",
|
|
118
119
|
]
|
|
119
120
|
filterwarnings = [
|