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.
- package/CHANGELOG.md +153 -0
- package/README.md +4 -0
- package/SECURITY.md +61 -9
- package/bin/brain.js +24 -3
- package/bin/cloud-sync.js +49 -6
- package/bin/install.js +72 -14
- package/bin/memorize.js +50 -6
- package/bin/port.js +174 -0
- package/bin/recall.js +16 -6
- package/bin/reinforce.js +5 -0
- package/bin/session-start.js +30 -4
- package/bin/verify.js +42 -4
- package/commands/brain/memorize.md +8 -0
- package/commands/brain/sync.md +23 -0
- package/commands/brain/verify.md +10 -2
- package/hooks/citation-check.mjs +94 -0
- package/hooks/hooks.json +11 -0
- package/hooks/lib.mjs +6 -0
- package/hooks/prompt-recall.mjs +24 -3
- package/hooks/session-start.mjs +4 -2
- package/integrations/README.md +4 -0
- package/integrations/agentskills/brain-memory/SKILL.md +9 -5
- package/package.json +10 -5
- package/prompts/antigravity.md +4 -2
- package/prompts/claude.md +4 -2
- package/prompts/copilot.md +4 -2
- package/prompts/kilo.md +4 -2
- package/prompts/openai.md +4 -2
- package/prompts/opencode.md +4 -2
- package/src/adapters.js +240 -0
- package/src/anomaly.js +41 -1
- package/src/cloud-sync.js +123 -11
- package/src/content-lint.js +55 -2
- package/src/export-import.js +1 -1
- package/src/git-sync.js +1 -1
- package/src/index-manager.js +9 -5
- package/src/installer.js +35 -1
- package/src/pinning.js +20 -1
- package/src/provenance.js +34 -0
- package/src/quarantine.js +82 -5
- package/src/receipt.js +9 -4
- package/src/surfaced.js +188 -0
- package/store/CONTRACT.md +244 -0
- package/store/Dockerfile +24 -0
- package/store/README.md +43 -0
- package/store/SELF-HOSTING.md +200 -0
- package/store/bin/brain-store.js +189 -0
- package/store/conformance/conformance.test.js +341 -0
- package/store/conformance/helpers.js +199 -0
- package/store/deploy/Caddyfile +14 -0
- package/store/deploy/connector.Dockerfile +38 -0
- package/store/deploy/docker-compose.yml +83 -0
- package/store/deploy/env.example +19 -0
- package/store/lib/auth.js +174 -0
- package/store/lib/oidc.js +206 -0
- package/store/lib/storage.js +333 -0
- package/store/lib/tar.js +150 -0
- package/store/openapi.yaml +318 -0
- package/store/server.js +465 -0
- package/store/test/mock-issuer.js +104 -0
- package/store/test/oidc.test.js +222 -0
- package/store/test/store.test.js +445 -0
|
@@ -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.
|
package/store/Dockerfile
ADDED
|
@@ -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"]
|
package/store/README.md
ADDED
|
@@ -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).
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Self-hosting Brain
|
|
2
|
+
|
|
3
|
+
Run your own store, and optionally your own MCP connector in front of it, so
|
|
4
|
+
that every agent you use reaches memory that lives on a machine you control.
|
|
5
|
+
Nothing here needs a Brain Cloud account.
|
|
6
|
+
|
|
7
|
+
There are two pieces, and you can stop after the first.
|
|
8
|
+
|
|
9
|
+
| Piece | What it gives you | Needs |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| **`brain-store`** | Sync between your machines with `brain cloud push` and `pull` | Node.js 18+, or Docker |
|
|
12
|
+
| **The connector** | The same brain inside MCP-only hosts: Claude.ai, ChatGPT, goose and others | Docker, two DNS names, ports 80 and 443 |
|
|
13
|
+
|
|
14
|
+
The store never reads your memories. It keeps each brain as one archive, exactly
|
|
15
|
+
as the client sent it. The interface is documented in [CONTRACT.md](CONTRACT.md).
|
|
16
|
+
|
|
17
|
+
## 1. The store by itself
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx -p brain-memory brain-store user add alice # prints alice's token, once
|
|
21
|
+
npx -p brain-memory brain-store serve # http://127.0.0.1:8787
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
From a checkout of this repository, use `node store/bin/brain-store.js` in place
|
|
25
|
+
of `npx -p brain-memory brain-store`.
|
|
26
|
+
|
|
27
|
+
On each machine that should share the brain:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pbpaste | brain cloud login --api-url https://store.example.com --token-stdin
|
|
31
|
+
brain cloud push # from the machine that has the memories
|
|
32
|
+
brain cloud pull # on the others
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`--token-stdin` keeps the token out of your shell history. `--token TOKEN` and
|
|
36
|
+
the `BRAIN_STORE_TOKEN` environment variable also work.
|
|
37
|
+
|
|
38
|
+
The server speaks plain HTTP and binds to `127.0.0.1`. To reach it from other
|
|
39
|
+
machines, put a TLS-terminating reverse proxy in front of it; the Compose setup
|
|
40
|
+
below does that for you. The `brain` CLI refuses to send a token over plain HTTP
|
|
41
|
+
to another host unless you pass `--allow-http`.
|
|
42
|
+
|
|
43
|
+
### Pushing from two machines
|
|
44
|
+
|
|
45
|
+
`push` is conditional. If another machine has pushed since you last pulled, the
|
|
46
|
+
store refuses the upload and nothing is overwritten:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
Error: The store has changes you have not pulled, so nothing was uploaded.
|
|
50
|
+
Run `brain cloud pull` and push again, or `brain cloud push --force` to overwrite the store.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Pull, then push. The store keeps the last five archives it replaced, so even a
|
|
54
|
+
forced push can be undone: `brain restore --list --from cloud`, then
|
|
55
|
+
`brain restore --to <version> --from cloud`.
|
|
56
|
+
|
|
57
|
+
### Configuration
|
|
58
|
+
|
|
59
|
+
| Variable | Default | Meaning |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `STORE_DATA_DIR` | `~/.brain-store` | Where users and archives live |
|
|
62
|
+
| `STORE_HOST`, `STORE_PORT` | `127.0.0.1`, `8787` | Bind address |
|
|
63
|
+
| `STORE_ENCRYPTION_KEY` | unset | 32 bytes, hex or base64. Turns on encryption at rest. Make one with `brain-store keygen` |
|
|
64
|
+
| `STORE_MAX_UPLOAD_MB` | `50` | Largest archive accepted |
|
|
65
|
+
| `STORE_MAX_USER_MB` | `0` | Storage per user; `0` is unlimited |
|
|
66
|
+
| `STORE_TRUST_PROXY` | unset | Set to `1` behind a reverse proxy, so rate limits see the real client address |
|
|
67
|
+
| `STORE_QUIET` | unset | Set to `1` to silence the request log |
|
|
68
|
+
|
|
69
|
+
Users:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
brain-store user add <name> [--email E] # create; prints the token once
|
|
73
|
+
brain-store user list
|
|
74
|
+
brain-store user rotate <name> # new token; the old one stops working at once
|
|
75
|
+
brain-store user remove <name> [--purge] # --purge also deletes their brains
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Run one server process per data directory. The lock that makes conditional
|
|
79
|
+
uploads safe lives inside the process.
|
|
80
|
+
|
|
81
|
+
## 2. Store and connector with Docker Compose
|
|
82
|
+
|
|
83
|
+
This runs the store, the connector and [Caddy](https://caddyserver.com), which
|
|
84
|
+
obtains TLS certificates by itself.
|
|
85
|
+
|
|
86
|
+
1. Point two DNS names at the host, for example `store.example.com` and
|
|
87
|
+
`mcp.example.com`, and open ports 80 and 443.
|
|
88
|
+
2. Configure:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
cd store/deploy
|
|
92
|
+
cp env.example .env
|
|
93
|
+
docker compose run --rm store keygen # paste into STORE_ENCRYPTION_KEY
|
|
94
|
+
openssl rand -hex 32 # paste into CONNECTOR_STATE_KEY
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Fill in the two domain names as well.
|
|
98
|
+
3. Start it, and create a user:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
docker compose up -d --build
|
|
102
|
+
docker compose exec store node store/bin/brain-store.js user add alice
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
4. Connect a client. In any MCP host, add the server `https://mcp.example.com/mcp`.
|
|
106
|
+
For example:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
claude mcp add --transport http brain https://mcp.example.com/mcp
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The host opens a sign-in page served by your connector. Paste the token from
|
|
113
|
+
step 3. The CLI on your own machines uses `https://store.example.com` with the
|
|
114
|
+
same token, as in part 1.
|
|
115
|
+
|
|
116
|
+
The connector is stateless in the sense that matters: it holds no memories of
|
|
117
|
+
its own. At login it pulls the user's brain from the store into memory, answers
|
|
118
|
+
recall from that copy, writes changes back, and discards the copy after fifteen
|
|
119
|
+
idle minutes or when the session ends.
|
|
120
|
+
|
|
121
|
+
## 3. Signing in through your organisation's identity provider
|
|
122
|
+
|
|
123
|
+
For more than a handful of people, issuing tokens by hand does not scale. The
|
|
124
|
+
store can instead accept ID tokens from an OpenID Connect issuer you already run:
|
|
125
|
+
Microsoft Entra, Google Workspace, Keycloak, Okta. People sign in with their work
|
|
126
|
+
account, and the store creates their user and first brain the first time it sees
|
|
127
|
+
them. Static tokens keep working alongside, which is how the `brain` CLI still
|
|
128
|
+
connects (`brain-store user rotate <oidc user id>` issues one for an OIDC user).
|
|
129
|
+
|
|
130
|
+
1. Register an application with your identity provider. Its redirect URI is
|
|
131
|
+
`https://mcp.example.com/oidc/callback`. Note the issuer URL and the client id.
|
|
132
|
+
2. Configure the store and the connector with the same issuer and client id:
|
|
133
|
+
|
|
134
|
+
| Store | Connector |
|
|
135
|
+
|---|---|
|
|
136
|
+
| `STORE_OIDC_ISSUER` | `OIDC_ISSUER` |
|
|
137
|
+
| `STORE_OIDC_AUDIENCE` (the client id) | `OIDC_CLIENT_ID` |
|
|
138
|
+
| `STORE_OIDC_ALLOWED_DOMAINS`, `STORE_OIDC_ALLOWED_EMAILS` | `OIDC_ALLOWED_DOMAINS`, `OIDC_ALLOWED_EMAILS` |
|
|
139
|
+
| | `CONNECTOR_IDP=oidc` |
|
|
140
|
+
| | `OIDC_CLIENT_SECRET`, if your provider issues one |
|
|
141
|
+
| | `OIDC_SCOPES` (default `openid email profile offline_access`) |
|
|
142
|
+
| | `OIDC_AUTH_PARAMS`, extra query parameters for the sign-in request |
|
|
143
|
+
|
|
144
|
+
3. Provider notes:
|
|
145
|
+
- **Microsoft Entra:** use the tenant-specific issuer,
|
|
146
|
+
`https://login.microsoftonline.com/<tenant id>/v2.0`. Everyone in that tenant
|
|
147
|
+
can then sign in; no allow-list is needed.
|
|
148
|
+
- **Google:** the issuer `https://accounts.google.com` gives tokens to anyone
|
|
149
|
+
with a Google account, so the store refuses to start without an allow-list.
|
|
150
|
+
Set `STORE_OIDC_ALLOWED_DOMAINS` to your Workspace domain. Google does not
|
|
151
|
+
accept the `offline_access` scope: set `OIDC_SCOPES=openid email profile` and
|
|
152
|
+
`OIDC_AUTH_PARAMS=access_type=offline&prompt=consent`.
|
|
153
|
+
- Allow-lists match an address only when the provider marks it verified, or
|
|
154
|
+
match Google's hosted-domain claim.
|
|
155
|
+
|
|
156
|
+
Only RS256 and ES256 signatures are accepted. The token's issuer, audience,
|
|
157
|
+
expiry and nonce are all checked, and the issuer must be reached over HTTPS.
|
|
158
|
+
|
|
159
|
+
This path is tested against a mock issuer that signs real tokens. It has not yet
|
|
160
|
+
been exercised against each real provider; expect to adjust scopes and parameters
|
|
161
|
+
for yours, and please report what you had to change.
|
|
162
|
+
|
|
163
|
+
## Backups
|
|
164
|
+
|
|
165
|
+
Everything is under the store's data directory (the `store-data` volume in
|
|
166
|
+
Compose): `users.json` and `brains/`. Copy that directory. With encryption at
|
|
167
|
+
rest switched on, a copy is useless without `STORE_ENCRYPTION_KEY`, so keep the
|
|
168
|
+
key somewhere separate from the backups, and do not lose it.
|
|
169
|
+
|
|
170
|
+
## What to know before you expose this to the internet
|
|
171
|
+
|
|
172
|
+
- **TLS is not optional.** Tokens are bearer credentials. The Compose setup
|
|
173
|
+
terminates TLS in Caddy; if you use another proxy, do the same.
|
|
174
|
+
- **Tokens are stored hashed** (SHA-256 of 256 random bits). A stolen
|
|
175
|
+
`users.json` does not yield usable tokens. A token shown by `user add` cannot
|
|
176
|
+
be shown again; rotate it if it is lost.
|
|
177
|
+
- **Encryption at rest protects a stolen disk or backup, not a compromised
|
|
178
|
+
server.** The server holds the key while it runs. This is server-side
|
|
179
|
+
encryption, not end-to-end encryption.
|
|
180
|
+
- **The connector holds plaintext working copies while a user is active.** In
|
|
181
|
+
the Compose setup they live on a memory-backed filesystem and are never written
|
|
182
|
+
to disk.
|
|
183
|
+
- **Failed logins are rate limited** by client address, at the store and at the
|
|
184
|
+
connector's sign-in endpoint.
|
|
185
|
+
- **Removing or rotating a user at the store ends their connector sessions** at
|
|
186
|
+
the next silent renewal, within the hour.
|
|
187
|
+
|
|
188
|
+
Report security problems privately: see [SECURITY.md](../SECURITY.md).
|
|
189
|
+
|
|
190
|
+
## Checking your deployment
|
|
191
|
+
|
|
192
|
+
The conformance suite is a black-box test of the contract. Create a disposable
|
|
193
|
+
user, then:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
STORE_URL=https://store.example.com STORE_TOKEN=bst_… node --test store/conformance/
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
It overwrites the brain it works on. Do not point it at a user whose memories
|
|
200
|
+
you want to keep.
|