brain-memory 0.3.0 → 0.5.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 (62) hide show
  1. package/CHANGELOG.md +153 -0
  2. package/README.md +4 -0
  3. package/SECURITY.md +61 -9
  4. package/bin/brain.js +24 -3
  5. package/bin/cloud-sync.js +49 -6
  6. package/bin/install.js +72 -14
  7. package/bin/memorize.js +50 -6
  8. package/bin/port.js +174 -0
  9. package/bin/recall.js +16 -6
  10. package/bin/reinforce.js +5 -0
  11. package/bin/session-start.js +30 -4
  12. package/bin/verify.js +42 -4
  13. package/commands/brain/memorize.md +8 -0
  14. package/commands/brain/sync.md +23 -0
  15. package/commands/brain/verify.md +10 -2
  16. package/hooks/citation-check.mjs +94 -0
  17. package/hooks/hooks.json +11 -0
  18. package/hooks/lib.mjs +6 -0
  19. package/hooks/prompt-recall.mjs +24 -3
  20. package/hooks/session-start.mjs +4 -2
  21. package/integrations/README.md +4 -0
  22. package/integrations/agentskills/brain-memory/SKILL.md +9 -5
  23. package/package.json +10 -5
  24. package/prompts/antigravity.md +4 -2
  25. package/prompts/claude.md +4 -2
  26. package/prompts/copilot.md +4 -2
  27. package/prompts/kilo.md +4 -2
  28. package/prompts/openai.md +4 -2
  29. package/prompts/opencode.md +4 -2
  30. package/src/adapters.js +240 -0
  31. package/src/anomaly.js +41 -1
  32. package/src/cloud-sync.js +123 -11
  33. package/src/content-lint.js +55 -2
  34. package/src/export-import.js +1 -1
  35. package/src/git-sync.js +1 -1
  36. package/src/index-manager.js +9 -5
  37. package/src/installer.js +35 -1
  38. package/src/pinning.js +20 -1
  39. package/src/provenance.js +34 -0
  40. package/src/quarantine.js +82 -5
  41. package/src/receipt.js +9 -4
  42. package/src/surfaced.js +188 -0
  43. package/store/CONTRACT.md +244 -0
  44. package/store/Dockerfile +24 -0
  45. package/store/README.md +43 -0
  46. package/store/SELF-HOSTING.md +200 -0
  47. package/store/bin/brain-store.js +189 -0
  48. package/store/conformance/conformance.test.js +341 -0
  49. package/store/conformance/helpers.js +199 -0
  50. package/store/deploy/Caddyfile +14 -0
  51. package/store/deploy/connector.Dockerfile +38 -0
  52. package/store/deploy/docker-compose.yml +83 -0
  53. package/store/deploy/env.example +19 -0
  54. package/store/lib/auth.js +174 -0
  55. package/store/lib/oidc.js +206 -0
  56. package/store/lib/storage.js +333 -0
  57. package/store/lib/tar.js +150 -0
  58. package/store/openapi.yaml +318 -0
  59. package/store/server.js +465 -0
  60. package/store/test/mock-issuer.js +104 -0
  61. package/store/test/oidc.test.js +222 -0
  62. package/store/test/store.test.js +445 -0
@@ -0,0 +1,318 @@
1
+ openapi: 3.1.0
2
+ info:
3
+ title: Brain store contract
4
+ version: "1.1"
5
+ summary: The HTTP interface between a Brain client and a remote store.
6
+ description: >
7
+ Machine-readable companion to CONTRACT.md. Where the two disagree,
8
+ CONTRACT.md is correct.
9
+ license:
10
+ name: MIT
11
+ identifier: MIT
12
+
13
+ servers:
14
+ - url: https://store.example
15
+ description: Your store
16
+
17
+ security:
18
+ - bearer: []
19
+
20
+ paths:
21
+ /health:
22
+ get:
23
+ summary: Liveness and contract discovery
24
+ security: []
25
+ responses:
26
+ "200":
27
+ description: The store is up.
28
+ content:
29
+ application/json:
30
+ schema: { $ref: "#/components/schemas/Health" }
31
+
32
+ /auth/me:
33
+ get:
34
+ summary: Describe the caller
35
+ responses:
36
+ "200":
37
+ description: The authenticated user.
38
+ content:
39
+ application/json:
40
+ schema:
41
+ type: object
42
+ required: [user]
43
+ properties:
44
+ user: { $ref: "#/components/schemas/User" }
45
+ storage_used: { type: integer, description: Bytes stored for this user. }
46
+ "401": { $ref: "#/components/responses/Unauthorized" }
47
+
48
+ /api/brains:
49
+ get:
50
+ summary: List the caller's brains, oldest first
51
+ responses:
52
+ "200":
53
+ description: Brain records.
54
+ content:
55
+ application/json:
56
+ schema:
57
+ type: array
58
+ items: { $ref: "#/components/schemas/Brain" }
59
+ "401": { $ref: "#/components/responses/Unauthorized" }
60
+ post:
61
+ summary: Create a brain
62
+ requestBody:
63
+ required: false
64
+ content:
65
+ application/json:
66
+ schema:
67
+ type: object
68
+ properties:
69
+ name: { type: string, default: default }
70
+ responses:
71
+ "201":
72
+ description: The new brain.
73
+ content:
74
+ application/json:
75
+ schema: { $ref: "#/components/schemas/Brain" }
76
+ "401": { $ref: "#/components/responses/Unauthorized" }
77
+ "403": { $ref: "#/components/responses/Error" }
78
+
79
+ /api/brains/{id}:
80
+ parameters:
81
+ - $ref: "#/components/parameters/BrainId"
82
+ get:
83
+ summary: Fetch one brain record
84
+ responses:
85
+ "200":
86
+ description: The brain.
87
+ content:
88
+ application/json:
89
+ schema: { $ref: "#/components/schemas/Brain" }
90
+ "400": { $ref: "#/components/responses/Error" }
91
+ "401": { $ref: "#/components/responses/Unauthorized" }
92
+ "404": { $ref: "#/components/responses/Error" }
93
+ delete:
94
+ summary: Delete a brain, its archive and its snapshots
95
+ responses:
96
+ "204": { description: Deleted. }
97
+ "401": { $ref: "#/components/responses/Unauthorized" }
98
+ "404": { $ref: "#/components/responses/Error" }
99
+
100
+ /api/brains/{id}/sync:
101
+ parameters:
102
+ - $ref: "#/components/parameters/BrainId"
103
+ get:
104
+ summary: Download the archive, or a snapshot
105
+ parameters:
106
+ - name: version
107
+ in: query
108
+ required: false
109
+ schema: { type: string }
110
+ description: A snapshot name from the versions listing.
111
+ - name: If-None-Match
112
+ in: header
113
+ required: false
114
+ schema: { type: string }
115
+ description: (1.1) Checksum the client already holds, as an entity tag.
116
+ responses:
117
+ "200":
118
+ description: The archive.
119
+ headers:
120
+ X-Checksum: { schema: { type: string }, description: SHA-256 of the archive. }
121
+ ETag: { schema: { type: string }, description: (1.1) The same checksum, quoted. }
122
+ content:
123
+ application/gzip:
124
+ schema: { type: string, format: binary }
125
+ "304": { description: (1.1) The client is current. }
126
+ "401": { $ref: "#/components/responses/Unauthorized" }
127
+ "404": { $ref: "#/components/responses/Error" }
128
+ put:
129
+ summary: Upload the archive
130
+ parameters:
131
+ - name: force
132
+ in: query
133
+ required: false
134
+ schema: { type: boolean }
135
+ description: Override the empty-push guard. Does not override If-Match.
136
+ - name: If-Match
137
+ in: header
138
+ required: false
139
+ schema: { type: string }
140
+ description: (1.1) Proceed only if the stored archive has this checksum.
141
+ - name: If-None-Match
142
+ in: header
143
+ required: false
144
+ schema: { type: string, enum: ["*"] }
145
+ description: (1.1) Proceed only if no archive is stored yet.
146
+ requestBody:
147
+ required: true
148
+ content:
149
+ multipart/form-data:
150
+ schema:
151
+ type: object
152
+ required: [brain]
153
+ properties:
154
+ brain:
155
+ type: string
156
+ format: binary
157
+ description: A gzip-compressed tar archive of the brain directory.
158
+ responses:
159
+ "200":
160
+ description: Stored.
161
+ headers:
162
+ ETag: { schema: { type: string }, description: (1.1) Checksum of the stored archive. }
163
+ content:
164
+ application/json:
165
+ schema: { $ref: "#/components/schemas/SyncResult" }
166
+ "400": { $ref: "#/components/responses/Error" }
167
+ "401": { $ref: "#/components/responses/Unauthorized" }
168
+ "404": { $ref: "#/components/responses/Error" }
169
+ "409":
170
+ description: The empty-push guard refused the upload.
171
+ content:
172
+ application/json:
173
+ schema: { $ref: "#/components/schemas/Error" }
174
+ "412": { $ref: "#/components/responses/PreconditionFailed" }
175
+ "413": { $ref: "#/components/responses/Error" }
176
+ "429": { $ref: "#/components/responses/RateLimited" }
177
+
178
+ /api/brains/{id}/versions:
179
+ parameters:
180
+ - $ref: "#/components/parameters/BrainId"
181
+ get:
182
+ summary: List snapshots, newest first
183
+ responses:
184
+ "200":
185
+ description: Snapshots.
186
+ content:
187
+ application/json:
188
+ schema:
189
+ type: object
190
+ required: [versions, total]
191
+ properties:
192
+ total: { type: integer }
193
+ versions:
194
+ type: array
195
+ items:
196
+ type: object
197
+ required: [version]
198
+ properties:
199
+ version: { type: string, description: Opaque snapshot name. }
200
+ date: { type: string, format: date-time }
201
+ "401": { $ref: "#/components/responses/Unauthorized" }
202
+ "404": { $ref: "#/components/responses/Error" }
203
+
204
+ /api/brains/{id}/versions/{version}/restore:
205
+ parameters:
206
+ - $ref: "#/components/parameters/BrainId"
207
+ - name: version
208
+ in: path
209
+ required: true
210
+ schema: { type: string }
211
+ post:
212
+ summary: Make a snapshot the live archive
213
+ parameters:
214
+ - name: If-Match
215
+ in: header
216
+ required: false
217
+ schema: { type: string }
218
+ description: (1.1) As for upload.
219
+ responses:
220
+ "200":
221
+ description: Restored. The previous live archive was kept as a snapshot.
222
+ content:
223
+ application/json:
224
+ schema:
225
+ type: object
226
+ required: [restored_version]
227
+ properties:
228
+ restored_version: { type: string }
229
+ checksum: { type: string }
230
+ "401": { $ref: "#/components/responses/Unauthorized" }
231
+ "404": { $ref: "#/components/responses/Error" }
232
+ "412": { $ref: "#/components/responses/PreconditionFailed" }
233
+
234
+ components:
235
+ securitySchemes:
236
+ bearer:
237
+ type: http
238
+ scheme: bearer
239
+
240
+ parameters:
241
+ BrainId:
242
+ name: id
243
+ in: path
244
+ required: true
245
+ schema: { type: string, format: uuid }
246
+
247
+ schemas:
248
+ Health:
249
+ type: object
250
+ required: [status]
251
+ properties:
252
+ status: { type: string, enum: [ok, degraded] }
253
+ contract: { type: string, description: Highest contract version implemented. Absent means "1". }
254
+ capabilities:
255
+ type: array
256
+ items: { type: string, examples: [static-token, device-code, conditional-sync] }
257
+ additionalProperties: true
258
+ User:
259
+ type: object
260
+ required: [id, email]
261
+ properties:
262
+ id: { type: string }
263
+ email: { type: string }
264
+ additionalProperties: true
265
+ Brain:
266
+ type: object
267
+ required: [id, name, size_bytes, file_count, checksum, last_synced_at, created_at]
268
+ properties:
269
+ id: { type: string, format: uuid }
270
+ name: { type: string }
271
+ size_bytes: { type: integer }
272
+ file_count: { type: integer, description: Regular-file entries in the archive. }
273
+ checksum: { type: [string, "null"], description: Lowercase hex SHA-256 of the archive. }
274
+ last_synced_at: { type: [string, "null"], format: date-time }
275
+ created_at: { type: string, format: date-time }
276
+ additionalProperties: true
277
+ SyncResult:
278
+ type: object
279
+ required: [size_bytes, file_count, checksum]
280
+ properties:
281
+ size_bytes: { type: integer }
282
+ file_count: { type: integer }
283
+ checksum: { type: string }
284
+ Error:
285
+ type: object
286
+ required: [error]
287
+ properties:
288
+ error: { type: string, description: Human-readable. Do not parse. }
289
+ additionalProperties: true
290
+
291
+ responses:
292
+ Error:
293
+ description: The request failed.
294
+ content:
295
+ application/json:
296
+ schema: { $ref: "#/components/schemas/Error" }
297
+ Unauthorized:
298
+ description: Missing, unknown or expired token.
299
+ content:
300
+ application/json:
301
+ schema: { $ref: "#/components/schemas/Error" }
302
+ RateLimited:
303
+ description: Too many requests.
304
+ headers:
305
+ Retry-After: { schema: { type: integer }, description: Seconds to wait. }
306
+ content:
307
+ application/json:
308
+ schema: { $ref: "#/components/schemas/Error" }
309
+ PreconditionFailed:
310
+ description: (1.1) The stored archive is not the one the client named. Nothing changed.
311
+ content:
312
+ application/json:
313
+ schema:
314
+ type: object
315
+ required: [error]
316
+ properties:
317
+ error: { type: string }
318
+ current_checksum: { type: [string, "null"] }