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,191 @@
1
+ /**
2
+ * Brain Memory — Skill Verification (Skill-DisCo, arXiv:2606.26669)
3
+ *
4
+ * A crystallized skill is a claim: "this is how this repo does migrations."
5
+ * Today that claim is only ever tested by *using* it — `brain skill use
6
+ * --failed` demotes one that misfires, so a bad skill decays out of the L0
7
+ * index eventually. Eventually is the problem: the skill is advertised to
8
+ * every session until enough failures accumulate, and the first few failures
9
+ * are paid by the user.
10
+ *
11
+ * The Skill-DisCo result is that procedural memory should compile to something
12
+ * **checkable offline** — verifiable without running the agent. This module is
13
+ * that check: a skill may declare preconditions, and `brain skill verify`
14
+ * answers whether they still hold in the current working directory.
15
+ *
16
+ * The value is drift detection. A skill distilled six months ago against a repo
17
+ * whose `migrations/` folder has since been renamed is not weakly-supported —
18
+ * it is *wrong*, and it will confidently misdirect the next session that
19
+ * matches its triggers. A precondition check catches that in milliseconds.
20
+ *
21
+ * ── Why declarative checks and not a shell command ───────────────────────
22
+ * The obvious design is `verify: npm run migrate:check`. It is also a loaded
23
+ * gun pointed at the rest of this codebase.
24
+ *
25
+ * Skills are crystallized automatically from experience (sleep Phase 4b), they
26
+ * sync between machines, and they can be imported from other people. A `verify`
27
+ * field holding arbitrary shell would mean a memory file that executes code —
28
+ * turning every one of Brain's poisoning defenses into theatre, because the
29
+ * payload would no longer need to persuade the agent of anything. It would just
30
+ * need to be run. `curl … | bash` in a synced skill is precisely the OWASP
31
+ * ASI06 scenario with the hard part removed.
32
+ *
33
+ * So checks are DECLARATIVE and READ-ONLY. Every check type below inspects
34
+ * state; none of them execute anything, and there is deliberately no escape
35
+ * hatch. A skill can ask "does `migrations/` exist?" It cannot ask the machine
36
+ * to run something and trust the exit code.
37
+ *
38
+ * ── Check types ──────────────────────────────────────────────────────────
39
+ * { file_exists: "migrations/" }
40
+ * { file_absent: "config/legacy.yml" }
41
+ * { file_contains: { path: "package.json", text: "\"migrate\"" } }
42
+ * { command_available: "psql" } — PATH lookup only, never executed
43
+ * { env_set: "DATABASE_URL" } — presence only, value never read
44
+ */
45
+
46
+ const fs = require('fs');
47
+ const path = require('path');
48
+
49
+ // A contains-check reads a file into memory; cap it so a skill pointed at a
50
+ // multi-gigabyte artifact degrades to a failed check instead of an OOM.
51
+ const MAX_CONTAINS_BYTES = 2 * 1024 * 1024;
52
+
53
+ const CHECK_TYPES = ['file_exists', 'file_absent', 'file_contains', 'command_available', 'env_set'];
54
+
55
+ /**
56
+ * Resolve a skill-declared path inside the working directory.
57
+ *
58
+ * Skills sync between machines and can be imported from other people, so a
59
+ * declared path is untrusted input. Anything that escapes the working
60
+ * directory — `../`, an absolute path, a symlink pointing out — resolves to
61
+ * null and fails the check, so a skill can never be used to probe for files
62
+ * elsewhere on the disk.
63
+ *
64
+ * @param {string} cwd - Directory the checks run against
65
+ * @param {string} rel - Skill-declared path
66
+ * @returns {string|null} Absolute path, or null when it escapes `cwd`
67
+ */
68
+ function resolveInside(cwd, rel) {
69
+ if (typeof rel !== 'string' || rel.length === 0) return null;
70
+ if (path.isAbsolute(rel)) return null;
71
+ const base = fs.realpathSync.native ? path.resolve(cwd) : path.resolve(cwd);
72
+ const target = path.resolve(base, rel);
73
+ const withSep = base.endsWith(path.sep) ? base : base + path.sep;
74
+ if (target !== base && !target.startsWith(withSep)) return null;
75
+ return target;
76
+ }
77
+
78
+ /** Is `name` an executable on PATH? Resolves only — never runs it. */
79
+ function onPath(name) {
80
+ if (typeof name !== 'string' || !/^[A-Za-z0-9._-]+$/.test(name)) return false;
81
+ const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
82
+ // Windows resolves commands through PATHEXT (`node` on PATH is node.exe);
83
+ // POSIX has no equivalent, so the bare name is the only candidate there.
84
+ const exts = process.platform === 'win32'
85
+ ? ['', ...(process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
86
+ : [''];
87
+ for (const dir of dirs) {
88
+ for (const ext of exts) {
89
+ try {
90
+ fs.accessSync(path.join(dir, name + ext), fs.constants.X_OK);
91
+ return true;
92
+ } catch { /* keep looking */ }
93
+ }
94
+ }
95
+ return false;
96
+ }
97
+
98
+ /**
99
+ * Evaluate one declarative check.
100
+ *
101
+ * @param {Object} check - Single-key object, e.g. { file_exists: "migrations/" }
102
+ * @param {string} cwd
103
+ * @returns {{ check: string, target: string, ok: boolean, detail?: string }}
104
+ */
105
+ function runCheck(check, cwd) {
106
+ if (!check || typeof check !== 'object') {
107
+ return { check: 'malformed', target: '', ok: false, detail: 'check is not an object' };
108
+ }
109
+ const kind = Object.keys(check).find((k) => CHECK_TYPES.includes(k));
110
+ if (!kind) {
111
+ return {
112
+ check: 'unknown',
113
+ target: String(Object.keys(check)[0] || ''),
114
+ ok: false,
115
+ detail: `unsupported check; expected one of ${CHECK_TYPES.join(', ')}`,
116
+ };
117
+ }
118
+
119
+ const value = check[kind];
120
+
121
+ if (kind === 'env_set') {
122
+ const ok = typeof value === 'string' && Boolean(process.env[value]);
123
+ // Presence only. The value is never read, so a check can't exfiltrate a
124
+ // secret into a result payload that later gets synced.
125
+ return { check: kind, target: String(value), ok };
126
+ }
127
+
128
+ if (kind === 'command_available') {
129
+ return { check: kind, target: String(value), ok: onPath(value) };
130
+ }
131
+
132
+ if (kind === 'file_exists' || kind === 'file_absent') {
133
+ const abs = resolveInside(cwd, value);
134
+ if (abs === null) {
135
+ return { check: kind, target: String(value), ok: false, detail: 'path escapes the working directory' };
136
+ }
137
+ const exists = fs.existsSync(abs);
138
+ return { check: kind, target: String(value), ok: kind === 'file_exists' ? exists : !exists };
139
+ }
140
+
141
+ // file_contains
142
+ const spec = value && typeof value === 'object' ? value : {};
143
+ const abs = resolveInside(cwd, spec.path);
144
+ if (abs === null) {
145
+ return { check: kind, target: String(spec.path || ''), ok: false, detail: 'path escapes the working directory' };
146
+ }
147
+ if (typeof spec.text !== 'string' || spec.text.length === 0) {
148
+ return { check: kind, target: String(spec.path || ''), ok: false, detail: 'missing `text`' };
149
+ }
150
+ try {
151
+ const stat = fs.statSync(abs);
152
+ if (stat.size > MAX_CONTAINS_BYTES) {
153
+ return { check: kind, target: spec.path, ok: false, detail: 'file too large to scan' };
154
+ }
155
+ return { check: kind, target: spec.path, ok: fs.readFileSync(abs, 'utf-8').includes(spec.text) };
156
+ } catch {
157
+ return { check: kind, target: String(spec.path || ''), ok: false, detail: 'unreadable' };
158
+ }
159
+ }
160
+
161
+ /**
162
+ * Run every check a skill declares.
163
+ *
164
+ * A skill with no `verify` block is `unverifiable` — not passing and not
165
+ * failing. Most skills are prose and always will be; treating an absent block
166
+ * as failure would demote the whole library on the first verification sweep.
167
+ *
168
+ * @param {Object} skill - Skill record (needs `verify` array)
169
+ * @param {Object} [opts]
170
+ * @param {string} [opts.cwd=process.cwd()]
171
+ * @returns {{ status: 'passed'|'failed'|'unverifiable', checks: Object[], passed: number, total: number }}
172
+ */
173
+ function verifySkill(skill, opts = {}) {
174
+ const cwd = opts.cwd || process.cwd();
175
+ const declared = (skill && skill.verify) || null;
176
+
177
+ if (!Array.isArray(declared) || declared.length === 0) {
178
+ return { status: 'unverifiable', checks: [], passed: 0, total: 0 };
179
+ }
180
+
181
+ const checks = declared.map((c) => runCheck(c, cwd));
182
+ const passed = checks.filter((c) => c.ok).length;
183
+ return {
184
+ status: passed === checks.length ? 'passed' : 'failed',
185
+ checks,
186
+ passed,
187
+ total: checks.length,
188
+ };
189
+ }
190
+
191
+ module.exports = { verifySkill, runCheck, resolveInside, onPath, CHECK_TYPES, MAX_CONTAINS_BYTES };
package/src/skills.js CHANGED
@@ -22,6 +22,7 @@ const {
22
22
  atomicWriteSync,
23
23
  } = require('./index-manager');
24
24
  const { setFrontmatterFields } = require('./pinning');
25
+ const { verifySkill } = require('./skill-verify');
25
26
 
26
27
  const SKILLS_DIR = '_skills';
27
28
  const DEFAULT_STRENGTH = 0.6;
@@ -83,6 +84,10 @@ function addSkill(projectRoot, skill) {
83
84
  use_count: 0,
84
85
  fail_count: 0,
85
86
  last_used: null,
87
+ // Declarative, read-only preconditions (src/skill-verify.js). Only set when
88
+ // present, so prose-only skills stay lean and are reported `unverifiable`
89
+ // rather than failing a check they never claimed to support.
90
+ ...(Array.isArray(skill.verify) && skill.verify.length ? { verify: skill.verify } : {}),
86
91
  };
87
92
  atomicWriteSync(path.join(dir, 'SKILL.md'), buildSkillFile({ ...record, body: skill.body }));
88
93
 
@@ -116,6 +121,63 @@ function showSkill(projectRoot, name) {
116
121
  }
117
122
  }
118
123
 
124
+ /**
125
+ * Check a skill's declared preconditions against the current working directory.
126
+ *
127
+ * Answers "does this skill still describe reality?" without running the agent
128
+ * — the offline-checkable half of procedural memory (Skill-DisCo,
129
+ * arXiv:2606.26669). A skill distilled against a repo layout that has since
130
+ * changed is not weakly-supported, it is wrong, and it will keep being
131
+ * advertised to every matching session until enough real failures accumulate.
132
+ *
133
+ * A failed verification demotes exactly like a failed use, because the user
134
+ * pays the same price either way. A *passing* verification does NOT strengthen:
135
+ * preconditions holding says the skill is still applicable, not that following
136
+ * it produced a good outcome, and inflating strength on a cheap automatic check
137
+ * would let a skill climb the index without ever having worked.
138
+ *
139
+ * Skills with no `verify` block return `unverifiable` and are left untouched.
140
+ *
141
+ * @param {string} projectRoot
142
+ * @param {string} name
143
+ * @param {Object} [opts] - { cwd }
144
+ * @returns {Object} { name, status, passed, total, checks, strength? }
145
+ */
146
+ function verifySkillByName(projectRoot, name, opts = {}) {
147
+ const idx = readSkillsIndex(projectRoot);
148
+ const s = idx.skills.find((x) => x.name === slug(name));
149
+ if (!s) return { error: `Skill not found: ${name}` };
150
+
151
+ const result = verifySkill(s, { cwd: opts.cwd || process.cwd() });
152
+ if (result.status === 'unverifiable') {
153
+ return { name: s.name, ...result };
154
+ }
155
+
156
+ const now = new Date().toISOString();
157
+ s.last_verified = now;
158
+ s.verify_status = result.status;
159
+ if (result.status === 'failed') {
160
+ s.fail_count = (s.fail_count || 0) + 1;
161
+ s.strength = Math.max(0, (s.strength ?? DEFAULT_STRENGTH) - 0.10);
162
+ }
163
+ writeSkillsIndex(idx, projectRoot);
164
+
165
+ setFrontmatterFields(getBrainDir(projectRoot), skillPath(name), {
166
+ last_verified: now,
167
+ verify_status: result.status,
168
+ ...(result.status === 'failed'
169
+ ? { strength: Math.round(s.strength * 1000) / 1000, fail_count: s.fail_count }
170
+ : {}),
171
+ });
172
+
173
+ return {
174
+ name: s.name,
175
+ ...result,
176
+ strength: Math.round((s.strength ?? DEFAULT_STRENGTH) * 1000) / 1000,
177
+ advertised: isAdvertised(s),
178
+ };
179
+ }
180
+
119
181
  /**
120
182
  * Record a use. Success strengthens; failure weakens and counts toward demotion.
121
183
  * @param {Object} [opts] - { failed: boolean }
@@ -202,6 +264,7 @@ module.exports = {
202
264
  advertisedSummaries,
203
265
  showSkill,
204
266
  useSkill,
267
+ verifySkillByName,
205
268
  removeSkill,
206
269
  exportSkill,
207
270
  DEMOTE_FAIL_RATIO,
@@ -0,0 +1,244 @@
1
+ # The Brain store contract
2
+
3
+ **Version 1.1** · Status: draft
4
+
5
+ This document specifies the HTTP interface between a Brain client and a remote
6
+ store. A client is anything that reads or writes a brain over the network: the
7
+ `brain` command line, the MCP connector, or a tool you write. A store is any
8
+ server that implements this document.
9
+
10
+ Two stores implement it today: `brain-store` in this directory, and the hosted
11
+ Brain Cloud service. The [conformance suite](conformance/) checks an
12
+ implementation against this document over HTTP and knows nothing about how the
13
+ store is built. [`openapi.yaml`](openapi.yaml) describes the same interface in
14
+ machine-readable form. Where the two disagree, this document is correct.
15
+
16
+ The key words MUST, SHOULD and MAY are used as in RFC 2119.
17
+
18
+ ## 1. Model
19
+
20
+ A **brain** is one person's memory: a directory of Markdown files with YAML
21
+ frontmatter, plus index files. A store holds each brain as a single
22
+ **archive**: a gzip-compressed tar file of that directory.
23
+
24
+ The store treats the archive as opaque. It MUST NOT need to read the memories
25
+ inside it, and MUST return exactly the bytes it was given. The one thing a
26
+ store derives from the contents is the number of regular-file entries in the
27
+ archive, reported as `file_count`.
28
+
29
+ Every brain belongs to exactly one user. A store MUST NOT let one user observe
30
+ that another user's brain exists.
31
+
32
+ A store MAY encrypt archives at rest. Checksums, sizes and file counts always
33
+ describe the archive as the client sent it, never the stored form.
34
+
35
+ ## 2. Conventions
36
+
37
+ - Requests and responses are JSON (`application/json`) unless stated otherwise.
38
+ - An error is a JSON object with a string `error` member, and an HTTP status
39
+ that reflects the failure. Clients MUST NOT parse the text of `error`.
40
+ - A **checksum** is the lowercase hexadecimal SHA-256 of the archive bytes.
41
+ - Brain identifiers are UUIDs.
42
+ - Timestamps are RFC 3339 strings in UTC.
43
+
44
+ ## 3. Authentication
45
+
46
+ Every endpoint except `GET /health` requires `Authorization: Bearer <token>`. A
47
+ missing, malformed, unknown or expired token MUST yield `401`.
48
+
49
+ How a client obtains a token is outside the core contract. A store advertises
50
+ what it supports in the `capabilities` array of `GET /health`:
51
+
52
+ | Capability | Meaning |
53
+ |---|---|
54
+ | `static-token` | The operator issues long-lived tokens out of band. There is nothing to refresh. |
55
+ | `device-code` | The store implements the device-code login endpoints (`POST /auth/device/request`, `POST /auth/device/poll`, `POST /auth/refresh`). |
56
+ | `oidc` | The store accepts an OpenID Connect ID token from an issuer its operator configured as the bearer token, and creates the user on first sight. |
57
+
58
+ A store that lacks a capability MUST answer its endpoints with `404`.
59
+
60
+ Tokens are credentials. A store MUST NOT log them, and SHOULD store only a hash
61
+ of a static token. A client MUST NOT send a token over plain HTTP to a host
62
+ other than the local machine unless the user has explicitly allowed it.
63
+
64
+ ## 4. Endpoints
65
+
66
+ ### 4.1 `GET /health`
67
+
68
+ No authentication. `200` with:
69
+
70
+ ```json
71
+ { "status": "ok", "contract": "1.1", "capabilities": ["static-token", "conditional-sync"] }
72
+ ```
73
+
74
+ `contract` is the highest version of this document the store implements. A
75
+ store that omits it implements version 1. Additional members are allowed.
76
+
77
+ ### 4.2 `GET /auth/me`
78
+
79
+ `200` with `{ "user": { "id": "...", "email": "..." }, "storage_used": 12345 }`.
80
+ `user` MAY carry further members.
81
+
82
+ ### 4.3 `GET /api/brains`
83
+
84
+ `200` with a JSON array of [brain records](#5-the-brain-record) owned by the
85
+ caller, oldest first. An account with no brains yields `[]`.
86
+
87
+ ### 4.4 `POST /api/brains`
88
+
89
+ Body: `{ "name": "work" }`. The body, and `name`, are optional; the default name
90
+ is `default`. `201` with the new brain record. `403` when the account may not
91
+ create another brain.
92
+
93
+ ### 4.5 `GET /api/brains/{id}`
94
+
95
+ `200` with the brain record. `404` when the brain does not exist or belongs to
96
+ someone else. `400` or `404` for a malformed identifier.
97
+
98
+ ### 4.6 `DELETE /api/brains/{id}`
99
+
100
+ Removes the brain, its archive and its snapshots. `204`, or `200`.
101
+
102
+ ### 4.7 `PUT /api/brains/{id}/sync` — upload
103
+
104
+ The body is `multipart/form-data` with one file field named `brain` that holds
105
+ the archive.
106
+
107
+ On success, `200` with:
108
+
109
+ ```json
110
+ { "size_bytes": 48211, "file_count": 132, "checksum": "9f2c…" }
111
+ ```
112
+
113
+ and, from version 1.1, an `ETag` header carrying the same checksum.
114
+
115
+ Before replacing a stored archive, the store MUST keep the previous one as a
116
+ [snapshot](#49-snapshots). The replacement MUST be atomic: a concurrent download
117
+ sees the old archive or the new one, never a mixture, and a failed upload
118
+ leaves the old archive in place.
119
+
120
+ **The empty-push guard.** If the uploaded archive contains no regular files and
121
+ the stored brain has five or more, the store MUST refuse with `409` unless the
122
+ request carries `?force=true`. This protects against a freshly initialised
123
+ client overwriting a populated brain.
124
+
125
+ Other failures: `400` when the `brain` field is missing; `413` when the archive
126
+ exceeds the store's size limit or the account's quota; `429` when rate limited,
127
+ with a `Retry-After` header.
128
+
129
+ **Conditional upload (1.1).** Two clients that share a brain can otherwise
130
+ overwrite each other without noticing. A client SHOULD therefore make its
131
+ uploads conditional:
132
+
133
+ | Request header | Store behaviour |
134
+ |---|---|
135
+ | `If-Match: "<checksum>"` | Proceed only if the stored archive has that checksum. Otherwise `412`. A brain with no archive yet never matches. |
136
+ | `If-Match: *` | Proceed only if some archive is stored. |
137
+ | `If-None-Match: *` | Proceed only if no archive is stored yet. Otherwise `412`. |
138
+ | neither | Proceed unconditionally. This is version 1 behaviour and remains valid. |
139
+
140
+ A `412` response changes nothing. Its body carries the checksum the store
141
+ currently holds, so the client can tell what it is missing:
142
+
143
+ ```json
144
+ { "error": "precondition failed: …", "current_checksum": "41ab…" }
145
+ ```
146
+
147
+ The precondition check and the replacement MUST be a single atomic step. When
148
+ two uploads carry the same `If-Match`, exactly one succeeds.
149
+
150
+ `?force=true` overrides only the empty-push guard. To overwrite on purpose, a
151
+ client omits `If-Match`.
152
+
153
+ **Archive validation (1.1).** The store MUST reject an upload that is not a
154
+ gzip-compressed tar archive with `400`, and SHOULD bound the inflated size and
155
+ the number of entries it is willing to examine.
156
+
157
+ ### 4.8 `GET /api/brains/{id}/sync` — download
158
+
159
+ `200` with the archive as `application/gzip`, and an `X-Checksum` header. `404`
160
+ when nothing has been uploaded yet.
161
+
162
+ From version 1.1 the response also carries `ETag: "<checksum>"`, and the store
163
+ honours `If-None-Match`: when it names the stored checksum, the answer is `304`
164
+ with no body.
165
+
166
+ With `?version=<name>`, the response is that [snapshot](#49-snapshots) instead.
167
+ `404` when there is no such snapshot. The store MUST reject a name that is not
168
+ one it issued; in particular a name MUST NOT be able to address a file outside
169
+ the brain's snapshots.
170
+
171
+ ### 4.9 Snapshots
172
+
173
+ `GET /api/brains/{id}/versions` → `200` with:
174
+
175
+ ```json
176
+ { "versions": [ { "version": "20260918T101500.123000000.tar.gz", "date": "2026-09-18T10:15:00Z" } ], "total": 1 }
177
+ ```
178
+
179
+ newest first. `version` is an opaque name; `date` is optional. A store keeps at
180
+ least the most recent snapshot and MAY prune older ones.
181
+
182
+ `POST /api/brains/{id}/versions/{version}/restore` makes that snapshot the live
183
+ archive, first keeping the current archive as a new snapshot. `200` with
184
+ `{ "restored_version": "<name>" }`. `404` when there is no such snapshot. From
185
+ version 1.1 a restore honours `If-Match` exactly as an upload does.
186
+
187
+ ## 5. The brain record
188
+
189
+ ```json
190
+ {
191
+ "id": "0b5f6c1e-6f0e-4a57-9d0a-4a1f2f1c9e11",
192
+ "name": "default",
193
+ "size_bytes": 48211,
194
+ "file_count": 132,
195
+ "checksum": "9f2c…",
196
+ "last_synced_at": "2026-09-18T10:15:00Z",
197
+ "created_at": "2026-09-01T08:00:00Z"
198
+ }
199
+ ```
200
+
201
+ `checksum` and `last_synced_at` are `null` until the first upload. Additional
202
+ members are allowed.
203
+
204
+ ## 6. What a client does
205
+
206
+ **Pull.** Download; if the client already has the archive with that checksum,
207
+ send `If-None-Match` and treat `304` as "nothing to do". Remember the checksum
208
+ of what was pulled as the brain's *base*.
209
+
210
+ **Push.** Upload with `If-Match: "<base>"`. On `200`, the returned checksum
211
+ becomes the new base. On `412`, pull first, then push again. A client that
212
+ writes small changes (a single new memory) SHOULD do this automatically; a
213
+ client acting on a whole directory SHOULD tell the user and let them decide.
214
+
215
+ **First push.** With no base, either upload unconditionally or, to be safe
216
+ against a concurrent first writer, send `If-None-Match: *`.
217
+
218
+ Unpacking an archive is the client's responsibility, and a client MUST treat it
219
+ as untrusted input: extract to a staging directory, copy only regular files and
220
+ directories, never follow or create symbolic links, and never write outside the
221
+ brain directory.
222
+
223
+ ## 7. Versions of this contract
224
+
225
+ - **1** — Everything above except the parts marked 1.1. This is what Brain Cloud
226
+ served before September 2026.
227
+ - **1.1** — Adds `contract` and `capabilities` to `GET /health`, `ETag` and
228
+ `If-None-Match` on download, `If-Match` and `If-None-Match: *` on upload and
229
+ restore, `current_checksum` in the `412` body, and archive validation. A
230
+ version 1 client works unchanged against a 1.1 store.
231
+
232
+ A per-memory interface, where a client reads and writes single files with
233
+ content-hash preconditions instead of whole archives, is planned as a separate
234
+ proposal. It is not part of this document.
235
+
236
+ ## 8. Checking an implementation
237
+
238
+ ```bash
239
+ STORE_URL=https://store.example STORE_TOKEN=… node --test store/conformance/
240
+ ```
241
+
242
+ Set `STORE_TOKEN_2` to a second user's token to include the isolation tests, and
243
+ `STORE_CONTRACT=1` to check only version 1. The suite overwrites the brain it
244
+ works on. Use a disposable account.
@@ -0,0 +1,24 @@
1
+ # brain-store — the reference store server. No dependencies to install.
2
+ # Build from the repository root: docker build -f store/Dockerfile -t brain-store .
3
+ FROM node:22-alpine
4
+
5
+ WORKDIR /app
6
+ COPY store/ ./store/
7
+
8
+ # Data lives on a volume, owned by the unprivileged user the server runs as.
9
+ RUN mkdir -p /data && chown node:node /data
10
+ USER node
11
+
12
+ ENV NODE_ENV=production \
13
+ STORE_DATA_DIR=/data \
14
+ STORE_HOST=0.0.0.0 \
15
+ STORE_PORT=8787
16
+
17
+ VOLUME ["/data"]
18
+ EXPOSE 8787
19
+
20
+ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
21
+ CMD wget -qO- http://127.0.0.1:8787/health >/dev/null || exit 1
22
+
23
+ ENTRYPOINT ["node", "store/bin/brain-store.js"]
24
+ CMD ["serve"]
@@ -0,0 +1,43 @@
1
+ # store/
2
+
3
+ The open interface between a Brain client and a remote store, and a small server
4
+ that implements it.
5
+
6
+ | | |
7
+ |---|---|
8
+ | [CONTRACT.md](CONTRACT.md) | The store contract, version 1.1. Start here if you want to write a store or a client. |
9
+ | [openapi.yaml](openapi.yaml) | The same interface, machine-readable. |
10
+ | [conformance/](conformance/) | A black-box test suite. Point it at any store over HTTP. |
11
+ | [server.js](server.js), [lib/](lib/), [bin/](bin/) | `brain-store`, the reference server. Node.js, no dependencies, files only. |
12
+ | [SELF-HOSTING.md](SELF-HOSTING.md) | Running your own store and MCP connector. |
13
+ | [deploy/](deploy/) | Docker Compose: store, connector and Caddy for TLS. Start from `env.example`. |
14
+
15
+ ## Why a contract
16
+
17
+ A brain is a directory of plain files that belongs to one person. Syncing it
18
+ should not tie that person to one vendor. The contract is deliberately small: a
19
+ store keeps each brain as an opaque archive, never reads the memories inside it,
20
+ and returns exactly the bytes it was given. Two stores implement it today: this
21
+ one, and the hosted Brain Cloud service.
22
+
23
+ Version 1.1 adds conditional sync. Two clients that share a brain, such as a
24
+ laptop and an MCP connector, used to be able to overwrite each other without
25
+ noticing. A client now names the archive it started from (`If-Match`), and a store
26
+ that has moved on refuses the upload.
27
+
28
+ ## Running the tests
29
+
30
+ ```bash
31
+ npm run test:store # reference server + conformance suite
32
+ npm run test:conformance # conformance suite alone, against the reference server
33
+
34
+ # against any other store
35
+ STORE_URL=https://store.example.com STORE_TOKEN=… node --test store/conformance/
36
+ ```
37
+
38
+ ## Writing another implementation
39
+
40
+ You need the endpoints in CONTRACT.md §4 and nothing else. The conformance suite
41
+ tells you when you are done. If the contract is unclear or the suite is wrong,
42
+ open an issue: changes to the contract go through the `rfc` process described in
43
+ [GOVERNANCE.md](../GOVERNANCE.md).