sqlew 4.0.4 → 4.0.5
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 +20 -0
- package/LICENSE +177 -39
- package/NOTICE +24 -0
- package/README.md +171 -93
- package/dist/index.js +1 -1
- package/docs/AI_AGENT_GUIDE.md +138 -37
- package/docs/DECISION_CONTEXT.md +41 -19
- package/package.json +11 -6
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
+
## [4.0.5] - 2025-12-19
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
**License Change: AGPL-3.0 → Apache-2.0**
|
|
15
|
+
|
|
16
|
+
- Changed license from AGPLv3 to Apache License 2.0
|
|
17
|
+
- More permissive license for commercial and enterprise adoption
|
|
18
|
+
- Added NOTICE file with third-party attributions
|
|
19
|
+
- Updated LICENSE file with full Apache 2.0 text
|
|
20
|
+
- Updated package.json license field
|
|
21
|
+
|
|
22
|
+
**Why Apache 2.0?**
|
|
23
|
+
- Patent protection for contributors and users
|
|
24
|
+
- Widely adopted by major tech companies (Google, Microsoft, AWS)
|
|
25
|
+
- Easier enterprise adoption without copyleft concerns
|
|
26
|
+
- Compatible with most open source licenses
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
10
30
|
## [4.0.4] - 2025-12-10
|
|
11
31
|
|
|
12
32
|
### Fixed
|
package/LICENSE
CHANGED
|
@@ -1,52 +1,190 @@
|
|
|
1
|
-
|
|
2
|
-
Version
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
3
4
|
|
|
4
|
-
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
it under the terms of the GNU Affero General Public License as published
|
|
8
|
-
by the Free Software Foundation, either version 3 of the License, or
|
|
9
|
-
(at your option) any later version.
|
|
7
|
+
1. Definitions.
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
14
|
-
GNU Affero General Public License for more details.
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
15
11
|
|
|
16
|
-
|
|
17
|
-
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
18
14
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
✅ Using sqlew to manage context for your AI agents
|
|
29
|
-
✅ Running sqlew as-is without modifications
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
30
29
|
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
33
34
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
37
39
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
41
47
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to the Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
45
61
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
3. Include this license notice and copyright in your software
|
|
50
|
-
4. State any changes you made to the original software
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
51
65
|
|
|
52
|
-
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
Copyright 2025 sin5ddd
|
|
179
|
+
|
|
180
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
181
|
+
you may not use this file except in compliance with the License.
|
|
182
|
+
You may obtain a copy of the License at
|
|
183
|
+
|
|
184
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
185
|
+
|
|
186
|
+
Unless required by applicable law or agreed to in writing, software
|
|
187
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
188
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
189
|
+
See the License for the specific language governing permissions and
|
|
190
|
+
limitations under the License.
|
package/NOTICE
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
sqlew
|
|
2
|
+
Copyright 2025 sin5ddd
|
|
3
|
+
|
|
4
|
+
This product includes software developed by sin5ddd.
|
|
5
|
+
|
|
6
|
+
Licensed under the Apache License, Version 2.0.
|
|
7
|
+
|
|
8
|
+
================================================================================
|
|
9
|
+
Third-Party Notices
|
|
10
|
+
================================================================================
|
|
11
|
+
|
|
12
|
+
This software uses the following open source packages:
|
|
13
|
+
|
|
14
|
+
- Model Context Protocol SDK (https://github.com/modelcontextprotocol/sdk)
|
|
15
|
+
Licensed under MIT License
|
|
16
|
+
|
|
17
|
+
- better-sqlite3 (https://github.com/WiseLibs/better-sqlite3)
|
|
18
|
+
Licensed under MIT License
|
|
19
|
+
|
|
20
|
+
- Knex.js (https://knexjs.org/)
|
|
21
|
+
Licensed under MIT License
|
|
22
|
+
|
|
23
|
+
- TypeScript (https://www.typescriptlang.org/)
|
|
24
|
+
Licensed under Apache License 2.0
|
package/README.md
CHANGED
|
@@ -2,91 +2,165 @@
|
|
|
2
2
|
|
|
3
3
|
|
|
4
4
|
[](https://www.npmjs.com/package/sqlew)
|
|
5
|
-
[](https://opensource.org/licenses/Apache-2.0)
|
|
6
6
|
|
|
7
|
-
> **
|
|
7
|
+
> **ADR (Architecture Decision Record) for AI Agents** – An MCP server that enables AI agents to create, query, and maintain architecture decision records in a structured SQL database
|
|
8
|
+
|
|
9
|
+
## 🚀 Quick Start: /sqlew Command
|
|
10
|
+
|
|
11
|
+
**The `/sqlew` command is the easiest way to use sqlew!** Just type `/sqlew` in Claude Code with natural language input.
|
|
12
|
+
|
|
13
|
+
### Most Common Uses
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# Show status and get suggestions
|
|
17
|
+
/sqlew
|
|
18
|
+
|
|
19
|
+
# Record a decision
|
|
20
|
+
/sqlew record we use PostgreSQL 15 for production database
|
|
21
|
+
|
|
22
|
+
# Search past decisions
|
|
23
|
+
/sqlew search why we chose Knex for migrations
|
|
24
|
+
|
|
25
|
+
# List remaining tasks
|
|
26
|
+
/sqlew show remaining tasks
|
|
27
|
+
|
|
28
|
+
# Plan a new feature (breakdown into tasks)
|
|
29
|
+
/sqlew plan implementing user authentication
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The `/sqlew` command automatically detects your intent (search, record, list, execute, task creation) and invokes the appropriate MCP tools.
|
|
33
|
+
|
|
34
|
+
---
|
|
8
35
|
|
|
9
36
|
## What is sqlew?
|
|
10
37
|
|
|
11
|
-
**sqlew** is a Model Context Protocol (MCP) server that
|
|
38
|
+
**sqlew** is a Model Context Protocol (MCP) server that brings ADR (Architecture Decision Record) capabilities to AI agents through a shared SQL-backed repository.
|
|
12
39
|
|
|
13
|
-
###
|
|
14
|
-
Every
|
|
40
|
+
### The Problem: AI Agents Lack Decision Memory
|
|
41
|
+
Every AI session starts with zero context. Agents must re-learn architectural decisions, can reintroduce previously rejected patterns, and have no systematic way to understand WHY past choices were made.
|
|
15
42
|
|
|
16
|
-
|
|
17
|
-
|
|
43
|
+
Traditional ADR approaches use Markdown files scattered across repositories. While human-readable, this format creates challenges for AI agents:
|
|
44
|
+
- **No structured querying** – AI must read entire files to find relevant decisions
|
|
45
|
+
- **Context explosion** – Token costs grow linearly with decision history
|
|
46
|
+
- **No duplicate detection** – AI cannot easily identify similar or conflicting decisions
|
|
47
|
+
- **Poor discoverability** – Finding related decisions requires full-text search across many files
|
|
18
48
|
|
|
19
|
-
|
|
49
|
+
### *sqlew* brings structured ADR to AI agents
|
|
50
|
+
sqlew transforms ADR from static documentation into a **queryable, AI-native decision database**:
|
|
20
51
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- Eliminates duplicate work via task management
|
|
52
|
+
- **Structured records** – Decisions stored as relational data with metadata, tags, and relationships
|
|
53
|
+
- **Efficient querying** – AI agents retrieve only relevant decisions via SQL queries
|
|
54
|
+
- **Smart suggestions** – Three-tier similarity system detects duplicate or related decisions
|
|
55
|
+
- **Constraint tracking** – Architectural rules and principles as first-class entities
|
|
56
|
+
- **Task integration** – Link decisions to implementation tasks and affected files
|
|
27
57
|
|
|
28
58
|
> *This software does not send any data to external networks. We NEVER collect any data or usage statistics. Please use it with complete security.*
|
|
29
59
|
|
|
30
|
-
## Concept: Decision
|
|
60
|
+
## Concept: ADR (Architecture Decision Record) for AI Agents
|
|
31
61
|
|
|
32
|
-
|
|
62
|
+
**Architecture Decision Records (ADR)** document the architectural decisions made on a project, including context, consequences, and alternatives considered. sqlew extends this proven pattern to AI agents.
|
|
33
63
|
|
|
34
|
-
|
|
64
|
+
### Core ADR Concepts in sqlew
|
|
35
65
|
|
|
36
|
-
|
|
37
|
-
- **
|
|
66
|
+
**Decisions** capture architectural choices with full context:
|
|
67
|
+
- **What** was decided (the decision itself)
|
|
68
|
+
- **Why** it was chosen (rationale, trade-offs)
|
|
69
|
+
- **What else** was considered (alternatives rejected)
|
|
70
|
+
- **Impact** on the system (consequences, affected components)
|
|
38
71
|
|
|
39
|
-
|
|
72
|
+
**Constraints** define architectural principles and rules:
|
|
73
|
+
- **Performance requirements** (response time limits, throughput goals)
|
|
74
|
+
- **Technology choices** ("must use PostgreSQL", "avoid microservices")
|
|
75
|
+
- **Coding standards** ("async/await only", "no any types")
|
|
76
|
+
- **Security policies** (authentication patterns, data handling rules)
|
|
40
77
|
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
78
|
+
**Implementation tracking** connects decisions to reality:
|
|
79
|
+
- **Tasks** link decisions to actual implementation work
|
|
80
|
+
- **File tracking** shows which code was affected by decisions
|
|
81
|
+
- **Status evolution** tracks decision lifecycle (draft → active → deprecated)
|
|
44
82
|
|
|
45
|
-
|
|
83
|
+
### Why SQL for ADR?
|
|
46
84
|
|
|
47
|
-
|
|
85
|
+
Traditional text-based ADR forces AI to:
|
|
86
|
+
- Read complete files even for simple queries
|
|
87
|
+
- Parse unstructured text to find relationships
|
|
88
|
+
- Manually detect duplicate or conflicting decisions
|
|
48
89
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
90
|
+
sqlew's **SQL-backed ADR repository** enables AI to:
|
|
91
|
+
- Query by layer, tags, status in milliseconds (2-50ms)
|
|
92
|
+
- Join decisions with constraints, tasks, and files
|
|
93
|
+
- Leverage similarity algorithms to prevent duplicates
|
|
94
|
+
- Scale to thousands of decisions without context explosion
|
|
54
95
|
|
|
55
|
-
|
|
56
|
-
**60-75% token reduction** in multi-session projects through structured data storage and selective querying.
|
|
96
|
+
**Token efficiency**: 60-75% reduction compared to reading Markdown ADRs
|
|
57
97
|
|
|
58
|
-
###
|
|
98
|
+
### Why RDBMS + MCP for ADR?
|
|
59
99
|
|
|
60
|
-
|
|
61
|
-
- **
|
|
62
|
-
- **
|
|
63
|
-
- **
|
|
100
|
+
**RDBMS (Relational Database)** provides efficient structured queries:
|
|
101
|
+
- **Indexed searches** – Find decisions by tags/layers in milliseconds, not seconds
|
|
102
|
+
- **JOIN operations** – Query related decisions, constraints, and tasks in a single operation
|
|
103
|
+
- **Transaction support** – ACID guarantees ensure data integrity across concurrent AI agents
|
|
104
|
+
- **Scalability** – Handle thousands of ADRs without performance degradation
|
|
64
105
|
|
|
65
|
-
|
|
66
|
-
- **
|
|
67
|
-
- **
|
|
106
|
+
**MCP (Model Context Protocol)** enables seamless AI integration:
|
|
107
|
+
- **Direct tool access** – AI agents call ADR operations as native functions
|
|
108
|
+
- **Token efficiency** – Retrieve only required data, avoiding full-file reads
|
|
109
|
+
- **Type safety** – Structured parameters prevent errors and guide correct usage
|
|
110
|
+
- **Cross-session persistence** – ADRs survive beyond individual chat sessions
|
|
68
111
|
|
|
69
|
-
|
|
70
|
-
- **Bug Prevention**: AI won't reintroduce bugs you already fixed (decisions document "what didn't work")
|
|
71
|
-
- **Pattern Enforcement**: Constraints ensure AI writes code matching your team's style
|
|
72
|
-
- **Context-Aware Suggestions**: AI sees related decisions before creating new ones ("Did you know we already solved this?")
|
|
73
|
-
- **Rationale Documentation**: Every decision includes WHY it was made, preventing cargo-cult programming
|
|
112
|
+
**Together**: AI agents gain SQL-powered ADR capabilities without managing databases directly.
|
|
74
113
|
|
|
75
|
-
|
|
76
|
-
- **Task Dependencies**: AI knows Task B needs Task A completed first
|
|
77
|
-
- **Auto File Watching**: Tasks auto-update when AI edits tracked files (zero manual updates)
|
|
78
|
-
- **Progress Visibility**: See exactly what AI is working on, what's blocked, what's done
|
|
114
|
+
## Why Use sqlew?
|
|
79
115
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
116
|
+
### 🏛️ ADR Made AI-Native
|
|
117
|
+
Traditional ADR approaches weren't designed for AI agents. sqlew reimagines ADR for the AI era:
|
|
118
|
+
|
|
119
|
+
| Traditional ADR (Markdown) | sqlew ADR (SQL) |
|
|
120
|
+
|---------------------------|-----------------|
|
|
121
|
+
| Read entire files | Query specific decisions |
|
|
122
|
+
| Manual duplicate checking | Automatic similarity detection |
|
|
123
|
+
| Text parsing required | Structured, typed data |
|
|
124
|
+
| Linear token scaling | Constant-time lookups |
|
|
125
|
+
| File-based organization | Relational queries with JOINs |
|
|
126
|
+
|
|
127
|
+
### 🎯 Key Benefits for AI-Driven Development
|
|
128
|
+
|
|
129
|
+
#### 📚 **Persistent Architectural Memory**
|
|
130
|
+
- **Zero context loss** – AI agents remember every architectural decision across sessions
|
|
131
|
+
- **Rationale preservation** – Never forget WHY a decision was made, not just WHAT
|
|
132
|
+
- **Alternative tracking** – Document rejected options to prevent circular debates
|
|
133
|
+
- **Evolution history** – See how decisions changed over time with full version history
|
|
134
|
+
|
|
135
|
+
#### 🛡️ **Prevent Architectural Drift**
|
|
136
|
+
- **Constraint enforcement** – Define architectural rules once, AI follows them forever
|
|
137
|
+
- **Pattern consistency** – AI generates code matching established patterns automatically
|
|
138
|
+
- **Anti-pattern prevention** – Document "what NOT to do" as enforceable constraints
|
|
139
|
+
- **Regression prevention** – AI won't reintroduce previously rejected approaches
|
|
140
|
+
|
|
141
|
+
#### 🔍 **Intelligent Decision Discovery**
|
|
142
|
+
- **Similarity detection** – AI identifies duplicate or related decisions before creating new ones
|
|
143
|
+
- **Context-aware search** – Query by layer, tags, or relationships to find relevant decisions
|
|
144
|
+
- **Impact analysis** – Trace which files and tasks are affected by each decision
|
|
145
|
+
- **Conflict detection** – Find decisions that contradict or supersede each other
|
|
146
|
+
|
|
147
|
+
#### 📊 **Implementation Transparency**
|
|
148
|
+
- **Decision-to-task linking** – Track implementation status of architectural choices
|
|
149
|
+
- **File impact tracking** – See exactly which code implements each decision
|
|
150
|
+
- **Status lifecycle** – Draft → Active → Deprecated → Superseded transitions
|
|
151
|
+
- **Progress visibility** – Monitor which ADRs are implemented, which are pending
|
|
152
|
+
|
|
153
|
+
#### ⚡ **Extreme Efficiency**
|
|
154
|
+
- **60-75% token reduction** – Query only relevant decisions instead of reading all ADRs
|
|
155
|
+
- **Millisecond queries** – 2-50ms response times even with thousands of decisions
|
|
156
|
+
- **Scalable architecture** – Perform well with large decision histories
|
|
157
|
+
- **Production-ready** – 495/495 tests passing (100%), battle-tested on real projects
|
|
84
158
|
|
|
85
159
|
---
|
|
86
160
|
|
|
87
|
-
**Technical Features**:
|
|
161
|
+
**Technical Features**: 8 MCP tools (5 core: decision, constraint, task, file, suggest + 3 utility: help, example, use_case), three-tier similarity detection (0-100 point scoring), ACID transaction support, multi-database backend (SQLite/PostgreSQL/MySQL), metadata-driven organization with layers and tags
|
|
88
162
|
|
|
89
|
-
See [docs/
|
|
163
|
+
See [docs/DECISION_CONTEXT.md](docs/DECISION_CONTEXT.md) for ADR data model details.
|
|
90
164
|
|
|
91
165
|
### 🔖Kanban-style AI Scrum
|
|
92
166
|
|
|
@@ -119,33 +193,6 @@ The first time, sqlew initializes database, installs custom agents and slash com
|
|
|
119
193
|
|
|
120
194
|
It's Ready!
|
|
121
195
|
|
|
122
|
-
## 🚀 Quick Start: /sqlew Command
|
|
123
|
-
|
|
124
|
-
**The `/sqlew` command is the easiest way to use sqlew!** Just type `/sqlew` in Claude Code with natural language input.
|
|
125
|
-
|
|
126
|
-
### Most Common Uses
|
|
127
|
-
|
|
128
|
-
```bash
|
|
129
|
-
# Show status and get suggestions
|
|
130
|
-
/sqlew
|
|
131
|
-
|
|
132
|
-
# Record a decision
|
|
133
|
-
/sqlew record we use PostgreSQL 15 for production database
|
|
134
|
-
|
|
135
|
-
# Search past decisions
|
|
136
|
-
/sqlew search why we chose Knex for migrations
|
|
137
|
-
|
|
138
|
-
# List remaining tasks
|
|
139
|
-
/sqlew show remaining tasks
|
|
140
|
-
|
|
141
|
-
# Plan a new feature (breakdown into tasks)
|
|
142
|
-
/sqlew plan implementing user authentication
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
The `/sqlew` command automatically detects your intent (search, record, list, execute, task creation) and invokes the appropriate MCP tools.
|
|
146
|
-
|
|
147
|
-
---
|
|
148
|
-
|
|
149
196
|
**⚠️Note**: Global install (`npm install -g`) is **not recommended** because sqlew requires an independent settings per project. Each project should maintain its own context database in `.sqlew/sqlew.db`.
|
|
150
197
|
|
|
151
198
|
**Custom database path:** Add path as argument: `"args": ["sqlew", "/path/to/db.db"]`
|
|
@@ -275,14 +322,23 @@ Power users can still call MCP tools directly. See [Available Tools](#available-
|
|
|
275
322
|
|
|
276
323
|
### Available Tools
|
|
277
324
|
|
|
325
|
+
#### Core ADR Tools
|
|
326
|
+
|
|
278
327
|
| Tool | Purpose | Example Use |
|
|
279
328
|
|------|---------|------------|
|
|
280
|
-
| **decision** | Record
|
|
281
|
-
| **constraint** | Define rules | "
|
|
282
|
-
| **task** | Track
|
|
283
|
-
| **file** | Track changes | "Modified auth.ts" |
|
|
284
|
-
| **
|
|
285
|
-
|
|
329
|
+
| **decision** | Record architectural decisions with context | "We chose PostgreSQL over MongoDB (ACID requirement)" |
|
|
330
|
+
| **constraint** | Define architectural rules and principles | "All API endpoints must use /v2/ prefix" |
|
|
331
|
+
| **task** | Track implementation of decisions | "Implement JWT authentication" |
|
|
332
|
+
| **file** | Track code changes linked to decisions | "Modified auth.ts per security ADR" |
|
|
333
|
+
| **suggest** | Find similar decisions, prevent duplicates | Duplicate detection, similarity search |
|
|
334
|
+
|
|
335
|
+
#### Utility Tools
|
|
336
|
+
|
|
337
|
+
| Tool | Purpose | Example Use |
|
|
338
|
+
|------|---------|------------|
|
|
339
|
+
| **help** | Query action documentation and parameters | Get decision.set parameters |
|
|
340
|
+
| **example** | Browse code examples by tool/action | Find task.create examples |
|
|
341
|
+
| **use_case** | Complete workflow scenarios | Multi-step ADR workflows |
|
|
286
342
|
|
|
287
343
|
|
|
288
344
|
## Documentation
|
|
@@ -333,10 +389,32 @@ All tools support:
|
|
|
333
389
|
|
|
334
390
|
## Use Cases
|
|
335
391
|
|
|
336
|
-
|
|
337
|
-
- **
|
|
338
|
-
- **
|
|
339
|
-
- **
|
|
392
|
+
### ADR-Driven Development with AI
|
|
393
|
+
- **Architecture Evolution** – Document major architectural decisions with full context and alternatives
|
|
394
|
+
- **Pattern Standardization** – Establish coding patterns as constraints, enforce via AI code generation
|
|
395
|
+
- **Technical Debt Tracking** – Record temporary decisions with deprecation paths and future plans
|
|
396
|
+
- **Onboarding Acceleration** – New AI sessions instantly understand architectural history
|
|
397
|
+
|
|
398
|
+
### Cross-Session AI Workflows
|
|
399
|
+
- **Multi-Session Projects** – AI maintains context across days/weeks without re-reading documentation
|
|
400
|
+
- **Multi-Agent Coordination** – Multiple AI agents share architectural understanding through ADR database
|
|
401
|
+
- **Breaking Change Management** – Document API changes, deprecations, and migration paths systematically
|
|
402
|
+
- **Refactoring Guidance** – AI references past decisions to maintain architectural consistency during refactors
|
|
403
|
+
|
|
404
|
+
### Real-World Examples
|
|
405
|
+
```bash
|
|
406
|
+
# Document an architectural decision with alternatives
|
|
407
|
+
/sqlew record we use PostgreSQL over MongoDB. MongoDB was rejected due to lack of ACID transactions for our financial data requirements.
|
|
408
|
+
|
|
409
|
+
# Search for past decisions before making new ones
|
|
410
|
+
/sqlew search why did we choose JWT authentication
|
|
411
|
+
|
|
412
|
+
# Create constraint to guide AI code generation
|
|
413
|
+
/sqlew add constraint all API endpoints must use /v2/ prefix for versioning
|
|
414
|
+
|
|
415
|
+
# Plan implementation of a decision
|
|
416
|
+
/sqlew plan implementing the PostgreSQL connection pool with pgBouncer
|
|
417
|
+
```
|
|
340
418
|
|
|
341
419
|
See [docs/WORKFLOWS.md](docs/WORKFLOWS.md) for detailed multi-step examples.
|
|
342
420
|
|
|
@@ -370,7 +448,7 @@ See [docs/DECISION_INTELLIGENCE.md](docs/DECISION_INTELLIGENCE.md) for details o
|
|
|
370
448
|
|
|
371
449
|
## License
|
|
372
450
|
|
|
373
|
-
|
|
451
|
+
Apache License 2.0 - Free for commercial and personal use. See [LICENSE](LICENSE) for details.
|
|
374
452
|
|
|
375
453
|
## Links
|
|
376
454
|
|
package/dist/index.js
CHANGED
package/docs/AI_AGENT_GUIDE.md
CHANGED
|
@@ -1,7 +1,31 @@
|
|
|
1
|
-
# AI Agent Guide for
|
|
1
|
+
# AI Agent Guide for sqlew ADR System
|
|
2
2
|
|
|
3
3
|
**Quick Reference for Claude Code and other AI agents using sqlew (v4.0.0+)**
|
|
4
4
|
|
|
5
|
+
## What is sqlew?
|
|
6
|
+
|
|
7
|
+
sqlew is an **ADR (Architecture Decision Record) system designed for AI agents**. It enables you to create, query, and maintain structured architectural decisions in a SQL database, providing persistent context across sessions.
|
|
8
|
+
|
|
9
|
+
### Core Concept: ADR for AI
|
|
10
|
+
|
|
11
|
+
Traditional ADR uses Markdown files. sqlew brings ADR to AI agents through **RDBMS + MCP**:
|
|
12
|
+
|
|
13
|
+
**RDBMS (Relational Database)** enables efficient operations:
|
|
14
|
+
- **Indexed queries** – Find decisions by tags/layers in milliseconds
|
|
15
|
+
- **JOIN operations** – Query related decisions, constraints, and tasks together
|
|
16
|
+
- **Transaction safety** – ACID guarantees prevent data corruption
|
|
17
|
+
- **Scalability** – Handle thousands of ADRs without slowdown
|
|
18
|
+
|
|
19
|
+
**MCP (Model Context Protocol)** provides AI-native access:
|
|
20
|
+
- **Native tool calls** – AI agents use ADR as built-in functions
|
|
21
|
+
- **Structured parameters** – Type-safe, validated inputs prevent errors
|
|
22
|
+
- **Token efficiency** – Retrieve only required data (60-75% reduction)
|
|
23
|
+
- **Session persistence** – ADRs survive beyond individual conversations
|
|
24
|
+
|
|
25
|
+
**Result**: AI agents query ADRs like database operations, not file reads.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
5
29
|
## Most Important Rule
|
|
6
30
|
|
|
7
31
|
**ALWAYS include the `action` parameter in EVERY tool call.** This is the #1 cause of errors.
|
|
@@ -9,44 +33,52 @@
|
|
|
9
33
|
```javascript
|
|
10
34
|
// WRONG - Missing action
|
|
11
35
|
{
|
|
12
|
-
key: "
|
|
13
|
-
value: "
|
|
36
|
+
key: "auth_method",
|
|
37
|
+
value: "jwt"
|
|
14
38
|
}
|
|
15
39
|
|
|
16
40
|
// CORRECT - action parameter present
|
|
17
41
|
{
|
|
18
42
|
action: "set",
|
|
19
|
-
key: "
|
|
20
|
-
value: "
|
|
43
|
+
key: "auth_method",
|
|
44
|
+
value: "jwt"
|
|
21
45
|
}
|
|
22
46
|
```
|
|
23
47
|
|
|
24
48
|
---
|
|
25
49
|
|
|
26
|
-
## Quick Start
|
|
50
|
+
## Quick Start: Creating Your First ADR
|
|
27
51
|
|
|
28
|
-
### Basic
|
|
52
|
+
### Basic ADR Workflow
|
|
29
53
|
|
|
30
54
|
```javascript
|
|
31
|
-
// 1.
|
|
55
|
+
// 1. Record an architectural decision
|
|
32
56
|
{
|
|
33
57
|
action: "set",
|
|
34
58
|
key: "auth_method",
|
|
35
|
-
value: "
|
|
59
|
+
value: "We chose JWT authentication over session-based auth. JWT enables stateless API design and better horizontal scaling. Session-based auth was rejected due to scaling concerns with shared session stores.",
|
|
36
60
|
layer: "business",
|
|
37
|
-
tags: ["security", "authentication"]
|
|
61
|
+
tags: ["security", "authentication", "api"]
|
|
38
62
|
}
|
|
39
63
|
|
|
40
|
-
// 2.
|
|
64
|
+
// 2. Retrieve the decision
|
|
41
65
|
{
|
|
42
66
|
action: "get",
|
|
43
67
|
key: "auth_method"
|
|
44
68
|
}
|
|
45
69
|
|
|
46
|
-
// 3.
|
|
70
|
+
// 3. Search for related decisions
|
|
47
71
|
{
|
|
48
72
|
action: "list",
|
|
49
|
-
|
|
73
|
+
tags: ["authentication"],
|
|
74
|
+
status: "active"
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// 4. Add architectural constraint
|
|
78
|
+
{
|
|
79
|
+
action: "add",
|
|
80
|
+
category: "security",
|
|
81
|
+
constraint_text: "All authentication must use JWT with RS256 signing algorithm",
|
|
50
82
|
layer: "business"
|
|
51
83
|
}
|
|
52
84
|
```
|
|
@@ -55,33 +87,71 @@
|
|
|
55
87
|
|
|
56
88
|
## When to Use Each Tool
|
|
57
89
|
|
|
58
|
-
|
|
90
|
+
### Core ADR Tools
|
|
91
|
+
|
|
92
|
+
| Tool | ADR Purpose | Key Feature |
|
|
93
|
+
|------|-------------|-------------|
|
|
94
|
+
| **decision** | Record architectural decisions | Full version history, alternatives tracking |
|
|
95
|
+
| **constraint** | Define architectural principles | Category-based rules, validation support |
|
|
96
|
+
| **task** | Track decision implementation | Links to decisions, status tracking |
|
|
97
|
+
| **file** | Document impacted code | Shows which files implement decisions |
|
|
98
|
+
| **suggest** | Find similar decisions | Prevent duplicate ADRs, detect conflicts |
|
|
99
|
+
|
|
100
|
+
### Utility Tools
|
|
101
|
+
|
|
102
|
+
| Tool | Purpose | When to Use |
|
|
59
103
|
|------|---------|-------------|
|
|
60
|
-
| **
|
|
61
|
-
| **
|
|
62
|
-
| **
|
|
63
|
-
|
|
64
|
-
|
|
104
|
+
| **help** | Query action parameters | Need to check available parameters for an action |
|
|
105
|
+
| **example** | Browse code examples | Want to see working code snippets |
|
|
106
|
+
| **use_case** | Learn complete workflows | Need end-to-end multi-step scenarios |
|
|
107
|
+
|
|
108
|
+
> **Note**: Utility tools provide documentation and examples without affecting your ADR data.
|
|
65
109
|
|
|
66
|
-
###
|
|
110
|
+
### Understanding the ADR Data Model
|
|
67
111
|
|
|
68
|
-
| Concept |
|
|
69
|
-
|
|
70
|
-
| **Decision** |
|
|
71
|
-
| **Constraint** |
|
|
72
|
-
| **Task** |
|
|
112
|
+
| Concept | ADR Equivalent | Example |
|
|
113
|
+
|---------|----------------|---------|
|
|
114
|
+
| **Decision** | Architecture Decision Record | "We chose PostgreSQL over MongoDB for ACID compliance" |
|
|
115
|
+
| **Constraint** | Architectural Principle/Rule | "All database queries must use prepared statements" |
|
|
116
|
+
| **Task** | Implementation Action | "Migrate user authentication to JWT" |
|
|
117
|
+
| **File** | Impacted Component | "Modified auth.ts to implement JWT" |
|
|
73
118
|
|
|
74
|
-
###
|
|
119
|
+
### Complete ADR Workflow Example
|
|
75
120
|
|
|
76
121
|
```javascript
|
|
77
|
-
// 1. Record decision
|
|
78
|
-
{
|
|
122
|
+
// 1. Record decision with full context
|
|
123
|
+
{
|
|
124
|
+
action: "set",
|
|
125
|
+
key: "database_choice",
|
|
126
|
+
value: "PostgreSQL selected for production database. Alternatives considered: MongoDB (rejected: no ACID), MySQL (rejected: weaker JSON support). PostgreSQL chosen for ACID compliance, mature ecosystem, and superior JSON handling.",
|
|
127
|
+
layer: "data",
|
|
128
|
+
tags: ["database", "postgresql", "architecture"]
|
|
129
|
+
}
|
|
79
130
|
|
|
80
|
-
// 2.
|
|
81
|
-
{
|
|
131
|
+
// 2. Define constraints based on decision
|
|
132
|
+
{
|
|
133
|
+
action: "add",
|
|
134
|
+
category: "database",
|
|
135
|
+
constraint_text: "All database operations must use connection pooling with max 20 connections",
|
|
136
|
+
layer: "data"
|
|
137
|
+
}
|
|
82
138
|
|
|
83
|
-
// 3. Create task
|
|
84
|
-
{
|
|
139
|
+
// 3. Create implementation task
|
|
140
|
+
{
|
|
141
|
+
action: "create",
|
|
142
|
+
title: "Set up PostgreSQL connection pool",
|
|
143
|
+
description: "Implement connection pooling as per database_choice ADR",
|
|
144
|
+
layer: "data",
|
|
145
|
+
tags: ["database", "postgresql"]
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// 4. Track file changes
|
|
149
|
+
{
|
|
150
|
+
action: "set",
|
|
151
|
+
path: "src/db/connection.ts",
|
|
152
|
+
description: "PostgreSQL connection pool implementation",
|
|
153
|
+
layer: "data"
|
|
154
|
+
}
|
|
85
155
|
```
|
|
86
156
|
|
|
87
157
|
---
|
|
@@ -147,13 +217,44 @@
|
|
|
147
217
|
|
|
148
218
|
---
|
|
149
219
|
|
|
150
|
-
## Best Practices
|
|
220
|
+
## ADR Best Practices for AI Agents
|
|
221
|
+
|
|
222
|
+
### Writing Good ADRs
|
|
223
|
+
|
|
224
|
+
1. **Include rationale** - Explain WHY, not just WHAT
|
|
225
|
+
```javascript
|
|
226
|
+
// BAD: "Use PostgreSQL"
|
|
227
|
+
// GOOD: "Use PostgreSQL for ACID compliance (rejected MongoDB for lack of transactions)"
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
2. **Document alternatives** - Show what was considered and rejected
|
|
231
|
+
```javascript
|
|
232
|
+
value: "JWT chosen. Alternatives: session-based (rejected: scaling), OAuth (overkill for internal API)"
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
3. **Use descriptive keys** - Make decisions discoverable
|
|
236
|
+
```javascript
|
|
237
|
+
// BAD: key: "db"
|
|
238
|
+
// GOOD: key: "database_postgresql_production"
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
4. **Tag comprehensively** - Enable efficient searching
|
|
242
|
+
```javascript
|
|
243
|
+
tags: ["database", "postgresql", "production", "acid", "scalability"]
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
5. **Link related entities** - Connect decisions to implementation
|
|
247
|
+
```javascript
|
|
248
|
+
// Record decision → Create constraint → Make task → Track files
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Technical Best Practices
|
|
151
252
|
|
|
152
253
|
1. **Always include `action` parameter** - #1 error source
|
|
153
|
-
2. **
|
|
154
|
-
3. **
|
|
155
|
-
4. **
|
|
156
|
-
5. **
|
|
254
|
+
2. **Always specify `layer`** - Required for architectural organization
|
|
255
|
+
3. **Use `atomic: false` for batch operations** - Avoid all-or-nothing failures
|
|
256
|
+
4. **Check for duplicates first** - Use `suggest` tool before creating decisions
|
|
257
|
+
5. **Version important changes** - Increment version for significant updates
|
|
157
258
|
|
|
158
259
|
> **Detailed best practices**: See [BEST_PRACTICES.md](BEST_PRACTICES.md)
|
|
159
260
|
|
package/docs/DECISION_CONTEXT.md
CHANGED
|
@@ -1,10 +1,19 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ADR Data Model - Architecture Decision Records (v3.2.2+)
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
sqlew implements a **structured ADR (Architecture Decision Record) data model** that captures not just decisions, but the complete context: **WHY** a decision was made, what alternatives were considered, and the trade-offs involved. This transforms traditional text-based ADR into a queryable, AI-native database that maintains architectural knowledge across sessions.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
### What is an ADR?
|
|
8
|
+
|
|
9
|
+
**Architecture Decision Records (ADR)** are documents that capture important architectural decisions made along with their context and consequences. sqlew extends this concept by:
|
|
10
|
+
|
|
11
|
+
- **Structured storage** – ADR data stored as relational database records
|
|
12
|
+
- **Version history** – Track how decisions evolve over time
|
|
13
|
+
- **Relationship tracking** – Link decisions to tasks, files, and constraints
|
|
14
|
+
- **AI-native queries** – Search by tags, layers, similarity scores
|
|
15
|
+
|
|
16
|
+
> **Preserved in v4.0.0**: This feature is fully preserved in the v4.0.0 schema refactoring. All ADR context data (rationale, alternatives, trade-offs, related links) continues to work without changes. The schema uses `v4_decision_context` table with the same structure and functionality.
|
|
8
17
|
|
|
9
18
|
---
|
|
10
19
|
|
|
@@ -650,26 +659,39 @@ If you have old decisions that need context, add it retroactively:
|
|
|
650
659
|
|
|
651
660
|
## Key Takeaways
|
|
652
661
|
|
|
653
|
-
###
|
|
662
|
+
### ADR for AI Agents: Context + Intelligence = Complete Knowledge Repository
|
|
654
663
|
|
|
655
|
-
**
|
|
664
|
+
**sqlew transforms traditional ADR into an AI-native knowledge system:**
|
|
656
665
|
|
|
657
|
-
1. **
|
|
658
|
-
2. **Decision Intelligence** (v3.9.0) →
|
|
666
|
+
1. **ADR Data Model** (v3.2.2) → Structured storage of decisions with rationale, alternatives, and trade-offs
|
|
667
|
+
2. **Decision Intelligence** (v3.9.0) → Automatic duplicate detection and version consolidation
|
|
668
|
+
3. **AI-Native Queries** → Fast, structured access to architectural decisions across sessions
|
|
659
669
|
|
|
660
670
|
**Together they provide:**
|
|
661
|
-
- **Living
|
|
662
|
-
- **
|
|
663
|
-
- **Automatic consolidation**
|
|
664
|
-
- **
|
|
665
|
-
- **
|
|
671
|
+
- **Living ADR repository** – Decisions evolve with your project through version history
|
|
672
|
+
- **AI-queryable records** – Search by tags, layers, similarity instead of reading files
|
|
673
|
+
- **Automatic consolidation** – Prevent duplicate ADRs, maintain single source of truth
|
|
674
|
+
- **Complete context** – Capture WHY, not just WHAT (alternatives, trade-offs, consequences)
|
|
675
|
+
- **Cross-session memory** – AI agents maintain architectural understanding across days/weeks
|
|
676
|
+
|
|
677
|
+
### ADR Best Practices for AI
|
|
678
|
+
|
|
679
|
+
**Before creating a decision:**
|
|
680
|
+
1. Use `check_duplicate` to find existing related ADRs
|
|
681
|
+
2. Review similar decisions to avoid redundancy
|
|
682
|
+
3. Update existing ADR if it's the same topic
|
|
683
|
+
|
|
684
|
+
**When documenting a decision:**
|
|
685
|
+
1. Include **rationale** – Explain WHY this choice was made
|
|
686
|
+
2. Document **alternatives** – Show what was considered and rejected
|
|
687
|
+
3. Capture **trade-offs** – Honest pros/cons for future reference
|
|
688
|
+
4. Link **related entities** – Connect to tasks, files, constraints
|
|
666
689
|
|
|
667
|
-
**
|
|
668
|
-
1.
|
|
669
|
-
2.
|
|
670
|
-
3.
|
|
671
|
-
4. Query `versions` to see decision evolution
|
|
690
|
+
**After implementation:**
|
|
691
|
+
1. Track affected files to show ADR impact
|
|
692
|
+
2. Update decision status as it evolves (active → deprecated → superseded)
|
|
693
|
+
3. Query `versions` to see architectural evolution over time
|
|
672
694
|
|
|
673
|
-
**
|
|
695
|
+
**ADR transforms your codebase from "what we built" into "why we built it this way"** - making architectural decisions discoverable and understandable to AI agents across the entire project lifecycle.
|
|
674
696
|
|
|
675
|
-
**Decision Intelligence ensures
|
|
697
|
+
**Decision Intelligence ensures ADRs remain living documents** - automatically consolidated and updated rather than scattered across fragmented entries.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sqlew",
|
|
3
|
-
"version": "4.0.4",
|
|
4
3
|
"description": "MCP server that gives AI agents a shared SQL-backed context repository for decisions, constraints, and tasks",
|
|
4
|
+
"version": "4.0.5",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"docs/",
|
|
16
16
|
"README.md",
|
|
17
17
|
"LICENSE",
|
|
18
|
+
"NOTICE",
|
|
18
19
|
"CHANGELOG.md",
|
|
19
20
|
"MIGRATION_v2.md",
|
|
20
21
|
"ARCHITECTURE.md"
|
|
@@ -84,18 +85,22 @@
|
|
|
84
85
|
},
|
|
85
86
|
"homepage": "https://github.com/sin5ddd/mcp-sqlew#readme",
|
|
86
87
|
"keywords": [
|
|
88
|
+
"adr",
|
|
89
|
+
"architecture-decision-record",
|
|
87
90
|
"mcp",
|
|
88
91
|
"mcp-server",
|
|
89
92
|
"model-context-protocol",
|
|
90
|
-
"
|
|
93
|
+
"ai-agents",
|
|
91
94
|
"claude-code",
|
|
92
|
-
"
|
|
95
|
+
"architectural-decisions",
|
|
96
|
+
"decision-management",
|
|
93
97
|
"sqlite",
|
|
94
|
-
"
|
|
95
|
-
"
|
|
98
|
+
"postgresql",
|
|
99
|
+
"mysql",
|
|
100
|
+
"token-efficiency"
|
|
96
101
|
],
|
|
97
102
|
"author": "sin5ddd",
|
|
98
|
-
"license": "
|
|
103
|
+
"license": "Apache-2.0",
|
|
99
104
|
"dependencies": {
|
|
100
105
|
"@modelcontextprotocol/sdk": "^1.21.1",
|
|
101
106
|
"better-sqlite3": "^12.4.1",
|