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.
Files changed (170) hide show
  1. package/CHANGELOG.md +120 -155
  2. package/README.md +115 -89
  3. package/api_server.py +2 -12
  4. package/docs/PATTERN-LEARNING.md +64 -199
  5. package/docs/example_graph_usage.py +4 -6
  6. package/install.sh +59 -0
  7. package/mcp_server.py +83 -7
  8. package/package.json +1 -8
  9. package/scripts/generate-thumbnails.py +3 -5
  10. package/skills/slm-build-graph/SKILL.md +1 -1
  11. package/skills/slm-list-recent/SKILL.md +1 -1
  12. package/skills/slm-recall/SKILL.md +1 -1
  13. package/skills/slm-remember/SKILL.md +1 -1
  14. package/skills/slm-show-patterns/SKILL.md +1 -1
  15. package/skills/slm-status/SKILL.md +1 -1
  16. package/skills/slm-switch-profile/SKILL.md +1 -1
  17. package/src/agent_registry.py +7 -18
  18. package/src/auth_middleware.py +3 -5
  19. package/src/auto_backup.py +3 -7
  20. package/src/behavioral/__init__.py +49 -0
  21. package/src/behavioral/behavioral_listener.py +203 -0
  22. package/src/behavioral/behavioral_patterns.py +275 -0
  23. package/src/behavioral/cross_project_transfer.py +206 -0
  24. package/src/behavioral/outcome_inference.py +194 -0
  25. package/src/behavioral/outcome_tracker.py +193 -0
  26. package/src/behavioral/tests/__init__.py +4 -0
  27. package/src/behavioral/tests/test_behavioral_integration.py +108 -0
  28. package/src/behavioral/tests/test_behavioral_patterns.py +150 -0
  29. package/src/behavioral/tests/test_cross_project_transfer.py +142 -0
  30. package/src/behavioral/tests/test_mcp_behavioral.py +139 -0
  31. package/src/behavioral/tests/test_mcp_report_outcome.py +117 -0
  32. package/src/behavioral/tests/test_outcome_inference.py +107 -0
  33. package/src/behavioral/tests/test_outcome_tracker.py +96 -0
  34. package/src/cache_manager.py +4 -6
  35. package/src/compliance/__init__.py +48 -0
  36. package/src/compliance/abac_engine.py +149 -0
  37. package/src/compliance/abac_middleware.py +116 -0
  38. package/src/compliance/audit_db.py +215 -0
  39. package/src/compliance/audit_logger.py +148 -0
  40. package/src/compliance/retention_manager.py +289 -0
  41. package/src/compliance/retention_scheduler.py +186 -0
  42. package/src/compliance/tests/__init__.py +4 -0
  43. package/src/compliance/tests/test_abac_enforcement.py +95 -0
  44. package/src/compliance/tests/test_abac_engine.py +124 -0
  45. package/src/compliance/tests/test_abac_mcp_integration.py +118 -0
  46. package/src/compliance/tests/test_audit_db.py +123 -0
  47. package/src/compliance/tests/test_audit_logger.py +98 -0
  48. package/src/compliance/tests/test_mcp_audit.py +128 -0
  49. package/src/compliance/tests/test_mcp_retention_policy.py +125 -0
  50. package/src/compliance/tests/test_retention_manager.py +131 -0
  51. package/src/compliance/tests/test_retention_scheduler.py +99 -0
  52. package/src/db_connection_manager.py +2 -12
  53. package/src/embedding_engine.py +61 -669
  54. package/src/embeddings/__init__.py +47 -0
  55. package/src/embeddings/cache.py +70 -0
  56. package/src/embeddings/cli.py +113 -0
  57. package/src/embeddings/constants.py +47 -0
  58. package/src/embeddings/database.py +91 -0
  59. package/src/embeddings/engine.py +247 -0
  60. package/src/embeddings/model_loader.py +145 -0
  61. package/src/event_bus.py +3 -13
  62. package/src/graph/__init__.py +36 -0
  63. package/src/graph/build_helpers.py +74 -0
  64. package/src/graph/cli.py +87 -0
  65. package/src/graph/cluster_builder.py +188 -0
  66. package/src/graph/cluster_summary.py +148 -0
  67. package/src/graph/constants.py +47 -0
  68. package/src/graph/edge_builder.py +162 -0
  69. package/src/graph/entity_extractor.py +95 -0
  70. package/src/graph/graph_core.py +226 -0
  71. package/src/graph/graph_search.py +231 -0
  72. package/src/graph/hierarchical.py +207 -0
  73. package/src/graph/schema.py +99 -0
  74. package/src/graph_engine.py +45 -1451
  75. package/src/hnsw_index.py +3 -7
  76. package/src/hybrid_search.py +36 -683
  77. package/src/learning/__init__.py +27 -12
  78. package/src/learning/adaptive_ranker.py +50 -12
  79. package/src/learning/cross_project_aggregator.py +2 -12
  80. package/src/learning/engagement_tracker.py +2 -12
  81. package/src/learning/feature_extractor.py +175 -43
  82. package/src/learning/feedback_collector.py +7 -12
  83. package/src/learning/learning_db.py +180 -12
  84. package/src/learning/project_context_manager.py +2 -12
  85. package/src/learning/source_quality_scorer.py +2 -12
  86. package/src/learning/synthetic_bootstrap.py +2 -12
  87. package/src/learning/tests/__init__.py +2 -0
  88. package/src/learning/tests/test_adaptive_ranker.py +2 -6
  89. package/src/learning/tests/test_adaptive_ranker_v28.py +60 -0
  90. package/src/learning/tests/test_aggregator.py +2 -6
  91. package/src/learning/tests/test_auto_retrain_v28.py +35 -0
  92. package/src/learning/tests/test_e2e_ranking_v28.py +82 -0
  93. package/src/learning/tests/test_feature_extractor_v28.py +93 -0
  94. package/src/learning/tests/test_feedback_collector.py +2 -6
  95. package/src/learning/tests/test_learning_db.py +2 -6
  96. package/src/learning/tests/test_learning_db_v28.py +110 -0
  97. package/src/learning/tests/test_learning_init_v28.py +48 -0
  98. package/src/learning/tests/test_outcome_signals.py +48 -0
  99. package/src/learning/tests/test_project_context.py +2 -6
  100. package/src/learning/tests/test_schema_migration.py +319 -0
  101. package/src/learning/tests/test_signal_inference.py +11 -13
  102. package/src/learning/tests/test_source_quality.py +2 -6
  103. package/src/learning/tests/test_synthetic_bootstrap.py +3 -7
  104. package/src/learning/tests/test_workflow_miner.py +2 -6
  105. package/src/learning/workflow_pattern_miner.py +2 -12
  106. package/src/lifecycle/__init__.py +54 -0
  107. package/src/lifecycle/bounded_growth.py +239 -0
  108. package/src/lifecycle/compaction_engine.py +226 -0
  109. package/src/lifecycle/lifecycle_engine.py +302 -0
  110. package/src/lifecycle/lifecycle_evaluator.py +225 -0
  111. package/src/lifecycle/lifecycle_scheduler.py +130 -0
  112. package/src/lifecycle/retention_policy.py +285 -0
  113. package/src/lifecycle/tests/__init__.py +4 -0
  114. package/src/lifecycle/tests/test_bounded_growth.py +193 -0
  115. package/src/lifecycle/tests/test_compaction.py +179 -0
  116. package/src/lifecycle/tests/test_lifecycle_engine.py +137 -0
  117. package/src/lifecycle/tests/test_lifecycle_evaluation.py +177 -0
  118. package/src/lifecycle/tests/test_lifecycle_scheduler.py +127 -0
  119. package/src/lifecycle/tests/test_lifecycle_search.py +109 -0
  120. package/src/lifecycle/tests/test_mcp_compact.py +149 -0
  121. package/src/lifecycle/tests/test_mcp_lifecycle_status.py +114 -0
  122. package/src/lifecycle/tests/test_retention_policy.py +162 -0
  123. package/src/mcp_tools_v28.py +280 -0
  124. package/src/memory-profiles.py +2 -12
  125. package/src/memory-reset.py +2 -12
  126. package/src/memory_compression.py +2 -12
  127. package/src/memory_store_v2.py +76 -20
  128. package/src/migrate_v1_to_v2.py +2 -12
  129. package/src/pattern_learner.py +29 -975
  130. package/src/patterns/__init__.py +24 -0
  131. package/src/patterns/analyzers.py +247 -0
  132. package/src/patterns/learner.py +267 -0
  133. package/src/patterns/scoring.py +167 -0
  134. package/src/patterns/store.py +223 -0
  135. package/src/patterns/terminology.py +138 -0
  136. package/src/provenance_tracker.py +4 -14
  137. package/src/query_optimizer.py +4 -6
  138. package/src/rate_limiter.py +2 -6
  139. package/src/search/__init__.py +20 -0
  140. package/src/search/cli.py +77 -0
  141. package/src/search/constants.py +26 -0
  142. package/src/search/engine.py +239 -0
  143. package/src/search/fusion.py +122 -0
  144. package/src/search/index_loader.py +112 -0
  145. package/src/search/methods.py +162 -0
  146. package/src/search_engine_v2.py +4 -6
  147. package/src/setup_validator.py +7 -13
  148. package/src/subscription_manager.py +2 -12
  149. package/src/tree/__init__.py +59 -0
  150. package/src/tree/builder.py +183 -0
  151. package/src/tree/nodes.py +196 -0
  152. package/src/tree/queries.py +252 -0
  153. package/src/tree/schema.py +76 -0
  154. package/src/tree_manager.py +10 -711
  155. package/src/trust/__init__.py +45 -0
  156. package/src/trust/constants.py +66 -0
  157. package/src/trust/queries.py +157 -0
  158. package/src/trust/schema.py +95 -0
  159. package/src/trust/scorer.py +299 -0
  160. package/src/trust/signals.py +95 -0
  161. package/src/trust_scorer.py +39 -697
  162. package/src/webhook_dispatcher.py +2 -12
  163. package/ui/app.js +1 -1
  164. package/ui/js/agents.js +1 -1
  165. package/ui_server.py +2 -14
  166. package/ATTRIBUTION.md +0 -140
  167. package/docs/ARCHITECTURE-V2.5.md +0 -190
  168. package/docs/GRAPH-ENGINE.md +0 -503
  169. package/docs/architecture-diagram.drawio +0 -405
  170. package/docs/plans/2026-02-13-benchmark-suite.md +0 -1349
@@ -1,141 +1,42 @@
1
- # Pattern Learner - Identity Profile Extraction
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 using local TF-IDF and heuristic analysis.
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
- ## Architecture
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
- **Formula:**
107
- ```python
108
- confidence = (evidence_count / total_memories) * recency_bonus * distribution_factor
13
+ ## What It Learns
109
14
 
110
- Where:
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
- **Conservative by design:** Low confidence with small datasets is correct behavior.
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
- ### 5. PatternStore
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
- **Tables:**
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 # Show patterns with >70% confidence
37
+ # Example: python pattern_learner.py list 0.7
137
38
 
138
- # Get context for Claude injection
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 Claude
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
- ### Claude Context Injection
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
- ## Confidence Calibration
101
+ ---
201
102
 
202
- ### Small Datasets (<20 memories)
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
- ### Medium Datasets (20-100 memories)
208
- - **Expected confidence:** 40-70%
209
- - **Reason:** Patterns emerging but still developing
210
- - **Recommendation:** Use min_confidence=0.5 for reliable patterns
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
- ### Large Datasets (>100 memories)
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
- **Note:** The system is designed to be conservative. Low confidence with small datasets is correct behavior, not a bug.
113
+ ---
218
114
 
219
115
  ## Pattern Update Schedule
220
116
 
221
117
  ### Incremental (on `/remember`)
222
- - Quick check for pattern updates
223
- - For datasets >50 memories, defers to weekly update
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
- ### Technology Stack
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
- ### Performance
276
- - **Full analysis (100 memories):** ~2-3 seconds
277
- - **Query patterns:** <10ms
278
- - **Database size:** ~1KB per pattern
159
+ ## Privacy & Security
279
160
 
280
- ## Security & Privacy
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
- ✅ **No external API calls**
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-only:** Pattern detection optimized for English text
291
- 2. **Technical domains:** Works best with technical/coding memories
292
- 3. **Minimum memories:** Requires 3+ mentions for pattern detection
293
- 4. **Confidence calibration:** Conservative scoring (by design)
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. Use lower threshold (0.1-0.3) or add more memories
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 showing correct preference
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 testing pattern detection:
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 200ms to 50ms" --tags performance
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
- ## Future Enhancements
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:** Complete and tested
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
- SuperLocalMemory V2 - example_graph_usage.py
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
- Licensed under MIT License (see LICENSE file)
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
- SuperLocalMemory V2 - MCP Server
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.7.6",
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
- SuperLocalMemory V2 - Thumbnail Generator
4
- Copyright (c) 2026 Varun Pratap Bhardwaj
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 with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
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 with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
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.*