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.
- package/CHANGELOG.md +193 -0
- package/README.md +27 -3
- package/SECURITY.md +44 -3
- package/bin/audit.js +18 -1
- package/bin/brain +4 -0
- package/bin/cloud-sync.js +49 -6
- package/bin/import.js +1 -1
- package/bin/install.js +10 -0
- package/bin/memorize.js +53 -8
- package/bin/recall.js +32 -13
- package/bin/reinforce.js +34 -1
- package/bin/session-start.js +17 -4
- package/bin/skill.js +8 -2
- package/commands/brain/import.md +1 -1
- package/commands/brain/memorize.md +25 -4
- package/commands/brain/skills.md +29 -0
- package/commands/brain/sync.md +23 -0
- package/hooks/hooks.json +39 -0
- package/hooks/lib.mjs +117 -0
- package/hooks/prompt-recall.mjs +123 -0
- package/hooks/session-end.md +54 -0
- package/hooks/session-end.mjs +63 -0
- package/hooks/session-start.md +58 -0
- package/hooks/session-start.mjs +82 -0
- package/integrations/agentskills/brain-memory/SKILL.md +5 -0
- package/package.json +10 -4
- package/prompts/antigravity.md +4 -1
- package/prompts/claude.md +4 -1
- package/prompts/copilot.md +4 -1
- package/prompts/kilo.md +4 -1
- package/prompts/openai.md +4 -1
- package/prompts/opencode.md +4 -1
- package/src/anomaly.js +7 -0
- package/src/cloud-sync.js +121 -9
- package/src/contradiction.js +106 -0
- package/src/harvest.js +174 -2
- package/src/index-manager.js +8 -0
- package/src/installer.js +126 -3
- package/src/integrity.js +155 -0
- package/src/receipt.js +8 -4
- package/src/sensitivity.js +134 -0
- package/src/skill-verify.js +191 -0
- package/src/skills.js +63 -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 +145 -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 +217 -0
- 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
|
|
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**
|
|
68
|
-
|
|
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.
|
|
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
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
|
|
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
|
|
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
|
|
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
|
|