@iamsyr/agentmind 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/LICENSE +21 -0
  3. package/README.md +462 -0
  4. package/RELEASING.md +42 -0
  5. package/dist/adapters/cursor.d.ts +2 -0
  6. package/dist/adapters/cursor.d.ts.map +1 -0
  7. package/dist/adapters/cursor.js +39 -0
  8. package/dist/adapters/cursor.js.map +1 -0
  9. package/dist/adapters/index.d.ts +9 -0
  10. package/dist/adapters/index.d.ts.map +1 -0
  11. package/dist/adapters/index.js +16 -0
  12. package/dist/adapters/index.js.map +1 -0
  13. package/dist/adapters/types.d.ts +24 -0
  14. package/dist/adapters/types.d.ts.map +1 -0
  15. package/dist/adapters/types.js +66 -0
  16. package/dist/adapters/types.js.map +1 -0
  17. package/dist/adapters/windsurf.d.ts +2 -0
  18. package/dist/adapters/windsurf.d.ts.map +1 -0
  19. package/dist/adapters/windsurf.js +44 -0
  20. package/dist/adapters/windsurf.js.map +1 -0
  21. package/dist/bridge/conflict.d.ts +9 -0
  22. package/dist/bridge/conflict.d.ts.map +1 -0
  23. package/dist/bridge/conflict.js +38 -0
  24. package/dist/bridge/conflict.js.map +1 -0
  25. package/dist/bridge/index.d.ts +5 -0
  26. package/dist/bridge/index.d.ts.map +1 -0
  27. package/dist/bridge/index.js +3 -0
  28. package/dist/bridge/index.js.map +1 -0
  29. package/dist/bridge/state.d.ts +30 -0
  30. package/dist/bridge/state.d.ts.map +1 -0
  31. package/dist/bridge/state.js +130 -0
  32. package/dist/bridge/state.js.map +1 -0
  33. package/dist/cli/commands/agents.d.ts +2 -0
  34. package/dist/cli/commands/agents.d.ts.map +1 -0
  35. package/dist/cli/commands/agents.js +38 -0
  36. package/dist/cli/commands/agents.js.map +1 -0
  37. package/dist/cli/commands/annotate.d.ts +4 -0
  38. package/dist/cli/commands/annotate.d.ts.map +1 -0
  39. package/dist/cli/commands/annotate.js +116 -0
  40. package/dist/cli/commands/annotate.js.map +1 -0
  41. package/dist/cli/commands/behaviors.d.ts +6 -0
  42. package/dist/cli/commands/behaviors.d.ts.map +1 -0
  43. package/dist/cli/commands/behaviors.js +76 -0
  44. package/dist/cli/commands/behaviors.js.map +1 -0
  45. package/dist/cli/commands/bridge.d.ts +15 -0
  46. package/dist/cli/commands/bridge.d.ts.map +1 -0
  47. package/dist/cli/commands/bridge.js +75 -0
  48. package/dist/cli/commands/bridge.js.map +1 -0
  49. package/dist/cli/commands/health.d.ts +4 -0
  50. package/dist/cli/commands/health.d.ts.map +1 -0
  51. package/dist/cli/commands/health.js +382 -0
  52. package/dist/cli/commands/health.js.map +1 -0
  53. package/dist/cli/commands/hooks.d.ts +3 -0
  54. package/dist/cli/commands/hooks.d.ts.map +1 -0
  55. package/dist/cli/commands/hooks.js +59 -0
  56. package/dist/cli/commands/hooks.js.map +1 -0
  57. package/dist/cli/commands/init.d.ts +2 -0
  58. package/dist/cli/commands/init.d.ts.map +1 -0
  59. package/dist/cli/commands/init.js +128 -0
  60. package/dist/cli/commands/init.js.map +1 -0
  61. package/dist/cli/commands/inject.d.ts +6 -0
  62. package/dist/cli/commands/inject.d.ts.map +1 -0
  63. package/dist/cli/commands/inject.js +84 -0
  64. package/dist/cli/commands/inject.js.map +1 -0
  65. package/dist/cli/commands/insights.d.ts +4 -0
  66. package/dist/cli/commands/insights.d.ts.map +1 -0
  67. package/dist/cli/commands/insights.js +124 -0
  68. package/dist/cli/commands/insights.js.map +1 -0
  69. package/dist/cli/commands/learn.d.ts +8 -0
  70. package/dist/cli/commands/learn.d.ts.map +1 -0
  71. package/dist/cli/commands/learn.js +121 -0
  72. package/dist/cli/commands/learn.js.map +1 -0
  73. package/dist/cli/commands/log-behavior.d.ts +14 -0
  74. package/dist/cli/commands/log-behavior.d.ts.map +1 -0
  75. package/dist/cli/commands/log-behavior.js +50 -0
  76. package/dist/cli/commands/log-behavior.js.map +1 -0
  77. package/dist/cli/commands/overlay.d.ts +10 -0
  78. package/dist/cli/commands/overlay.d.ts.map +1 -0
  79. package/dist/cli/commands/overlay.js +303 -0
  80. package/dist/cli/commands/overlay.js.map +1 -0
  81. package/dist/cli/commands/pull.d.ts +4 -0
  82. package/dist/cli/commands/pull.d.ts.map +1 -0
  83. package/dist/cli/commands/pull.js +93 -0
  84. package/dist/cli/commands/pull.js.map +1 -0
  85. package/dist/cli/commands/push.d.ts +5 -0
  86. package/dist/cli/commands/push.d.ts.map +1 -0
  87. package/dist/cli/commands/push.js +71 -0
  88. package/dist/cli/commands/push.js.map +1 -0
  89. package/dist/cli/commands/scan.d.ts +5 -0
  90. package/dist/cli/commands/scan.d.ts.map +1 -0
  91. package/dist/cli/commands/scan.js +134 -0
  92. package/dist/cli/commands/scan.js.map +1 -0
  93. package/dist/cli/commands/serve.d.ts +2 -0
  94. package/dist/cli/commands/serve.d.ts.map +1 -0
  95. package/dist/cli/commands/serve.js +17 -0
  96. package/dist/cli/commands/serve.js.map +1 -0
  97. package/dist/cli/commands/share.d.ts +5 -0
  98. package/dist/cli/commands/share.d.ts.map +1 -0
  99. package/dist/cli/commands/share.js +97 -0
  100. package/dist/cli/commands/share.js.map +1 -0
  101. package/dist/cli/commands/status.d.ts +2 -0
  102. package/dist/cli/commands/status.d.ts.map +1 -0
  103. package/dist/cli/commands/status.js +167 -0
  104. package/dist/cli/commands/status.js.map +1 -0
  105. package/dist/cli/commands/sync.d.ts +6 -0
  106. package/dist/cli/commands/sync.d.ts.map +1 -0
  107. package/dist/cli/commands/sync.js +60 -0
  108. package/dist/cli/commands/sync.js.map +1 -0
  109. package/dist/cli/commands/template.d.ts +5 -0
  110. package/dist/cli/commands/template.d.ts.map +1 -0
  111. package/dist/cli/commands/template.js +98 -0
  112. package/dist/cli/commands/template.js.map +1 -0
  113. package/dist/cli/index.d.ts +3 -0
  114. package/dist/cli/index.d.ts.map +1 -0
  115. package/dist/cli/index.js +172 -0
  116. package/dist/cli/index.js.map +1 -0
  117. package/dist/cli/utils.d.ts +6 -0
  118. package/dist/cli/utils.d.ts.map +1 -0
  119. package/dist/cli/utils.js +49 -0
  120. package/dist/cli/utils.js.map +1 -0
  121. package/dist/hooks/claude.d.ts +6 -0
  122. package/dist/hooks/claude.d.ts.map +1 -0
  123. package/dist/hooks/claude.js +189 -0
  124. package/dist/hooks/claude.js.map +1 -0
  125. package/dist/hooks/codex.d.ts +6 -0
  126. package/dist/hooks/codex.d.ts.map +1 -0
  127. package/dist/hooks/codex.js +120 -0
  128. package/dist/hooks/codex.js.map +1 -0
  129. package/dist/hooks/index.d.ts +5 -0
  130. package/dist/hooks/index.d.ts.map +1 -0
  131. package/dist/hooks/index.js +4 -0
  132. package/dist/hooks/index.js.map +1 -0
  133. package/dist/hooks/template.d.ts +5 -0
  134. package/dist/hooks/template.d.ts.map +1 -0
  135. package/dist/hooks/template.js +176 -0
  136. package/dist/hooks/template.js.map +1 -0
  137. package/dist/index.d.ts +5 -0
  138. package/dist/index.d.ts.map +1 -0
  139. package/dist/index.js +4 -0
  140. package/dist/index.js.map +1 -0
  141. package/dist/learn/analyzer.d.ts +11 -0
  142. package/dist/learn/analyzer.d.ts.map +1 -0
  143. package/dist/learn/analyzer.js +145 -0
  144. package/dist/learn/analyzer.js.map +1 -0
  145. package/dist/learn/generator.d.ts +12 -0
  146. package/dist/learn/generator.d.ts.map +1 -0
  147. package/dist/learn/generator.js +37 -0
  148. package/dist/learn/generator.js.map +1 -0
  149. package/dist/mcp/index.d.ts +2 -0
  150. package/dist/mcp/index.d.ts.map +1 -0
  151. package/dist/mcp/index.js +2 -0
  152. package/dist/mcp/index.js.map +1 -0
  153. package/dist/mcp/server.d.ts +2 -0
  154. package/dist/mcp/server.d.ts.map +1 -0
  155. package/dist/mcp/server.js +325 -0
  156. package/dist/mcp/server.js.map +1 -0
  157. package/dist/router/index.d.ts +3 -0
  158. package/dist/router/index.d.ts.map +1 -0
  159. package/dist/router/index.js +44 -0
  160. package/dist/router/index.js.map +1 -0
  161. package/dist/scanner/classify.d.ts +6 -0
  162. package/dist/scanner/classify.d.ts.map +1 -0
  163. package/dist/scanner/classify.js +101 -0
  164. package/dist/scanner/classify.js.map +1 -0
  165. package/dist/scanner/graph.d.ts +3 -0
  166. package/dist/scanner/graph.d.ts.map +1 -0
  167. package/dist/scanner/graph.js +104 -0
  168. package/dist/scanner/graph.js.map +1 -0
  169. package/dist/scanner/index.d.ts +6 -0
  170. package/dist/scanner/index.d.ts.map +1 -0
  171. package/dist/scanner/index.js +23 -0
  172. package/dist/scanner/index.js.map +1 -0
  173. package/dist/scanner/patterns.d.ts +3 -0
  174. package/dist/scanner/patterns.d.ts.map +1 -0
  175. package/dist/scanner/patterns.js +179 -0
  176. package/dist/scanner/patterns.js.map +1 -0
  177. package/dist/store/db.d.ts +21 -0
  178. package/dist/store/db.d.ts.map +1 -0
  179. package/dist/store/db.js +55 -0
  180. package/dist/store/db.js.map +1 -0
  181. package/dist/store/index.d.ts +3 -0
  182. package/dist/store/index.d.ts.map +1 -0
  183. package/dist/store/index.js +3 -0
  184. package/dist/store/index.js.map +1 -0
  185. package/dist/store/jsonl.d.ts +6 -0
  186. package/dist/store/jsonl.d.ts.map +1 -0
  187. package/dist/store/jsonl.js +55 -0
  188. package/dist/store/jsonl.js.map +1 -0
  189. package/dist/store/schema.d.ts +32 -0
  190. package/dist/store/schema.d.ts.map +1 -0
  191. package/dist/store/schema.js +210 -0
  192. package/dist/store/schema.js.map +1 -0
  193. package/dist/templates/go.d.ts +3 -0
  194. package/dist/templates/go.d.ts.map +1 -0
  195. package/dist/templates/go.js +35 -0
  196. package/dist/templates/go.js.map +1 -0
  197. package/dist/templates/index.d.ts +13 -0
  198. package/dist/templates/index.d.ts.map +1 -0
  199. package/dist/templates/index.js +98 -0
  200. package/dist/templates/index.js.map +1 -0
  201. package/dist/templates/nextjs.d.ts +3 -0
  202. package/dist/templates/nextjs.d.ts.map +1 -0
  203. package/dist/templates/nextjs.js +53 -0
  204. package/dist/templates/nextjs.js.map +1 -0
  205. package/dist/templates/python.d.ts +3 -0
  206. package/dist/templates/python.d.ts.map +1 -0
  207. package/dist/templates/python.js +41 -0
  208. package/dist/templates/python.js.map +1 -0
  209. package/dist/templates/react-native.d.ts +3 -0
  210. package/dist/templates/react-native.d.ts.map +1 -0
  211. package/dist/templates/react-native.js +35 -0
  212. package/dist/templates/react-native.js.map +1 -0
  213. package/dist/templates/registry.d.ts +24 -0
  214. package/dist/templates/registry.d.ts.map +1 -0
  215. package/dist/templates/registry.js +2 -0
  216. package/dist/templates/registry.js.map +1 -0
  217. package/dist/templates/rust.d.ts +3 -0
  218. package/dist/templates/rust.d.ts.map +1 -0
  219. package/dist/templates/rust.js +41 -0
  220. package/dist/templates/rust.js.map +1 -0
  221. package/dist/templates/sst.d.ts +3 -0
  222. package/dist/templates/sst.d.ts.map +1 -0
  223. package/dist/templates/sst.js +35 -0
  224. package/dist/templates/sst.js.map +1 -0
  225. package/dist/types/index.d.ts +92 -0
  226. package/dist/types/index.d.ts.map +1 -0
  227. package/dist/types/index.js +2 -0
  228. package/dist/types/index.js.map +1 -0
  229. package/package.json +62 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - First public npm-ready release of `agentmind`.
6
+ - Node 22+ CLI with scan, hooks, MCP server, and context sync commands.
7
+ - Node-based generated hooks for Claude and Codex.
8
+ - CI, smoke checks, and integration coverage for hooks, MCP serve, and JSONL import safety.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,462 @@
1
+ # agentmind
2
+
3
+ **Intelligent context routing for AI coding agents.**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/agentmind.svg)](https://www.npmjs.com/package/agentmind)
6
+ [![Node.js Version](https://img.shields.io/node/v/agentmind.svg)](https://nodejs.org)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+
9
+ ---
10
+
11
+ ## Why agentmind?
12
+
13
+ AI coding agents (Claude Code, Codex, Cursor, Windsurf) work better when they understand your project. But:
14
+
15
+ - **Context is lost** when a session ends
16
+ - **You re-explain** the same things every session
17
+ - **No shared knowledge** between agents
18
+ - **Conflicts** when multiple agents edit the same files
19
+
20
+ **agentmind fixes this** by:
21
+
22
+ 1. **Scanning** your project and building a context map
23
+ 2. **Storing** context in a git-friendly SQLite database
24
+ 3. **Routing** the right context to the right agent/file on demand
25
+ 4. **Exposing** it through CLI commands, hooks, and an MCP server
26
+
27
+ The result: agents understand your project faster, commit fewer bugs, and coordinate with each other.
28
+
29
+ ---
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ # Global CLI
35
+ npm install -g agentmind
36
+
37
+ # Or as a local dev dependency
38
+ npm install --save-dev agentmind
39
+ ```
40
+
41
+ **Requirements:** Node.js 22+ and native module `better-sqlite3`.
42
+
43
+ ### Run from source
44
+
45
+ ```bash
46
+ git clone https://github.com/your-org/agentmind.git
47
+ cd agentmind
48
+ npm install
49
+ npm run build
50
+ node dist/cli/index.js --help
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Quick Start
56
+
57
+ ```bash
58
+ # 1. Initialize agentmind in your project
59
+ agentmind init
60
+
61
+ # 2. Scan project files and build context map
62
+ agentmind scan
63
+
64
+ # 3. Check status
65
+ agentmind status
66
+
67
+ # 4. (Optional) Start MCP server for agent integration
68
+ agentmind serve
69
+ ```
70
+
71
+ ---
72
+
73
+ ## Architecture
74
+
75
+ ```
76
+ ┌─────────────────────────────────────────────────────────────┐
77
+ │ Project Files │
78
+ └─────────────────────────────────────────────────────────────┘
79
+
80
+
81
+ ┌─────────────────────────────────────────────────────────────┐
82
+ │ Scanner │
83
+ │ - Classify files (config, source, test, docs...) │
84
+ │ - Detect patterns (auth, api, database...) │
85
+ │ - Build dependency graph │
86
+ └─────────────────────────────────────────────────────────────┘
87
+
88
+
89
+ ┌─────────────────────────────────────────────────────────────┐
90
+ │ ContextStore (SQLite) │
91
+ │ - Annotations: human/agent notes per file │
92
+ │ - Rules: patterns to enforce │
93
+ │ - Behavior log: agent actions & outcomes │
94
+ │ - Project meta: stack, framework, conventions │
95
+ └─────────────────────────────────────────────────────────────┘
96
+
97
+ ┌─────────────────┼─────────────────┐
98
+ ▼ ▼ ▼
99
+ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
100
+ │ CLI Commands │ │ Hooks System │ │ MCP Server │
101
+ │ - status │ │ - pre-tool-use │ │ - get_context │
102
+ │ - annotate │ │ - post-tool-use│ │ - annotate_file│
103
+ │ - insights │ │ - post-commit │ │ - find_gaps │
104
+ └─────────────────┘ └─────────────────┘ └─────────────────┘
105
+ ```
106
+
107
+ ---
108
+
109
+ ## CLI Reference
110
+
111
+ ### Core Commands
112
+
113
+ | Command | Description | Options |
114
+ |----------------------|-------------------------------------------------|----------------------------|
115
+ | `init` | Initialize agentmind in the project | — |
116
+ | `scan` | Scan project files and build context map | `-f, --force`, `--json` |
117
+ | `status` | Show status and health overview | — |
118
+ | `health` | Dashboard with coverage, staleness, recs | `--json` |
119
+ | `annotate <path>` | Add a context annotation to a file | `-l, --line <number>` |
120
+
121
+ ### Agent Integration
122
+
123
+ | Command | Description | Options |
124
+ |----------------------|-------------------------------------------------|----------------------------|
125
+ | `hooks <agent>` | Install hooks for claude or codex | — |
126
+ | `unhook <agent>` | Remove hooks | — |
127
+ | `serve` | Start MCP server over stdio | — |
128
+ | `inject [query]` | Inject context into current agent session | `-f, --file <path>` |
129
+
130
+ ### Behavior & Insights
131
+
132
+ | Command | Description | Options |
133
+ |----------------------|-------------------------------------------------|----------------------------|
134
+ | `behaviors` | Show recent agent behavior log | `-n, --limit <number>` |
135
+ | `insights` | Analyze patterns, find failure hotspots | `--json` |
136
+ | `learn` | Auto-generate rules from behavior patterns | `--apply`, `--force` |
137
+
138
+ ### Multi-Agent Bridge
139
+
140
+ | Command | Description |
141
+ |----------------------------|--------------------------------------------|
142
+ | `bridge register` | Register a new agent |
143
+ | `bridge claim` | Claim files for editing (lock) |
144
+ | `bridge release` | Release claimed files |
145
+ | `bridge status` | Show bridge status |
146
+ | `bridge conflicts` | Show file conflicts |
147
+ | `agents` | List active agents and conflicts |
148
+
149
+ ### Sync & Share
150
+
151
+ | Command | Description | Options |
152
+ |----------------------|-------------------------------------------------|---------------------------------|
153
+ | `sync [tool]` | Sync context to .cursorrules/.windsurfrules | `--dry-run` |
154
+ | `unsync [tool]` | Remove from editor rule files | — |
155
+ | `share` | Export context snapshot | `-f json/md/curl`, `-o <file>` |
156
+ | `push` | Commit context changes | `-m <msg>`, `--remote` |
157
+ | `pull` | Pull remote context changes | `--force` |
158
+
159
+ ### Templates
160
+
161
+ | Command | Description |
162
+ |-----------------------------|-------------------------------------------|
163
+ | `template list` | List available templates |
164
+ | `template apply [name]` | Apply a template to the project |
165
+
166
+ ### Interactive
167
+
168
+ | Command | Description | Options |
169
+ |----------------------|-------------------------------------------------|----------------------------|
170
+ | `overlay` | Interactive annotation overlay | `--json` |
171
+
172
+ ---
173
+
174
+ ## MCP Server
175
+
176
+ Agentmind provides an MCP server over stdio (protocol version 2024-11-05).
177
+
178
+ ### Start server
179
+
180
+ ```bash
181
+ agentmind serve
182
+ ```
183
+
184
+ ### Available Tools
185
+
186
+ | Tool | Description | Parameters |
187
+ |-------------------|----------------------------------------------------------|----------------------------------------|
188
+ | `get_context` | Get project context for the current task | `filePath?`, `query?` |
189
+ | `get_health` | Check context health (coverage, staleness) | — |
190
+ | `annotate_file` | Add a context annotation to a file | `filePath`, `text`, `priority?` |
191
+ | `log_behavior` | Log agent behavior (called automatically by hooks) | `filePath`, `tool`, `success` |
192
+ | `find_gaps` | Find files missing context annotations | `directory?` |
193
+
194
+ ### Config for Claude Desktop
195
+
196
+ ```json
197
+ {
198
+ "mcpServers": {
199
+ "agentmind": {
200
+ "command": "node",
201
+ "args": ["/path/to/agentmind/dist/cli/index.js", "serve"]
202
+ }
203
+ }
204
+ }
205
+ ```
206
+
207
+ ---
208
+
209
+ ## Hooks System
210
+
211
+ Hooks let agentmind automatically track agent behavior and inject context.
212
+
213
+ ### Install hooks
214
+
215
+ ```bash
216
+ # Claude Code
217
+ agentmind hooks claude
218
+
219
+ # Codex
220
+ agentmind hooks codex
221
+ ```
222
+
223
+ ### Generated Files
224
+
225
+ ```
226
+ .agentmind/
227
+ ├── hooks/
228
+ │ ├── pre-tool-use.mjs # Runs before each tool call
229
+ │ ├── post-tool-use.mjs # Runs after each tool call
230
+ │ └── post-commit.mjs # Runs after git commit
231
+ └── config.json # Hook runtime config
232
+ ```
233
+
234
+ ### Config Targets
235
+
236
+ | Agent | Config File |
237
+ |--------|--------------------------------|
238
+ | Claude | `.claude/settings.local.json` |
239
+ | Codex | `.codex/config.json` |
240
+
241
+ ### Hook Behavior
242
+
243
+ - **pre-tool-use**: Log tool call, check file claims
244
+ - **post-tool-use**: Log success/failure, update patterns
245
+ - **post-commit**: Refresh context, export JSONL
246
+
247
+ ---
248
+
249
+ ## Multi-Agent Bridge
250
+
251
+ When multiple agents work concurrently, the Bridge prevents conflicts.
252
+
253
+ ### Workflow
254
+
255
+ ```
256
+ Agent A Agent B
257
+ │ │
258
+ │ bridge register --id A │
259
+ │────────────────────────> │
260
+ │ │
261
+ │ bridge claim --files │
262
+ │ src/auth.ts │
263
+ │────────────────────────> │ (src/auth.ts locked)
264
+ │ │
265
+ │ │ bridge claim src/auth.ts
266
+ │ │────────────────────────>
267
+ │ │ ✗ CONFLICT DETECTED
268
+ │ │
269
+ │ bridge release │
270
+ │────────────────────────> │ (src/auth.ts unlocked)
271
+ │ │ ✓ Can claim now
272
+ ```
273
+
274
+ ### Commands
275
+
276
+ ```bash
277
+ # Register an agent
278
+ agentmind bridge register --id agent-001 --tool claude
279
+
280
+ # Claim files (locks them)
281
+ agentmind bridge claim --id agent-001 --files src/auth.ts src/api.ts
282
+
283
+ # Check status
284
+ agentmind bridge status
285
+
286
+ # View conflicts
287
+ agentmind bridge conflicts
288
+
289
+ # Release files
290
+ agentmind bridge release --id agent-001 --files src/auth.ts
291
+ ```
292
+
293
+ ---
294
+
295
+ ## Programmatic API
296
+
297
+ Use agentmind as a library:
298
+
299
+ ```typescript
300
+ import {
301
+ startServer,
302
+ ContextStore,
303
+ importJSONL,
304
+ exportJSONL,
305
+ appendJSONL,
306
+ scan,
307
+ classify,
308
+ detectPatterns,
309
+ buildGraph,
310
+ } from "agentmind"
311
+
312
+ // Types
313
+ import type {
314
+ Annotation,
315
+ BehaviorEntry,
316
+ ContextEntry,
317
+ DependencyGraph,
318
+ DependencyNode,
319
+ FileClassification,
320
+ FileInfo,
321
+ HookConfig,
322
+ HookEvent,
323
+ NonInferablePattern,
324
+ ProjectMeta,
325
+ Rule,
326
+ ScanResult,
327
+ StoreHealth,
328
+ } from "agentmind"
329
+
330
+ // Initialize store
331
+ const store = new ContextStore("/path/to/project")
332
+
333
+ // Scan project
334
+ const result: ScanResult = await scan("/path/to/project")
335
+
336
+ // Export for git
337
+ exportJSONL(store, ".agentmind/context.jsonl")
338
+
339
+ // Import from remote
340
+ importJSONL(store, ".agentmind/context.jsonl")
341
+ ```
342
+
343
+ ---
344
+
345
+ ## Templates
346
+
347
+ Templates are pre-built context configurations for popular stacks.
348
+
349
+ ### Available Templates
350
+
351
+ | Template | Detect Pattern | Description |
352
+ |----------------|-------------------------|------------------------------------------|
353
+ | `nextjs` | `next.config.*` | Next.js app router, server components |
354
+ | `sst` | `sst.config.*` | SST serverless stack |
355
+ | `react-native` | `app.json` + RN deps | React Native mobile app |
356
+ | `python` | `requirements.txt` | Python project patterns |
357
+ | `go` | `go.mod` | Go module conventions |
358
+ | `rust` | `Cargo.toml` | Rust project structure |
359
+
360
+ ### Usage
361
+
362
+ ```bash
363
+ # List all templates
364
+ agentmind template list
365
+
366
+ # Auto-detect and apply matching templates
367
+ agentmind template apply --all
368
+
369
+ # Apply a specific template
370
+ agentmind template apply nextjs
371
+ ```
372
+
373
+ ---
374
+
375
+ ## Data Files & Git Integration
376
+
377
+ ```
378
+ .agentmind/
379
+ ├── context.db # SQLite database (local, do not commit)
380
+ ├── context.jsonl # Git-friendly export (commit to repo)
381
+ ├── config.json # Hook and runtime config
382
+ └── hooks/ # Generated hook scripts
383
+ ```
384
+
385
+ ### Git Workflow
386
+
387
+ ```bash
388
+ # Export DB → JSONL (before committing)
389
+ agentmind push -m "Update context"
390
+
391
+ # Import JSONL → DB (after pulling)
392
+ agentmind pull
393
+ ```
394
+
395
+ ### .gitignore
396
+
397
+ ```gitignore
398
+ # Do not commit (local state)
399
+ .agentmind/context.db
400
+ .agentmind/config.json
401
+
402
+ # Commit to repo (shared context)
403
+ # .agentmind/context.jsonl
404
+ ```
405
+
406
+ ---
407
+
408
+ ## Development
409
+
410
+ ```bash
411
+ # Build
412
+ npm run build
413
+
414
+ # Type check
415
+ npm run typecheck
416
+
417
+ # Run tests
418
+ npm test
419
+
420
+ # Smoke test
421
+ npm run smoke
422
+
423
+ # Pack check
424
+ npm run pack:check
425
+
426
+ # Full release check
427
+ npm run release:check
428
+ ```
429
+
430
+ ### Scripts
431
+
432
+ | Script | Description |
433
+ |-------------------|--------------------------------------------|
434
+ | `build` | Compile TypeScript → dist/ |
435
+ | `typecheck` | Type check without emit |
436
+ | `test` | Run tests with Node test runner |
437
+ | `smoke` | Verify CLI --help works |
438
+ | `pack:check` | npm pack --dry-run |
439
+ | `release:check` | Full check before npm publish |
440
+
441
+ ---
442
+
443
+ ## Contributing
444
+
445
+ 1. Fork the repository
446
+ 2. Create a feature branch: `git checkout -b feature/amazing-feature`
447
+ 3. Commit your changes: `git commit -m "Add amazing feature"`
448
+ 4. Push the branch: `git push origin feature/amazing-feature`
449
+ 5. Open a Pull Request
450
+
451
+ ### Code Style
452
+
453
+ - TypeScript strict mode
454
+ - ES modules (`type: module`)
455
+ - Node 22+ features are fine
456
+ - Tests required for new features
457
+
458
+ ---
459
+
460
+ ## License
461
+
462
+ [MIT](LICENSE) — Free for personal and commercial use.
package/RELEASING.md ADDED
@@ -0,0 +1,42 @@
1
+ # Releasing agentmind
2
+
3
+ ## Preconditions
4
+
5
+ - Node 22 or newer is installed.
6
+ - Native install for `better-sqlite3` succeeds on the release machine.
7
+ - You are authenticated with npm if publishing.
8
+
9
+ ## Release check
10
+
11
+ ```bash
12
+ npm install
13
+ npm run release:check
14
+ ```
15
+
16
+ This runs:
17
+
18
+ - typecheck
19
+ - tests
20
+ - CLI smoke check
21
+ - `npm pack --dry-run`
22
+
23
+ ## Version and publish
24
+
25
+ 1. Update `package.json` version.
26
+ 2. Add release notes to `CHANGELOG.md`.
27
+ 3. Run `npm run release:check`.
28
+ 4. Inspect `npm pack --dry-run` output and confirm only distributable files are included.
29
+ 5. Publish:
30
+
31
+ ```bash
32
+ npm publish
33
+ ```
34
+
35
+ ## Post-release verification
36
+
37
+ Verify a clean install works:
38
+
39
+ ```bash
40
+ npm install -g agentmind
41
+ agentmind --help
42
+ ```
@@ -0,0 +1,2 @@
1
+ export declare const cursor: import("./types.js").Adapter;
2
+ //# sourceMappingURL=cursor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/adapters/cursor.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,8BAyCjB,CAAA"}
@@ -0,0 +1,39 @@
1
+ import { createSyncAdapter } from "./types.js";
2
+ export const cursor = createSyncAdapter("cursor", ".cursorrules", (ctx) => {
3
+ const lines = [];
4
+ lines.push("# agentmind context (auto-generated — do not edit manually)");
5
+ lines.push("# Run `agentmind sync --tool cursor` to update");
6
+ lines.push("");
7
+ const withRules = ctx.entries.filter(e => e.rules.length > 0);
8
+ if (withRules.length > 0) {
9
+ lines.push("## Rules");
10
+ lines.push("");
11
+ for (const entry of withRules) {
12
+ for (const rule of entry.rules) {
13
+ const source = rule.path ? `${rule.path}: ` : "";
14
+ lines.push(`- ${source}${rule.description}`);
15
+ }
16
+ }
17
+ lines.push("");
18
+ }
19
+ const annotations = ctx.entries.flatMap(e => e.annotations);
20
+ if (annotations.length > 0) {
21
+ lines.push("## Annotations");
22
+ lines.push("");
23
+ for (const ann of annotations) {
24
+ const loc = ann.line ? `:${ann.line}` : "";
25
+ lines.push(`- ${ann.path}${loc}: ${ann.text}`);
26
+ }
27
+ lines.push("");
28
+ }
29
+ if (ctx.patterns.length > 0) {
30
+ lines.push("## Non-obvious patterns");
31
+ lines.push("");
32
+ for (const p of ctx.patterns) {
33
+ lines.push(`- ${p.path}: ${p.reason}`);
34
+ }
35
+ lines.push("");
36
+ }
37
+ return lines.join("\n");
38
+ });
39
+ //# sourceMappingURL=cursor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/adapters/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,CAAC,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,CAAC,GAAG,EAAE,EAAE;IACxE,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAA;IACzE,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAA;IAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAEd,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC7D,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;YAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;gBAChD,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;YAC9C,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IAED,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IAC3D,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;YAC1C,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;QAChD,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAA;QACrC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACd,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;QACxC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC,CAAC,CAAA"}
@@ -0,0 +1,9 @@
1
+ export { cursor } from "./cursor.js";
2
+ export { windsurf } from "./windsurf.js";
3
+ export type { Adapter, AdapterContext, AdapterOutput } from "./types.js";
4
+ export { SYNC_MARKER_START, SYNC_MARKER_END } from "./types.js";
5
+ import type { Adapter } from "./types.js";
6
+ export declare const adapters: Record<string, Adapter>;
7
+ export declare function getAdapter(name: string): Adapter | undefined;
8
+ export declare function getAdapterNames(): string[];
9
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAI/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEzC,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAG5C,CAAA;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAE5D;AAED,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C"}
@@ -0,0 +1,16 @@
1
+ export { cursor } from "./cursor.js";
2
+ export { windsurf } from "./windsurf.js";
3
+ export { SYNC_MARKER_START, SYNC_MARKER_END } from "./types.js";
4
+ import { cursor } from "./cursor.js";
5
+ import { windsurf } from "./windsurf.js";
6
+ export const adapters = {
7
+ cursor,
8
+ windsurf,
9
+ };
10
+ export function getAdapter(name) {
11
+ return adapters[name.toLowerCase()];
12
+ }
13
+ export function getAdapterNames() {
14
+ return Object.keys(adapters);
15
+ }
16
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC,MAAM,CAAC,MAAM,QAAQ,GAA4B;IAC/C,MAAM;IACN,QAAQ;CACT,CAAA;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;AACrC,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;AAC9B,CAAC"}
@@ -0,0 +1,24 @@
1
+ import type { ContextEntry, NonInferablePattern } from "../types/index.js";
2
+ import type { ContextStore } from "../store/schema.js";
3
+ export interface AdapterOutput {
4
+ filename: string;
5
+ content: string;
6
+ }
7
+ export interface AdapterContext {
8
+ entries: ContextEntry[];
9
+ patterns: NonInferablePattern[];
10
+ projectName?: string;
11
+ }
12
+ export interface Adapter {
13
+ name: string;
14
+ filename: string;
15
+ render(ctx: AdapterContext): string;
16
+ sync(projectRoot: string, store: ContextStore): void;
17
+ unsync(projectRoot: string): void;
18
+ isInstalled(projectRoot: string): boolean;
19
+ }
20
+ export declare const SYNC_MARKER_START = "<!-- agentmind:sync -->";
21
+ export declare const SYNC_MARKER_END = "<!-- agentmind:endsync -->";
22
+ export declare function buildContext(store: ContextStore): AdapterContext;
23
+ export declare function createSyncAdapter(name: string, filename: string, render: Adapter["render"]): Adapter;
24
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,QAAQ,EAAE,mBAAmB,EAAE,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAAA;IACnC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;IACpD,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAA;CAC1C;AAED,eAAO,MAAM,iBAAiB,4BAA4B,CAAA;AAC1D,eAAO,MAAM,eAAe,+BAA+B,CAAA;AAE3D,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CAehE;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,GACxB,OAAO,CAsDT"}