lemma-mcp 0.7.0 → 0.7.1

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 (3) hide show
  1. package/README.md +29 -19
  2. package/README.tr.md +484 -384
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -158,7 +158,7 @@ Add Lemma to your MCP client configuration:
158
158
  "mcpServers": {
159
159
  "lemma": {
160
160
  "command": "npx",
161
- "args": ["-y", "github:xenitV1/lemma"]
161
+ "args": ["-y", "lemma-mcp"]
162
162
  }
163
163
  }
164
164
  }
@@ -189,7 +189,7 @@ registerHook(HookTypes.ON_PROJECT_CHANGE, async (context) => {
189
189
  Extend the system prompt generation with custom transformations:
190
190
 
191
191
  ```javascript
192
- import { registerPromptModifier } from "@lemma/lemma/server";
192
+ import { registerPromptModifier } from "lemma-mcp/server";
193
193
 
194
194
  registerPromptModifier(async (prompt, context) => {
195
195
  if (context.project === "my-app") {
@@ -431,36 +431,46 @@ Get virtual session statistics: recent tool usage patterns and technologies.
431
431
  npm test
432
432
  ```
433
433
 
434
- 110 tests covering memory core, guides core, handlers, learning lifecycle, hook system, dynamic prompt generation, and virtual sessions. All I/O is isolated to temp directories.
434
+ 360 tests covering memory core, guides core, handlers, learning lifecycle, hook system, dynamic prompt generation, and virtual sessions. All I/O is isolated to temp directories.
435
+
436
+ ```bash
437
+ npm run typecheck # TypeScript type checking
438
+ npm run build # Compile TypeScript to dist/
439
+ ```
435
440
 
436
441
  ### Project Structure
437
442
 
438
443
  ```
439
444
  Lemma/
440
445
  ├── src/
441
- │ ├── index.js # MCP server entry point
446
+ │ ├── index.ts # MCP server entry point
447
+ │ ├── types.ts # Shared TypeScript interfaces
442
448
  │ ├── memory/
443
- │ │ ├── index.js # Memory module re-exports
444
- │ │ ├── core.js # Core memory logic, decay, search, dedup
445
- │ │ └── config.js # User configuration loader
449
+ │ │ ├── index.ts # Memory module re-exports
450
+ │ │ ├── core.ts # Core memory logic, decay, search, dedup
451
+ │ │ └── config.ts # User configuration loader
446
452
  │ ├── guides/
447
- │ │ ├── index.js # Guides module re-exports
448
- │ │ ├── core.js # Core guides logic, fuzzy dedup
449
- │ │ └── task-map.js # Task-to-guide mapping
453
+ │ │ ├── index.ts # Guides module re-exports
454
+ │ │ ├── core.ts # Core guides logic, fuzzy dedup
455
+ │ │ └── task-map.ts # Task-to-guide mapping
450
456
  │ ├── server/
451
- │ │ ├── index.js # Server setup, injection, notifications
452
- │ │ ├── handlers.js # Tool handlers (20 tools)
453
- │ │ ├── tools.js # Tool definitions
454
- │ │ ├── hooks.js # Hook system & prompt modifiers
455
- │ │ └── system-prompt.js # Dynamic system prompt
457
+ │ │ ├── index.ts # Server setup, injection, notifications
458
+ │ │ ├── handlers.ts # Tool handlers (20 tools)
459
+ │ │ ├── tools.ts # Tool definitions
460
+ │ │ ├── hooks.ts # Hook system & prompt modifiers
461
+ │ │ └── system-prompt.ts # Dynamic system prompt
456
462
  │ └── sessions/
457
- │ ├── index.js # Sessions module re-exports
458
- │ ├── core.js # Session lifecycle
459
- │ └── virtual.js # Virtual session tracking
463
+ │ ├── index.ts # Sessions module re-exports
464
+ │ ├── core.ts # Session lifecycle
465
+ │ └── virtual.ts # Virtual session tracking
460
466
  ├── tests/
461
- │ └── test.js # Test suite (110 tests)
467
+ │ ├── memory/ # 7 test files
468
+ │ ├── guides/ # 6 test files
469
+ │ ├── sessions/ # 2 test files
470
+ │ └── server/ # 10 test files
462
471
  ├── docs/ # Research papers and references
463
472
  ├── package.json
473
+ ├── tsconfig.json
464
474
  ├── CHANGELOG.md
465
475
  └── README.md
466
476
  ```
package/README.tr.md CHANGED
@@ -1,384 +1,484 @@
1
- <p align="center">
2
- <img src="assets/logo.png" width="200" alt="Lemma Logo">
3
- </p>
4
-
5
- # Lemma - LLM'ler için Kalıcı Bellek (MCP)
6
-
7
- [English](README.md) | [Türkçe](README.tr.md)
8
-
9
- Lemma, Büyük Dil Modelleri (LLM) için kalıcı bir bellek katmanı sağlayan bir Model Bağlam Protokolü (MCP) sunucusudur. LLM'lerin oturumlar arasında gerçekleri, tercihleri ve bağlamı hatırlamasını sağlar; otomatik bellek çürümesi ve öğrenme ile şık bir arayüz sunar.
10
-
11
- ## Lemma Nedir?
12
-
13
- Lemma, AI asistanları için harici bir hipokampüs görevi görür. İnsan beyni her şeyi kaydetmez — sentezler, damıtır ve fragmanlar bırakır. Sık erişilen bilgiler güçlenir; kullanılmayan bilgiler solar ve unutulur.
14
-
15
- Lemma aynı prensiple çalışır:
16
-
17
- - **Ham konuşmalar asla saklanmaz** — sadece sentezlenmiş fragmanlar
18
- - **Fragmanlar zamanla çürür** — sık erişilenler güçlenir
19
- - **Kullanılan bilgi bağlam kazanır** — etiketler ve ilişkiler otomatik oluşturulur
20
- - **LLM her oturumda fragmanları okur** ve kim olduğunu hatırlar
21
-
22
- ## Nasıl Çalışır?
23
-
24
- ### Dinamik Sistem İstemi
25
-
26
- Lemma, ilgili bağlamı LLM'nin sistem istemine çalışma zamanında otomatik enjekte eder:
27
-
28
- - **Küresel Bağlam**: Projeler arası öğrenimler ve tercihler (maksimum 10 fragman)
29
- - **Proje Bağlamı**: Projeye özel fragmanlar, güven görselleştirmesi ile (maksimum 20 fragman)
30
- - **Görsel Formatlama**: Güven çubukları (`███░░`) ve kaynak ikonları (🤖/👤)
31
- - **İstem Değiştiricileri**: Özel istem dönüşümleri için genişletilebilir sistem
32
-
33
- ### Bellek Yapısı
34
-
35
- Her bellek fragmanı şu alanlara sahiptir:
36
-
37
- | Alan | Tip | Açıklama |
38
- |-------|------|-------------|
39
- | `id` | string | Benzersiz kimlik (format: `m` + 6 hex karakter) |
40
- | `title` | string | Hızlı tarama için kısa başlık |
41
- | `fragment` | string | Sentezlenmiş bellek metni |
42
- | `project` | string | Proje kapsamı (küresel için `null`) |
43
- | `confidence` | float | Güvenilirlik 0.0-1.0 (zamanla çürür ve güçlenir) |
44
- | `source` | string | `"user"` veya `"ai"` |
45
- | `created` | string | Oluşturulma tarihi (YYYY-MM-DD) |
46
- | `lastAccessed` | string | Son okuma zamanı (ISO timestamp) |
47
- | `accessed` | int | Mevcut çürüme döngüsündeki erişim sayısı |
48
- | `tags` | string[] | Kullanımdan elde edilen bağlam etiketleri (örn. "debugging", "refactoring") |
49
- | `associatedWith` | string[] | Aynı oturumda erişilen fragman ID'leri |
50
- | `negativeHits` | int | Bu belleğin yardımcı olmadığı işaretlenme sayısı (oturum başına sıfırlanır) |
51
-
52
- ### Öğrenme Sistemi
53
-
54
- Statik belleğin aksine, Lemma bilginin kullanım yoluyla evrildiği biyolojik bir model kullanır:
55
-
56
- **Güçlendirme (erişimde):**
57
- ```
58
- confidence = min(1.0, confidence + 0.1)
59
- tags += context_tag (örn. "debugging")
60
- associatedWith += co_accessed_fragment_ids
61
- ```
62
-
63
- **Çürüme (oturum başına):**
64
- ```
65
- decay = max(0.005, 0.05 - (accessed * 0.005))
66
- confidence = confidence - decay
67
- ```
68
-
69
- - **Sıklık**: Sık erişilen öğeler daha yavaş çürür (minimum oturum başına 0.005)
70
- - **Kullanılmayan öğeler** temel oran olan oturum başına 0.05 çürür
71
- - **İlişkiler**: Birlikte kullanılan fragmanlar gelecekteki hatırlama için çapraz referanslar oluşturur
72
-
73
- ### Bellek Dosyası Konumu
74
-
75
- Bellekler JSONL formatında şu konumda saklanır:
76
-
77
- | İşletim Sistemi | Yol |
78
- |---|---|
79
- | **Windows** | `C:\Users\{kullanıcı}\.lemma\memory.jsonl` |
80
- | **macOS** | `/Users/{kullanıcı}/.lemma/memory.jsonl` |
81
- | **Linux** | `/home/{kullanıcı}/.lemma/memory.jsonl` |
82
-
83
- ## Hızlı Başlangıç
84
-
85
- Lemma'yı kullanmanın önerilen yolu **JSR** üzerindendir. MCP istemci konfigürasyonunuza ekleyin:
86
-
87
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
88
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
89
-
90
- ```json
91
- {
92
- "mcpServers": {
93
- "lemma": {
94
- "command": "npx",
95
- "args": ["-y", "jsr", "@lemma/lemma"]
96
- }
97
- }
98
- }
99
- ```
100
-
101
- ### Alternatif: Doğrudan GitHub'dan çalıştır
102
-
103
- ```json
104
- {
105
- "mcpServers": {
106
- "lemma": {
107
- "command": "npx",
108
- "args": ["-y", "github:xenitV1/lemma"]
109
- }
110
- }
111
- }
112
- ```
113
-
114
- ---
115
-
116
- ## Hook Sistemi
117
-
118
- Lemma, sunucu davranışını genişletmek için eklenti tabanlı bir hook sistemi sağlar:
119
-
120
- ### Yaşam Döngüsü Hook'ları
121
-
122
- ```javascript
123
- import { registerHook, HookTypes } from "@lemma/lemma/server";
124
-
125
- // Sunucu başlangıcında callback kaydet
126
- registerHook(HookTypes.ON_START, async (context) => {
127
- console.log("Sunucu başladı!", context);
128
- });
129
-
130
- // Proje bağlamı değişikliğinde callback kaydet
131
- registerHook(HookTypes.ON_PROJECT_CHANGE, async (context) => {
132
- console.log(`Proje değişti: ${context.project}`);
133
- });
134
- ```
135
-
136
- ### İstem Değiştiricileri
137
-
138
- Sistem istemi oluşturmayı özel dönüşümlerle genişletin:
139
-
140
- ```javascript
141
- import { registerPromptModifier } from "@lemma/lemma/server";
142
-
143
- registerPromptModifier(async (prompt, context) => {
144
- // İsteme özel bağlam ekle
145
- if (context.project === "uygulamam") {
146
- return prompt + "\n\n<custom>Not: Deneysel özellikler kullanılıyor.</custom>";
147
- }
148
- return prompt;
149
- });
150
- ```
151
-
152
- ---
153
-
154
- ## Manuel Kurulum (Geliştiriciler İçin)
155
-
156
- ```bash
157
- git clone https://github.com/xenitV1/lemma
158
- cd Lemma
159
- npm install
160
- ```
161
-
162
- **Gereksinimler:** Node.js 18.0.0 veya üzeri
163
-
164
- ### Yerel Konfigürasyon
165
-
166
- ```json
167
- {
168
- "mcpServers": {
169
- "lemma": {
170
- "command": "node",
171
- "args": ["C:\\yol\\to\\Lemma\\src\\index.js"]
172
- }
173
- }
174
- }
175
- ```
176
-
177
- ---
178
-
179
- ## Mevcut Araçlar
180
-
181
- ### Bellek Araçları
182
-
183
- #### `memory_read`
184
-
185
- Bellek fragmanlarını okur. ÖZET MODU sadece başlık + açıklama gösterir; tam detay için `id` kullanın.
186
-
187
- **Parametreler:**
188
- - `project` (string, opsiyonel): Filtrelenecek proje adı
189
- - `query` (string, opsiyonel): Semantik arama anahtar kelimesi
190
- - `id` (string, opsiyonel): Belirli bir fragmanın tam detayını al
191
- - `context` (string, opsiyonel): Bu erişimi bir bağlamla etiketle (örn. "debugging") — güveni artırır
192
- - `all` (boolean, opsiyonel): Tüm projelerden fragmanları göster (varsayılan: false)
193
-
194
- **Dönüş:** Güven çubuklarıyla formatlanmış string:
195
-
196
- ```
197
- === LEMMA BELLEK FRAGMANLARI (project: myapp) ===
198
- [m1a2b3] ████░ (🤖) [myapp] React Hooks
199
- useState ve useEffect pattern'leri
200
- ==============================
201
- ```
202
-
203
- #### `memory_add`
204
-
205
- **ZORUNLU:** Analizi tamamladıktan SONRA bulguları kaydetmek için çağır.
206
-
207
- **Parametreler:**
208
- - `fragment` (string, zorunlu): Saklanacak bellek metni
209
- - `title` (string, opsiyonel): Kısa başlık
210
- - `description` (string, opsiyonel): Kısa özet
211
- - `project` (string, opsiyonel): Proje kapsamı (null = küresel)
212
- - `source` (string, opsiyonel): "user" veya "ai", varsayılan "ai"
213
-
214
- #### `memory_update`
215
-
216
- Mevcut bir fragmanı ID ile güncelle.
217
-
218
- **Parametreler:**
219
- - `id` (string, zorunlu): Fragman ID'si
220
- - `title` (string, opsiyonel): Yeni başlık
221
- - `fragment` (string, opsiyonel): Yeni metin
222
- - `confidence` (number, opsiyonel): Yeni güven değeri 0-1
223
-
224
- #### `memory_feedback`
225
-
226
- Kullanımdan sonra bir bellek fragmanı hakkında geri bildirim ver. Pozitif geri bildirim güveni artırır; negatif geri bildirim doğrudan düşürür (-0.1).
227
-
228
- **Parametreler:**
229
- - `id` (string, zorunlu): Fragman ID'si
230
- - `useful` (boolean, zorunlu): Yardımcı olduysa `true`, olmadıysa `false`
231
-
232
- #### `memory_forget`
233
-
234
- Bir bellek fragmanını ID ile sil.
235
-
236
- **Parametreler:**
237
- - `id` (string, zorunlu): Fragman ID'si
238
-
239
- #### `memory_merge`
240
-
241
- Birden fazla fragmanı birleştir. Yeni ID oluşturur, orijinalleri siler.
242
-
243
- **Parametreler:**
244
- - `ids` (string[], zorunlu): Birleştirilecek fragman ID'leri
245
- - `title` (string, zorunlu): Birleştirilmiş fragmanın başlığı
246
- - `fragment` (string, zorunlu): Birleştirilmiş içerik
247
- - `project` (string, opsiyonel): Proje kapsamı
248
-
249
- ### Rehber Araçları
250
-
251
- #### `guide_get`
252
-
253
- Kullanım istatistikleriyle takip edilen rehberleri getir. Kullanım sayısına göre sıralı (en çok kullanılan önce).
254
-
255
- **Parametreler:**
256
- - `category` (string, opsiyonel): Kategoriye göre filtrele
257
- - `guide` (string, opsiyonel): Belirli rehber detayı al
258
- - `task` (string, opsiyonel): İlgili rehber önerileri almak için görev açıklaması
259
-
260
- #### `guide_practice`
261
-
262
- **ZORUNLU:** Çalışma sırasında bir rehber kullandığınızda kullanımını kaydedin.
263
-
264
- **Parametreler:**
265
- - `guide` (string, zorunlu): Rehber adı
266
- - `category` (string, zorunlu): Kategori
267
- - `description` (string, opsiyonel): Detaylı kılavuz/protokoller
268
- - `contexts` (string[], zorunlu): Kullanıldığı bağlamlar
269
- - `learnings` (string[], zorunlu): Keşfedilen yeni öğrenimler
270
-
271
- #### `guide_create`
272
-
273
- Detaylı bir kılavuzla rehber oluştur.
274
-
275
- **Parametreler:**
276
- - `guide` (string, zorunlu): Rehber adı
277
- - `category` (string, zorunlu): Kategori
278
- - `description` (string, zorunlu): Tam kılavuz/protokoller
279
- - `contexts` (string[], opsiyonel): İlk bağlamlar
280
- - `learnings` (string[], opsiyonel): İlk öğrenimler
281
-
282
- #### `guide_distill`
283
-
284
- Bir bellek fragmanını rehber öğrenimine dönüştür.
285
-
286
- **Parametreler:**
287
- - `memory_id` (string, zorunlu): Bellek fragmanı ID'si
288
- - `guide` (string, zorunlu): Hedef rehber adı
289
- - `category` (string, opsiyonel): Kategori (yeni rehber oluşturuluyorsa gerekli)
290
-
291
- #### `guide_update`
292
-
293
- Mevcut bir rehberin özelliklerini güncelle.
294
-
295
- **Parametreler:**
296
- - `guide` (string, zorunlu): Mevcut rehber adı
297
- - `new_name` (string, opsiyonel): Yeni ad
298
- - `category` (string, opsiyonel): Yeni kategori
299
- - `description` (string, opsiyonel): Yeni açıklama/kılavuz
300
-
301
- #### `guide_forget`
302
-
303
- Bir rehberi sil.
304
-
305
- **Parametreler:**
306
- - `guide` (string, zorunlu): Rehber adı
307
-
308
- #### `guide_merge`
309
-
310
- Birden fazla rehberi birleştir. Kullanım sayıları toplanır.
311
-
312
- **Parametreler:**
313
- - `guides` (string[], zorunlu): Birleştirilecek rehber adları
314
- - `guide` (string, zorunlu): Birleştirilmiş rehberin adı
315
- - `category` (string, zorunlu): Kategori
316
- - `description` (string, opsiyonel): Birleştirilmiş açıklama
317
- - `contexts` (string[], opsiyonel): Birleştirilmiş bağlamlar
318
- - `learnings` (string[], opsiyonel): Birleştirilmiş öğrenimler
319
-
320
- ## Felsefe
321
-
322
- ### Saklanması Gerekenler
323
-
324
- **Kullanıcı Katmanı:**
325
- - Kullanıcı tercihleri (iletişim tarzı, format, dil)
326
- - Proje bağlamı (teknoloji yığını, klasör yapısı, konvansiyonlar)
327
- - Açıkça istenen anılar
328
-
329
- **Yetenek Katmanı:**
330
- - Kullanılan başarılı çözümler ve yaklaşımlar
331
- - Tekrar eden görevler için keşfedilen kısayollar
332
- - Denenen ve başarısız olan yaklaşımlar
333
-
334
- ### Saklanmaması Gerekenler
335
-
336
- - Ham konuşma içeriği
337
- - Tekrar etmeyecek tek seferlik sorular
338
- - Geçici veya yüksek bağlama özgü bilgiler
339
- - Kişisel veya hassas veriler
340
-
341
- ## Geliştirme
342
-
343
- ### Testleri Çalıştırma
344
-
345
- ```bash
346
- npm test
347
- ```
348
-
349
- Kapsamlı test paketi: bellek çekirdeği, rehber çekirdeği, işleyiciler, öğrenme yaşam döngüsü, hook sistemi ve dinamik istem oluşturma. Tüm I/O geçici dizinlere izole edilir — gerçek verilere dokunulmaz.
350
-
351
- ### Proje Yapısı
352
-
353
- ```
354
- Lemma/
355
- ├── src/
356
- │ ├── index.js # MCP sunucu giriş noktası
357
- │ ├── memory/
358
- │ │ ├── index.js # Bellek modülü yeniden dışa aktarmalar
359
- │ │ └── core.js # Temel bellek mantığı
360
- │ ├── guides/
361
- │ │ ├── index.js # Rehber modülü yeniden dışa aktarmalar
362
- │ │ ├── core.js # Temel rehber mantığı
363
- │ │ └── task-map.js # Görev-rehber eşlemesi
364
- │ └── server/
365
- │ ├── index.js # Sunucu kurulumu
366
- │ ├── handlers.js # Araç işleyicileri
367
- │ ├── tools.js # Araç tanımları
368
- │ ├── hooks.js # Hook sistemi ve istem değiştiriciler
369
- │ └── system-prompt.js
370
- ├── tests/
371
- │ └── test.js # Test paketi
372
- ├── package.json
373
- ├── jsr.json
374
- ├── CHANGELOG.md
375
- └── README.md
376
- ```
377
-
378
- ## Güvenlik
379
-
380
- `memory.jsonl` ve `guides.jsonl` yerel dosyalardır ve asla hiçbir yere gönderilmez. Kullanıcılar içeriklerini inceleyebilir veya MCP araçları üzerinden istedikleri zaman temizleyebilirler.
381
-
382
- ## Lisans
383
-
384
- MIT License
1
+ <p align="center">
2
+ <img src="assets/logo.png" width="200" alt="Lemma Logo">
3
+ </p>
4
+
5
+ # Lemma - LLM'ler için Kalıcı Bellek (MCP)
6
+
7
+ [English](README.md) | [Türkçe](README.tr.md)
8
+
9
+ Lemma, Büyük Dil Modelleri (LLM) için kalıcı bir bellek katmanı sağlayan bir Model Bağlam Protokolü (MCP) sunucusudur. LLM'lerin oturumlar arasında gerçekleri, tercihleri ve bağlamı hatırlamasını sağlar; otomatik çürüme, öğrenme ve evrensel enjeksiyon ile biyolojik bir bellek modeli sunar.
10
+
11
+ ## Lemma Nedir?
12
+
13
+ Lemma, AI asistanları için harici bir hipokampüs görevi görür. İnsan beyni her şeyi kaydetmez — sentezler, damıtır ve fragmanlar bırakır. Sık erişilen bilgiler güçlenir; kullanılmayan bilgiler solar ve unutulur.
14
+
15
+ Lemma aynı prensiple çalışır:
16
+
17
+ - **Ham konuşmalar asla saklanmaz** — sadece sentezlenmiş fragmanlar
18
+ - **Fragmanlar zamanla çürür** — sık erişilenler güçlenir
19
+ - **Kullanılan bilgi bağlam kazanır** — etiketler ve ilişkiler otomatik oluşturulur
20
+ - **Bellekler otomatik enjekte edilir** — LLM araç çağırmadan onları görür
21
+
22
+ ## Nasıl Çalışır?
23
+
24
+ ### Evrensel Bellek Enjeksiyonu (Universal Memory Injection)
25
+
26
+ Lemma, bellekleri `tools/list` üzerinden doğrudan araç açıklamalarına enjekte eder. Bu **her MCP istemcisinde** çalışır — Claude Desktop, Cursor, VS Code, opencode, Gemini CLI ve diğerleri.
27
+
28
+ ```
29
+ tools/list → memory_read description includes:
30
+ "YOUR MEMORIES (you already know these):
31
+ [m8f728] React Architecture (95%)
32
+ Full content here...
33
+ [m1bbea] Clean Code Research (77%)
34
+ Full content here..."
35
+ ```
36
+
37
+ LLM her oturuma en önemli belleklerini zaten bilerek başlar. Açık bir araç çağrısına gerek yoktur.
38
+
39
+ **Çift katmanlı enjeksiyon:**
40
+ 1. **Açıklamalar (Tool descriptions)** — evrensel, her yerde çalışır
41
+ 2. **`instructions` alanı** — MCP başlatma talimatlarını destekleyen istemciler için
42
+
43
+ **3 katmanlı mimari:**
44
+ - Katman 1: En önemli bellekler için tam içerik (~3000 token, yapılandırılabilir)
45
+ - Katman 2: Kalan bellekler için özet indeksi
46
+ - Katman 3: Açıklamaları ve öğrenimleriyle aktif rehberler
47
+
48
+ ### Bellek Yapısı
49
+
50
+ Her bellek fragmanı şu alanlara sahiptir:
51
+
52
+ | Alan | Tip | Açıklama |
53
+ |-------|------|-------------|
54
+ | `id` | string | Benzersiz kimlik (`m` + crypto.randomUUID'den 12 hex karakter) |
55
+ | `title` | string | Hızlı tarama için kısa başlık |
56
+ | `fragment` | string | Sentezlenmiş bellek metni |
57
+ | `project` | string | Proje kapsamı (küresel için `null`) |
58
+ | `confidence` | float | Güvenilirlik 0.0-1.0 (zamanla çürür ve güçlenir) |
59
+ | `source` | string | `"user"` veya `"ai"` |
60
+ | `created` | string | Oluşturulma tarihi (YYYY-MM-DD) |
61
+ | `lastAccessed` | string | Son okuma zamanı (ISO timestamp) |
62
+ | `accessed` | int | Mevcut çürüme döngüsündeki erişim sayısı |
63
+ | `tags` | string[] | Kullanımdan elde edilen bağlam etiketleri (örn. "debugging", "refactoring") |
64
+ | `associatedWith` | string[] | Aynı oturumda erişilen fragman ID'leri |
65
+ | `negativeHits` | int | Bu belleğin yardımcı olmadığı işaretlenme sayısı (oturum başına sıfırlanır) |
66
+
67
+ ### Öğrenme Sistemi
68
+
69
+ Statik belleğin aksine, Lemma bilginin kullanım yoluyla evrildiği biyolojik bir model kullanır:
70
+
71
+ **Güçlendirme (erişimde):**
72
+ ```
73
+ confidence = min(1.0, confidence + 0.1)
74
+ tags += context_tag (e.g., "debugging")
75
+ associatedWith += co_accessed_fragment_ids
76
+ ```
77
+
78
+ **Çürüme (oturum başına):**
79
+ ```
80
+ decay = max(0.005, 0.05 - (accessed * 0.005))
81
+ confidence = confidence - decay
82
+ ```
83
+
84
+ - **Sıklık**: Sık erişilen öğeler daha yavaş çürür (minimum oturum başına 0.005)
85
+ - **Kullanılmayan öğeler** temel oran olan oturum başına 0.05 çürür
86
+ - **İlişkiler**: Birlikte kullanılan fragmanlar gelecekteki hatırlama için çapraz referanslar oluşturur
87
+
88
+ ### Tekilleştirme (Deduplication)
89
+
90
+ Lemma, tekilleştirme için **Fuse.js bulanık eşleştirme** (Jaccard değil) kullanır:
91
+ - "Use React hooks" vs "Don't use React hooks" — doğru şekilde farklı algılanır
92
+ - "react", "reactjs", "React.js" — doğru şekilde aynı algılanır (rehberler için)
93
+ - Hem kullanıcı hem de AI kaynaklı belleklere uygulanır
94
+
95
+ ### Sanal Oturumlar (Virtual Sessions)
96
+
97
+ Araç çağrıları otomatik olarak sanal oturumlara dönüştürülür:
98
+ - İlk araç çağrısında otomatik başlar
99
+ - 30 dakikalık işlem yapılmadığında otomatik sonlanır
100
+ - Karşılaşılan teknolojileri, kullanılan rehberleri, oluşturulan bellekleri izler
101
+ - Açık `session_start`/`session_end` gerekmez
102
+ - Oturumlar `~/.lemma/sessions/` dizininde saklanır
103
+
104
+ ### Veri Güvenliği
105
+
106
+ - **Kümülatif yedekleme**: `.bak` dosyaları ID tabanlı birleştirmedir — mevcut girdilerin üzerine asla yazmaz
107
+ - **Dosya kilitleme**: Modül düzeyinde yazma kilidi eşzamanlı veri bozulmasını önler
108
+ - **Güvenli I/O**: Boş/null diziler yazılmadan önce reddedilir
109
+ - **Örtük silme yok**: Çürüme sadece güveni azaltır, fragmanları asla kaldırmaz
110
+
111
+ ### Yapılandırma
112
+
113
+ `~/.lemma/config.json` konumunda isteğe bağlı yapılandırma dosyası:
114
+
115
+ ```json
116
+ {
117
+ "token_budget": {
118
+ "full_content": 3000,
119
+ "summary_index": 1000,
120
+ "guides_detail": 1000
121
+ },
122
+ "injection": {
123
+ "max_full_content_fragments": 15,
124
+ "max_summary_fragments": 30,
125
+ "max_guides": 20,
126
+ "max_guide_detail": 3
127
+ },
128
+ "virtual_session": {
129
+ "timeout_minutes": 30
130
+ }
131
+ }
132
+ ```
133
+
134
+ ### Dosya Konumları
135
+
136
+ | İşletim Sistemi | Yol |
137
+ |---|---|
138
+ | **Windows** | `C:\Users\{username}\.lemma\` |
139
+ | **macOS** | `/Users/{username}/.lemma/` |
140
+ | **Linux** | `/home/{username}/.lemma/` |
141
+
142
+ Dosyalar:
143
+ - `memory.jsonl` — bellek fragmanları
144
+ - `guides.jsonl` — deneyim rehberleri
145
+ - `config.json` — kullanıcı yapılandırması (isteğe bağlı)
146
+ - `sessions/` — sanal oturum kayıtları
147
+ - `.bak` dosyaları — kümülatif yedekler
148
+
149
+ ## Hızlı Başlangıç
150
+
151
+ Lemma'yı MCP istemci yapılandırmanıza ekleyin:
152
+
153
+ **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
154
+ **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
155
+
156
+ ```json
157
+ {
158
+ "mcpServers": {
159
+ "lemma": {
160
+ "command": "npx",
161
+ "args": ["-y", "lemma-mcp"]
162
+ }
163
+ }
164
+ }
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Hook Sistemi
170
+
171
+ Lemma, sunucu davranışını genişletmek için eklenti tabanlı bir hook sistemi sağlar:
172
+
173
+ ### Yaşam Döngüsü Hook'ları
174
+
175
+ ```javascript
176
+ import { registerHook, HookTypes } from "@lemma/lemma/server";
177
+
178
+ registerHook(HookTypes.ON_START, async (context) => {
179
+ console.log("Server started!", context);
180
+ });
181
+
182
+ registerHook(HookTypes.ON_PROJECT_CHANGE, async (context) => {
183
+ console.log(`Project changed to: ${context.project}`);
184
+ });
185
+ ```
186
+
187
+ ### İstem Değiştiricileri
188
+
189
+ Sistem istemi oluşturmayı özel dönüşümlerle genişletin:
190
+
191
+ ```javascript
192
+ import { registerPromptModifier } from "lemma-mcp/server";
193
+
194
+ registerPromptModifier(async (prompt, context) => {
195
+ if (context.project === "my-app") {
196
+ return prompt + "\n\n<custom>Note: Using experimental features.</custom>";
197
+ }
198
+ return prompt;
199
+ });
200
+ ```
201
+
202
+ ---
203
+
204
+ ## Manuel Kurulum
205
+
206
+ ```bash
207
+ git clone https://github.com/xenitV1/lemma
208
+ cd Lemma
209
+ npm install
210
+ ```
211
+
212
+ **Gereksinimler:** Node.js 18.0.0 veya üzeri
213
+
214
+ ### Yerel Yapılandırma
215
+
216
+ ```json
217
+ {
218
+ "mcpServers": {
219
+ "lemma": {
220
+ "command": "node",
221
+ "args": ["C:\\path\\to\\Lemma\\src\\index.js"]
222
+ }
223
+ }
224
+ }
225
+ ```
226
+
227
+ ---
228
+
229
+ ## Mevcut Araçlar (20)
230
+
231
+ ### Bellek Araçları (10)
232
+
233
+ #### `memory_read`
234
+
235
+ Bellek fragmanlarını okur. ÖZET MODU sadece başlık + açıklama gösterir; tam detay için `id` kullanın.
236
+
237
+ **Parametreler:**
238
+ - `project` (string, opsiyonel): Filtrelenecek proje adı
239
+ - `query` (string, opsiyonel): Semantik arama anahtar kelimesi
240
+ - `id` (string, opsiyonel): Belirli bir fragmanın tam detayını al
241
+ - `ids` (string[], opsiyonel): Birden fazla fragmanın tam detaylarını al
242
+ - `context` (string, opsiyonel): Bu erişimi bir bağlamla etiketle (örn. "debugging")
243
+ - `all` (boolean, opsiyonel): Tüm projelerden fragmanları göster (varsayılan: false)
244
+
245
+ #### `memory_add`
246
+
247
+ **ZORUNLU:** Analizi tamamladıktan SONRA bulguları kaydetmek için çağır.
248
+
249
+ **Parametreler:**
250
+ - `fragment` (string, zorunlu): Saklanacak bellek metni
251
+ - `title` (string, opsiyonel): Kısa başlık
252
+ - `description` (string, opsiyonel): Kısa özet
253
+ - `project` (string, opsiyonel): Proje kapsamı (null = küresel)
254
+ - `source` (string, opsiyonel): "user" veya "ai", varsayılan "ai"
255
+
256
+ #### `memory_update`
257
+
258
+ Mevcut bir fragmanı ID ile güncelle.
259
+
260
+ **Parametreler:**
261
+ - `id` (string, zorunlu): Fragman ID'si
262
+ - `title` (string, opsiyonel): Yeni başlık
263
+ - `fragment` (string, opsiyonel): Yeni metin
264
+ - `confidence` (number, opsiyonel): Yeni güven değeri 0-1
265
+
266
+ #### `memory_feedback`
267
+
268
+ Kullanımdan sonra bir bellek fragmanı hakkında geri bildirim ver. Pozitif geri bildirim güveni artırır; negatif -0.1 düşürür.
269
+
270
+ **Parametreler:**
271
+ - `id` (string, zorunlu): Fragman ID'si
272
+ - `useful` (boolean, zorunlu): Yardımcı olduysa `true`, olmadıysa `false`
273
+
274
+ #### `memory_forget`
275
+
276
+ Bir bellek fragmanını ID ile sil.
277
+
278
+ **Parametreler:**
279
+ - `id` (string, zorunlu): Fragman ID'si
280
+
281
+ #### `memory_merge`
282
+
283
+ Birden fazla fragmanı birleştir. Yeni ID oluşturur, orijinalleri siler.
284
+
285
+ **Parametreler:**
286
+ - `ids` (string[], zorunlu): Birleştirilecek fragman ID'leri
287
+ - `title` (string, zorunlu): Birleştirilmiş fragmanın başlığı
288
+ - `fragment` (string, zorunlu): Birleştirilmiş içerik
289
+ - `project` (string, opsiyonel): Proje kapsamı
290
+
291
+ #### `memory_stats`
292
+
293
+ Bellek deposu istatistiklerini getir: fragman sayıları, ortalama güven, proje dağılımı.
294
+
295
+ **Parametreler:**
296
+ - `project` (string, opsiyonel): Projeye göre filtrele
297
+
298
+ #### `memory_audit`
299
+
300
+ Bellek deposunda bütünlük sorunlarını denetle: yetim referanslar, yinelenen ID'ler, güven anomalileri.
301
+
302
+ ### Rehber Araçları (8)
303
+
304
+ #### `guide_get`
305
+
306
+ Kullanım istatistikleriyle takip edilen rehberleri getir. Kullanım sayısına göre sıralı (en çok kullanılan önce).
307
+
308
+ **Parametreler:**
309
+ - `category` (string, opsiyonel): Kategoriye göre filtrele
310
+ - `guide` (string, opsiyonel): Belirli rehber detayı al
311
+ - `task` (string, opsiyonel): İlgili rehber önerileri almak için görev açıklaması
312
+
313
+ #### `guide_practice`
314
+
315
+ **ZORUNLU:** Çalışma sırasında bir rehber kullandığınızda kullanımını kaydedin.
316
+
317
+ **Parametreler:**
318
+ - `guide` (string, zorunlu): Rehber adı
319
+ - `category` (string, zorunlu): Kategori
320
+ - `description` (string, opsiyonel): Detaylı kılavuz/protokoller
321
+ - `contexts` (string[], zorunlu): Kullanıldığı bağlamlar
322
+ - `learnings` (string[], zorunlu): Keşfedilen yeni öğrenimler
323
+ - `outcome` (string, opsiyonel): "success" veya "failure" — başarı oranını izler
324
+
325
+ #### `guide_create`
326
+
327
+ Detaylı bir kılavuzla rehber oluştur.
328
+
329
+ **Parametreler:**
330
+ - `guide` (string, zorunlu): Rehber adı
331
+ - `category` (string, zorunlu): Kategori
332
+ - `description` (string, zorunlu): Tam kılavuz/protokoller
333
+ - `contexts` (string[], opsiyonel): İlk bağlamlar
334
+ - `learnings` (string[], opsiyonel): İlk öğrenimler
335
+
336
+ #### `guide_distill`
337
+
338
+ Bir bellek fragmanını rehber öğrenimine dönüştür.
339
+
340
+ **Parametreler:**
341
+ - `memory_id` (string, zorunlu): Bellek fragmanı ID'si
342
+ - `guide` (string, zorunlu): Hedef rehber adı
343
+ - `category` (string, opsiyonel): Kategori (yeni rehber oluşturuluyorsa gerekli)
344
+
345
+ #### `guide_update`
346
+
347
+ Mevcut bir rehberin özelliklerini güncelle.
348
+
349
+ **Parametreler:**
350
+ - `guide` (string, zorunlu): Mevcut rehber adı
351
+ - `new_name` (string, opsiyonel): Yeni ad
352
+ - `category` (string, opsiyonel): Yeni kategori
353
+ - `description` (string, opsiyonel): Yeni açıklama/kılavuz
354
+ - `add_anti_patterns` (string[], opsiyonel): Anti-pattern'ler ekle
355
+ - `add_pitfalls` (string[], opsiyonel): Bilinen tuzaklar ekle
356
+ - `superseded_by` (string, opsiyonel): Başka bir rehberle değiştirildi olarak işaretle
357
+ - `deprecated` (boolean, opsiyonel): Kullanımdan kaldırıldı olarak işaretle
358
+
359
+ #### `guide_forget`
360
+
361
+ Bir rehberi sil.
362
+
363
+ **Parametreler:**
364
+ - `guide` (string, zorunlu): Rehber adı
365
+
366
+ #### `guide_merge`
367
+
368
+ Birden fazla rehberi birleştir. Kullanım sayıları toplanır.
369
+
370
+ **Parametreler:**
371
+ - `guides` (string[], zorunlu): Birleştirilecek rehber adları
372
+ - `guide` (string, zorunlu): Birleştirilmiş rehberin adı
373
+ - `category` (string, zorunlu): Kategori
374
+ - `description` (string, opsiyonel): Birleştirilmiş açıklama
375
+ - `contexts` (string[], opsiyonel): Birleştirilmiş bağlamlar
376
+ - `learnings` (string[], opsiyonel): Birleştirilmiş öğrenimler
377
+
378
+ ### Oturum Araçları (2)
379
+
380
+ #### `session_start`
381
+
382
+ İzlenen bir çalışma oturumu başlat. Görev metaverisini kaydeder ve ilgili rehberleri getirir.
383
+
384
+ **Parametreler:**
385
+ - `task_type` (string, zorunlu): "debugging", "implementation", "refactoring", "testing", "research", "documentation", "optimization" veya "other"
386
+ - `technologies` (string[], opsiyonel): İlgili teknolojiler
387
+ - `initial_approach` (string, opsiyonel): İlk plan
388
+
389
+ #### `session_end`
390
+
391
+ Mevcut oturumu sonlandır. Sonucu kaydeder ve rehber başarı takibini günceller.
392
+
393
+ **Parametreler:**
394
+ - `outcome` (string, zorunlu): "success", "partial", "failure" veya "abandoned"
395
+ - `final_approach` (string, opsiyonel): Hangi yaklaşım işe yaradı
396
+ - `lessons` (string[], opsiyonel): Öğrenilenler
397
+
398
+ #### `session_stats`
399
+
400
+ Sanal oturum istatistiklerini getir: son araç kullanım örüntüleri ve teknolojiler.
401
+
402
+ **Parametreler:**
403
+ - `count` (number, opsiyonel): Son oturum sayısı (varsayılan 10)
404
+
405
+ ## Felsefe
406
+
407
+ ### Saklanması Gerekenler
408
+
409
+ **Kullanıcı Katmanı:**
410
+ - Kullanıcı tercihleri (iletişim tarzı, format, dil)
411
+ - Proje bağlamı (teknoloji yığını, klasör yapısı, konvansiyonlar)
412
+ - Açıkça istenen anılar
413
+
414
+ **Yetenek Katmanı:**
415
+ - Kullanılan başarılı çözümler ve yaklaşımlar
416
+ - Tekrar eden görevler için keşfedilen kısayollar
417
+ - Denenen ve başarısız olan yaklaşımlar
418
+
419
+ ### Saklanmaması Gerekenler
420
+
421
+ - Ham konuşma içeriği
422
+ - Tekrar etmeyecek tek seferlik sorular
423
+ - Geçici veya yüksek bağlama özgü bilgiler
424
+ - Kişisel veya hassas veriler
425
+
426
+ ## Geliştirme
427
+
428
+ ### Testleri Çalıştırma
429
+
430
+ ```bash
431
+ npm test
432
+ ```
433
+
434
+ 360 test: bellek çekirdeği, rehber çekirdeği, işleyiciler, öğrenme yaşam döngüsü, hook sistemi, dinamik istem oluşturma ve sanal oturumları kapsar. Tüm I/O geçici dizinlere izole edilir.
435
+
436
+ ```bash
437
+ npm run typecheck # TypeScript tip kontrolü
438
+ npm run build # TypeScript'i dist/ dizinine derle
439
+ ```
440
+
441
+ ### Proje Yapısı
442
+
443
+ ```
444
+ Lemma/
445
+ ├── src/
446
+ │ ├── index.ts # MCP sunucu giriş noktası
447
+ │ ├── types.ts # Paylaşılan TypeScript arayüzleri
448
+ │ ├── memory/
449
+ │ │ ├── index.ts # Bellek modülü yeniden dışa aktarmalar
450
+ │ │ ├── core.ts # Temel bellek mantığı, çürüme, arama, tekilleştirme
451
+ │ │ └── config.ts # Kullanıcı yapılandırma yükleyici
452
+ │ ├── guides/
453
+ │ │ ├── index.ts # Rehber modülü yeniden dışa aktarmalar
454
+ │ │ ├── core.ts # Temel rehber mantığı, bulanık tekilleştirme
455
+ │ │ └── task-map.ts # Görev-rehber eşlemesi
456
+ │ ├── server/
457
+ │ │ ├── index.ts # Sunucu kurulumu, enjeksiyon, bildirimler
458
+ │ │ ├── handlers.ts # Araç işleyicileri (20 araç)
459
+ │ │ ├── tools.ts # Araç tanımları
460
+ │ │ ├── hooks.ts # Hook sistemi ve istem değiştiriciler
461
+ │ │ └── system-prompt.ts # Dinamik sistem istemi
462
+ │ └── sessions/
463
+ │ ├── index.ts # Oturum modülü yeniden dışa aktarmalar
464
+ │ ├── core.ts # Oturum yaşam döngüsü
465
+ │ └── virtual.ts # Sanal oturum izleme
466
+ ├── tests/
467
+ │ ├── memory/ # 7 test dosyası
468
+ │ ├── guides/ # 6 test dosyası
469
+ │ ├── sessions/ # 2 test dosyası
470
+ │ └── server/ # 10 test dosyası
471
+ ├── docs/ # Araştırma makaleleri ve referanslar
472
+ ├── package.json
473
+ ├── tsconfig.json
474
+ ├── CHANGELOG.md
475
+ └── README.md
476
+ ```
477
+
478
+ ## Güvenlik
479
+
480
+ Tüm veriler yerel olarak `~/.lemma/` dizininde saklanır. Hiçbir şey harici sunuculara gönderilmez. Kullanıcılar istedikleri zaman MCP araçları üzerinden veya doğrudan verileri inceleyebilir, düzenleyebilir veya temizleyebilir.
481
+
482
+ ## Lisans
483
+
484
+ MIT License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lemma-mcp",
3
- "version": "0.7.0",
3
+ "version": "0.7.1",
4
4
  "description": "Persistent memory layer for LLMs via MCP",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",