superlocalmemory 2.7.6 → 2.8.0
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/CHANGELOG.md +120 -155
- package/README.md +115 -89
- package/api_server.py +2 -12
- package/docs/PATTERN-LEARNING.md +64 -199
- package/docs/example_graph_usage.py +4 -6
- package/install.sh +59 -0
- package/mcp_server.py +83 -7
- package/package.json +1 -8
- package/scripts/generate-thumbnails.py +3 -5
- package/skills/slm-build-graph/SKILL.md +1 -1
- package/skills/slm-list-recent/SKILL.md +1 -1
- package/skills/slm-recall/SKILL.md +1 -1
- package/skills/slm-remember/SKILL.md +1 -1
- package/skills/slm-show-patterns/SKILL.md +1 -1
- package/skills/slm-status/SKILL.md +1 -1
- package/skills/slm-switch-profile/SKILL.md +1 -1
- package/src/agent_registry.py +7 -18
- package/src/auth_middleware.py +3 -5
- package/src/auto_backup.py +3 -7
- package/src/behavioral/__init__.py +49 -0
- package/src/behavioral/behavioral_listener.py +203 -0
- package/src/behavioral/behavioral_patterns.py +275 -0
- package/src/behavioral/cross_project_transfer.py +206 -0
- package/src/behavioral/outcome_inference.py +194 -0
- package/src/behavioral/outcome_tracker.py +193 -0
- package/src/behavioral/tests/__init__.py +4 -0
- package/src/behavioral/tests/test_behavioral_integration.py +108 -0
- package/src/behavioral/tests/test_behavioral_patterns.py +150 -0
- package/src/behavioral/tests/test_cross_project_transfer.py +142 -0
- package/src/behavioral/tests/test_mcp_behavioral.py +139 -0
- package/src/behavioral/tests/test_mcp_report_outcome.py +117 -0
- package/src/behavioral/tests/test_outcome_inference.py +107 -0
- package/src/behavioral/tests/test_outcome_tracker.py +96 -0
- package/src/cache_manager.py +4 -6
- package/src/compliance/__init__.py +48 -0
- package/src/compliance/abac_engine.py +149 -0
- package/src/compliance/abac_middleware.py +116 -0
- package/src/compliance/audit_db.py +215 -0
- package/src/compliance/audit_logger.py +148 -0
- package/src/compliance/retention_manager.py +289 -0
- package/src/compliance/retention_scheduler.py +186 -0
- package/src/compliance/tests/__init__.py +4 -0
- package/src/compliance/tests/test_abac_enforcement.py +95 -0
- package/src/compliance/tests/test_abac_engine.py +124 -0
- package/src/compliance/tests/test_abac_mcp_integration.py +118 -0
- package/src/compliance/tests/test_audit_db.py +123 -0
- package/src/compliance/tests/test_audit_logger.py +98 -0
- package/src/compliance/tests/test_mcp_audit.py +128 -0
- package/src/compliance/tests/test_mcp_retention_policy.py +125 -0
- package/src/compliance/tests/test_retention_manager.py +131 -0
- package/src/compliance/tests/test_retention_scheduler.py +99 -0
- package/src/db_connection_manager.py +2 -12
- package/src/embedding_engine.py +61 -669
- package/src/embeddings/__init__.py +47 -0
- package/src/embeddings/cache.py +70 -0
- package/src/embeddings/cli.py +113 -0
- package/src/embeddings/constants.py +47 -0
- package/src/embeddings/database.py +91 -0
- package/src/embeddings/engine.py +247 -0
- package/src/embeddings/model_loader.py +145 -0
- package/src/event_bus.py +3 -13
- package/src/graph/__init__.py +36 -0
- package/src/graph/build_helpers.py +74 -0
- package/src/graph/cli.py +87 -0
- package/src/graph/cluster_builder.py +188 -0
- package/src/graph/cluster_summary.py +148 -0
- package/src/graph/constants.py +47 -0
- package/src/graph/edge_builder.py +162 -0
- package/src/graph/entity_extractor.py +95 -0
- package/src/graph/graph_core.py +226 -0
- package/src/graph/graph_search.py +231 -0
- package/src/graph/hierarchical.py +207 -0
- package/src/graph/schema.py +99 -0
- package/src/graph_engine.py +45 -1451
- package/src/hnsw_index.py +3 -7
- package/src/hybrid_search.py +36 -683
- package/src/learning/__init__.py +27 -12
- package/src/learning/adaptive_ranker.py +50 -12
- package/src/learning/cross_project_aggregator.py +2 -12
- package/src/learning/engagement_tracker.py +2 -12
- package/src/learning/feature_extractor.py +175 -43
- package/src/learning/feedback_collector.py +7 -12
- package/src/learning/learning_db.py +180 -12
- package/src/learning/project_context_manager.py +2 -12
- package/src/learning/source_quality_scorer.py +2 -12
- package/src/learning/synthetic_bootstrap.py +2 -12
- package/src/learning/tests/__init__.py +2 -0
- package/src/learning/tests/test_adaptive_ranker.py +2 -6
- package/src/learning/tests/test_adaptive_ranker_v28.py +60 -0
- package/src/learning/tests/test_aggregator.py +2 -6
- package/src/learning/tests/test_auto_retrain_v28.py +35 -0
- package/src/learning/tests/test_e2e_ranking_v28.py +82 -0
- package/src/learning/tests/test_feature_extractor_v28.py +93 -0
- package/src/learning/tests/test_feedback_collector.py +2 -6
- package/src/learning/tests/test_learning_db.py +2 -6
- package/src/learning/tests/test_learning_db_v28.py +110 -0
- package/src/learning/tests/test_learning_init_v28.py +48 -0
- package/src/learning/tests/test_outcome_signals.py +48 -0
- package/src/learning/tests/test_project_context.py +2 -6
- package/src/learning/tests/test_schema_migration.py +319 -0
- package/src/learning/tests/test_signal_inference.py +11 -13
- package/src/learning/tests/test_source_quality.py +2 -6
- package/src/learning/tests/test_synthetic_bootstrap.py +3 -7
- package/src/learning/tests/test_workflow_miner.py +2 -6
- package/src/learning/workflow_pattern_miner.py +2 -12
- package/src/lifecycle/__init__.py +54 -0
- package/src/lifecycle/bounded_growth.py +239 -0
- package/src/lifecycle/compaction_engine.py +226 -0
- package/src/lifecycle/lifecycle_engine.py +302 -0
- package/src/lifecycle/lifecycle_evaluator.py +225 -0
- package/src/lifecycle/lifecycle_scheduler.py +130 -0
- package/src/lifecycle/retention_policy.py +285 -0
- package/src/lifecycle/tests/__init__.py +4 -0
- package/src/lifecycle/tests/test_bounded_growth.py +193 -0
- package/src/lifecycle/tests/test_compaction.py +179 -0
- package/src/lifecycle/tests/test_lifecycle_engine.py +137 -0
- package/src/lifecycle/tests/test_lifecycle_evaluation.py +177 -0
- package/src/lifecycle/tests/test_lifecycle_scheduler.py +127 -0
- package/src/lifecycle/tests/test_lifecycle_search.py +109 -0
- package/src/lifecycle/tests/test_mcp_compact.py +149 -0
- package/src/lifecycle/tests/test_mcp_lifecycle_status.py +114 -0
- package/src/lifecycle/tests/test_retention_policy.py +162 -0
- package/src/mcp_tools_v28.py +280 -0
- package/src/memory-profiles.py +2 -12
- package/src/memory-reset.py +2 -12
- package/src/memory_compression.py +2 -12
- package/src/memory_store_v2.py +76 -20
- package/src/migrate_v1_to_v2.py +2 -12
- package/src/pattern_learner.py +29 -975
- package/src/patterns/__init__.py +24 -0
- package/src/patterns/analyzers.py +247 -0
- package/src/patterns/learner.py +267 -0
- package/src/patterns/scoring.py +167 -0
- package/src/patterns/store.py +223 -0
- package/src/patterns/terminology.py +138 -0
- package/src/provenance_tracker.py +4 -14
- package/src/query_optimizer.py +4 -6
- package/src/rate_limiter.py +2 -6
- package/src/search/__init__.py +20 -0
- package/src/search/cli.py +77 -0
- package/src/search/constants.py +26 -0
- package/src/search/engine.py +239 -0
- package/src/search/fusion.py +122 -0
- package/src/search/index_loader.py +112 -0
- package/src/search/methods.py +162 -0
- package/src/search_engine_v2.py +4 -6
- package/src/setup_validator.py +7 -13
- package/src/subscription_manager.py +2 -12
- package/src/tree/__init__.py +59 -0
- package/src/tree/builder.py +183 -0
- package/src/tree/nodes.py +196 -0
- package/src/tree/queries.py +252 -0
- package/src/tree/schema.py +76 -0
- package/src/tree_manager.py +10 -711
- package/src/trust/__init__.py +45 -0
- package/src/trust/constants.py +66 -0
- package/src/trust/queries.py +157 -0
- package/src/trust/schema.py +95 -0
- package/src/trust/scorer.py +299 -0
- package/src/trust/signals.py +95 -0
- package/src/trust_scorer.py +39 -697
- package/src/webhook_dispatcher.py +2 -12
- package/ui/app.js +1 -1
- package/ui/js/agents.js +1 -1
- package/ui_server.py +2 -14
- package/ATTRIBUTION.md +0 -140
- package/docs/ARCHITECTURE-V2.5.md +0 -190
- package/docs/GRAPH-ENGINE.md +0 -503
- package/docs/architecture-diagram.drawio +0 -405
- package/docs/plans/2026-02-13-benchmark-suite.md +0 -1349
package/docs/PATTERN-LEARNING.md
CHANGED
|
@@ -1,141 +1,42 @@
|
|
|
1
|
-
# Pattern
|
|
1
|
+
# Pattern Learning
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
|
-
The Pattern Learner is Layer 4 of the SuperLocalMemory system. It automatically learns user preferences, coding style, and terminology from stored memories
|
|
5
|
+
The Pattern Learner is Layer 4 of the SuperLocalMemory system. It automatically learns user preferences, coding style, and terminology from stored memories — all processed locally with no external API calls.
|
|
6
6
|
|
|
7
7
|
**No external APIs. All processing is local.**
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
> For technical details on the learning algorithms, see our published research: https://zenodo.org/records/18709670
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
┌─────────────────────────────────────────────────────────┐
|
|
13
|
-
│ PatternLearner │
|
|
14
|
-
│ │
|
|
15
|
-
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
16
|
-
│ │ Frequency │ │ Context │ │
|
|
17
|
-
│ │ Analyzer │ │ Analyzer │ │
|
|
18
|
-
│ └──────────────────┘ └──────────────────┘ │
|
|
19
|
-
│ │
|
|
20
|
-
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
21
|
-
│ │ Terminology │ │ Confidence │ │
|
|
22
|
-
│ │ Learner │ │ Scorer │ │
|
|
23
|
-
│ └──────────────────┘ └──────────────────┘ │
|
|
24
|
-
│ │
|
|
25
|
-
│ ┌──────────────────┐ │
|
|
26
|
-
│ │ Pattern Store │ │
|
|
27
|
-
│ └──────────────────┘ │
|
|
28
|
-
└─────────────────────────────────────────────────────────┘
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Components
|
|
32
|
-
|
|
33
|
-
### 1. FrequencyAnalyzer
|
|
34
|
-
**Purpose:** Detect technology preferences via frequency counting
|
|
35
|
-
|
|
36
|
-
**Categories tracked:**
|
|
37
|
-
- Frontend frameworks (React, Next.js, Vue, Angular, Svelte)
|
|
38
|
-
- Backend frameworks (Express, FastAPI, Django, Flask)
|
|
39
|
-
- Databases (PostgreSQL, MySQL, MongoDB, Redis)
|
|
40
|
-
- State management (Redux, Context, Zustand)
|
|
41
|
-
- Styling (Tailwind, CSS Modules, Styled Components)
|
|
42
|
-
- Languages (Python, JavaScript, TypeScript, Go, Rust)
|
|
43
|
-
- Deployment (Docker, Kubernetes, Vercel, AWS)
|
|
44
|
-
- Testing (Jest, Pytest, Vitest, Cypress)
|
|
45
|
-
|
|
46
|
-
**Algorithm:**
|
|
47
|
-
1. Count keyword mentions across all memories
|
|
48
|
-
2. Calculate relative frequency (top choice vs others)
|
|
49
|
-
3. Create pattern if confidence > 60% and count >= 3
|
|
50
|
-
|
|
51
|
-
**Example output:**
|
|
52
|
-
```
|
|
53
|
-
Pattern: frontend_framework
|
|
54
|
-
Value: "Next.js over React"
|
|
55
|
-
Confidence: 85%
|
|
56
|
-
Evidence: 12 memories
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
### 2. ContextAnalyzer
|
|
60
|
-
**Purpose:** Detect coding style patterns from context
|
|
61
|
-
|
|
62
|
-
**Patterns tracked:**
|
|
63
|
-
- **Optimization priority:** Performance vs Readability
|
|
64
|
-
- **Error handling:** Explicit vs Permissive
|
|
65
|
-
- **Testing approach:** Comprehensive vs Minimal
|
|
66
|
-
- **Code organization:** Modular vs Monolithic
|
|
67
|
-
|
|
68
|
-
**Algorithm:**
|
|
69
|
-
1. Define indicator keywords for each style dimension
|
|
70
|
-
2. Count mentions in memory contexts
|
|
71
|
-
3. Determine dominant style if confidence > 65%
|
|
72
|
-
|
|
73
|
-
**Example output:**
|
|
74
|
-
```
|
|
75
|
-
Pattern: optimization_priority
|
|
76
|
-
Value: "Performance over readability"
|
|
77
|
-
Confidence: 90%
|
|
78
|
-
Evidence: 15 memories
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
### 3. TerminologyLearner
|
|
82
|
-
**Purpose:** Learn user-specific definitions of ambiguous terms
|
|
83
|
-
|
|
84
|
-
**Terms tracked:**
|
|
85
|
-
- optimize, refactor, clean, simple
|
|
86
|
-
- mvp, prototype, scale, production-ready
|
|
87
|
-
- fix, improve, update, enhance
|
|
88
|
-
|
|
89
|
-
**Algorithm:**
|
|
90
|
-
1. Extract 100-char context window around each term mention
|
|
91
|
-
2. Analyze co-occurring words across contexts
|
|
92
|
-
3. Apply heuristic rules to determine meaning
|
|
93
|
-
4. Require 3+ examples for confidence
|
|
94
|
-
|
|
95
|
-
**Example output:**
|
|
96
|
-
```
|
|
97
|
-
Pattern: optimize
|
|
98
|
-
Value: "Performance optimization (speed/latency)"
|
|
99
|
-
Confidence: 90%
|
|
100
|
-
Evidence: 15 memories
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
### 4. ConfidenceScorer
|
|
104
|
-
**Purpose:** Calculate reliability scores for patterns
|
|
11
|
+
---
|
|
105
12
|
|
|
106
|
-
|
|
107
|
-
```python
|
|
108
|
-
confidence = (evidence_count / total_memories) * recency_bonus * distribution_factor
|
|
13
|
+
## What It Learns
|
|
109
14
|
|
|
110
|
-
|
|
111
|
-
- evidence_count: Number of memories supporting pattern
|
|
112
|
-
- total_memories: Total memories in database
|
|
113
|
-
- recency_bonus: 1.2 if >50% evidence is from last 30 days, else 1.0
|
|
114
|
-
- distribution_factor: 1.1 if memories span >7 days, 0.8 if <3 memories
|
|
115
|
-
```
|
|
15
|
+
Pattern learning analyzes your saved memories and builds a profile of your preferences across multiple dimensions:
|
|
116
16
|
|
|
117
|
-
**
|
|
17
|
+
- **Technology preferences** — Which frameworks, languages, and tools appear most often in your memories
|
|
18
|
+
- **Architecture choices** — Your preferred patterns (e.g., REST vs GraphQL, microservices vs monolith)
|
|
19
|
+
- **Security approaches** — Your go-to authentication and authorization patterns
|
|
20
|
+
- **Coding style** — Performance vs readability, testing approach, code organization
|
|
21
|
+
- **Domain terminology** — How you define common terms in your project context
|
|
118
22
|
|
|
119
|
-
|
|
120
|
-
**Purpose:** Persist patterns to database
|
|
23
|
+
Each detected preference gets a confidence score based on the supporting evidence. The system is conservative by design — low confidence with small datasets is correct behavior, not a bug.
|
|
121
24
|
|
|
122
|
-
|
|
123
|
-
- `identity_patterns`: Pattern definitions with confidence scores
|
|
124
|
-
- `pattern_examples`: Representative excerpts showing patterns
|
|
25
|
+
---
|
|
125
26
|
|
|
126
27
|
## Usage
|
|
127
28
|
|
|
128
29
|
### Command Line Interface
|
|
129
30
|
|
|
130
31
|
```bash
|
|
131
|
-
# Full pattern update (run weekly)
|
|
32
|
+
# Full pattern update (run weekly or after bulk imports)
|
|
132
33
|
python pattern_learner.py update
|
|
133
34
|
|
|
134
35
|
# List learned patterns
|
|
135
36
|
python pattern_learner.py list [min_confidence]
|
|
136
|
-
# Example: python pattern_learner.py list 0.7
|
|
37
|
+
# Example: python pattern_learner.py list 0.7
|
|
137
38
|
|
|
138
|
-
# Get context for
|
|
39
|
+
# Get context formatted for AI assistant injection
|
|
139
40
|
python pattern_learner.py context [min_confidence]
|
|
140
41
|
# Example: python pattern_learner.py context 0.6
|
|
141
42
|
|
|
@@ -160,13 +61,16 @@ learner.on_new_memory(memory_id=42)
|
|
|
160
61
|
# Query patterns
|
|
161
62
|
patterns = learner.get_patterns(min_confidence=0.7)
|
|
162
63
|
|
|
163
|
-
# Get formatted context for
|
|
64
|
+
# Get formatted context for AI injection
|
|
164
65
|
context = learner.get_identity_context(min_confidence=0.7)
|
|
165
66
|
```
|
|
166
67
|
|
|
68
|
+
---
|
|
69
|
+
|
|
167
70
|
## Example Output
|
|
168
71
|
|
|
169
72
|
### Pattern List
|
|
73
|
+
|
|
170
74
|
```
|
|
171
75
|
Type Category Pattern Confidence Evidence
|
|
172
76
|
-----------------------------------------------------------------------------------------------
|
|
@@ -177,51 +81,42 @@ terminology general Optimize: Performance optimi... 90% 15
|
|
|
177
81
|
style general Error Handling: Explicit err... 78% 9
|
|
178
82
|
```
|
|
179
83
|
|
|
180
|
-
###
|
|
84
|
+
### AI Context Injection
|
|
85
|
+
|
|
181
86
|
```markdown
|
|
182
87
|
## Working with User - Learned Patterns
|
|
183
88
|
|
|
184
89
|
**Technology Preferences:**
|
|
185
90
|
- **Frontend Framework:** Next.js over React (confidence: 85%, 12 examples)
|
|
186
91
|
- **Database:** PostgreSQL (confidence: 72%, 8 examples)
|
|
187
|
-
- **State Management:** Redux for complex, Context for simple (confidence: 68%, 7 examples)
|
|
188
92
|
|
|
189
93
|
**Coding Style:**
|
|
190
94
|
- **Optimization Priority:** Performance over readability (confidence: 90%, 15 examples)
|
|
191
95
|
- **Error Handling:** Explicit error boundaries (confidence: 78%, 9 examples)
|
|
192
|
-
- **Code Organization:** Modular organization (confidence: 75%, 11 examples)
|
|
193
96
|
|
|
194
97
|
**Terminology:**
|
|
195
98
|
- **Optimize:** Performance optimization (speed/latency) (confidence: 90%, 15 examples)
|
|
196
|
-
- **Refactor:** Architecture change, not just renaming (confidence: 82%, 10 examples)
|
|
197
|
-
- **MVP:** Core features only, no polish (confidence: 85%, 8 examples)
|
|
198
99
|
```
|
|
199
100
|
|
|
200
|
-
|
|
101
|
+
---
|
|
201
102
|
|
|
202
|
-
|
|
203
|
-
- **Expected confidence:** 10-40%
|
|
204
|
-
- **Reason:** Limited evidence means low certainty
|
|
205
|
-
- **Recommendation:** Use min_confidence=0.1 for exploration
|
|
103
|
+
## Confidence Calibration
|
|
206
104
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
-
|
|
210
|
-
-
|
|
105
|
+
| Dataset Size | Expected Confidence | Recommended Threshold |
|
|
106
|
+
|-------------|--------------------|-----------------------|
|
|
107
|
+
| Under 20 memories | 10-40% | Use 0.1 for exploration |
|
|
108
|
+
| 20-100 memories | 40-70% | Use 0.5 for reliable patterns |
|
|
109
|
+
| Over 100 memories | 70-95% | Use 0.7 for high-confidence patterns |
|
|
211
110
|
|
|
212
|
-
|
|
213
|
-
- **Expected confidence:** 70-95%
|
|
214
|
-
- **Reason:** Strong evidence across time
|
|
215
|
-
- **Recommendation:** Use min_confidence=0.7 for high-confidence patterns
|
|
111
|
+
The system is designed to be conservative. Low confidence with small datasets is correct behavior.
|
|
216
112
|
|
|
217
|
-
|
|
113
|
+
---
|
|
218
114
|
|
|
219
115
|
## Pattern Update Schedule
|
|
220
116
|
|
|
221
117
|
### Incremental (on `/remember`)
|
|
222
|
-
- Quick check for pattern updates
|
|
223
|
-
- For datasets
|
|
224
|
-
- For small datasets, triggers full update
|
|
118
|
+
- Quick check for pattern updates on every new memory
|
|
119
|
+
- For large datasets, defers to weekly consolidation
|
|
225
120
|
|
|
226
121
|
### Weekly Consolidation
|
|
227
122
|
- Full re-analysis of all memories
|
|
@@ -231,13 +126,15 @@ style general Error Handling: Explicit err... 78% 9
|
|
|
231
126
|
0 2 * * 0 cd ~/.claude-memory && python3 pattern_learner.py update >> pattern_updates.log 2>&1
|
|
232
127
|
```
|
|
233
128
|
|
|
129
|
+
---
|
|
130
|
+
|
|
234
131
|
## Integration with AI Assistants
|
|
235
132
|
|
|
236
|
-
### Context Injection
|
|
133
|
+
### Automatic Context Injection
|
|
134
|
+
|
|
237
135
|
The `get_identity_context()` method formats patterns for any AI assistant's context window:
|
|
238
136
|
|
|
239
137
|
```python
|
|
240
|
-
# In your AI assistant integration:
|
|
241
138
|
learner = PatternLearner()
|
|
242
139
|
identity_context = learner.get_identity_context(min_confidence=0.7)
|
|
243
140
|
|
|
@@ -249,76 +146,64 @@ prompt = f"""
|
|
|
249
146
|
"""
|
|
250
147
|
```
|
|
251
148
|
|
|
149
|
+
**Works with:** Claude CLI, GPT, local LLMs, or any AI assistant that accepts context.
|
|
150
|
+
|
|
252
151
|
### Benefits
|
|
253
152
|
1. **Personalized responses:** AI understands your technology preferences
|
|
254
153
|
2. **Consistent terminology:** AI uses terms the way you define them
|
|
255
154
|
3. **Style matching:** AI respects your coding style priorities
|
|
256
|
-
4. **Efficient communication:** No need to repeat preferences
|
|
257
|
-
|
|
258
|
-
**Works with:** Claude CLI, GPT, local LLMs, or any AI assistant that accepts context.
|
|
259
|
-
|
|
260
|
-
## Implementation Details
|
|
155
|
+
4. **Efficient communication:** No need to repeat preferences every session
|
|
261
156
|
|
|
262
|
-
|
|
263
|
-
- **Language:** Python 3.8+
|
|
264
|
-
- **Database:** SQLite3 (local)
|
|
265
|
-
- **NLP:** sklearn TfidfVectorizer (optional, local)
|
|
266
|
-
- **No external APIs**
|
|
267
|
-
|
|
268
|
-
### Files
|
|
269
|
-
- `pattern_learner.py` - Main implementation (850 lines)
|
|
270
|
-
- `memory.db` - SQLite database (includes pattern tables)
|
|
271
|
-
- Schema tables:
|
|
272
|
-
- `identity_patterns` - Pattern definitions
|
|
273
|
-
- `pattern_examples` - Representative excerpts
|
|
157
|
+
---
|
|
274
158
|
|
|
275
|
-
|
|
276
|
-
- **Full analysis (100 memories):** ~2-3 seconds
|
|
277
|
-
- **Query patterns:** <10ms
|
|
278
|
-
- **Database size:** ~1KB per pattern
|
|
159
|
+
## Privacy & Security
|
|
279
160
|
|
|
280
|
-
|
|
161
|
+
- **No external API calls** — all processing is local
|
|
162
|
+
- **All data stays local** — stored in `~/.claude-memory/`
|
|
163
|
+
- **SQL injection protected** — parameterized queries throughout
|
|
164
|
+
- **No credentials stored**
|
|
165
|
+
- **No network access required**
|
|
281
166
|
|
|
282
|
-
|
|
283
|
-
✅ **All data stays local** (~/.claude-memory/)
|
|
284
|
-
✅ **SQL injection protected** (parameterized queries)
|
|
285
|
-
✅ **No credentials stored**
|
|
286
|
-
✅ **No network access required**
|
|
167
|
+
---
|
|
287
168
|
|
|
288
169
|
## Limitations
|
|
289
170
|
|
|
290
|
-
1. **English-
|
|
291
|
-
2. **Technical domains:** Works best with technical
|
|
292
|
-
3. **Minimum
|
|
293
|
-
4. **
|
|
171
|
+
1. **English-optimized:** Pattern detection works best with English text
|
|
172
|
+
2. **Technical domains:** Works best with technical and coding memories
|
|
173
|
+
3. **Minimum samples:** Requires a few mentions before a pattern is detected
|
|
174
|
+
4. **Conservative scoring:** Low confidence with small datasets is by design
|
|
175
|
+
|
|
176
|
+
---
|
|
294
177
|
|
|
295
178
|
## Troubleshooting
|
|
296
179
|
|
|
297
180
|
### "No patterns learned yet"
|
|
298
181
|
- **Cause:** Not enough memories or technical content
|
|
299
|
-
- **Solution:** Add 10-20 memories with technical details
|
|
182
|
+
- **Solution:** Add 10-20 memories with technical details about your preferences
|
|
300
183
|
|
|
301
184
|
### Low confidence scores
|
|
302
185
|
- **Cause:** Small dataset or mixed evidence
|
|
303
|
-
- **Solution:** Normal behavior.
|
|
186
|
+
- **Solution:** Normal behavior. Lower the threshold (0.1-0.3) or add more memories
|
|
304
187
|
|
|
305
188
|
### Wrong preference detected
|
|
306
|
-
- **Cause:** More mentions of alternative technology
|
|
307
|
-
- **Solution:** Add more memories
|
|
189
|
+
- **Cause:** More mentions of alternative technology than your true preference
|
|
190
|
+
- **Solution:** Add more memories explicitly stating your correct preference
|
|
308
191
|
|
|
309
192
|
### Pattern not updating
|
|
310
193
|
- **Cause:** Weekly update not run
|
|
311
194
|
- **Solution:** Run `python pattern_learner.py update` manually
|
|
312
195
|
|
|
196
|
+
---
|
|
197
|
+
|
|
313
198
|
## Testing
|
|
314
199
|
|
|
315
|
-
Sample memories for
|
|
200
|
+
Sample memories for verifying pattern detection:
|
|
316
201
|
|
|
317
202
|
```bash
|
|
318
203
|
# Add sample memories
|
|
319
204
|
python memory_store.py add "Built with Next.js for better performance" --tags nextjs
|
|
320
205
|
python memory_store.py add "Using Next.js on all new projects" --tags nextjs
|
|
321
|
-
python memory_store.py add "Optimized API from
|
|
206
|
+
python memory_store.py add "Optimized API from slow to fast" --tags performance
|
|
322
207
|
python memory_store.py add "Performance is critical for UX" --tags performance
|
|
323
208
|
python memory_store.py add "When I say optimize, I mean make it faster" --tags terminology
|
|
324
209
|
|
|
@@ -330,27 +215,7 @@ python pattern_learner.py list 0.1
|
|
|
330
215
|
python pattern_learner.py context 0.1
|
|
331
216
|
```
|
|
332
217
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
Potential improvements (not yet implemented):
|
|
336
|
-
|
|
337
|
-
1. **True incremental updates:** Update only affected patterns
|
|
338
|
-
2. **Pattern decay:** Reduce confidence over time if not reinforced
|
|
339
|
-
3. **Conflict detection:** Identify contradicting patterns
|
|
340
|
-
4. **Cross-project patterns:** Detect project-specific vs global preferences
|
|
341
|
-
5. **Multi-language support:** Extend beyond English
|
|
342
|
-
6. **Pattern visualization:** Web UI for pattern exploration
|
|
343
|
-
|
|
344
|
-
## References
|
|
345
|
-
|
|
346
|
-
Architecture documentation:
|
|
347
|
-
- `docs/architecture/05-pattern-learner.md` - Detailed algorithm specification
|
|
348
|
-
- `docs/architecture/01-database-schema.md` - Pattern table schemas
|
|
349
|
-
- `docs/ARCHITECTURE.md` - System overview
|
|
350
|
-
|
|
351
|
-
Research inspiration:
|
|
352
|
-
- xMemory (arxiv.org/abs/2602.02007) - Semantic memory components
|
|
353
|
-
- A-RAG - Agentic multi-level retrieval
|
|
218
|
+
---
|
|
354
219
|
|
|
355
220
|
## License
|
|
356
221
|
|
|
@@ -358,6 +223,6 @@ Part of SuperLocalMemory system. See main project LICENSE.
|
|
|
358
223
|
|
|
359
224
|
---
|
|
360
225
|
|
|
361
|
-
**Implementation Status:**
|
|
226
|
+
**Implementation Status:** Complete and tested
|
|
362
227
|
|
|
363
228
|
**Last Updated:** 2026-02-05
|
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
|
-
|
|
3
|
-
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
|
|
4
|
+
"""SuperLocalMemory V2 - example_graph_usage.py
|
|
4
5
|
|
|
5
|
-
Copyright (c) 2026 Varun Pratap Bhardwaj
|
|
6
6
|
Solution Architect & Original Creator
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
Repository: https://github.com/varun369/SuperLocalMemoryV2
|
|
8
|
+
(see LICENSE file)
|
|
10
9
|
|
|
11
10
|
ATTRIBUTION REQUIRED: This notice must be preserved in all copies.
|
|
12
11
|
"""
|
|
13
|
-
|
|
14
12
|
import sys
|
|
15
13
|
from pathlib import Path
|
|
16
14
|
|
package/install.sh
CHANGED
|
@@ -164,6 +164,27 @@ if [ -d "${REPO_DIR}/src/learning" ]; then
|
|
|
164
164
|
echo "✓ Learning modules copied"
|
|
165
165
|
fi
|
|
166
166
|
|
|
167
|
+
# Copy lifecycle modules (v2.8+)
|
|
168
|
+
if [ -d "${REPO_DIR}/src/lifecycle" ]; then
|
|
169
|
+
mkdir -p "${INSTALL_DIR}/lifecycle"
|
|
170
|
+
cp -r "${REPO_DIR}/src/lifecycle/"* "${INSTALL_DIR}/lifecycle/"
|
|
171
|
+
echo "✓ Lifecycle modules copied"
|
|
172
|
+
fi
|
|
173
|
+
|
|
174
|
+
# Copy behavioral modules (v2.8+)
|
|
175
|
+
if [ -d "${REPO_DIR}/src/behavioral" ]; then
|
|
176
|
+
mkdir -p "${INSTALL_DIR}/behavioral"
|
|
177
|
+
cp -r "${REPO_DIR}/src/behavioral/"* "${INSTALL_DIR}/behavioral/"
|
|
178
|
+
echo "✓ Behavioral modules copied"
|
|
179
|
+
fi
|
|
180
|
+
|
|
181
|
+
# Copy compliance modules (v2.8+)
|
|
182
|
+
if [ -d "${REPO_DIR}/src/compliance" ]; then
|
|
183
|
+
mkdir -p "${INSTALL_DIR}/compliance"
|
|
184
|
+
cp -r "${REPO_DIR}/src/compliance/"* "${INSTALL_DIR}/compliance/"
|
|
185
|
+
echo "✓ Compliance modules copied"
|
|
186
|
+
fi
|
|
187
|
+
|
|
167
188
|
# Copy hooks
|
|
168
189
|
echo "Copying hooks..."
|
|
169
190
|
mkdir -p "${INSTALL_DIR}/hooks"
|
|
@@ -230,8 +251,41 @@ mkdir -p "${INSTALL_DIR}/profiles"
|
|
|
230
251
|
mkdir -p "${INSTALL_DIR}/vectors"
|
|
231
252
|
mkdir -p "${INSTALL_DIR}/cold-storage"
|
|
232
253
|
mkdir -p "${INSTALL_DIR}/jobs"
|
|
254
|
+
mkdir -p "${INSTALL_DIR}/policies"
|
|
233
255
|
echo "✓ Directories created"
|
|
234
256
|
|
|
257
|
+
# Initialize audit database (v2.8+ — compliance engine)
|
|
258
|
+
if [ ! -f "${INSTALL_DIR}/audit.db" ]; then
|
|
259
|
+
python3 -c "
|
|
260
|
+
import sqlite3
|
|
261
|
+
from pathlib import Path
|
|
262
|
+
audit_path = Path.home() / '.claude-memory' / 'audit.db'
|
|
263
|
+
conn = sqlite3.connect(audit_path)
|
|
264
|
+
cursor = conn.cursor()
|
|
265
|
+
cursor.execute('''CREATE TABLE IF NOT EXISTS audit_events (
|
|
266
|
+
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
267
|
+
event_type TEXT NOT NULL,
|
|
268
|
+
actor TEXT,
|
|
269
|
+
target TEXT,
|
|
270
|
+
action TEXT,
|
|
271
|
+
detail TEXT,
|
|
272
|
+
hash TEXT,
|
|
273
|
+
prev_hash TEXT,
|
|
274
|
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
275
|
+
)''')
|
|
276
|
+
cursor.execute('''CREATE TABLE IF NOT EXISTS retention_policies (
|
|
277
|
+
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
278
|
+
policy_name TEXT UNIQUE NOT NULL,
|
|
279
|
+
retention_days INTEGER,
|
|
280
|
+
auto_delete INTEGER DEFAULT 0,
|
|
281
|
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
282
|
+
)''')
|
|
283
|
+
conn.commit()
|
|
284
|
+
conn.close()
|
|
285
|
+
print('Audit database ready')
|
|
286
|
+
" 2>/dev/null && echo "✓ Audit database initialized (v2.8)" || echo "○ Audit database skipped (optional)"
|
|
287
|
+
fi
|
|
288
|
+
|
|
235
289
|
# Make Python scripts executable
|
|
236
290
|
chmod +x "${INSTALL_DIR}/"*.py 2>/dev/null || true
|
|
237
291
|
|
|
@@ -799,6 +853,11 @@ echo "Learning System (v2.7+):"
|
|
|
799
853
|
echo " slm learning status - Check learning system"
|
|
800
854
|
echo " slm engagement - View engagement metrics"
|
|
801
855
|
echo ""
|
|
856
|
+
echo "Lifecycle & Compliance (v2.8+):"
|
|
857
|
+
echo " slm lifecycle-status - View memory lifecycle states"
|
|
858
|
+
echo " slm compact --dry-run - Preview lifecycle transitions"
|
|
859
|
+
echo " slm behavioral-patterns - View learned patterns"
|
|
860
|
+
echo ""
|
|
802
861
|
# Optional: Offer to install optional features
|
|
803
862
|
if [ "$NON_INTERACTIVE" = true ]; then
|
|
804
863
|
INSTALL_CHOICE="N"
|
package/mcp_server.py
CHANGED
|
@@ -1,12 +1,9 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
|
-
|
|
3
|
-
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
|
|
4
|
+
"""SuperLocalMemory V2 - MCP Server
|
|
4
5
|
Universal memory access for all MCP-compatible tools (Cursor, Windsurf, Claude Desktop, Continue.dev)
|
|
5
6
|
|
|
6
|
-
Copyright (c) 2026 Varun Pratap Bhardwaj
|
|
7
|
-
Licensed under MIT License
|
|
8
|
-
Repository: https://github.com/varun369/SuperLocalMemoryV2
|
|
9
|
-
|
|
10
7
|
IMPORTANT: This is an ADDITION to existing skills, not a replacement.
|
|
11
8
|
Skills in Claude Code continue to work unchanged.
|
|
12
9
|
|
|
@@ -24,7 +21,6 @@ Usage:
|
|
|
24
21
|
# Run as HTTP MCP server (for remote access)
|
|
25
22
|
python3 mcp_server.py --transport http --port 8001
|
|
26
23
|
"""
|
|
27
|
-
|
|
28
24
|
from mcp.server.fastmcp import FastMCP, Context
|
|
29
25
|
from mcp.types import ToolAnnotations
|
|
30
26
|
import sys
|
|
@@ -1349,6 +1345,79 @@ async def fetch(id: str) -> dict:
|
|
|
1349
1345
|
raise ValueError(f"Failed to fetch memory {id}: {_sanitize_error(e)}")
|
|
1350
1346
|
|
|
1351
1347
|
|
|
1348
|
+
# ============================================================================
|
|
1349
|
+
# v2.8 MCP TOOLS — Lifecycle, Behavioral Learning, Compliance
|
|
1350
|
+
# ============================================================================
|
|
1351
|
+
|
|
1352
|
+
try:
|
|
1353
|
+
from mcp_tools_v28 import (
|
|
1354
|
+
report_outcome as _report_outcome,
|
|
1355
|
+
get_lifecycle_status as _get_lifecycle_status,
|
|
1356
|
+
set_retention_policy as _set_retention_policy,
|
|
1357
|
+
compact_memories as _compact_memories,
|
|
1358
|
+
get_behavioral_patterns as _get_behavioral_patterns,
|
|
1359
|
+
audit_trail as _audit_trail,
|
|
1360
|
+
)
|
|
1361
|
+
|
|
1362
|
+
V28_AVAILABLE = True
|
|
1363
|
+
|
|
1364
|
+
@mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
|
|
1365
|
+
async def report_outcome(
|
|
1366
|
+
memory_ids: list,
|
|
1367
|
+
outcome: str,
|
|
1368
|
+
action_type: str = "other",
|
|
1369
|
+
context: str = None,
|
|
1370
|
+
agent_id: str = "user",
|
|
1371
|
+
project: str = None,
|
|
1372
|
+
) -> dict:
|
|
1373
|
+
"""Record action outcome for behavioral learning. Outcomes: success/failure/partial."""
|
|
1374
|
+
return await _report_outcome(memory_ids, outcome, action_type, context, agent_id, project)
|
|
1375
|
+
|
|
1376
|
+
@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False))
|
|
1377
|
+
async def get_lifecycle_status(memory_id: int = None) -> dict:
|
|
1378
|
+
"""Get memory lifecycle status — state distribution or single memory state."""
|
|
1379
|
+
return await _get_lifecycle_status(memory_id)
|
|
1380
|
+
|
|
1381
|
+
@mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
|
|
1382
|
+
async def set_retention_policy(
|
|
1383
|
+
name: str,
|
|
1384
|
+
framework: str,
|
|
1385
|
+
retention_days: int,
|
|
1386
|
+
action: str = "retain",
|
|
1387
|
+
applies_to_tags: list = None,
|
|
1388
|
+
applies_to_project: str = None,
|
|
1389
|
+
) -> dict:
|
|
1390
|
+
"""Create a retention policy (GDPR, HIPAA, EU AI Act)."""
|
|
1391
|
+
return await _set_retention_policy(
|
|
1392
|
+
name, framework, retention_days, action, applies_to_tags, applies_to_project
|
|
1393
|
+
)
|
|
1394
|
+
|
|
1395
|
+
@mcp.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
|
|
1396
|
+
async def compact_memories(dry_run: bool = True, profile: str = None) -> dict:
|
|
1397
|
+
"""Evaluate and compact stale memories through lifecycle transitions. dry_run=True by default."""
|
|
1398
|
+
return await _compact_memories(dry_run, profile)
|
|
1399
|
+
|
|
1400
|
+
@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False))
|
|
1401
|
+
async def get_behavioral_patterns(
|
|
1402
|
+
min_confidence: float = 0.0, project: str = None
|
|
1403
|
+
) -> dict:
|
|
1404
|
+
"""Get learned behavioral patterns from outcome analysis."""
|
|
1405
|
+
return await _get_behavioral_patterns(min_confidence, project)
|
|
1406
|
+
|
|
1407
|
+
@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False))
|
|
1408
|
+
async def audit_trail(
|
|
1409
|
+
event_type: str = None,
|
|
1410
|
+
actor: str = None,
|
|
1411
|
+
limit: int = 50,
|
|
1412
|
+
verify_chain: bool = False,
|
|
1413
|
+
) -> dict:
|
|
1414
|
+
"""Query compliance audit trail with optional hash chain verification."""
|
|
1415
|
+
return await _audit_trail(event_type, actor, limit, verify_chain)
|
|
1416
|
+
|
|
1417
|
+
except ImportError:
|
|
1418
|
+
V28_AVAILABLE = False # v2.8 tools unavailable — graceful degradation
|
|
1419
|
+
|
|
1420
|
+
|
|
1352
1421
|
# ============================================================================
|
|
1353
1422
|
# MCP RESOURCES (Data endpoints)
|
|
1354
1423
|
# ============================================================================
|
|
@@ -1586,6 +1655,13 @@ if __name__ == "__main__":
|
|
|
1586
1655
|
print(" - memory_used(memory_id, query, usefulness) [v2.7 Learning]", file=sys.stderr)
|
|
1587
1656
|
print(" - get_learned_patterns(min_confidence, category) [v2.7 Learning]", file=sys.stderr)
|
|
1588
1657
|
print(" - correct_pattern(pattern_id, correct_value) [v2.7 Learning]", file=sys.stderr)
|
|
1658
|
+
if V28_AVAILABLE:
|
|
1659
|
+
print(" - report_outcome(memory_ids, outcome) [v2.8 Behavioral]", file=sys.stderr)
|
|
1660
|
+
print(" - get_lifecycle_status(memory_id) [v2.8 Lifecycle]", file=sys.stderr)
|
|
1661
|
+
print(" - set_retention_policy(name, framework, days) [v2.8 Compliance]", file=sys.stderr)
|
|
1662
|
+
print(" - compact_memories(dry_run) [v2.8 Lifecycle]", file=sys.stderr)
|
|
1663
|
+
print(" - get_behavioral_patterns(min_confidence) [v2.8 Behavioral]", file=sys.stderr)
|
|
1664
|
+
print(" - audit_trail(event_type, verify_chain) [v2.8 Compliance]", file=sys.stderr)
|
|
1589
1665
|
print("", file=sys.stderr)
|
|
1590
1666
|
print("MCP Resources Available:", file=sys.stderr)
|
|
1591
1667
|
print(" - memory://recent/{limit}", file=sys.stderr)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "superlocalmemory",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.8.0",
|
|
4
4
|
"description": "Your AI Finally Remembers You - Local-first intelligent memory system for AI assistants. Works with Claude, Cursor, Windsurf, VS Code/Copilot, Codex, and 17+ AI tools. 100% local, zero cloud dependencies.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai-memory",
|
|
@@ -94,13 +94,6 @@
|
|
|
94
94
|
"url": "https://github.com/varun369"
|
|
95
95
|
}
|
|
96
96
|
],
|
|
97
|
-
"attribution": {
|
|
98
|
-
"creator": "Varun Pratap Bhardwaj",
|
|
99
|
-
"role": "Solution Architect & Original Creator",
|
|
100
|
-
"year": "2026",
|
|
101
|
-
"github": "https://github.com/varun369",
|
|
102
|
-
"required": "Attribution notice must be preserved in all copies and derivative works"
|
|
103
|
-
},
|
|
104
97
|
"dependencies": {
|
|
105
98
|
"docx": "^9.5.1"
|
|
106
99
|
}
|
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
Licensed under MIT License
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
|
|
4
|
+
"""SuperLocalMemory V2 - Thumbnail Generator
|
|
6
5
|
|
|
7
6
|
Generates optimized thumbnail versions of all screenshots.
|
|
8
7
|
- Size: 320×180px (16:9 ratio)
|
|
@@ -10,7 +9,6 @@ Generates optimized thumbnail versions of all screenshots.
|
|
|
10
9
|
- Quality: High enough to recognize content
|
|
11
10
|
- File size: < 50KB per thumbnail
|
|
12
11
|
"""
|
|
13
|
-
|
|
14
12
|
import os
|
|
15
13
|
import json
|
|
16
14
|
from pathlib import Path
|
|
@@ -417,7 +417,7 @@ Each profile has separate graph
|
|
|
417
417
|
|
|
418
418
|
**Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
|
|
419
419
|
**Project:** SuperLocalMemory V2
|
|
420
|
-
**License:** MIT
|
|
420
|
+
**License:** MIT (see [LICENSE](../../LICENSE))
|
|
421
421
|
**Repository:** https://github.com/varun369/SuperLocalMemoryV2
|
|
422
422
|
|
|
423
423
|
*Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*
|
|
@@ -342,7 +342,7 @@ date
|
|
|
342
342
|
|
|
343
343
|
**Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
|
|
344
344
|
**Project:** SuperLocalMemory V2
|
|
345
|
-
**License:** MIT
|
|
345
|
+
**License:** MIT (see [LICENSE](../../LICENSE))
|
|
346
346
|
**Repository:** https://github.com/varun369/SuperLocalMemoryV2
|
|
347
347
|
|
|
348
348
|
*Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*
|