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,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.
@@ -0,0 +1,189 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ /**
5
+ * brain-store — self-hostable store for Brain Memory
6
+ *
7
+ * brain-store serve Run the server
8
+ * brain-store user add <name> Create a user and print their token (once)
9
+ * brain-store user list List users
10
+ * brain-store user rotate <name> Issue a new token; the old one stops working
11
+ * brain-store user remove <name> Remove a user (--purge also deletes their data)
12
+ * brain-store keygen Print a fresh encryption key
13
+ */
14
+
15
+ const crypto = require('crypto');
16
+ const os = require('os');
17
+ const path = require('path');
18
+ const { createStore, VERSION } = require('../server');
19
+ const { UserStore } = require('../lib/auth');
20
+ const { Storage, parseKey } = require('../lib/storage');
21
+
22
+ const HELP = `
23
+ brain-store ${VERSION} — self-hostable store for Brain Memory
24
+
25
+ Commands:
26
+ serve [--port N] [--host H] [--data DIR] Run the server
27
+ user add <name> [--email E] [--data DIR] Create a user; prints the token once
28
+ user list [--data DIR] List users
29
+ user rotate <name> [--data DIR] Issue a new token for a user
30
+ user remove <name> [--purge] [--data DIR] Remove a user (--purge deletes their brains)
31
+ keygen Print a fresh encryption key
32
+
33
+ Environment (flags win over environment):
34
+ STORE_DATA_DIR Data directory (default: ~/.brain-store)
35
+ STORE_PORT Port (default: 8787)
36
+ STORE_HOST Bind address (default: 127.0.0.1)
37
+ STORE_ENCRYPTION_KEY 32-byte key, hex or base64. Enables encryption at rest.
38
+ STORE_MAX_UPLOAD_MB Largest accepted archive (default: 50)
39
+ STORE_MAX_USER_MB Storage per user, 0 = unlimited (default: 0)
40
+ STORE_TRUST_PROXY "1" when behind a reverse proxy that sets X-Forwarded-For
41
+ STORE_OIDC_ISSUER Accept OpenID Connect ID tokens from this issuer ...
42
+ STORE_OIDC_AUDIENCE ... issued to this client id. Users are created on first sign-in.
43
+ STORE_OIDC_ALLOWED_DOMAINS, STORE_OIDC_ALLOWED_EMAILS
44
+ Comma-separated allow-lists. Required for a public issuer.
45
+ STORE_QUIET "1" to silence the request log
46
+
47
+ The server speaks plain HTTP. Put it behind a TLS-terminating reverse proxy
48
+ before exposing it beyond localhost. See SELF-HOSTING.md.
49
+ `.trim();
50
+
51
+ function flag(args, name) {
52
+ const i = args.indexOf(name);
53
+ if (i === -1) return undefined;
54
+ const value = args[i + 1];
55
+ args.splice(i, 2);
56
+ return value;
57
+ }
58
+
59
+ function boolFlag(args, name) {
60
+ const i = args.indexOf(name);
61
+ if (i === -1) return false;
62
+ args.splice(i, 1);
63
+ return true;
64
+ }
65
+
66
+ function dataDir(args) {
67
+ return path.resolve(
68
+ flag(args, '--data') || process.env.STORE_DATA_DIR || path.join(os.homedir(), '.brain-store')
69
+ );
70
+ }
71
+
72
+ async function serve(args) {
73
+ const dir = dataDir(args);
74
+ const port = Number(flag(args, '--port') || process.env.STORE_PORT || 8787);
75
+ const host = flag(args, '--host') || process.env.STORE_HOST || '127.0.0.1';
76
+ const quiet = process.env.STORE_QUIET === '1';
77
+ const encryptionKey = parseKey(process.env.STORE_ENCRYPTION_KEY);
78
+
79
+ const oidc = process.env.STORE_OIDC_ISSUER
80
+ ? {
81
+ issuer: process.env.STORE_OIDC_ISSUER,
82
+ audience: process.env.STORE_OIDC_AUDIENCE,
83
+ allowedDomains: process.env.STORE_OIDC_ALLOWED_DOMAINS,
84
+ allowedEmails: process.env.STORE_OIDC_ALLOWED_EMAILS,
85
+ }
86
+ : null;
87
+
88
+ const store = createStore({
89
+ dataDir: dir,
90
+ encryptionKey,
91
+ oidc,
92
+ maxUploadBytes: Number(process.env.STORE_MAX_UPLOAD_MB || 50) * 1024 * 1024,
93
+ maxUserBytes: Number(process.env.STORE_MAX_USER_MB || 0) * 1024 * 1024,
94
+ trustProxy: process.env.STORE_TRUST_PROXY === '1',
95
+ log: quiet ? null : (entry) => process.stdout.write(JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n'),
96
+ });
97
+
98
+ const server = await store.listen(port, host);
99
+ const bound = server.address();
100
+ console.error(`brain-store ${VERSION} listening on http://${bound.address}:${bound.port}`);
101
+ console.error(` data: ${dir}`);
102
+ console.error(` encryption at rest: ${encryptionKey ? 'on' : 'off'}`);
103
+ console.error(` sign-in: static tokens${oidc ? ' + OpenID Connect (' + oidc.issuer + ')' : ''}`);
104
+ console.error(` users: ${store.users.list().length}`);
105
+ if (!['127.0.0.1', '::1', 'localhost'].includes(host)) {
106
+ console.error(' note: serving plain HTTP on a non-loopback address. Terminate TLS in front of this server.');
107
+ }
108
+
109
+ const stop = () => server.close(() => process.exit(0));
110
+ process.on('SIGINT', stop);
111
+ process.on('SIGTERM', stop);
112
+ }
113
+
114
+ function user(args) {
115
+ const sub = args.shift();
116
+ const dir = dataDir(args);
117
+ const users = new UserStore(dir);
118
+
119
+ if (sub === 'list') {
120
+ const all = users.list();
121
+ if (!all.length) return console.log('No users. Create one with: brain-store user add <name>');
122
+ for (const u of all) console.log(`${u.id}\t${u.name}\t${u.email || '-'}\t${u.created_at}`);
123
+ return;
124
+ }
125
+
126
+ if (sub === 'add') {
127
+ const email = flag(args, '--email');
128
+ const name = args.shift();
129
+ if (!name) throw new Error('usage: brain-store user add <name> [--email E]');
130
+ const created = users.add(name, email);
131
+ // A first brain, so a client that logs in has something to sync to.
132
+ new Storage(dir).createBrain(created.user.id, 'default');
133
+ printToken(created, 'created');
134
+ return;
135
+ }
136
+
137
+ if (sub === 'rotate') {
138
+ const name = args.shift();
139
+ if (!name) throw new Error('usage: brain-store user rotate <name>');
140
+ printToken(users.rotate(name), 'rotated');
141
+ return;
142
+ }
143
+
144
+ if (sub === 'remove') {
145
+ const purge = boolFlag(args, '--purge');
146
+ const name = args.shift();
147
+ if (!name) throw new Error('usage: brain-store user remove <name> [--purge]');
148
+ const removed = users.remove(name);
149
+ if (purge) new Storage(dir).deleteUser(removed.id);
150
+ console.log(`Removed ${removed.name} (${removed.id})${purge ? ' and deleted their brains' : '. Their brains were kept; add --purge to delete them'}.`);
151
+ return;
152
+ }
153
+
154
+ throw new Error('usage: brain-store user add|list|rotate|remove');
155
+ }
156
+
157
+ function printToken(result, verb) {
158
+ console.log(`User ${result.user.name} (${result.user.id}) ${verb}.`);
159
+ console.log('');
160
+ console.log('Token (shown once; the store keeps only a hash):');
161
+ console.log('');
162
+ console.log(' ' + result.token);
163
+ console.log('');
164
+ console.log('Connect a brain with:');
165
+ console.log(' brain cloud login --api-url <store URL> --token-stdin');
166
+ }
167
+
168
+ async function main() {
169
+ const args = process.argv.slice(2);
170
+ const command = args.shift();
171
+
172
+ if (!command || command === '--help' || command === '-h' || command === 'help') {
173
+ console.log(HELP);
174
+ return;
175
+ }
176
+ if (command === '--version' || command === '-v') return console.log(VERSION);
177
+ if (command === 'serve') return serve(args);
178
+ if (command === 'user') return user(args);
179
+ if (command === 'keygen') return console.log(crypto.randomBytes(32).toString('hex'));
180
+
181
+ console.error(`Unknown command: ${command}\n`);
182
+ console.error(HELP);
183
+ process.exit(1);
184
+ }
185
+
186
+ main().catch((err) => {
187
+ console.error('Error: ' + err.message);
188
+ process.exit(1);
189
+ });