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
package/CHANGELOG.md CHANGED
@@ -6,6 +6,199 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.4.0] - 2026-09-18
10
+
11
+ Opens up sync. The HTTP interface between a Brain client and a remote store is
12
+ now a published contract with a conformance suite, and `brain-store` is a small
13
+ reference server you can run yourself, so a brain no longer has to live in Brain
14
+ Cloud to be shared between machines or reached from MCP-only hosts. Sync also
15
+ stops being last-writer-wins: clients name the archive they started from, and a
16
+ store that has moved on refuses the upload instead of overwriting another
17
+ device's memories. The contract is a **draft** and is open for comment in
18
+ [#6](https://github.com/omelas-tech/brain/issues/6) until at least 25 September
19
+ 2026; it may still change. The project also gains a governance document, a
20
+ maintainers file and a code of conduct.
21
+
22
+ ### Added
23
+ - **An open store contract and a self-hostable store.** `store/CONTRACT.md` (with
24
+ `store/openapi.yaml`) specifies the HTTP interface between a Brain client and a
25
+ remote store. `brain-store` is a reference server for it: Node.js, no
26
+ dependencies, files only, static bearer tokens stored as hashes, optional
27
+ AES-256-GCM encryption at rest. `store/conformance/` is a black-box suite that
28
+ checks any implementation over HTTP. See `store/SELF-HOSTING.md`.
29
+ - **Conditional sync (store contract 1.1).** `brain cloud push` now names the
30
+ archive it started from (`If-Match`). If another device pushed in the meantime
31
+ the store answers `412` and nothing is overwritten; pull, then push again, or
32
+ `brain cloud push --force`. Stores that predate 1.1 ignore the header, so
33
+ behaviour against them is unchanged.
34
+ - **Token login for self-hosted stores:** `brain cloud login --api-url URL
35
+ --token-stdin` (also `--token`, or `BRAIN_STORE_TOKEN`). The CLI refuses to send
36
+ a token over plain HTTP to another host unless `--allow-http` is given.
37
+ - **Connector: pluggable identity.** `CONNECTOR_IDP=static` lets the MCP connector
38
+ run in front of a self-hosted store with no Firebase: the sign-in page takes the
39
+ store token, and the store decides who the user is. Firebase remains the default
40
+ for the hosted service and its behaviour is unchanged.
41
+ `CONNECTOR_TRUST_PROXY` names the reverse proxy when it is not on loopback.
42
+ - **Sign-in through an organisation's identity provider (OpenID Connect).** The
43
+ store accepts ID tokens from a configured issuer (`STORE_OIDC_ISSUER`,
44
+ `STORE_OIDC_AUDIENCE`) and creates users on first sign-in; `CONNECTOR_IDP=oidc`
45
+ sends people to that issuer (authorization code, PKCE, nonce). RS256 and ES256
46
+ only; a public issuer such as Google requires an allow-list. Tested against a
47
+ mock issuer, not yet against each real provider.
48
+ - **Connector: no lost writes.** Sync-back is conditional. When another device
49
+ pushed first, the connector discards its working copy, starts again from the
50
+ store's brain, re-applies the write and pushes, so both sides' memories survive.
51
+ - Docker Compose for a store, a connector and Caddy (`store/deploy/`).
52
+ - `GOVERNANCE.md`, `MAINTAINERS.md`, `CODE_OF_CONDUCT.md`.
53
+
54
+ ### Fixed
55
+ - `brain cloud push` on macOS no longer uploads an AppleDouble `._name` entry
56
+ beside every file with extended attributes (`COPYFILE_DISABLE`), which inflated
57
+ the archive and its reported file count.
58
+ - Connector: a user whose brain exists but has never been pushed to is treated as
59
+ new rather than as a store outage, so their session can be renewed.
60
+ - `CONTRIBUTING.md` described a project layout several releases old.
61
+ - `SECURITY.md` described the hosted service's retired key-derivation scheme.
62
+
63
+ ## [0.3.0] - 2026-09-04
64
+
65
+ Ships brain as a plugin and moves its session behaviour from prompts into
66
+ hooks. The repository is now a Claude Code plugin and a Codex plugin, and a
67
+ marketplace ChatGPT workspaces can import; `SessionStart`, `UserPromptSubmit`
68
+ and `SessionEnd` hooks inject memory deterministically on both hosts instead
69
+ of asking the model to remember to run anything. Memories gain a consent tier
70
+ (`sensitivity`) that matches the published Anthropic vocabulary so the two
71
+ models interoperate, `brain import` learns Codex rollouts, and the earlier
72
+ unreleased work lands: content-integrity baselines, verifiable skills,
73
+ contradiction boundaries, recorded recall history and the benchmark harness.
74
+
75
+ ### Added
76
+
77
+ - **Plugin packaging: one repo, three hosts.** The repository root is now a
78
+ Claude Code plugin (`.claude-plugin/plugin.json`, name `brain` so commands stay
79
+ `/brain:*`), a Codex plugin (`.codex-plugin/plugin.json` overlay — Codex reads
80
+ the Claude manifest and exports `CLAUDE_PLUGIN_ROOT` to plugin hooks), and a
81
+ marketplace for both (`.claude-plugin/marketplace.json`,
82
+ `.agents/plugins/marketplace.json`). ChatGPT Business/Enterprise admins can
83
+ import the same repo (Admin → Plugins → Import marketplace) with daily sync.
84
+ Two plugins: `brain` (local-first: hooks + commands + the bundled CLI via a
85
+ `bin/brain` shim) and `brain-cloud` (the hosted MCP connector only, so
86
+ local-CLI users are never pushed into cloud OAuth).
87
+ - **Sensitive-topic consent tier** (`src/sensitivity.js`). Every memory now
88
+ carries `sensitivity: standard | sensitive | blocked`, using the vocabulary
89
+ of the largest deployed consent model for assistant memory (Anthropic, Aug
90
+ 2026) so brains interoperate with it instead of inventing a schema.
91
+ `sensitive` (health, race, ethnicity, religious beliefs, politics, gender
92
+ identity or sexual orientation) is stored only after the user opts in
93
+ (`sensitive_topics: true` in config.json); until then the write lands
94
+ quarantined (`sensitive_opt_out`) and is hidden from recall and
95
+ session-start, and `brain verify approve` is the per-item consent. `blocked`
96
+ (government ID numbers, criminal history, immigration status) is refused
97
+ outright. The agent classifies; the CLI's patterns are a narrow backstop that
98
+ can raise a label but never lower it. Receipts carry `⚠ sensitive`. Opting in
99
+ is never retroactive. This turns the positioning claim "provenance *and
100
+ consent* on every fragment" from copy into a shipped property.
101
+ - **Codex integration, as hooks.** `brain --codex` now registers brain's three
102
+ hooks in `~/.codex/hooks.json` (non-destructive merge; `/hooks` once to trust)
103
+ in addition to the `AGENTS.md` prompt and skills — the same scripts the plugin
104
+ ships, with `${CLAUDE_PLUGIN_ROOT}` expanded to the npm package path. Codex's
105
+ extension API for rewriting MCP tool results (0.151.0) is compile-time Rust
106
+ inside the Codex binary, so hooks are the integration surface a third party
107
+ actually has. The unshipped `integrations/codex/hooks/` copies and the
108
+ `Stop`-hook turn queue are gone: `brain import --source codex` reads
109
+ `$CODEX_HOME/sessions/` directly.
110
+ - **Prompt-time recall hook** (`UserPromptSubmit`, both hosts). Each substantive
111
+ prompt gets a deterministic `brain recall` pass; the top `prompt_recall_top` (3)
112
+ matches within `prompt_recall_budget_tokens` (600) are injected with receipts
113
+ and a short excerpt, wrapped in `<brain-context>`. The relevance floor means
114
+ unrelated prompts inject nothing; short prompts, slash commands and
115
+ acknowledgements are skipped; nothing is reinforced unless the model uses it.
116
+ - **`brain import --source codex`.** A Codex rollout adapter for
117
+ `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl` (format verified against
118
+ Codex 0.153): genuine prompts are told apart from injected AGENTS.md /
119
+ environment / hook context by `content_item_kinds` (marker matching for
120
+ pre-0.148 files), background threads (subagent, guardian, consolidation) are
121
+ skipped, thread names come from `session_index.jsonl`, touched files from
122
+ `apply_patch` calls. Harvest now also strips brain's own `<brain-context>`
123
+ and `<brain-session-context>` injections, so recalled memories are never
124
+ harvested back into new ones.
125
+ - **`brain session-start --budget N`** tightens the working-memory cap for one
126
+ call (never raises it) — for hosts with a smaller injection window than
127
+ config.json assumes. `brain recall` is now importable in-process
128
+ (`computeRecall`) with byte-identical scoring to the CLI.
129
+ - **Deterministic hooks for Claude Code and Codex** (`hooks/hooks.json`,
130
+ shared by both hosts). `SessionStart` injects the `brain session-start`
131
+ payload plus the ambient rules as `additionalContext` — the first time Claude
132
+ Code gets brain's session-start behaviour from the host rather than from a
133
+ prompt the model has to obey. `SessionEnd` appends a session-boundary entry
134
+ to `~/.brain/contexts.json`. Hooks run the engine in-process from the plugin
135
+ root, fail soft (`{}` + exit 0), and never touch a brain that does not exist.
136
+ - **Content integrity baselines (OWASP ASI06, Store phase).** Every memory is
137
+ hashed (SHA-256) at write time, and `brain audit` reports memories whose bytes
138
+ no longer match. Closes the one poisoning route every other defense here was
139
+ blind to: an editor. Provenance, content-lint, quarantine, and anomaly
140
+ detection all guard the *write path* and assume an attacker arrives through
141
+ `brain memorize` — but `~/.brain/` is plain Markdown, so anything with write
142
+ access to the home directory could rewrite a trusted, pinned memory without
143
+ touching the index, the audit log, or any origin label. Drift findings are
144
+ **advisory** (sleep and the user both edit files legitimately) and are never
145
+ auto-quarantined. Re-baseline with `brain audit --rebaseline`.
146
+ - **Contradiction proposals carry the boundary.** `potential_conflicts` now
147
+ reports `proposed_valid_until` — the exact instant a supersede would stamp on
148
+ the older memory — plus `authority` and `shared_tags`. Detection also widened
149
+ beyond pinned/stable to like-for-like memories (a `decision` that may have
150
+ replaced a `decision`), which is the ordinary "we changed our minds" case
151
+ users never think to flag. Still never auto-resolved: tag overlap is a
152
+ relatedness signal, not a contradiction signal.
153
+ - **Verifiable skills** (`brain skill verify <name>`). A skill may declare
154
+ read-only preconditions (`file_exists`, `file_absent`, `file_contains`,
155
+ `command_available`, `env_set`) that are checked against the working directory
156
+ without running the agent, so a skill distilled against a repo layout that has
157
+ since changed is caught in milliseconds instead of after several real
158
+ failures. Checks are **declarative by design** — skills are crystallized
159
+ automatically, they sync, and they can be imported, so a `verify` field
160
+ holding arbitrary shell would be a memory file that executes code. Failure
161
+ demotes; passing does not promote.
162
+ - **`recall_history` is actually recorded.** The field was declared in the
163
+ schema, documented in all six agent prompts and three docs pages, and never
164
+ written — `brain reinforce` updated `access_count` but not the series, so the
165
+ brain knew a memory had been recalled N times and never *when*. Each
166
+ reinforcement now appends a capped row (timestamp, interval, strength
167
+ before/after).
168
+ - **Benchmark: LongMemEval-S adapter** (`harness/longmemeval.js`). Scores the
169
+ retrieval half of the public 500-question benchmark with no LLM spend.
170
+ Brain: **R@5 = 0.909** over ~48-session haystacks.
171
+ - **Benchmark: real-embedding arm** (`harness/retrievers/dense.js`) and a
172
+ **retrieval-only pilot** (`harness/retrieval-only.js`) that scores Recall@k
173
+ for every retriever without an agent. The existing `vector-baseline` arm is a
174
+ hashed bag-of-words, not a semantic model, and could not answer whether
175
+ embeddings help; `dense` can.
176
+ - **Benchmark: decay calibration** (`harness/decay-calibration.js`). Compares
177
+ each memory type's implied half-life against observed recall intervals.
178
+
179
+ ### Fixed
180
+
181
+ - **Frontmatter serializer corrupted arrays of objects.** `updateMemoryFile`
182
+ rendered them via `String(value)`, producing `[object Object]` — lossy and
183
+ invalid YAML. Now JSON-encoded (a YAML subset), so they round-trip.
184
+
185
+ ### Changed
186
+
187
+ - **Positioning: two claims added, one now evidence-backed.** Deterministic
188
+ cross-agent ranking and poisoning resistance are stated in the README and on
189
+ the site. "No embeddings required" is no longer an assertion: on the hardest
190
+ retrieval scenario a real embedding model ranked the target memories *worse*
191
+ than BM25 (oracle ranks 45/20/15 plain, 21/20/8 with the model's task
192
+ prefixes, vs BM25's 21/20/1), and ties it at 0.909 R@5 on LongMemEval-S.
193
+ - **`brain-bm25` is rank-identical to plain BM25** on both scenario A and all
194
+ 500 LongMemEval-S instances. Title-3x/tags-2x field weighting and the custom
195
+ stemmer buy nothing measurable — Brain's advantage lives in decay, spreading
196
+ activation, context match, and pinning, not the relevance function.
197
+ - **Single-principal invariant documented.** "One brain, one person" is now an
198
+ explicit design principle; `scope` and `principal` are reserved frontmatter
199
+ field names.
200
+
201
+
9
202
  ## [0.2.0] - 2026-08-18
10
203
 
11
204
  Adds the second time axis. Memory now records not just when it learned a
package/README.md CHANGED
@@ -41,8 +41,9 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
41
41
  - **Git-friendly** — Full version history of how memories evolve
42
42
  - **Strength + decay** — Recalled memories get stronger, forgotten ones fade. Just like your brain
43
43
  - **Recall receipts** — Memory that visibly fires: every answer shaped by a memory ends with a one-line attributable receipt (`◉ memory: "<title>" (<type>, <age>)`), minted by the engine so it can't be hallucinated
44
- - **Provenance-bounded trust** — Every memory records where it came from (`user`, `agent-inferred`, `tool-output`, `external`), and recall weighs it: a fact planted by a web page or tool output is down-ranked, flagged `low_trust`, marked `⚠` on its receipt, and can never outrank what you said directly — no matter how many copies of it get written
44
+ - **Provenance-bounded trust** — Every memory records where it came from (`user`, `agent-inferred`, `tool-output`, `external`), and recall weighs it: a fact planted by a web page or tool output is down-ranked, flagged `low_trust`, marked `⚠` on its receipt, and can never outrank what you said directly — no matter how many copies of it get written. And because memories are plain files, Brain records a **SHA-256 baseline** of each one at write time — so `brain audit` also catches a memory edited *outside* any write path, the one poisoning route every write-path defense is blind to
45
45
  - **Bitemporal — it knows *when* a fact was true** — Every memory separates record time (when the brain learned it) from valid time (`valid_from` / `valid_until`, when it was actually true). So "we deploy to Fly.io" and "we deploy to Render" aren't a contradiction to guess between — they're one fact with a boundary. `brain recall "deploy target" --as-of 2026-03-01` answers what was true in March; `--as-known-of` answers what the brain knew then. Facts that stopped being true are demoted and marked `⌛ expired`, never silently served as current
46
+ - **Deterministic recall — every agent ranks identically** — Scoring is arithmetic over files, not a model call: TF-IDF/BM25 relevance, decayed strength, spreading activation, context match, salience. Claude, Codex, and Gemini asking the same question of the same brain get the *same* ranking, in the same order, offline. No embedding-model version can silently reshuffle what your agent remembers
46
47
  - **Associative network** — Memories link to each other with weighted connections. Recalling one activates related ones automatically
47
48
  - **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
48
49
  - **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
@@ -51,7 +52,7 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
51
52
  - **Procedural skills** — Reusable how-to workflows with progressive disclosure, learned automatically from repeated experience and exportable to your agent's native skills
52
53
  - **On-demand depth** — Subcategories are created as needed, not pre-defined
53
54
  - **Consolidation** — Weak related memories merge into stronger combined knowledge
54
- - **Zero dependencies** — Pure file I/O, no databases, no servers, no embeddings required
55
+ - **Zero dependencies — and measured, not assumed** — Pure file I/O: no database, no server, no embedding model. That is a deliberate result, not a shortcut. On our hardest retrieval scenario (1,021 memories, 1,000 plausible distractors) a real embedding model ranked the target memories *worse* than BM25 — see the [retrieval-only pilot](benchmark/README.md#retrieval-only-pilot-no-agent-no-llm-spend)
55
56
 
56
57
  ## Install
57
58
 
@@ -135,12 +136,28 @@ The second command runs the setup wizard, which asks which runtime(s) to configu
135
136
  | Runtime | Instructions file | Commands land at |
136
137
  |---------|-------------------|------------------|
137
138
  | **Claude Code** | `CLAUDE.md` | `~/.claude/commands/brain/` (plugin slash commands) |
138
- | **OpenAI Codex CLI** | `AGENTS.md` (`~/.codex/`) | `~/.agents/skills/<name>/SKILL.md` |
139
+ | **OpenAI Codex CLI** | `AGENTS.md` (`~/.codex/`) + hooks in `~/.codex/hooks.json` (SessionStart, UserPromptSubmit, SessionEnd — trust once via `/hooks`) | `~/.agents/skills/<name>/SKILL.md` |
139
140
  | **OpenCode** | `AGENTS.md` | `~/.config/opencode/commands/` |
140
141
  | **GitHub Copilot CLI** | `copilot-instructions.md` (`~/.copilot/`), repo-local `AGENTS.md` | `~/.agents/skills/<name>/SKILL.md` (shared with Codex) |
141
142
  | **Kilo** | `rules/brain-memory.md` + `kilo.jsonc` `instructions` entry (`~/.config/kilo/`), repo-local `AGENTS.md` | `~/.config/kilo/commands/` |
142
143
  | **Google Antigravity** | `GEMINI.md` | `~/.gemini/skills/` *(experimental — verify paths against a live install)* |
143
144
 
145
+ #### Plugin install — Claude Code, Codex, ChatGPT workspaces
146
+
147
+ This repository is also a plugin marketplace. Installing the `brain` plugin gives Claude Code and Codex the same `/brain:*` commands **plus deterministic hooks**: `SessionStart` injects the budget-bounded `brain session-start` payload as context (no prompt file to edit, nothing for the model to remember to run) and `SessionEnd` records the session boundary in `~/.brain/contexts.json`. The plugin bundles the CLI, so no npm install is required for the hooks.
148
+
149
+ ```bash
150
+ # Claude Code
151
+ claude plugin marketplace add omelas-tech/brain
152
+ claude plugin install brain@brain-memory # local-first: hooks + /brain:* commands
153
+ claude plugin install brain-cloud@brain-memory # optional: the hosted MCP connector
154
+
155
+ # Codex CLI — same repo, same two plugins (Codex reads the Claude manifests)
156
+ codex /plugins # then add marketplace omelas-tech/brain
157
+ ```
158
+
159
+ **ChatGPT Business / Enterprise / Edu:** a workspace admin imports the marketplace once (Admin → Plugins → Add → Import marketplace → `https://github.com/omelas-tech/brain`) and the workspace picks up new versions daily. `brain` (skills + hooks) serves Codex users in the workspace; `brain-cloud` (the MCP connector) serves ChatGPT desktop. Import does not grant access by itself — each user completes the connector's OAuth sign-in on first use.
160
+
144
161
  #### Non-interactive
145
162
 
146
163
  ```bash
@@ -547,6 +564,9 @@ Each recall also improves the memory's decay rate: `new_rate = rate + 0.10 * (0.
547
564
 
548
565
  **Confidence** (0.0-1.0) tracks epistemic certainty. Set at encoding based on source quality, reduced when contradictions are found during Knowledge Propagation (-0.20), boosted during validations (+0.10). Low-confidence memories are flagged during recall.
549
566
 
567
+ ### Sensitive Topics (Consent)
568
+ Every memory carries a consent tier: `standard` (default), `sensitive` (health, race, ethnicity, religious beliefs, politics, gender identity or sexual orientation, and similar), or `blocked` (government ID numbers, criminal history, immigration status — never stored). Classify honestly when memorizing (`"sensitivity": "sensitive"`). Sensitive memories are stored only when the user has opted in (`sensitive_topics: true` in `~/.brain/config.json`); otherwise they wait quarantined and hidden until the user approves them (`brain verify approve <id>`), and their receipts carry `⚠ sensitive`. Opting in is never retroactive, and the CLI refuses `blocked` content outright.
569
+
550
570
  ### Consolidation
551
571
 
552
572
  When memories decay below the threshold (default: 0.3), they become candidates for consolidation. The agent groups related weak memories by path proximity, tag overlap, and temporal closeness, then merges them into a single stronger memory:
@@ -744,6 +764,10 @@ Brain configuration lives in `~/.brain/index.json` under the `config` key:
744
764
  | `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
745
765
  | `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
746
766
 
767
+ ### Sensitive Topics
768
+
769
+ `sensitive_topics` (default `false`). Memories classified `sensitive` — health, race, ethnicity, religious beliefs, politics, gender identity or sexual orientation — are stored only when this is `true`; otherwise they wait quarantined and hidden until you approve them one by one (`brain verify approve <id>`). Turning it on is never retroactive. `blocked` content (government ID numbers, criminal history, immigration status) is refused whatever the setting. See `src/sensitivity.js` for the exact tiers.
770
+
747
771
  ### Working-Memory Budget
748
772
 
749
773
  A separate `~/.brain/config.json` (created lazily with safe defaults) caps how much the brain injects into the context window at session start, so the always-present tier can never crowd out your actual work:
package/SECURITY.md CHANGED
@@ -64,8 +64,10 @@ connector** (a remote MCP server) are entirely optional. When you do use them, t
64
64
  is how your data is protected:
65
65
 
66
66
  - **Encrypted at rest.** Brains stored in Brain Cloud are encrypted on disk with
67
- **AES-256-GCM** using a **per-user key** (HKDF-derived from a server master key).
68
- A stolen disk, backup, or snapshot yields no readable memories.
67
+ **AES-256-GCM** envelope encryption: each user's data is encrypted with a
68
+ **per-user data key**, and that key is itself wrapped by a key held in a cloud
69
+ **key management service (KMS)**, not on the server's disk. A stolen disk,
70
+ backup, or snapshot yields no readable memories.
69
71
  - **No plaintext on the connector.** The connector keeps each user's working copy
70
72
  in **RAM only** (a tmpfs, wiped on restart) — it is never written to the
71
73
  connector's disk.
@@ -87,11 +89,50 @@ your memories in memory. If you require that the server never sees plaintext, ke
87
89
  your brain **local-only** (the default) or use Git/export sync with a passphrase
88
90
  (below) instead of Brain Cloud.
89
91
 
92
+ ## Self-hosted store (`brain-store`)
93
+
94
+ `store/` contains a reference store server you can run yourself
95
+ (`store/SELF-HOSTING.md`). What it does and does not protect:
96
+
97
+ - **Tokens are never stored.** A token is 256 random bits, shown once; the server
98
+ keeps its SHA-256 and compares in constant time. Tokens are never logged.
99
+ - **Failed logins are rate limited** per client address, and each user's request
100
+ and upload rates are bounded.
101
+ - **Uploads are untrusted input.** Size is bounded before and while reading. The
102
+ archive is inflated as a stream and only tar headers are examined, with bounds on
103
+ inflated size and entry count, so a compression bomb cannot exhaust memory. The
104
+ server never extracts an archive to disk.
105
+ - **Identifiers cannot leave the data directory.** User ids, brain ids and
106
+ snapshot names are matched against strict patterns before any path is built.
107
+ - **Tenant isolation.** Another user's brain is indistinguishable from one that
108
+ does not exist.
109
+ - **Optional encryption at rest** (AES-256-GCM, per-user key derived by
110
+ HKDF-SHA256 from `STORE_ENCRYPTION_KEY`). This protects a stolen disk or backup.
111
+ It is server-side encryption: the running server holds the key.
112
+ - **No TLS of its own.** The server speaks plain HTTP and binds to loopback by
113
+ default. Terminate TLS in a reverse proxy; the provided Compose setup does.
114
+ - **Conditional writes.** The precondition check and the replacement of an archive
115
+ happen under one in-process lock. Run one server process per data directory.
116
+
117
+ - **OpenID Connect sign-in is opt-in and narrow.** Only RS256 and ES256 are
118
+ accepted; `none` and HMAC algorithms are refused, and the key type must agree
119
+ with the algorithm named in the token. Issuer, audience, expiry and nonce are
120
+ checked, the issuer must be reached over HTTPS, and its discovery document must
121
+ name itself. A public issuer (Google) is refused unless an allow-list is set,
122
+ and allow-lists only honour addresses the issuer marks verified.
123
+
124
+ The connector's `static` identity provider sends the pasted store token only to
125
+ the store named in `BRAIN_CLOUD_API_URL`, and refuses to start unless that address
126
+ is set explicitly. Its sign-in page loads nothing from other hosts and cannot be
127
+ framed. The token is kept with the refresh grant encrypted under
128
+ `CONNECTOR_STATE_KEY`; without that key it is held in memory only.
129
+
90
130
  ## Supported Versions
91
131
 
92
132
  | Version | Supported |
93
133
  |---------|-----------|
94
- | 0.1.x (beta) | Yes |
134
+ | 0.3.x | Yes |
135
+ | < 0.3 | No — please upgrade |
95
136
 
96
137
  ## Design Principles
97
138
 
package/bin/audit.js CHANGED
@@ -10,6 +10,7 @@
10
10
  *
11
11
  * Usage:
12
12
  * brain audit [--window 24h|7d] [--apply] [--max-apply N]
13
+ * brain audit --rebaseline
13
14
  *
14
15
  * --apply flags at most N (default 20) proposed memories per run — an audit
15
16
  * can propose broadly but never mass-quarantine; `truncated: true` reports
@@ -24,6 +25,7 @@ const path = require('path');
24
25
  const { getBrainDir, readIndex, writeIndex, readAssociations } = require('../src/index-manager');
25
26
  const { appendAudit } = require('../src/audit');
26
27
  const { runAudit } = require('../src/anomaly');
28
+ const { rebaseline } = require('../src/integrity');
27
29
 
28
30
  /** Parse "24h" / "7d" / bare hours into hours. */
29
31
  function parseWindow(value) {
@@ -35,7 +37,7 @@ function parseWindow(value) {
35
37
  }
36
38
 
37
39
  function parseArgs(argv) {
38
- const args = { windowHours: 24, apply: false, maxApply: 20 };
40
+ const args = { windowHours: 24, apply: false, maxApply: 20, rebaseline: false };
39
41
  for (let i = 0; i < argv.length; i++) {
40
42
  switch (argv[i]) {
41
43
  case '--window': {
@@ -45,6 +47,7 @@ function parseArgs(argv) {
45
47
  }
46
48
  case '--apply': args.apply = true; break;
47
49
  case '--max-apply': args.maxApply = parseInt(argv[++i], 10) || 20; break;
50
+ case '--rebaseline': args.rebaseline = true; break;
48
51
  default: break;
49
52
  }
50
53
  }
@@ -77,6 +80,20 @@ function main(argv) {
77
80
  associations = { version: 1, edges: {} };
78
81
  }
79
82
 
83
+ // --rebaseline records the CURRENT bytes as the trusted baseline for every
84
+ // memory, then exits without auditing. Run it after a legitimate bulk
85
+ // rewrite (a sleep cycle, a restore, a sync pull) so the next audit compares
86
+ // against what the brain actually agreed with, not a pre-maintenance ghost.
87
+ // It is deliberately a separate run: re-baselining as a side effect of an
88
+ // audit would erase the very drift the audit exists to surface.
89
+ if (args.rebaseline) {
90
+ const { baselined, unreadable } = rebaseline(brainDir, index);
91
+ writeIndex(index);
92
+ appendAudit(brainDir, { event: 'integrity_rebaseline', count: baselined, unreadable });
93
+ console.log(JSON.stringify({ rebaselined: baselined, unreadable }, null, 2));
94
+ return;
95
+ }
96
+
80
97
  const result = runAudit(
81
98
  brainDir,
82
99
  { index, associations, appendAudit, writeIndex },
package/bin/brain ADDED
@@ -0,0 +1,4 @@
1
+ #!/bin/sh
2
+ # Plugin-install shim: Claude Code adds a plugin's bin/ to PATH, so `brain` resolves
3
+ # to the bundled CLI without an npm install. npm installs use bin/brain.js directly.
4
+ exec node "$(dirname "$0")/brain.js" "$@"
package/bin/cloud-sync.js CHANGED
@@ -1,12 +1,14 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  /**
4
- * brain cloud — CLI for Brain Cloud sync
4
+ * brain cloud — CLI for syncing with Brain Cloud or a self-hosted brain-store
5
5
  *
6
6
  * Usage:
7
7
  * brain cloud login [--api-url URL] Authenticate via device code flow
8
+ * brain cloud login --api-url URL --token-stdin
9
+ * Authenticate to a self-hosted store with a token
8
10
  * brain cloud logout Clear stored credentials
9
- * brain cloud push Upload ~/.brain/ to the cloud
11
+ * brain cloud push [--force] Upload ~/.brain/ to the cloud
10
12
  * brain cloud pull Download from the cloud to ~/.brain/
11
13
  * brain cloud status Show connection and sync status
12
14
  */
@@ -29,9 +31,18 @@ brain cloud — Brain Cloud sync CLI
29
31
  Commands:
30
32
  login [--api-url URL] Authenticate via device code flow
31
33
  logout Clear stored credentials
32
- push Upload ~/.brain/ to the cloud
34
+ push [--force] Upload ~/.brain/ to the cloud
33
35
  pull Download from the cloud to ~/.brain/
34
36
  status Show connection and sync status
37
+
38
+ Self-hosted store (brain-store):
39
+ login --api-url URL --token-stdin Read the token from standard input, e.g.
40
+ pbpaste | brain cloud login --api-url URL --token-stdin
41
+ login --api-url URL --token TOKEN Pass the token as an argument (it lands in shell history)
42
+ login --api-url URL With BRAIN_STORE_TOKEN set in the environment
43
+ --allow-http Permit plain HTTP to a host other than this machine
44
+
45
+ push refuses to overwrite changes it has not pulled. --force uploads anyway.
35
46
  `.trim());
36
47
  process.exit(0);
37
48
  }
@@ -44,7 +55,7 @@ Commands:
44
55
  cmdLogout();
45
56
  break;
46
57
  case 'push':
47
- await cmdPush();
58
+ await cmdPush(args);
48
59
  break;
49
60
  case 'pull':
50
61
  await cmdPull();
@@ -65,6 +76,17 @@ async function cmdLogin(args) {
65
76
  apiUrl = args[urlIdx + 1];
66
77
  }
67
78
 
79
+ const token = await readToken(args);
80
+ if (token) {
81
+ const result = await cloud.loginWithToken(BRAIN_DIR, apiUrl, token, {
82
+ allowHttp: args.includes('--allow-http'),
83
+ });
84
+ console.log(`✓ Logged in as ${result.user_email || 'unknown'}`);
85
+ console.log(` Brain ID: ${result.brain_id}`);
86
+ console.log(` API: ${result.api_url}`);
87
+ return;
88
+ }
89
+
68
90
  console.log('Requesting device code...');
69
91
  const loginInfo = await cloud.login(BRAIN_DIR, apiUrl);
70
92
 
@@ -88,14 +110,35 @@ async function cmdLogin(args) {
88
110
  console.log(` API: ${config.api_url}`);
89
111
  }
90
112
 
113
+ /**
114
+ * A store token from --token-stdin, --token, or BRAIN_STORE_TOKEN, in that order.
115
+ * Standard input is preferred: it keeps the token out of shell history and out of
116
+ * the process list.
117
+ */
118
+ async function readToken(args) {
119
+ if (args.includes('--token-stdin')) {
120
+ const chunks = [];
121
+ for await (const chunk of process.stdin) chunks.push(chunk);
122
+ const token = Buffer.concat(chunks).toString('utf8').trim();
123
+ if (!token) throw new Error('--token-stdin was given but standard input was empty.');
124
+ return token;
125
+ }
126
+ const idx = args.indexOf('--token');
127
+ if (idx !== -1) {
128
+ if (!args[idx + 1]) throw new Error('--token needs a value.');
129
+ return args[idx + 1];
130
+ }
131
+ return process.env.BRAIN_STORE_TOKEN || null;
132
+ }
133
+
91
134
  function cmdLogout() {
92
135
  cloud.logout(BRAIN_DIR);
93
136
  console.log('✓ Logged out. Credentials cleared.');
94
137
  }
95
138
 
96
- async function cmdPush() {
139
+ async function cmdPush(args) {
97
140
  console.log('Packing ~/.brain/ ...');
98
- const result = await cloud.push(BRAIN_DIR);
141
+ const result = await cloud.push(BRAIN_DIR, { force: args.includes('--force') });
99
142
  console.log();
100
143
  console.log('✓ Push complete!');
101
144
  console.log(` Size: ${formatBytes(result.size_bytes)}`);
package/bin/import.js CHANGED
@@ -9,7 +9,7 @@
9
9
  * anything else. Nothing here writes a memory.
10
10
  *
11
11
  * Usage:
12
- * brain import [--source claude-code] [--project P] [--since ISO] [--limit N] [--all]
12
+ * brain import [--source claude-code|codex] [--project P] [--since ISO] [--limit N] [--all]
13
13
  * brain import --sources List detected history stores
14
14
  * brain import --mark <id> [<id>...] Record sessions as imported
15
15
  *
package/bin/install.js CHANGED
@@ -79,6 +79,14 @@ function warnIfManualRegistration(result, config) {
79
79
  console.log(` ⚠ Could not edit ${configPath} safely (${reg.reason}).`);
80
80
  console.log(` Add "${promptPath}" to its "instructions" array to activate the global prompt.`);
81
81
  }
82
+ const hooks = result.hooks;
83
+ if (hooks && hooks.registered) {
84
+ console.log(` Hooks registered in ${hooks.path} (SessionStart, UserPromptSubmit, SessionEnd).`);
85
+ console.log(' Run /hooks inside Codex once to review and trust them.');
86
+ } else if (hooks && hooks.manual) {
87
+ console.log(` ⚠ Could not edit ${hooks.path} safely (${hooks.reason}).`);
88
+ console.log(' Merge hooks/hooks.json from the brain-memory package into it by hand.');
89
+ }
82
90
  }
83
91
 
84
92
  // ---------------------------------------------------------------------------
@@ -230,6 +238,7 @@ async function runUpdate(flags) {
230
238
  const parts = [];
231
239
  if (d.commandsFound) parts.push('commands');
232
240
  if (d.promptFound) parts.push('prompt');
241
+ if (d.hooksFound) parts.push('hooks');
233
242
  console.log(` ${d.runtimeName} (${d.scope}) — ${parts.join(' + ')}`);
234
243
  }
235
244
 
@@ -272,6 +281,7 @@ async function runUninstall(flags) {
272
281
  const parts = [];
273
282
  if (d.commandsFound) parts.push('commands');
274
283
  if (d.promptFound) parts.push('prompt section');
284
+ if (d.hooksFound) parts.push('hooks');
275
285
  console.log(` ${d.runtimeName} (${d.scope}) — ${parts.join(' + ')}`);
276
286
  }
277
287