sqlew 2.0.0 → 2.1.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 (42) hide show
  1. package/CHANGELOG.md +222 -0
  2. package/README.md +314 -209
  3. package/assets/schema.sql +122 -36
  4. package/dist/cli.d.ts +7 -0
  5. package/dist/cli.d.ts.map +1 -0
  6. package/dist/cli.js +312 -0
  7. package/dist/cli.js.map +1 -0
  8. package/dist/database.d.ts.map +1 -1
  9. package/dist/database.js +18 -0
  10. package/dist/database.js.map +1 -1
  11. package/dist/index.js +136 -42
  12. package/dist/index.js.map +1 -1
  13. package/dist/migrations/add-v2.1.0-features.d.ts +29 -0
  14. package/dist/migrations/add-v2.1.0-features.d.ts.map +1 -0
  15. package/dist/migrations/add-v2.1.0-features.js +198 -0
  16. package/dist/migrations/add-v2.1.0-features.js.map +1 -0
  17. package/dist/schema.d.ts.map +1 -1
  18. package/dist/schema.js +5 -0
  19. package/dist/schema.js.map +1 -1
  20. package/dist/tools/context.d.ts +91 -1
  21. package/dist/tools/context.d.ts.map +1 -1
  22. package/dist/tools/context.js +695 -70
  23. package/dist/tools/context.js.map +1 -1
  24. package/dist/tools/files.d.ts +10 -1
  25. package/dist/tools/files.d.ts.map +1 -1
  26. package/dist/tools/files.js +98 -1
  27. package/dist/tools/files.js.map +1 -1
  28. package/dist/tools/messaging.d.ts +10 -1
  29. package/dist/tools/messaging.d.ts.map +1 -1
  30. package/dist/tools/messaging.js +107 -1
  31. package/dist/tools/messaging.js.map +1 -1
  32. package/dist/tools/utils.d.ts +9 -1
  33. package/dist/tools/utils.d.ts.map +1 -1
  34. package/dist/tools/utils.js +115 -0
  35. package/dist/tools/utils.js.map +1 -1
  36. package/dist/types.d.ts +196 -0
  37. package/dist/types.d.ts.map +1 -1
  38. package/dist/utils/cleanup.d.ts +12 -1
  39. package/dist/utils/cleanup.d.ts.map +1 -1
  40. package/dist/utils/cleanup.js +20 -3
  41. package/dist/utils/cleanup.js.map +1 -1
  42. package/package.json +4 -2
package/README.md CHANGED
@@ -1,52 +1,146 @@
1
1
  # sqlew
2
+ ![sqlew_logo](assets/sqlew-logo.png)
2
3
 
3
4
  [![npm version](https://img.shields.io/npm/v/sqlew.svg)](https://www.npmjs.com/package/sqlew)
4
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
6
 
6
- **sqlew** (SQL Efficient Workflow) is a Model Context Protocol (MCP) server for efficient context sharing between Claude Code sub-agents. Achieve **96% token reduction** through action-based tools while managing structured data through a metadata-driven SQLite database.
7
+ > **SQL Efficient Workflow** - MCP server for efficient context sharing between Claude Code sub-agents
7
8
 
8
- ## ⚠️ Version 2.0.0 - Breaking Changes
9
+ ## Overview
9
10
 
10
- **v2.0.0 introduces action-based tools that consolidate the API from 20 tools to 6 tools.** This is a breaking change in the MCP tool API only.
11
+ **sqlew** is a Model Context Protocol (MCP) server that enables efficient context sharing between multiple Claude Code agents through a SQLite-backed database. It dramatically reduces token consumption while providing structured data management through metadata-driven organization.
11
12
 
12
- **Database Compatibility:** ✅ **100% compatible** - v2.0 uses the same database schema as v1.x. No data migration needed.
13
+ **Current Version:** 2.1.1
13
14
 
14
- **Migration Required:** Only for code that calls MCP tools - see [MIGRATION_v2.md](MIGRATION_v2.md) for upgrade guide.
15
+ ## Benefits
15
16
 
16
- ## Why sqlew?
17
+ ### 🧠 Organizational Memory for AI Agents
17
18
 
18
- When coordinating multiple Claude Code agents on a complex project, context sharing becomes critical. Traditional JSON-based approaches consume massive amounts of tokens. sqlew solves this with:
19
+ **sqlew solves the "organizational memory" problem that traditional code can't:**
19
20
 
20
- - **96% Token Reduction:** Action-based API eliminates tool duplication (12,848 → 481 tokens)
21
- - **67% MCP Context Reduction:** From ~13,730 to ~4,482 tokens in MCP server definitions
22
- - **Structured Metadata:** Tags, layers, scopes, versions, and priorities for intelligent organization
23
- - **Fast & Reliable:** SQLite-backed with ACID guarantees and automatic cleanup
24
- - **6 Action-Based Tools:** Comprehensive API for decisions, messaging, file tracking, constraints, config, and stats
25
- - **Help Actions:** On-demand documentation with zero token cost until called
21
+ | What Traditional Code Provides | What sqlew Adds |
22
+ |-------------------------------|-----------------|
23
+ | **Git history** - WHAT changed | **Decisions** - WHY it changed |
24
+ | **Code comments** - HOW it works | ✅ **Constraints** - WHY it must work this way |
25
+ | **Architectural decisions** - Missing! | **Context survival** - Across sessions |
26
+
27
+ **Real-World Example:**
28
+ ```typescript
29
+ // Agent in Session 1 records:
30
+ {
31
+ key: "loom/duration-constraint",
32
+ value: "Duration must NOT occur in Loom module",
33
+ layer: "business",
34
+ tags: ["architecture", "constraint", "breaking"]
35
+ }
36
+
37
+ // Agent in Session 2 queries:
38
+ "What are business layer constraints for Loom module?"
39
+ → Finds: "Duration must NOT occur in Loom"
40
+ → Avoids introducing the same bug you just fixed!
41
+ ```
42
+
43
+ ### 💡 Why This Matters for LLMs
44
+
45
+ 1. **Context Survival**: Next Claude session can query architectural decisions from previous sessions
46
+ 2. **Prevents Regression**: Constraints like "Duration must NOT occur in Loom" prevent reintroducing bugs
47
+ 3. **Historical Reasoning**: Captures WHY decisions were made, not just WHAT changed
48
+ 4. **Knowledge Discovery**: Searchable by layer/tag/scope - "Show me all breaking changes in business layer"
49
+
50
+ ### ⚡ Real-World Token Savings
51
+
52
+ **Scenario: 5 Agents Working Across 10 Sessions**
53
+
54
+ | Approach | Token Usage | Details |
55
+ |----------|-------------|---------|
56
+ | **Without sqlew** | ~20,000 tokens | All context re-provided every session |
57
+ | **With sqlew** | ~7,400 tokens | Selective queries, persistent storage |
58
+ | **Savings** | **63% reduction** | Realistic multi-session project |
59
+
60
+ **Why sqlew Saves Tokens:**
61
+
62
+ 1. **Selective Retrieval** (50-70% savings)
63
+ - Without: Must read ALL context every time
64
+ - With: Query only what's needed - `search_layer("business")` returns 5 decisions, not 100
65
+
66
+ 2. **Structured vs Unstructured** (60-85% savings)
67
+ - Without: "We decided to use JWT because..." (50-200 tokens in prose)
68
+ - With: `{key: "auth", value: "JWT", layer: "business"}` (20-30 tokens)
69
+
70
+ 3. **Cross-Session Persistence** (80-95% savings)
71
+ - Without: Context re-provided every new session
72
+ - With: Query from database, context survives sessions
73
+
74
+ 4. **Search Instead of Scan** (70-90% savings)
75
+ - Without: Read all 100 decisions to find 5 relevant ones
76
+ - With: `search_tags(["breaking", "api"])` → only relevant results
77
+
78
+ **Expected Token Reduction (Typical Multi-Agent Project):**
79
+ - Conservative: 50-65% reduction
80
+ - Realistic: 60-75% reduction
81
+ - Optimal: 70-85% reduction
82
+
83
+ *Note: Internal architecture improvements (v1.0.0→v2.0.0) achieved 96% tool definition reduction and 67% MCP context reduction. The percentages above reflect real-world usage benefits.*
84
+
85
+ **Performance:**
86
+ - Query response: 2-50ms
87
+ - Concurrent access: 5+ simultaneous agents
88
+ - Storage efficiency: ~140 bytes per decision
89
+
90
+ **Reliability:**
91
+ - SQLite ACID transactions
92
+ - 100% backward compatible upgrades
26
93
 
27
94
  ## Features
28
95
 
29
- - **Context Management:** Record and retrieve decisions with advanced filtering (tags, layers, scopes, versions)
30
- - **Agent Messaging:** Priority-based messaging system with broadcast support
31
- - **File Change Tracking:** Layer-based file organization with lock detection
32
- - **Constraint Management:** Track performance, architecture, and security constraints
33
- - **Token Efficient:** Pre-aggregated views and integer enums minimize token consumption
34
- - **Weekend-Aware Auto-Cleanup:** Smart retention policies that pause during weekends
35
- - **Configurable Retention:** Adjust cleanup periods via CLI args or MCP tools
36
- - **Version History:** Track decision evolution over time
37
- - **Concurrent Access:** Supports multiple agents simultaneously
96
+ ### Core Capabilities
97
+ - **Context Management** - Store and retrieve decisions with tags, layers, scopes, and versions
98
+ - **Agent Messaging** - Priority-based messaging system with broadcast support
99
+ - **File Change Tracking** - Layer-based file organization with lock detection
100
+ - **Constraint Management** - Track performance, architecture, and security constraints
101
+ - **Activity Logging** - Automatic tracking of all agent actions (v2.1.0)
102
+ - **Weekend-Aware Auto-Cleanup** - Smart retention policies that pause during weekends
103
+
104
+ ### Advanced Features (v2.1.0)
105
+ - **Smart Defaults** - Auto-infer layer and tags from file paths (60% token reduction)
106
+ - **Batch Operations** - Process up to 50 operations atomically (70% token reduction)
107
+ - **Update Polling** - Lightweight subscription mechanism (95% token reduction)
108
+ - **Advanced Query** - Complex multi-criteria filtering with full-text search
109
+ - **Templates** - 5 built-in templates + custom template support
110
+ - **CLI Tool** - Standalone query commands without MCP server
111
+
112
+ ### 6 Consolidated Tools (26 Actions)
113
+ 1. **`decision`** (13 actions) - Context management with metadata
114
+ 2. **`message`** (4 actions) - Agent-to-agent messaging
115
+ 3. **`file`** (4 actions) - File change tracking
116
+ 4. **`constraint`** (3 actions) - Constraint management
117
+ 5. **`stats`** (4 actions) - Statistics and cleanup
118
+ 6. **`config`** (2 actions) - Configuration management
38
119
 
39
120
  ## Installation
40
121
 
122
+ ### Requirements
123
+ - Node.js 18.0.0 or higher
124
+ - npm or npx
125
+
126
+ ### Install from npm
127
+
41
128
  ```bash
42
129
  npm install sqlew
43
130
  ```
44
131
 
132
+ ### Quick Test
133
+
134
+ ```bash
135
+ # Test with MCP Inspector
136
+ npx @modelcontextprotocol/inspector npx sqlew
137
+ ```
138
+
45
139
  ## Quick Start
46
140
 
47
141
  ### Add to Claude Desktop
48
142
 
49
- Add sqlew to your Claude Desktop configuration (`claude_desktop_config.json`):
143
+ Add to your Claude Desktop configuration (`claude_desktop_config.json`):
50
144
 
51
145
  ```json
52
146
  {
@@ -59,7 +153,7 @@ Add sqlew to your Claude Desktop configuration (`claude_desktop_config.json`):
59
153
  }
60
154
  ```
61
155
 
62
- Or with a custom database path:
156
+ ### Custom Database Path
63
157
 
64
158
  ```json
65
159
  {
@@ -72,7 +166,7 @@ Or with a custom database path:
72
166
  }
73
167
  ```
74
168
 
75
- Or with weekend-aware auto-deletion enabled:
169
+ ### Weekend-Aware Auto-Deletion
76
170
 
77
171
  ```json
78
172
  {
@@ -90,30 +184,24 @@ Or with weekend-aware auto-deletion enabled:
90
184
  }
91
185
  ```
92
186
 
93
- ### Using with MCP Inspector
94
-
95
- Test all tools interactively:
96
-
97
- ```bash
98
- npx @modelcontextprotocol/inspector npx sqlew
99
- ```
100
-
101
- ### Database Location
187
+ ### Default Database Location
102
188
 
103
- Default: `.sqlew/sqlew.db` (created in current directory)
189
+ `.sqlew/sqlew.db` (created in current directory)
104
190
 
105
- ## Available Tools (v2.0.0)
191
+ ## MCP Tools Reference
106
192
 
107
- All tools now use action-based routing. Call any tool with `action: "help"` for comprehensive documentation.
193
+ All tools use action-based routing. Call any tool with `action: "help"` for comprehensive documentation.
108
194
 
109
- ### `decision` - Context Management
195
+ ### 1. `decision` - Context Management
110
196
 
111
197
  Manage decisions with metadata (tags, layers, versions, scopes).
112
198
 
113
- **Actions:** `set`, `get`, `list`, `search_tags`, `search_layer`, `versions`, `help`
199
+ **Actions:** `set`, `get`, `list`, `search_tags`, `search_layer`, `versions`, `quick_set`, `search_advanced`, `set_batch`, `has_updates`, `set_from_template`, `create_template`, `list_templates`, `help`
200
+
201
+ **Examples:**
114
202
 
115
203
  ```typescript
116
- // Set a decision
204
+ // Standard set
117
205
  {
118
206
  action: "set",
119
207
  key: "auth_method",
@@ -121,29 +209,57 @@ Manage decisions with metadata (tags, layers, versions, scopes).
121
209
  agent: "auth-agent",
122
210
  layer: "business",
123
211
  tags: ["authentication", "security"],
124
- scopes: ["user-service"],
125
- version: "1.0.0",
126
- status: "active"
212
+ version: "1.0.0"
127
213
  }
128
214
 
129
- // Get decision by key
215
+ // Quick set with smart defaults (auto-infers layer, tags)
130
216
  {
131
- action: "get",
132
- key: "auth_method"
217
+ action: "quick_set",
218
+ key: "api/users/auth",
219
+ value: "JWT validation updated",
220
+ agent: "auth-agent"
221
+ // Auto-infers: layer="presentation", tags=["api", "users", "auth"]
222
+ }
223
+
224
+ // Batch set (up to 50 decisions atomically)
225
+ {
226
+ action: "set_batch",
227
+ decisions: [
228
+ { key: "api_v1", value: "REST", layer: "presentation" },
229
+ { key: "api_v2", value: "GraphQL", layer: "presentation" }
230
+ ],
231
+ atomic: true
232
+ }
233
+
234
+ // Check for updates (lightweight polling)
235
+ {
236
+ action: "has_updates",
237
+ agent_name: "my-agent",
238
+ since_timestamp: "2025-10-15T10:00:00Z"
133
239
  }
134
240
 
135
- // List with filtering
241
+ // Advanced search with complex filtering
136
242
  {
137
- action: "list",
243
+ action: "search_advanced",
244
+ layers: ["business", "data"],
245
+ tags_all: ["security"],
246
+ search_text: "authentication",
138
247
  status: "active",
139
- layer: "business"
248
+ limit: 20
140
249
  }
141
250
 
142
- // Search by tags
251
+ // Set from template
143
252
  {
144
- action: "search_tags",
145
- tags: ["authentication", "security"],
146
- tag_match: "AND"
253
+ action: "set_from_template",
254
+ template: "api-endpoint",
255
+ key: "user_api",
256
+ value: "GET /api/users"
257
+ }
258
+
259
+ // Get decision
260
+ {
261
+ action: "get",
262
+ key: "auth_method"
147
263
  }
148
264
 
149
265
  // Get version history
@@ -156,11 +272,13 @@ Manage decisions with metadata (tags, layers, versions, scopes).
156
272
  { action: "help" }
157
273
  ```
158
274
 
159
- ### `message` - Agent Messaging
275
+ ### 2. `message` - Agent Messaging
276
+
277
+ Send and retrieve messages with priority levels.
160
278
 
161
- Send and retrieve messages between agents with priority levels.
279
+ **Actions:** `send`, `get`, `mark_read`, `send_batch`, `help`
162
280
 
163
- **Actions:** `send`, `get`, `mark_read`, `help`
281
+ **Examples:**
164
282
 
165
283
  ```typescript
166
284
  // Send message
@@ -174,9 +292,31 @@ Send and retrieve messages between agents with priority levels.
174
292
  payload: { file: "/src/auth.ts" }
175
293
  }
176
294
 
295
+ // Batch send (up to 50 messages)
296
+ {
297
+ action: "send_batch",
298
+ messages: [
299
+ {
300
+ from_agent: "orchestrator",
301
+ to_agent: "auth-agent",
302
+ msg_type: "request",
303
+ message: "Start setup",
304
+ priority: "high"
305
+ },
306
+ {
307
+ from_agent: "orchestrator",
308
+ to_agent: "db-agent",
309
+ msg_type: "request",
310
+ message: "Initialize schema",
311
+ priority: "high"
312
+ }
313
+ ]
314
+ }
315
+
177
316
  // Get messages
178
317
  {
179
318
  action: "get",
319
+ agent_name: "agent1",
180
320
  unread_only: true,
181
321
  priority_filter: "high"
182
322
  }
@@ -184,15 +324,18 @@ Send and retrieve messages between agents with priority levels.
184
324
  // Mark as read
185
325
  {
186
326
  action: "mark_read",
327
+ agent_name: "agent1",
187
328
  message_ids: [1, 2, 3]
188
329
  }
189
330
  ```
190
331
 
191
- ### `file` - File Change Tracking
332
+ ### 3. `file` - File Change Tracking
192
333
 
193
- Track file modifications with layer assignment and lock detection.
334
+ Track file modifications with layer assignment.
194
335
 
195
- **Actions:** `record`, `get`, `check_lock`, `help`
336
+ **Actions:** `record`, `get`, `check_lock`, `record_batch`, `help`
337
+
338
+ **Examples:**
196
339
 
197
340
  ```typescript
198
341
  // Record file change
@@ -205,10 +348,29 @@ Track file modifications with layer assignment and lock detection.
205
348
  description: "Updated JWT validation"
206
349
  }
207
350
 
351
+ // Batch record (up to 50 file changes)
352
+ {
353
+ action: "record_batch",
354
+ file_changes: [
355
+ {
356
+ file_path: "/src/auth/jwt.ts",
357
+ agent_name: "auth-agent",
358
+ change_type: "created",
359
+ layer: "business"
360
+ },
361
+ {
362
+ file_path: "/src/auth/validation.ts",
363
+ agent_name: "auth-agent",
364
+ change_type: "created",
365
+ layer: "business"
366
+ }
367
+ ]
368
+ }
369
+
208
370
  // Get file changes
209
371
  {
210
372
  action: "get",
211
- since: "2025-01-10T10:00:00Z",
373
+ since: "2025-10-15T10:00:00Z",
212
374
  layer: "business"
213
375
  }
214
376
 
@@ -220,12 +382,14 @@ Track file modifications with layer assignment and lock detection.
220
382
  }
221
383
  ```
222
384
 
223
- ### `constraint` - Constraint Management
385
+ ### 4. `constraint` - Constraint Management
224
386
 
225
387
  Manage architectural, performance, and security constraints.
226
388
 
227
389
  **Actions:** `add`, `get`, `deactivate`, `help`
228
390
 
391
+ **Examples:**
392
+
229
393
  ```typescript
230
394
  // Add constraint
231
395
  {
@@ -251,11 +415,13 @@ Manage architectural, performance, and security constraints.
251
415
  }
252
416
  ```
253
417
 
254
- ### `stats` - Statistics & Utilities
418
+ ### 5. `stats` - Statistics & Utilities
255
419
 
256
420
  Get database statistics and manage data cleanup.
257
421
 
258
- **Actions:** `layer_summary`, `db_stats`, `clear`, `help`
422
+ **Actions:** `layer_summary`, `db_stats`, `clear`, `activity_log`, `help`
423
+
424
+ **Examples:**
259
425
 
260
426
  ```typescript
261
427
  // Layer summary
@@ -264,6 +430,14 @@ Get database statistics and manage data cleanup.
264
430
  // Database stats
265
431
  { action: "db_stats" }
266
432
 
433
+ // Activity log (v2.1.0)
434
+ {
435
+ action: "activity_log",
436
+ since: "1h",
437
+ agent_names: ["auth-agent"],
438
+ limit: 100
439
+ }
440
+
267
441
  // Clear old data (weekend-aware)
268
442
  {
269
443
  action: "clear",
@@ -272,12 +446,14 @@ Get database statistics and manage data cleanup.
272
446
  }
273
447
  ```
274
448
 
275
- ### `config` - Configuration
449
+ ### 6. `config` - Configuration
276
450
 
277
451
  Manage auto-deletion and retention settings.
278
452
 
279
453
  **Actions:** `get`, `update`, `help`
280
454
 
455
+ **Examples:**
456
+
281
457
  ```typescript
282
458
  // Get config
283
459
  { action: "get" }
@@ -291,79 +467,61 @@ Manage auto-deletion and retention settings.
291
467
  }
292
468
  ```
293
469
 
294
- ## Database Schema
295
-
296
- sqlew uses a normalized SQLite schema (v1.3.0) optimized for token efficiency with category-based table prefixes:
470
+ ## CLI Tool (v2.1.0)
297
471
 
298
- **Master Tables (m_ prefix):** m_agents, m_files, m_context_keys, m_layers, m_tags, m_scopes, m_constraint_categories, m_config
472
+ Query your database directly from terminal without MCP server.
299
473
 
300
- **Transaction Tables (t_ prefix):** t_decisions, t_decisions_numeric, t_decision_history, t_decision_tags, t_decision_scopes, t_agent_messages, t_file_changes, t_constraints, t_constraint_tags
474
+ ### Available Commands
301
475
 
302
- **Token-Efficient Views (v_ prefix):** v_tagged_decisions, v_active_context, v_layer_summary, v_unread_messages_by_priority, v_recent_file_changes, v_tagged_constraints
476
+ ```bash
477
+ # Query decisions
478
+ npx sqlew-cli query decisions --layer=business --tags=breaking --output=table
303
479
 
304
- **Triggers (trg_ prefix):** trg_record_decision_history
480
+ # Query messages
481
+ npx sqlew-cli query messages --unread --priority=high --output=json
305
482
 
306
- ### Automatic Migration
483
+ # Query file changes
484
+ npx sqlew-cli query files --since=1h --layer=data --output=table
307
485
 
308
- When upgrading from v1.2.0 to v1.3.0, the server automatically migrates your database to use the new prefixed table names. The migration is safe and runs in a transaction - if it fails, the database is unchanged.
486
+ # Query activity log
487
+ npx sqlew-cli query activity --since=5m --agent=* --output=json
488
+ ```
309
489
 
310
- ## Token Efficiency
490
+ ### Common Options
311
491
 
312
- sqlew achieves **96% token reduction** through:
492
+ - `--output <format>` - Output format: `json` or `table` (default: json)
493
+ - `--layer <layer>` - Filter by layer
494
+ - `--tags <tags>` - Filter by tags (comma-separated)
495
+ - `--since <time>` - Time filter (e.g., "5m", "1h", "2d", or ISO timestamp)
496
+ - `--limit <number>` - Limit results
497
+ - `--db-path <path>` - Custom database path
498
+ - `--help` - Show help
313
499
 
314
- 1. **Action-Based Tools (v2.0):** Consolidates 20 tools → 6 tools, eliminating duplication
315
- 2. **ID-Based Normalization:** Strings stored once, referenced by integer IDs
316
- 3. **Integer Enums:** Status, priority, message types use integers (1-4) instead of strings
317
- 4. **Pre-Aggregated Views:** Common queries use pre-computed results
318
- 5. **Type-Based Tables:** Separate storage for numeric vs string values
319
- 6. **Automatic Cleanup:** Prevents database bloat
500
+ ## Architecture Layers
320
501
 
321
- ### v2.0.0 Token Savings
502
+ sqlew organizes code by standard architecture layers:
322
503
 
323
- - **Tool Definitions:** 12,848 481 tokens (96.3% reduction)
324
- - **MCP Context Usage:** ~13,730 → ~4,482 tokens (67% reduction)
504
+ - **presentation** - UI, API endpoints, views
505
+ - **business** - Business logic, services, use cases
506
+ - **data** - Repositories, database access
507
+ - **infrastructure** - Configuration, external services
508
+ - **cross-cutting** - Logging, security, utilities
325
509
 
326
- ### Example Comparison
510
+ ## Database Schema
327
511
 
328
- **Traditional JSON (1000 tokens):**
329
- ```json
330
- {
331
- "key": "auth_method",
332
- "value": "JWT",
333
- "agent": "auth-agent",
334
- "layer": "business",
335
- "status": "active",
336
- "tags": ["authentication", "security"],
337
- "scopes": ["user-service"],
338
- "updated": "2025-01-10T12:00:00Z"
339
- }
340
- ```
512
+ **Master Tables (m_ prefix):** Normalization layer (agents, files, keys, layers, tags, scopes, categories, config, templates)
341
513
 
342
- **sqlew Response (280 tokens):**
343
- ```json
344
- {
345
- "key_id": 42,
346
- "value": "JWT",
347
- "agent_id": 5,
348
- "layer_id": 2,
349
- "status": 1,
350
- "tag_ids": [1,4],
351
- "scope_ids": [3],
352
- "ts": 1736510400
353
- }
354
- ```
514
+ **Transaction Tables (t_ prefix):** Core data (decisions, history, messages, file changes, constraints, activity log)
355
515
 
356
- **Token Savings: 720 tokens (72%)**
516
+ **Views (v_ prefix):** Token-efficient pre-aggregated queries
357
517
 
358
- ## Architecture Layers
518
+ **Triggers (trg_ prefix):** Automatic version history and activity logging
359
519
 
360
- sqlew organizes code by standard architecture layers:
520
+ ### Automatic Migration
361
521
 
362
- - **presentation:** UI, API endpoints, views
363
- - **business:** Business logic, services, use cases
364
- - **data:** Repositories, database access
365
- - **infrastructure:** Configuration, external services
366
- - **cross-cutting:** Logging, security, utilities
522
+ - **v1.x → v2.x:** Automatic migration adds table prefixes and new features
523
+ - **v2.0 → v2.1:** Adds activity log and template tables
524
+ - All migrations are safe with rollback protection
367
525
 
368
526
  ## Development
369
527
 
@@ -376,119 +534,76 @@ npm install
376
534
  npm run build
377
535
  ```
378
536
 
379
- ### Running Locally
537
+ ### Available Scripts
380
538
 
381
539
  ```bash
382
- npm start
540
+ npm start # Start MCP server
541
+ npm run cli # Run CLI tool
542
+ npm run inspector # Test with MCP Inspector
543
+ npm run build # Build TypeScript
544
+ npm run dev # Watch mode
545
+ npm run rebuild # Clean and rebuild
383
546
  ```
384
547
 
385
- ### Testing
386
-
387
- ```bash
388
- # Use MCP Inspector to test all tools
389
- npm run inspector
390
-
391
- # Or test individual tools via CLI
392
- npx @modelcontextprotocol/inspector npx sqlew
393
- ```
548
+ ## Configuration
394
549
 
395
- ### Project Structure
550
+ ### Retention Periods (Defaults)
396
551
 
397
- ```
398
- sqlew/
399
- ├── src/
400
- │ ├── index.ts # MCP server entry point
401
- │ ├── database.ts # Database initialization
402
- │ ├── schema.ts # Schema management
403
- │ ├── types.ts # TypeScript types
404
- │ ├── constants.ts # Constants & enums
405
- │ └── tools/
406
- │ ├── context.ts # Context management
407
- │ ├── messaging.ts # Messaging system
408
- │ ├── files.ts # File tracking
409
- │ ├── constraints.ts # Constraint management
410
- │ └── utils.ts # Utilities
411
- ├── dist/ # Compiled JavaScript
412
- └── package.json
413
- ```
552
+ - **Messages:** 24 hours (weekend-aware optional)
553
+ - **File Changes:** 7 days (weekend-aware optional)
554
+ - **Decisions:** Permanent (version history preserved)
555
+ - **Constraints:** Permanent (soft delete only)
414
556
 
415
- ## Configuration
557
+ ### Weekend-Aware Cleanup
416
558
 
417
- ### Weekend-Aware Auto-Deletion
559
+ When enabled, weekends (Saturday/Sunday) don't count toward retention periods:
418
560
 
419
- sqlew supports weekend-aware retention policies that intelligently handle 3-day weekends and holidays:
561
+ - Message sent Friday 3pm Deleted Monday 3pm (skips weekend)
562
+ - Message sent Monday 10am → Deleted Tuesday 10am
420
563
 
421
- **How it works:**
422
- - When `ignoreWeekend: false` (default): Standard time-based deletion
423
- - When `ignoreWeekend: true`: Weekends (Sat/Sun) don't count toward retention period
564
+ Configure via CLI args or MCP tools at runtime.
424
565
 
425
- **Example:** With 24-hour retention and `ignoreWeekend: true`:
426
- - Message sent Friday 3pm → Deleted Monday 3pm (skips Sat/Sun)
427
- - Message sent Monday 10am → Deleted Tuesday 10am (no weekend in between)
566
+ ## Migration Guide
428
567
 
429
- **Configuration Methods:**
568
+ ### From v2.1.0 to v2.1.1
430
569
 
431
- 1. **CLI Arguments (at startup):**
432
- ```bash
433
- npx sqlew \
434
- --autodelete-ignore-weekend \
435
- --autodelete-message-hours=48 \
436
- --autodelete-file-history-days=10
437
- ```
570
+ No breaking changes. Only bin command configuration changed:
438
571
 
439
- 2. **MCP Tools (runtime):**
440
- ```typescript
441
- // Get current config
442
- get_config()
572
+ - **Old:** `npx sqlew` → CLI, `npx sqlew-server` → MCP server
573
+ - **New:** `npx sqlew` → MCP server, `npx sqlew-cli` → CLI
443
574
 
444
- // Update config
445
- update_config({
446
- ignoreWeekend: true,
447
- messageRetentionHours: 72,
448
- fileHistoryRetentionDays: 14
449
- })
450
- ```
575
+ Update Claude Desktop config if using custom commands.
451
576
 
452
- 3. **Database (persisted):**
453
- Config is stored in the database and travels with the DB file.
577
+ ### From v2.0.0 to v2.1.0
454
578
 
455
- ### Default Retention Periods
579
+ No breaking changes. Database migrates automatically on startup.
456
580
 
457
- - **Messages:** 24 hours (weekend-aware optional)
458
- - **File Changes:** 7 days (weekend-aware optional)
459
- - **Decisions:** Permanent (version history preserved)
460
- - **Constraints:** Permanent (soft delete only)
581
+ New features are opt-in via new actions.
461
582
 
462
- ### Environment Variables
583
+ ### From v1.x to v2.0.0
463
584
 
464
- - `DEBUG_SQL`: Set to enable SQL query logging
585
+ Requires migration. See [MIGRATION_v2.md](MIGRATION_v2.md) for details.
465
586
 
466
587
  ## License
467
588
 
468
589
  MIT - see [LICENSE](LICENSE) file for details
469
590
 
470
- ## Contributing
471
-
472
- Contributions welcome! Areas of interest:
591
+ ## Links
473
592
 
474
- - Performance optimizations
475
- - Additional metadata features
476
- - Enhanced querying capabilities
477
- - Integration with other MCP tools
593
+ - [npm package](https://www.npmjs.com/package/sqlew)
594
+ - [GitHub repository](https://github.com/sin5ddd/mcp-sqlew)
595
+ - [Changelog](CHANGELOG.md)
596
+ - [Architecture Documentation](ARCHITECTURE.md)
597
+ - [Model Context Protocol](https://modelcontextprotocol.io/)
478
598
 
479
- ### Development Guidelines
599
+ ## Author
480
600
 
481
- 1. Fork the repository
482
- 2. Create a feature branch
483
- 3. Make your changes
484
- 4. Add tests if applicable
485
- 5. Submit a pull request
601
+ **sin5ddd**
486
602
 
487
603
  ## Support
488
604
 
489
605
  - **Issues:** [GitHub Issues](https://github.com/sin5ddd/mcp-sqlew/issues)
490
606
  - **Documentation:** See [ARCHITECTURE.md](ARCHITECTURE.md) for technical details
491
- - **Schema Reference:** See source code for complete schema
492
607
 
493
608
  ## Acknowledgments
494
609
 
@@ -496,13 +611,3 @@ Built with:
496
611
  - [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
497
612
  - [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
498
613
  - TypeScript
499
-
500
- ## Author
501
-
502
- **sin5ddd**
503
-
504
- ## Links
505
-
506
- - [npm package](https://www.npmjs.com/package/sqlew)
507
- - [GitHub repository](https://github.com/sin5ddd/mcp-sqlew)
508
- - [Model Context Protocol](https://modelcontextprotocol.io/)