brain-memory 0.2.0 → 0.4.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 (63) hide show
  1. package/CHANGELOG.md +193 -0
  2. package/README.md +27 -3
  3. package/SECURITY.md +44 -3
  4. package/bin/audit.js +18 -1
  5. package/bin/brain +4 -0
  6. package/bin/cloud-sync.js +49 -6
  7. package/bin/import.js +1 -1
  8. package/bin/install.js +10 -0
  9. package/bin/memorize.js +53 -8
  10. package/bin/recall.js +32 -13
  11. package/bin/reinforce.js +34 -1
  12. package/bin/session-start.js +17 -4
  13. package/bin/skill.js +8 -2
  14. package/commands/brain/import.md +1 -1
  15. package/commands/brain/memorize.md +25 -4
  16. package/commands/brain/skills.md +29 -0
  17. package/commands/brain/sync.md +23 -0
  18. package/hooks/hooks.json +39 -0
  19. package/hooks/lib.mjs +117 -0
  20. package/hooks/prompt-recall.mjs +123 -0
  21. package/hooks/session-end.md +54 -0
  22. package/hooks/session-end.mjs +63 -0
  23. package/hooks/session-start.md +58 -0
  24. package/hooks/session-start.mjs +82 -0
  25. package/integrations/agentskills/brain-memory/SKILL.md +5 -0
  26. package/package.json +10 -4
  27. package/prompts/antigravity.md +4 -1
  28. package/prompts/claude.md +4 -1
  29. package/prompts/copilot.md +4 -1
  30. package/prompts/kilo.md +4 -1
  31. package/prompts/openai.md +4 -1
  32. package/prompts/opencode.md +4 -1
  33. package/src/anomaly.js +7 -0
  34. package/src/cloud-sync.js +121 -9
  35. package/src/contradiction.js +106 -0
  36. package/src/harvest.js +174 -2
  37. package/src/index-manager.js +8 -0
  38. package/src/installer.js +126 -3
  39. package/src/integrity.js +155 -0
  40. package/src/receipt.js +8 -4
  41. package/src/sensitivity.js +134 -0
  42. package/src/skill-verify.js +191 -0
  43. package/src/skills.js +63 -0
  44. package/store/CONTRACT.md +244 -0
  45. package/store/Dockerfile +24 -0
  46. package/store/README.md +43 -0
  47. package/store/SELF-HOSTING.md +200 -0
  48. package/store/bin/brain-store.js +189 -0
  49. package/store/conformance/conformance.test.js +341 -0
  50. package/store/conformance/helpers.js +145 -0
  51. package/store/deploy/Caddyfile +14 -0
  52. package/store/deploy/connector.Dockerfile +38 -0
  53. package/store/deploy/docker-compose.yml +83 -0
  54. package/store/deploy/env.example +19 -0
  55. package/store/lib/auth.js +174 -0
  56. package/store/lib/oidc.js +206 -0
  57. package/store/lib/storage.js +333 -0
  58. package/store/lib/tar.js +150 -0
  59. package/store/openapi.yaml +318 -0
  60. package/store/server.js +465 -0
  61. package/store/test/mock-issuer.js +104 -0
  62. package/store/test/oidc.test.js +217 -0
  63. package/store/test/store.test.js +445 -0
@@ -0,0 +1,341 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Store contract conformance suite.
5
+ *
6
+ * Black-box: it speaks HTTP to a store and knows nothing about how the store is
7
+ * built. Point it at any implementation:
8
+ *
9
+ * STORE_URL=https://store.example STORE_TOKEN=... node --test store/conformance/
10
+ *
11
+ * STORE_TOKEN_2 a second user's token; enables the tenant-isolation tests
12
+ * STORE_BRAIN_ID use this (disposable!) brain instead of creating one, for
13
+ * accounts that cannot create another brain
14
+ * STORE_CONTRACT "1" to check only contract version 1; default "1.1"
15
+ *
16
+ * With no STORE_URL, the suite starts the reference server on a temporary
17
+ * directory and tests that.
18
+ *
19
+ * The suite overwrites the brain it works on. Never point it at a brain you care
20
+ * about.
21
+ */
22
+
23
+ const { describe, it, before, after } = require('node:test');
24
+ const assert = require('node:assert/strict');
25
+ const { sampleArchive, makeArchive, sha256, client, startReferenceStore } = require('./helpers');
26
+
27
+ const LEVEL_1_1 = (process.env.STORE_CONTRACT || '1.1') !== '1';
28
+ const UNKNOWN_BRAIN = '00000000-0000-4000-8000-000000000000';
29
+
30
+ describe('store contract', () => {
31
+ let reference = null;
32
+ let api;
33
+ let api2 = null;
34
+ let anonymous;
35
+ let brainId;
36
+ let createdBrain = false;
37
+
38
+ let first; // archives uploaded along the way
39
+ let second;
40
+
41
+ before(async () => {
42
+ let url = process.env.STORE_URL;
43
+ let token = process.env.STORE_TOKEN;
44
+ let token2 = process.env.STORE_TOKEN_2;
45
+ if (!url) {
46
+ reference = await startReferenceStore();
47
+ ({ url, token, token2 } = reference);
48
+ }
49
+ assert.ok(token, 'STORE_TOKEN is required when STORE_URL is set');
50
+ api = client(url, token);
51
+ anonymous = client(url, null);
52
+ if (token2) api2 = client(url, token2);
53
+ });
54
+
55
+ after(async () => {
56
+ if (createdBrain && brainId) await api.json('DELETE', `/api/brains/${brainId}`);
57
+ if (reference) await reference.close();
58
+ });
59
+
60
+ // -- version 1 -------------------------------------------------------------
61
+
62
+ describe('health and authentication', () => {
63
+ it('GET /health answers without credentials', async () => {
64
+ const res = await anonymous.json('GET', '/health');
65
+ assert.equal(res.status, 200);
66
+ assert.equal(res.data.status, 'ok');
67
+ });
68
+
69
+ it('rejects requests without a token', async () => {
70
+ assert.equal((await anonymous.json('GET', '/api/brains')).status, 401);
71
+ assert.equal((await anonymous.json('GET', '/auth/me')).status, 401);
72
+ });
73
+
74
+ it('rejects an unknown token', async () => {
75
+ const stranger = client(process.env.STORE_URL || reference.url, 'bst_not-a-real-token');
76
+ assert.equal((await stranger.json('GET', '/api/brains')).status, 401);
77
+ });
78
+
79
+ it('GET /auth/me describes the caller', async () => {
80
+ const res = await api.json('GET', '/auth/me');
81
+ assert.equal(res.status, 200);
82
+ assert.equal(typeof res.data.user, 'object');
83
+ assert.equal(typeof res.data.user.id, 'string');
84
+ assert.equal(typeof res.data.user.email, 'string');
85
+ });
86
+
87
+ it('errors are JSON objects with an "error" string', async () => {
88
+ const res = await anonymous.json('GET', '/api/brains');
89
+ assert.equal(typeof res.data.error, 'string');
90
+ });
91
+ });
92
+
93
+ describe('brain records', () => {
94
+ it('creates a brain, or adopts STORE_BRAIN_ID', async () => {
95
+ if (process.env.STORE_BRAIN_ID) {
96
+ brainId = process.env.STORE_BRAIN_ID;
97
+ return;
98
+ }
99
+ const name = 'conformance-' + Date.now();
100
+ const res = await api.json('POST', '/api/brains', { name });
101
+ assert.equal(res.status, 201, `could not create a brain (${res.status}); set STORE_BRAIN_ID to a disposable brain`);
102
+ assert.match(res.data.id, /^[0-9a-f-]{36}$/i);
103
+ assert.equal(res.data.name, name);
104
+ brainId = res.data.id;
105
+ createdBrain = true;
106
+ });
107
+
108
+ it('lists the brain as a bare JSON array', async () => {
109
+ const res = await api.json('GET', '/api/brains');
110
+ assert.equal(res.status, 200);
111
+ assert.ok(Array.isArray(res.data));
112
+ assert.ok(res.data.some((b) => b.id === brainId));
113
+ });
114
+
115
+ it('returns the brain record with the documented fields', async () => {
116
+ const res = await api.json('GET', `/api/brains/${brainId}`);
117
+ assert.equal(res.status, 200);
118
+ for (const field of ['id', 'name', 'size_bytes', 'file_count', 'last_synced_at', 'checksum', 'created_at']) {
119
+ assert.ok(field in res.data, `missing field ${field}`);
120
+ }
121
+ });
122
+
123
+ it('answers 404 for an unknown brain and 400 or 404 for a malformed ID', async () => {
124
+ assert.equal((await api.json('GET', `/api/brains/${UNKNOWN_BRAIN}`)).status, 404);
125
+ assert.ok([400, 404].includes((await api.json('GET', '/api/brains/not-a-uuid')).status));
126
+ });
127
+ });
128
+
129
+ describe('sync', () => {
130
+ it('downloading a brain that was never uploaded is 404', { skip: Boolean(process.env.STORE_BRAIN_ID) }, async () => {
131
+ assert.equal((await api.download(brainId)).status, 404);
132
+ });
133
+
134
+ it('accepts an upload and reports size, file count and SHA-256 of the archive', async () => {
135
+ first = sampleArchive(6, 'first'); // 6 memories + index.json
136
+ const res = await api.upload(brainId, first);
137
+ assert.equal(res.status, 200);
138
+ assert.equal(res.data.size_bytes, first.length);
139
+ assert.equal(res.data.file_count, 7);
140
+ assert.equal(res.data.checksum, sha256(first));
141
+ });
142
+
143
+ it('returns exactly the bytes that were uploaded, with X-Checksum', async () => {
144
+ const res = await api.download(brainId);
145
+ assert.equal(res.status, 200);
146
+ assert.ok(res.body.equals(first), 'downloaded archive differs from the upload');
147
+ assert.equal(res.headers.get('x-checksum'), sha256(first));
148
+ });
149
+
150
+ it('reflects the upload in the brain record', async () => {
151
+ const res = await api.json('GET', `/api/brains/${brainId}`);
152
+ assert.equal(res.data.size_bytes, first.length);
153
+ assert.equal(res.data.file_count, 7);
154
+ assert.equal(res.data.checksum, sha256(first));
155
+ assert.ok(!Number.isNaN(Date.parse(res.data.last_synced_at)));
156
+ });
157
+
158
+ it('rejects a request with no "brain" file field', async () => {
159
+ const res = await api.upload(brainId, first, { field: 'something-else' });
160
+ assert.equal(res.status, 400);
161
+ });
162
+ });
163
+
164
+ describe('snapshots', () => {
165
+ it('keeps the previous archive as a snapshot when a new one is uploaded', async () => {
166
+ second = sampleArchive(6, 'second');
167
+ assert.equal((await api.upload(brainId, second)).status, 200);
168
+
169
+ const res = await api.json('GET', `/api/brains/${brainId}/versions`);
170
+ assert.equal(res.status, 200);
171
+ assert.ok(Array.isArray(res.data.versions));
172
+ assert.ok(res.data.versions.length >= 1);
173
+ assert.equal(res.data.total, res.data.versions.length);
174
+ assert.equal(typeof res.data.versions[0].version, 'string');
175
+ });
176
+
177
+ it('lists snapshots newest first', async () => {
178
+ const { data } = await api.json('GET', `/api/brains/${brainId}/versions`);
179
+ const names = data.versions.map((v) => v.version);
180
+ assert.deepEqual(names, [...names].sort().reverse());
181
+ });
182
+
183
+ it('serves a snapshot through ?version=', async () => {
184
+ const { data } = await api.json('GET', `/api/brains/${brainId}/versions`);
185
+ const res = await api.download(brainId, { query: `?version=${encodeURIComponent(data.versions[0].version)}` });
186
+ assert.equal(res.status, 200);
187
+ assert.ok(res.body.equals(first), 'newest snapshot should be the archive that was just replaced');
188
+ });
189
+
190
+ it('refuses version names that try to leave the snapshot directory', async () => {
191
+ for (const name of ['../meta.json', '..%2F..%2Fusers.json', 'nope.tar.gz']) {
192
+ const res = await api.download(brainId, { query: `?version=${name}` });
193
+ assert.ok([400, 404].includes(res.status), `${name} -> ${res.status}`);
194
+ }
195
+ });
196
+
197
+ it('restores a snapshot as the live archive', async () => {
198
+ const { data } = await api.json('GET', `/api/brains/${brainId}/versions`);
199
+ const version = data.versions[0].version;
200
+ const res = await api.json('POST', `/api/brains/${brainId}/versions/${encodeURIComponent(version)}/restore`);
201
+ assert.equal(res.status, 200);
202
+ assert.equal(res.data.restored_version, version);
203
+ assert.ok((await api.download(brainId)).body.equals(first));
204
+ });
205
+
206
+ it('answers 404 when restoring a snapshot that does not exist', async () => {
207
+ const res = await api.json('POST', `/api/brains/${brainId}/versions/19990101T000000.000000000.tar.gz/restore`);
208
+ assert.equal(res.status, 404);
209
+ });
210
+ });
211
+
212
+ describe('the empty-push guard', () => {
213
+ it('refuses an empty archive over a brain that has memories', async () => {
214
+ const res = await api.upload(brainId, makeArchive({}));
215
+ assert.equal(res.status, 409);
216
+ assert.ok((await api.download(brainId)).body.equals(first), 'a refused push must change nothing');
217
+ });
218
+
219
+ it('accepts it with ?force=true', async () => {
220
+ const empty = makeArchive({});
221
+ const res = await api.upload(brainId, empty, { query: '?force=true' });
222
+ assert.equal(res.status, 200);
223
+ assert.equal(res.data.file_count, 0);
224
+ // Put real content back for the tests that follow.
225
+ assert.equal((await api.upload(brainId, first)).status, 200);
226
+ });
227
+ });
228
+
229
+ describe('tenant isolation', () => {
230
+ it('hides one user\'s brain from another', async (t) => {
231
+ if (!api2) return t.skip('no second token (STORE_TOKEN_2)');
232
+ assert.equal((await api2.json('GET', `/api/brains/${brainId}`)).status, 404);
233
+ assert.equal((await api2.download(brainId)).status, 404);
234
+ assert.equal((await api2.upload(brainId, sampleArchive(1, 'intruder'))).status, 404);
235
+ assert.equal((await api2.json('GET', `/api/brains/${brainId}/versions`)).status, 404);
236
+ const list = await api2.json('GET', '/api/brains');
237
+ assert.ok(!list.data.some((b) => b.id === brainId));
238
+ assert.ok((await api.download(brainId)).body.equals(first), 'the owner\'s archive must be untouched');
239
+ });
240
+ });
241
+
242
+ // -- version 1.1: conditional sync -------------------------------------------
243
+
244
+ describe('conditional sync (contract 1.1)', { skip: !LEVEL_1_1 }, () => {
245
+ it('GET /health advertises contract 1.1 or later', async () => {
246
+ const { data } = await anonymous.json('GET', '/health');
247
+ assert.ok(parseFloat(data.contract) >= 1.1, `contract is ${data.contract}`);
248
+ });
249
+
250
+ it('sends the checksum as a strong ETag on download and upload', async () => {
251
+ const down = await api.download(brainId);
252
+ assert.equal(down.headers.get('etag'), `"${sha256(first)}"`);
253
+ const up = await api.upload(brainId, first);
254
+ assert.equal(up.headers.get('etag'), `"${sha256(first)}"`);
255
+ });
256
+
257
+ it('answers 304 to If-None-Match when the client is current', async () => {
258
+ const res = await api.download(brainId, { headers: { 'If-None-Match': `"${sha256(first)}"` } });
259
+ assert.equal(res.status, 304);
260
+ assert.equal(res.body.length, 0);
261
+ });
262
+
263
+ it('sends the archive when If-None-Match is stale', async () => {
264
+ const res = await api.download(brainId, { headers: { 'If-None-Match': `"${'0'.repeat(64)}"` } });
265
+ assert.equal(res.status, 200);
266
+ assert.ok(res.body.equals(first));
267
+ });
268
+
269
+ it('accepts an upload whose If-Match names the current archive', async () => {
270
+ second = sampleArchive(6, 'second-conditional');
271
+ const res = await api.upload(brainId, second, { headers: { 'If-Match': `"${sha256(first)}"` } });
272
+ assert.equal(res.status, 200);
273
+ assert.equal(res.data.checksum, sha256(second));
274
+ });
275
+
276
+ it('refuses a stale If-Match with 412, reports the current checksum, and changes nothing', async () => {
277
+ const late = sampleArchive(6, 'late-writer');
278
+ const res = await api.upload(brainId, late, { headers: { 'If-Match': `"${sha256(first)}"` } });
279
+ assert.equal(res.status, 412);
280
+ assert.equal(res.data.current_checksum, sha256(second));
281
+ assert.ok((await api.download(brainId)).body.equals(second), 'a refused push must change nothing');
282
+ const { data } = await api.json('GET', `/api/brains/${brainId}`);
283
+ assert.equal(data.checksum, sha256(second));
284
+ });
285
+
286
+ it('lets exactly one of two racing writers win', async () => {
287
+ const base = sha256(second);
288
+ const a = sampleArchive(6, 'racer-a');
289
+ const b = sampleArchive(6, 'racer-b');
290
+ const results = await Promise.all([
291
+ api.upload(brainId, a, { headers: { 'If-Match': `"${base}"` } }),
292
+ api.upload(brainId, b, { headers: { 'If-Match': `"${base}"` } }),
293
+ ]);
294
+ const statuses = results.map((r) => r.status).sort();
295
+ assert.deepEqual(statuses, [200, 412]);
296
+ const winner = results[0].status === 200 ? a : b;
297
+ assert.ok((await api.download(brainId)).body.equals(winner));
298
+ second = winner;
299
+ });
300
+
301
+ it('treats If-None-Match: * on upload as "only if nothing is stored yet"', async () => {
302
+ const res = await api.upload(brainId, sampleArchive(6, 'first-writer'), { headers: { 'If-None-Match': '*' } });
303
+ assert.equal(res.status, 412);
304
+ assert.ok((await api.download(brainId)).body.equals(second));
305
+ });
306
+
307
+ it('still accepts an unconditional upload (version 1 clients)', async () => {
308
+ const res = await api.upload(brainId, first);
309
+ assert.equal(res.status, 200);
310
+ });
311
+
312
+ it('rejects an upload that is not a gzip-compressed tar archive', async () => {
313
+ for (const junk of [Buffer.from('this is not an archive'), require('zlib').gzipSync(Buffer.from('gzip, but not tar'.repeat(64)))]) {
314
+ const res = await api.upload(brainId, junk);
315
+ assert.equal(res.status, 400);
316
+ }
317
+ assert.ok((await api.download(brainId)).body.equals(first), 'a rejected upload must change nothing');
318
+ });
319
+
320
+ it('honours If-Match on restore', async () => {
321
+ const { data } = await api.json('GET', `/api/brains/${brainId}/versions`);
322
+ const version = data.versions[0].version;
323
+ const res = await api.json('POST', `/api/brains/${brainId}/versions/${encodeURIComponent(version)}/restore`,
324
+ null, { 'If-Match': `"${'0'.repeat(64)}"` });
325
+ assert.equal(res.status, 412);
326
+ });
327
+ });
328
+
329
+ // -- last: removal -----------------------------------------------------------
330
+
331
+ describe('removal', () => {
332
+ it('deletes a brain, after which it is gone', async (t) => {
333
+ if (!createdBrain) return t.skip('working on STORE_BRAIN_ID; not deleting it');
334
+ const res = await api.json('DELETE', `/api/brains/${brainId}`);
335
+ assert.ok([200, 204].includes(res.status));
336
+ assert.equal((await api.json('GET', `/api/brains/${brainId}`)).status, 404);
337
+ assert.equal((await api.download(brainId)).status, 404);
338
+ createdBrain = false;
339
+ });
340
+ });
341
+ });
@@ -0,0 +1,145 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Helpers for the store conformance suite. Nothing here imports the reference
5
+ * server except startReferenceStore(), so the suite can be pointed at any
6
+ * implementation of the contract.
7
+ */
8
+
9
+ const crypto = require('crypto');
10
+ const fs = require('fs');
11
+ const os = require('os');
12
+ const path = require('path');
13
+ const zlib = require('zlib');
14
+
15
+ // -- a minimal ustar writer, so the suite needs no system `tar` ----------------
16
+
17
+ function tarHeader(name, size, typeflag) {
18
+ const header = Buffer.alloc(512);
19
+ header.write(name, 0, 100, 'utf8');
20
+ header.write('0000644\0', 100, 'latin1');
21
+ header.write('0000000\0', 108, 'latin1');
22
+ header.write('0000000\0', 116, 'latin1');
23
+ header.write(size.toString(8).padStart(11, '0') + '\0', 124, 'latin1');
24
+ header.write('00000000000\0', 136, 'latin1');
25
+ header.fill(0x20, 148, 156);
26
+ header.write(typeflag, 156, 'latin1');
27
+ header.write('ustar\0', 257, 'latin1');
28
+ header.write('00', 263, 'latin1');
29
+ let sum = 0;
30
+ for (let i = 0; i < 512; i++) sum += header[i];
31
+ header.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'latin1');
32
+ return header;
33
+ }
34
+
35
+ /**
36
+ * Build a gzip-compressed tar archive.
37
+ * @param {Object<string,string>} files path -> content
38
+ */
39
+ function makeArchive(files) {
40
+ const blocks = [tarHeader('./', 0, '5')];
41
+ for (const [name, content] of Object.entries(files)) {
42
+ const body = Buffer.from(content, 'utf8');
43
+ blocks.push(tarHeader(name, body.length, '0'), body);
44
+ const pad = (512 - (body.length % 512)) % 512;
45
+ if (pad) blocks.push(Buffer.alloc(pad));
46
+ }
47
+ blocks.push(Buffer.alloc(1024));
48
+ return zlib.gzipSync(Buffer.concat(blocks));
49
+ }
50
+
51
+ /** An archive with `count` memory files and unique content, so its checksum is unique too. */
52
+ function sampleArchive(count, label) {
53
+ const files = {};
54
+ const nonce = crypto.randomBytes(8).toString('hex');
55
+ for (let i = 0; i < count; i++) {
56
+ files[`professional/mem_${i}.md`] = `---\nid: mem_${i}\n---\n\n${label || 'sample'} ${nonce} ${i}\n`;
57
+ }
58
+ if (count > 0) files['index.json'] = JSON.stringify({ label: label || 'sample', nonce });
59
+ return makeArchive(files);
60
+ }
61
+
62
+ function sha256(buf) {
63
+ return crypto.createHash('sha256').update(buf).digest('hex');
64
+ }
65
+
66
+ // -- a thin client -----------------------------------------------------------
67
+
68
+ function client(baseUrl, token) {
69
+ const base = baseUrl.replace(/\/$/, '');
70
+ const auth = token ? { Authorization: `Bearer ${token}` } : {};
71
+
72
+ async function json(method, pathname, body, headers) {
73
+ const res = await fetch(base + pathname, {
74
+ method,
75
+ headers: { ...auth, ...(body ? { 'Content-Type': 'application/json' } : {}), ...(headers || {}) },
76
+ body: body ? JSON.stringify(body) : undefined,
77
+ });
78
+ const text = await res.text();
79
+ let data = null;
80
+ try { data = text ? JSON.parse(text) : null; } catch { data = text; }
81
+ return { status: res.status, headers: res.headers, data };
82
+ }
83
+
84
+ async function upload(brainId, archive, { headers, query, field } = {}) {
85
+ const boundary = '----conformance' + crypto.randomBytes(8).toString('hex');
86
+ const head = Buffer.from(
87
+ `--${boundary}\r\n` +
88
+ `Content-Disposition: form-data; name="${field || 'brain'}"; filename="brain.tar.gz"\r\n` +
89
+ 'Content-Type: application/gzip\r\n\r\n'
90
+ );
91
+ const tail = Buffer.from(`\r\n--${boundary}--\r\n`);
92
+ const res = await fetch(`${base}/api/brains/${brainId}/sync${query || ''}`, {
93
+ method: 'PUT',
94
+ headers: { ...auth, 'Content-Type': `multipart/form-data; boundary=${boundary}`, ...(headers || {}) },
95
+ body: Buffer.concat([head, archive, tail]),
96
+ });
97
+ const text = await res.text();
98
+ let data = null;
99
+ try { data = text ? JSON.parse(text) : null; } catch { data = text; }
100
+ return { status: res.status, headers: res.headers, data };
101
+ }
102
+
103
+ async function download(brainId, { headers, query } = {}) {
104
+ const res = await fetch(`${base}/api/brains/${brainId}/sync${query || ''}`, {
105
+ headers: { ...auth, ...(headers || {}) },
106
+ });
107
+ const body = Buffer.from(await res.arrayBuffer());
108
+ return { status: res.status, headers: res.headers, body };
109
+ }
110
+
111
+ return { json, upload, download };
112
+ }
113
+
114
+ // -- the reference store, for when no STORE_URL is given ------------------------
115
+
116
+ async function startReferenceStore(options = {}) {
117
+ const { createStore } = require('../server');
118
+ const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-store-conformance-'));
119
+ const store = createStore({
120
+ dataDir,
121
+ requestsPerMinute: 0,
122
+ uploadsPerMinute: 0,
123
+ failedAuthPerMinute: 0,
124
+ ...options,
125
+ });
126
+ const a = store.users.add('conformance-a', 'a@example.test');
127
+ const b = store.users.add('conformance-b', 'b@example.test');
128
+ const server = await store.listen(0, '127.0.0.1');
129
+ return {
130
+ url: `http://127.0.0.1:${server.address().port}`,
131
+ token: a.token,
132
+ token2: b.token,
133
+ store,
134
+ dataDir,
135
+ close: () => new Promise((resolve) => {
136
+ server.close(() => {
137
+ fs.rmSync(dataDir, { recursive: true, force: true });
138
+ resolve();
139
+ });
140
+ if (server.closeAllConnections) server.closeAllConnections();
141
+ }),
142
+ };
143
+ }
144
+
145
+ module.exports = { makeArchive, sampleArchive, sha256, client, startReferenceStore };
@@ -0,0 +1,14 @@
1
+ # Caddy terminates TLS for both services and obtains certificates by itself.
2
+ # Point two DNS names at this host, put them in .env, and open ports 80 and 443.
3
+
4
+ {$STORE_DOMAIN} {
5
+ encode zstd gzip
6
+ reverse_proxy store:8787
7
+ }
8
+
9
+ {$MCP_DOMAIN} {
10
+ reverse_proxy connector:8788 {
11
+ # MCP responses can be event streams: do not buffer them.
12
+ flush_interval -1
13
+ }
14
+ }
@@ -0,0 +1,38 @@
1
+ # The MCP connector, configured for a self-hosted store.
2
+ # Build from the repository root:
3
+ # docker build -f store/deploy/connector.Dockerfile -t brain-connector .
4
+ #
5
+ # The connector runs the repository's own command-line tools (bin/, src/) against
6
+ # each user's working copy, so the image carries those alongside connector/.
7
+ FROM node:22-alpine
8
+
9
+ WORKDIR /app
10
+ COPY package.json ./
11
+ COPY bin/ ./bin/
12
+ COPY src/ ./src/
13
+ # The OpenID Connect token verifier is shared with the store.
14
+ COPY store/lib/ ./store/lib/
15
+
16
+ WORKDIR /app/connector
17
+ COPY connector/package.json connector/package-lock.json ./
18
+ # tsx runs the TypeScript sources directly and is a dev dependency.
19
+ RUN npm ci --include=dev && npm cache clean --force
20
+ COPY connector/tsconfig.json ./
21
+ COPY connector/src/ ./src/
22
+
23
+ RUN mkdir -p /var/lib/brain-connector && chown node:node /var/lib/brain-connector
24
+ USER node
25
+
26
+ ENV NODE_ENV=production \
27
+ PORT=8788 \
28
+ CONNECTOR_BIND_HOST=0.0.0.0 \
29
+ CONNECTOR_IDP=static \
30
+ CONNECTOR_BRAIN_BASE=/run/brain-connector \
31
+ CONNECTOR_STATE_DIR=/var/lib/brain-connector
32
+
33
+ EXPOSE 8788
34
+
35
+ HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
36
+ CMD wget -qO- http://127.0.0.1:8788/health >/dev/null || exit 1
37
+
38
+ CMD ["node", "--import", "tsx", "src/server.ts"]
@@ -0,0 +1,83 @@
1
+ # Self-hosted Brain: a store, a stateless MCP connector in front of it, and Caddy
2
+ # for TLS. See ../SELF-HOSTING.md.
3
+ #
4
+ # cp env.example .env # then fill it in
5
+ # docker compose up -d --build
6
+ # docker compose exec store node store/bin/brain-store.js user add <name>
7
+
8
+ name: brain
9
+
10
+ services:
11
+ store:
12
+ build:
13
+ context: ../..
14
+ dockerfile: store/Dockerfile
15
+ restart: unless-stopped
16
+ environment:
17
+ STORE_ENCRYPTION_KEY: ${STORE_ENCRYPTION_KEY:?set STORE_ENCRYPTION_KEY in .env}
18
+ STORE_MAX_UPLOAD_MB: ${STORE_MAX_UPLOAD_MB:-50}
19
+ STORE_MAX_USER_MB: ${STORE_MAX_USER_MB:-0}
20
+ STORE_TRUST_PROXY: "1"
21
+ volumes:
22
+ - store-data:/data
23
+ read_only: true
24
+ tmpfs:
25
+ - /tmp
26
+ cap_drop: [ALL]
27
+ security_opt:
28
+ - no-new-privileges:true
29
+ networks: [internal]
30
+
31
+ connector:
32
+ build:
33
+ context: ../..
34
+ dockerfile: store/deploy/connector.Dockerfile
35
+ restart: unless-stopped
36
+ depends_on:
37
+ store:
38
+ condition: service_healthy
39
+ environment:
40
+ CONNECTOR_IDP: static
41
+ # The connector talks to the store over the private network, never the internet.
42
+ BRAIN_CLOUD_API_URL: http://store:8787
43
+ CONNECTOR_STATE_KEY: ${CONNECTOR_STATE_KEY:?set CONNECTOR_STATE_KEY in .env}
44
+ # Caddy is another container on the private network, not loopback.
45
+ CONNECTOR_TRUST_PROXY: uniquelocal
46
+ volumes:
47
+ - connector-state:/var/lib/brain-connector
48
+ read_only: true
49
+ tmpfs:
50
+ - /tmp
51
+ # Users' working copies are plaintext. Keep them in memory only.
52
+ - /run/brain-connector:uid=1000,gid=1000,mode=0700
53
+ - /home/node/.npm
54
+ cap_drop: [ALL]
55
+ security_opt:
56
+ - no-new-privileges:true
57
+ networks: [internal]
58
+
59
+ caddy:
60
+ image: caddy:2-alpine
61
+ restart: unless-stopped
62
+ depends_on: [store, connector]
63
+ ports:
64
+ - "80:80"
65
+ - "443:443"
66
+ - "443:443/udp"
67
+ environment:
68
+ STORE_DOMAIN: ${STORE_DOMAIN:?set STORE_DOMAIN in .env}
69
+ MCP_DOMAIN: ${MCP_DOMAIN:?set MCP_DOMAIN in .env}
70
+ volumes:
71
+ - ./Caddyfile:/etc/caddy/Caddyfile:ro
72
+ - caddy-data:/data
73
+ - caddy-config:/config
74
+ networks: [internal]
75
+
76
+ volumes:
77
+ store-data:
78
+ connector-state:
79
+ caddy-data:
80
+ caddy-config:
81
+
82
+ networks:
83
+ internal:
@@ -0,0 +1,19 @@
1
+ # Copy to .env and fill in: cp env.example .env
2
+ # Never commit the real file.
3
+
4
+ # Two DNS names that point at this host. Caddy gets certificates for them.
5
+ STORE_DOMAIN=store.example.com
6
+ MCP_DOMAIN=mcp.example.com
7
+
8
+ # Encrypts archives at rest. Generate with:
9
+ # docker compose run --rm store keygen
10
+ # Keep a copy somewhere safe: without it the stored archives cannot be read.
11
+ STORE_ENCRYPTION_KEY=
12
+
13
+ # Encrypts the connector's saved logins (so users are not logged out on restart).
14
+ # Generate with: openssl rand -hex 32
15
+ CONNECTOR_STATE_KEY=
16
+
17
+ # Optional limits.
18
+ STORE_MAX_UPLOAD_MB=50
19
+ STORE_MAX_USER_MB=0