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.
- package/CHANGELOG.md +222 -0
- package/README.md +314 -209
- package/assets/schema.sql +122 -36
- package/dist/cli.d.ts +7 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +312 -0
- package/dist/cli.js.map +1 -0
- package/dist/database.d.ts.map +1 -1
- package/dist/database.js +18 -0
- package/dist/database.js.map +1 -1
- package/dist/index.js +136 -42
- package/dist/index.js.map +1 -1
- package/dist/migrations/add-v2.1.0-features.d.ts +29 -0
- package/dist/migrations/add-v2.1.0-features.d.ts.map +1 -0
- package/dist/migrations/add-v2.1.0-features.js +198 -0
- package/dist/migrations/add-v2.1.0-features.js.map +1 -0
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +5 -0
- package/dist/schema.js.map +1 -1
- package/dist/tools/context.d.ts +91 -1
- package/dist/tools/context.d.ts.map +1 -1
- package/dist/tools/context.js +695 -70
- package/dist/tools/context.js.map +1 -1
- package/dist/tools/files.d.ts +10 -1
- package/dist/tools/files.d.ts.map +1 -1
- package/dist/tools/files.js +98 -1
- package/dist/tools/files.js.map +1 -1
- package/dist/tools/messaging.d.ts +10 -1
- package/dist/tools/messaging.d.ts.map +1 -1
- package/dist/tools/messaging.js +107 -1
- package/dist/tools/messaging.js.map +1 -1
- package/dist/tools/utils.d.ts +9 -1
- package/dist/tools/utils.d.ts.map +1 -1
- package/dist/tools/utils.js +115 -0
- package/dist/tools/utils.js.map +1 -1
- package/dist/types.d.ts +196 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/cleanup.d.ts +12 -1
- package/dist/utils/cleanup.d.ts.map +1 -1
- package/dist/utils/cleanup.js +20 -3
- package/dist/utils/cleanup.js.map +1 -1
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,52 +1,146 @@
|
|
|
1
1
|
# sqlew
|
|
2
|
+

|
|
2
3
|
|
|
3
4
|
[](https://www.npmjs.com/package/sqlew)
|
|
4
5
|
[](https://opensource.org/licenses/MIT)
|
|
5
6
|
|
|
6
|
-
**
|
|
7
|
+
> **SQL Efficient Workflow** - MCP server for efficient context sharing between Claude Code sub-agents
|
|
7
8
|
|
|
8
|
-
##
|
|
9
|
+
## Overview
|
|
9
10
|
|
|
10
|
-
**
|
|
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
|
-
**
|
|
13
|
+
**Current Version:** 2.1.1
|
|
13
14
|
|
|
14
|
-
|
|
15
|
+
## Benefits
|
|
15
16
|
|
|
16
|
-
|
|
17
|
+
### 🧠 Organizational Memory for AI Agents
|
|
17
18
|
|
|
18
|
-
|
|
19
|
+
**sqlew solves the "organizational memory" problem that traditional code can't:**
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
30
|
-
- **
|
|
31
|
-
- **
|
|
32
|
-
- **
|
|
33
|
-
- **
|
|
34
|
-
- **
|
|
35
|
-
- **
|
|
36
|
-
|
|
37
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
189
|
+
`.sqlew/sqlew.db` (created in current directory)
|
|
104
190
|
|
|
105
|
-
##
|
|
191
|
+
## MCP Tools Reference
|
|
106
192
|
|
|
107
|
-
All tools
|
|
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
|
-
//
|
|
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
|
-
|
|
125
|
-
version: "1.0.0",
|
|
126
|
-
status: "active"
|
|
212
|
+
version: "1.0.0"
|
|
127
213
|
}
|
|
128
214
|
|
|
129
|
-
//
|
|
215
|
+
// Quick set with smart defaults (auto-infers layer, tags)
|
|
130
216
|
{
|
|
131
|
-
action: "
|
|
132
|
-
key: "
|
|
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
|
-
//
|
|
241
|
+
// Advanced search with complex filtering
|
|
136
242
|
{
|
|
137
|
-
action: "
|
|
243
|
+
action: "search_advanced",
|
|
244
|
+
layers: ["business", "data"],
|
|
245
|
+
tags_all: ["security"],
|
|
246
|
+
search_text: "authentication",
|
|
138
247
|
status: "active",
|
|
139
|
-
|
|
248
|
+
limit: 20
|
|
140
249
|
}
|
|
141
250
|
|
|
142
|
-
//
|
|
251
|
+
// Set from template
|
|
143
252
|
{
|
|
144
|
-
action: "
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
|
|
279
|
+
**Actions:** `send`, `get`, `mark_read`, `send_batch`, `help`
|
|
162
280
|
|
|
163
|
-
**
|
|
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
|
|
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-
|
|
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
|
-
##
|
|
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
|
-
|
|
472
|
+
Query your database directly from terminal without MCP server.
|
|
299
473
|
|
|
300
|
-
|
|
474
|
+
### Available Commands
|
|
301
475
|
|
|
302
|
-
|
|
476
|
+
```bash
|
|
477
|
+
# Query decisions
|
|
478
|
+
npx sqlew-cli query decisions --layer=business --tags=breaking --output=table
|
|
303
479
|
|
|
304
|
-
|
|
480
|
+
# Query messages
|
|
481
|
+
npx sqlew-cli query messages --unread --priority=high --output=json
|
|
305
482
|
|
|
306
|
-
|
|
483
|
+
# Query file changes
|
|
484
|
+
npx sqlew-cli query files --since=1h --layer=data --output=table
|
|
307
485
|
|
|
308
|
-
|
|
486
|
+
# Query activity log
|
|
487
|
+
npx sqlew-cli query activity --since=5m --agent=* --output=json
|
|
488
|
+
```
|
|
309
489
|
|
|
310
|
-
|
|
490
|
+
### Common Options
|
|
311
491
|
|
|
312
|
-
|
|
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
|
-
|
|
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
|
-
|
|
502
|
+
sqlew organizes code by standard architecture layers:
|
|
322
503
|
|
|
323
|
-
- **
|
|
324
|
-
- **
|
|
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
|
-
|
|
510
|
+
## Database Schema
|
|
327
511
|
|
|
328
|
-
**
|
|
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
|
-
**
|
|
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
|
-
**
|
|
516
|
+
**Views (v_ prefix):** Token-efficient pre-aggregated queries
|
|
357
517
|
|
|
358
|
-
|
|
518
|
+
**Triggers (trg_ prefix):** Automatic version history and activity logging
|
|
359
519
|
|
|
360
|
-
|
|
520
|
+
### Automatic Migration
|
|
361
521
|
|
|
362
|
-
- **
|
|
363
|
-
- **
|
|
364
|
-
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
###
|
|
550
|
+
### Retention Periods (Defaults)
|
|
396
551
|
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
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
|
-
|
|
557
|
+
### Weekend-Aware Cleanup
|
|
416
558
|
|
|
417
|
-
|
|
559
|
+
When enabled, weekends (Saturday/Sunday) don't count toward retention periods:
|
|
418
560
|
|
|
419
|
-
|
|
561
|
+
- Message sent Friday 3pm → Deleted Monday 3pm (skips weekend)
|
|
562
|
+
- Message sent Monday 10am → Deleted Tuesday 10am
|
|
420
563
|
|
|
421
|
-
|
|
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
|
-
|
|
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
|
-
|
|
568
|
+
### From v2.1.0 to v2.1.1
|
|
430
569
|
|
|
431
|
-
|
|
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
|
-
|
|
440
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
579
|
+
No breaking changes. Database migrates automatically on startup.
|
|
456
580
|
|
|
457
|
-
|
|
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
|
-
###
|
|
583
|
+
### From v1.x to v2.0.0
|
|
463
584
|
|
|
464
|
-
|
|
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
|
-
##
|
|
471
|
-
|
|
472
|
-
Contributions welcome! Areas of interest:
|
|
591
|
+
## Links
|
|
473
592
|
|
|
474
|
-
-
|
|
475
|
-
-
|
|
476
|
-
-
|
|
477
|
-
-
|
|
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
|
-
|
|
599
|
+
## Author
|
|
480
600
|
|
|
481
|
-
|
|
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/)
|