brain-memory 0.1.0 → 0.3.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 (46) hide show
  1. package/CHANGELOG.md +216 -0
  2. package/README.md +34 -5
  3. package/bin/audit.js +18 -1
  4. package/bin/brain +4 -0
  5. package/bin/forget.js +10 -1
  6. package/bin/import.js +1 -1
  7. package/bin/install.js +10 -0
  8. package/bin/memorize.js +99 -21
  9. package/bin/recall.js +64 -13
  10. package/bin/reinforce.js +34 -1
  11. package/bin/session-start.js +32 -4
  12. package/bin/skill.js +8 -2
  13. package/bin/verify.js +35 -3
  14. package/commands/brain/import.md +1 -1
  15. package/commands/brain/memorize.md +45 -4
  16. package/commands/brain/remember.md +10 -1
  17. package/commands/brain/skills.md +29 -0
  18. package/commands/brain/sleep.md +1 -1
  19. package/commands/brain/verify.md +6 -0
  20. package/hooks/hooks.json +39 -0
  21. package/hooks/lib.mjs +117 -0
  22. package/hooks/prompt-recall.mjs +123 -0
  23. package/hooks/session-end.md +54 -0
  24. package/hooks/session-end.mjs +63 -0
  25. package/hooks/session-start.md +58 -0
  26. package/hooks/session-start.mjs +82 -0
  27. package/integrations/agentskills/brain-memory/SKILL.md +5 -0
  28. package/package.json +5 -3
  29. package/prompts/antigravity.md +26 -2
  30. package/prompts/claude.md +26 -2
  31. package/prompts/copilot.md +26 -2
  32. package/prompts/kilo.md +26 -2
  33. package/prompts/openai.md +26 -2
  34. package/prompts/opencode.md +26 -2
  35. package/src/anomaly.js +7 -0
  36. package/src/contradiction.js +106 -0
  37. package/src/harvest.js +174 -2
  38. package/src/index-manager.js +8 -0
  39. package/src/installer.js +126 -3
  40. package/src/integrity.js +155 -0
  41. package/src/receipt.js +14 -4
  42. package/src/scorer.js +75 -7
  43. package/src/sensitivity.js +134 -0
  44. package/src/skill-verify.js +191 -0
  45. package/src/skills.js +63 -0
  46. package/src/temporal.js +228 -0
package/CHANGELOG.md CHANGED
@@ -6,6 +6,222 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.3.0] - 2026-09-04
10
+
11
+ Ships brain as a plugin and moves its session behaviour from prompts into
12
+ hooks. The repository is now a Claude Code plugin and a Codex plugin, and a
13
+ marketplace ChatGPT workspaces can import; `SessionStart`, `UserPromptSubmit`
14
+ and `SessionEnd` hooks inject memory deterministically on both hosts instead
15
+ of asking the model to remember to run anything. Memories gain a consent tier
16
+ (`sensitivity`) that matches the published Anthropic vocabulary so the two
17
+ models interoperate, `brain import` learns Codex rollouts, and the earlier
18
+ unreleased work lands: content-integrity baselines, verifiable skills,
19
+ contradiction boundaries, recorded recall history and the benchmark harness.
20
+
21
+ ### Added
22
+
23
+ - **Plugin packaging: one repo, three hosts.** The repository root is now a
24
+ Claude Code plugin (`.claude-plugin/plugin.json`, name `brain` so commands stay
25
+ `/brain:*`), a Codex plugin (`.codex-plugin/plugin.json` overlay — Codex reads
26
+ the Claude manifest and exports `CLAUDE_PLUGIN_ROOT` to plugin hooks), and a
27
+ marketplace for both (`.claude-plugin/marketplace.json`,
28
+ `.agents/plugins/marketplace.json`). ChatGPT Business/Enterprise admins can
29
+ import the same repo (Admin → Plugins → Import marketplace) with daily sync.
30
+ Two plugins: `brain` (local-first: hooks + commands + the bundled CLI via a
31
+ `bin/brain` shim) and `brain-cloud` (the hosted MCP connector only, so
32
+ local-CLI users are never pushed into cloud OAuth).
33
+ - **Sensitive-topic consent tier** (`src/sensitivity.js`). Every memory now
34
+ carries `sensitivity: standard | sensitive | blocked`, using the vocabulary
35
+ of the largest deployed consent model for assistant memory (Anthropic, Aug
36
+ 2026) so brains interoperate with it instead of inventing a schema.
37
+ `sensitive` (health, race, ethnicity, religious beliefs, politics, gender
38
+ identity or sexual orientation) is stored only after the user opts in
39
+ (`sensitive_topics: true` in config.json); until then the write lands
40
+ quarantined (`sensitive_opt_out`) and is hidden from recall and
41
+ session-start, and `brain verify approve` is the per-item consent. `blocked`
42
+ (government ID numbers, criminal history, immigration status) is refused
43
+ outright. The agent classifies; the CLI's patterns are a narrow backstop that
44
+ can raise a label but never lower it. Receipts carry `⚠ sensitive`. Opting in
45
+ is never retroactive. This turns the positioning claim "provenance *and
46
+ consent* on every fragment" from copy into a shipped property.
47
+ - **Codex integration, as hooks.** `brain --codex` now registers brain's three
48
+ hooks in `~/.codex/hooks.json` (non-destructive merge; `/hooks` once to trust)
49
+ in addition to the `AGENTS.md` prompt and skills — the same scripts the plugin
50
+ ships, with `${CLAUDE_PLUGIN_ROOT}` expanded to the npm package path. Codex's
51
+ extension API for rewriting MCP tool results (0.151.0) is compile-time Rust
52
+ inside the Codex binary, so hooks are the integration surface a third party
53
+ actually has. The unshipped `integrations/codex/hooks/` copies and the
54
+ `Stop`-hook turn queue are gone: `brain import --source codex` reads
55
+ `$CODEX_HOME/sessions/` directly.
56
+ - **Prompt-time recall hook** (`UserPromptSubmit`, both hosts). Each substantive
57
+ prompt gets a deterministic `brain recall` pass; the top `prompt_recall_top` (3)
58
+ matches within `prompt_recall_budget_tokens` (600) are injected with receipts
59
+ and a short excerpt, wrapped in `<brain-context>`. The relevance floor means
60
+ unrelated prompts inject nothing; short prompts, slash commands and
61
+ acknowledgements are skipped; nothing is reinforced unless the model uses it.
62
+ - **`brain import --source codex`.** A Codex rollout adapter for
63
+ `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl` (format verified against
64
+ Codex 0.153): genuine prompts are told apart from injected AGENTS.md /
65
+ environment / hook context by `content_item_kinds` (marker matching for
66
+ pre-0.148 files), background threads (subagent, guardian, consolidation) are
67
+ skipped, thread names come from `session_index.jsonl`, touched files from
68
+ `apply_patch` calls. Harvest now also strips brain's own `<brain-context>`
69
+ and `<brain-session-context>` injections, so recalled memories are never
70
+ harvested back into new ones.
71
+ - **`brain session-start --budget N`** tightens the working-memory cap for one
72
+ call (never raises it) — for hosts with a smaller injection window than
73
+ config.json assumes. `brain recall` is now importable in-process
74
+ (`computeRecall`) with byte-identical scoring to the CLI.
75
+ - **Deterministic hooks for Claude Code and Codex** (`hooks/hooks.json`,
76
+ shared by both hosts). `SessionStart` injects the `brain session-start`
77
+ payload plus the ambient rules as `additionalContext` — the first time Claude
78
+ Code gets brain's session-start behaviour from the host rather than from a
79
+ prompt the model has to obey. `SessionEnd` appends a session-boundary entry
80
+ to `~/.brain/contexts.json`. Hooks run the engine in-process from the plugin
81
+ root, fail soft (`{}` + exit 0), and never touch a brain that does not exist.
82
+ - **Content integrity baselines (OWASP ASI06, Store phase).** Every memory is
83
+ hashed (SHA-256) at write time, and `brain audit` reports memories whose bytes
84
+ no longer match. Closes the one poisoning route every other defense here was
85
+ blind to: an editor. Provenance, content-lint, quarantine, and anomaly
86
+ detection all guard the *write path* and assume an attacker arrives through
87
+ `brain memorize` — but `~/.brain/` is plain Markdown, so anything with write
88
+ access to the home directory could rewrite a trusted, pinned memory without
89
+ touching the index, the audit log, or any origin label. Drift findings are
90
+ **advisory** (sleep and the user both edit files legitimately) and are never
91
+ auto-quarantined. Re-baseline with `brain audit --rebaseline`.
92
+ - **Contradiction proposals carry the boundary.** `potential_conflicts` now
93
+ reports `proposed_valid_until` — the exact instant a supersede would stamp on
94
+ the older memory — plus `authority` and `shared_tags`. Detection also widened
95
+ beyond pinned/stable to like-for-like memories (a `decision` that may have
96
+ replaced a `decision`), which is the ordinary "we changed our minds" case
97
+ users never think to flag. Still never auto-resolved: tag overlap is a
98
+ relatedness signal, not a contradiction signal.
99
+ - **Verifiable skills** (`brain skill verify <name>`). A skill may declare
100
+ read-only preconditions (`file_exists`, `file_absent`, `file_contains`,
101
+ `command_available`, `env_set`) that are checked against the working directory
102
+ without running the agent, so a skill distilled against a repo layout that has
103
+ since changed is caught in milliseconds instead of after several real
104
+ failures. Checks are **declarative by design** — skills are crystallized
105
+ automatically, they sync, and they can be imported, so a `verify` field
106
+ holding arbitrary shell would be a memory file that executes code. Failure
107
+ demotes; passing does not promote.
108
+ - **`recall_history` is actually recorded.** The field was declared in the
109
+ schema, documented in all six agent prompts and three docs pages, and never
110
+ written — `brain reinforce` updated `access_count` but not the series, so the
111
+ brain knew a memory had been recalled N times and never *when*. Each
112
+ reinforcement now appends a capped row (timestamp, interval, strength
113
+ before/after).
114
+ - **Benchmark: LongMemEval-S adapter** (`harness/longmemeval.js`). Scores the
115
+ retrieval half of the public 500-question benchmark with no LLM spend.
116
+ Brain: **R@5 = 0.909** over ~48-session haystacks.
117
+ - **Benchmark: real-embedding arm** (`harness/retrievers/dense.js`) and a
118
+ **retrieval-only pilot** (`harness/retrieval-only.js`) that scores Recall@k
119
+ for every retriever without an agent. The existing `vector-baseline` arm is a
120
+ hashed bag-of-words, not a semantic model, and could not answer whether
121
+ embeddings help; `dense` can.
122
+ - **Benchmark: decay calibration** (`harness/decay-calibration.js`). Compares
123
+ each memory type's implied half-life against observed recall intervals.
124
+
125
+ ### Fixed
126
+
127
+ - **Frontmatter serializer corrupted arrays of objects.** `updateMemoryFile`
128
+ rendered them via `String(value)`, producing `[object Object]` — lossy and
129
+ invalid YAML. Now JSON-encoded (a YAML subset), so they round-trip.
130
+
131
+ ### Changed
132
+
133
+ - **Positioning: two claims added, one now evidence-backed.** Deterministic
134
+ cross-agent ranking and poisoning resistance are stated in the README and on
135
+ the site. "No embeddings required" is no longer an assertion: on the hardest
136
+ retrieval scenario a real embedding model ranked the target memories *worse*
137
+ than BM25 (oracle ranks 45/20/15 plain, 21/20/8 with the model's task
138
+ prefixes, vs BM25's 21/20/1), and ties it at 0.909 R@5 on LongMemEval-S.
139
+ - **`brain-bm25` is rank-identical to plain BM25** on both scenario A and all
140
+ 500 LongMemEval-S instances. Title-3x/tags-2x field weighting and the custom
141
+ stemmer buy nothing measurable — Brain's advantage lives in decay, spreading
142
+ activation, context match, and pinning, not the relevance function.
143
+ - **Single-principal invariant documented.** "One brain, one person" is now an
144
+ explicit design principle; `scope` and `principal` are reserved frontmatter
145
+ field names.
146
+
147
+
148
+ ## [0.2.0] - 2026-08-18
149
+
150
+ Adds the second time axis. Memory now records not just when it learned a
151
+ fact but when that fact was true, so recall can answer "what was true in
152
+ March?" instead of ranking a stale answer first — and closes two
153
+ supersession holes that, chained, let an unverified write quietly demote a
154
+ trusted memory.
155
+
156
+ ### Added
157
+
158
+ - **Bitemporal validity.** Memories now carry a valid-time window
159
+ (`valid_from` / `valid_until`, half-open `[from, until)`) alongside the
160
+ record time they already had (`created`) — the difference between *when a
161
+ fact was true* and *when the brain learned it*. Two new recall flags travel
162
+ back along each axis: `brain recall "<q>" --as-of <date>` returns what was
163
+ **true** at that instant (and lifts the supersession demotion for memories
164
+ still inside their window — at that moment they were simply the truth), and
165
+ `--as-known-of <date>` returns what the brain had **recorded** by then. Pass
166
+ both to reconstruct exactly what the brain believed, and when. Superseding
167
+ stamps the predecessor's `valid_until` automatically, so the existing corpus
168
+ gains real validity windows without re-authoring anything. An expired memory
169
+ is demoted and marked (`expired: true`, `⌛ expired` on its receipt), never
170
+ deleted — "that was true until June" stays answerable. Inverted or
171
+ unparseable windows are rejected at write time, as are unparseable `--as-of`
172
+ bounds; silently ignoring one would answer a point-in-time question with
173
+ present-day memories.
174
+ - **Expired pins are held out of the always-apply tier.** A pinned memory whose
175
+ validity window has closed is no longer injected every session as an active
176
+ constraint; session start reports the count as `expired_pins` so it can be
177
+ updated or unpinned. It stays reachable through ordinary recall.
178
+ - **Bitemporal on the hosted connector.** `brain_recall` gained `as_of` and
179
+ `as_known_of`; `brain_memorize` gained `valid_from`, `valid_until`, and
180
+ `supersedes`. Expired hits are called out in the text channel rather than only
181
+ as a JSON field, and a replacement held back by quarantine is stated
182
+ explicitly ("the replacement of X is HELD until you approve this write; those
183
+ memories are still current") instead of failing silently.
184
+ - **`brain-connector-gated` benchmark arm.** Brain ships two retrieval
185
+ *policies* and only one was measured: the local plugin injects ranked memory
186
+ at session start unconditionally, while the hosted connector advertises memory
187
+ as tools and lets the model decide whether to recall at all. The new arm
188
+ models that gating policy — the model sees the connector's real tool
189
+ advertisement and the task, decides, and if it recalls, the engine runs with
190
+ *its own* query. The gate call's tokens are charged to the arm and a decline
191
+ scores as a retrieval miss rather than "not measured", so the policy can't
192
+ flatter itself. Each run records whether the model declined to look or looked
193
+ with a poor query — different failures, different fixes.
194
+
195
+ ### Fixed
196
+
197
+ - **A quarantined write could demote a trusted memory before anyone looked at
198
+ it** (ASI06). `supersedes` was applied unconditionally, so a memory written
199
+ from a fetched page or tool result — pending verification precisely because
200
+ it isn't trusted — immediately stamped `superseded_by` on its target and cut
201
+ that memory's recall score to a quarter. The stamp is now withheld while a
202
+ write is quarantined (reported as `supersede_pending`) and applied by
203
+ `brain verify approve`; rejection leaves the original untouched.
204
+ - **Archiving a memory left everything it had superseded permanently demoted**,
205
+ behind a `superseded_by` pointer to an id that no longer existed — so
206
+ rejecting a poisoned write archived the write but kept its damage. Archival
207
+ (and therefore `brain verify reject` and `brain forget`) now withdraws the
208
+ supersessions a memory imposed, reported as `released`. Automatically stamped
209
+ validity is withdrawn with it; a window set by hand is left alone.
210
+ - **Corrected a false MCP conformance claim in the connector.** A note in
211
+ `connector/src/result.ts` described its `_meta` cache marker as
212
+ "forward-compatible with the final spec". Checked against the final
213
+ 2026-07-28 text (SEP-2549) it isn't: `cacheScope`/`ttlMs` are top-level fields
214
+ on `CacheableResult` and apply to `tools/list`, `prompts/list`,
215
+ `resources/list`, `resources/read`, and `resources/templates/list` —
216
+ `tools/call` is not a cacheable result, so a memory response carries no spec
217
+ `cacheScope` at all. The marker stays as deliberate defense-in-depth against
218
+ an intermediary that caches tool output heuristically; it is simply no longer
219
+ described as conformance. `connector/docs/mcp-2026-07-28-conformance.md`
220
+ records the verified per-item status: statelessness and the OAuth 2.1
221
+ resource-server requirements are met, while `server/discover`, per-request
222
+ `_meta`, and `tools/list` caching are blocked on the TypeScript SDK — both
223
+ 1.29.0 and the current latest 1.30.0 still top out at protocol 2025-11-25.
224
+
9
225
  ## [0.1.0] - 2026-08-08
10
226
 
11
227
  First stable release. Completes the memory-poisoning defense (OWASP ASI06),
package/README.md CHANGED
@@ -41,7 +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
+ - **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
45
47
  - **Associative network** — Memories link to each other with weighted connections. Recalling one activates related ones automatically
46
48
  - **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
47
49
  - **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
@@ -50,7 +52,7 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
50
52
  - **Procedural skills** — Reusable how-to workflows with progressive disclosure, learned automatically from repeated experience and exportable to your agent's native skills
51
53
  - **On-demand depth** — Subcategories are created as needed, not pre-defined
52
54
  - **Consolidation** — Weak related memories merge into stronger combined knowledge
53
- - **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)
54
56
 
55
57
  ## Install
56
58
 
@@ -123,7 +125,7 @@ The first time a host connects you'll complete an OAuth sign-in with the Google
123
125
  ### 2. Local-first path — the native plugin
124
126
 
125
127
  ```bash
126
- npm install -g brain-memory@beta
128
+ npm install -g brain-memory
127
129
  brain
128
130
  ```
129
131
 
@@ -134,12 +136,28 @@ The second command runs the setup wizard, which asks which runtime(s) to configu
134
136
  | Runtime | Instructions file | Commands land at |
135
137
  |---------|-------------------|------------------|
136
138
  | **Claude Code** | `CLAUDE.md` | `~/.claude/commands/brain/` (plugin slash commands) |
137
- | **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` |
138
140
  | **OpenCode** | `AGENTS.md` | `~/.config/opencode/commands/` |
139
141
  | **GitHub Copilot CLI** | `copilot-instructions.md` (`~/.copilot/`), repo-local `AGENTS.md` | `~/.agents/skills/<name>/SKILL.md` (shared with Codex) |
140
142
  | **Kilo** | `rules/brain-memory.md` + `kilo.jsonc` `instructions` entry (`~/.config/kilo/`), repo-local `AGENTS.md` | `~/.config/kilo/commands/` |
141
143
  | **Google Antigravity** | `GEMINI.md` | `~/.gemini/skills/` *(experimental — verify paths against a live install)* |
142
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
+
143
161
  #### Non-interactive
144
162
 
145
163
  ```bash
@@ -178,7 +196,7 @@ Both are backed by the same `brain` CLI the coding-agent installs use — one me
178
196
  ### Update
179
197
 
180
198
  ```bash
181
- npm install -g brain-memory@beta
199
+ npm install -g brain-memory
182
200
  brain update
183
201
  ```
184
202
 
@@ -425,6 +443,10 @@ strength: 0.92
425
443
  decay_rate: 0.995
426
444
  salience: 0.8
427
445
  confidence: 0.9
446
+ # Valid time — when the fact was TRUE, as distinct from `created` above (when
447
+ # it was recorded). Optional and half-open [from, until); omit for facts that
448
+ # are simply true. Superseding stamps `valid_until` on the old memory for you.
449
+ valid_from: 2026-02-13T14:30:00Z
428
450
  tags: [architecture, microservices, scaling]
429
451
  related: [mem_20260210_b4e5d6]
430
452
  source: project-alpha-session
@@ -542,6 +564,9 @@ Each recall also improves the memory's decay rate: `new_rate = rate + 0.10 * (0.
542
564
 
543
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.
544
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
+
545
570
  ### Consolidation
546
571
 
547
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:
@@ -739,6 +764,10 @@ Brain configuration lives in `~/.brain/index.json` under the `config` key:
739
764
  | `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
740
765
  | `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
741
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
+
742
771
  ### Working-Memory Budget
743
772
 
744
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/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/forget.js CHANGED
@@ -36,6 +36,7 @@ const {
36
36
  // re-appends `.brain`, which would silently no-op the search-index update here.)
37
37
  const { removeDocument, readSearchIndex, writeSearchIndex } = require('../src/tfidf');
38
38
  const { appendAudit } = require('../src/audit');
39
+ const { clearSupersessionsBy } = require('../src/temporal');
39
40
 
40
41
  // CoALA salience protection: high-salience memories are "never auto-pruned"
41
42
  // (the documented guarantee). Enforced deterministically here — the only
@@ -97,7 +98,12 @@ function archiveMemory(brainDir, id, opts = {}) {
97
98
  arch.archived_count = Object.keys(arch.memories).length;
98
99
  writeArchiveIndex(arch);
99
100
 
100
- // 3. Remove from the live index.
101
+ // 3. Withdraw any supersession this memory imposed, then remove it from the
102
+ // live index. Order matters: the sweep reads `superseded_by` back-pointers
103
+ // out of the index, and without it every memory this one replaced would stay
104
+ // demoted 4x at recall forever, behind a pointer to an id that no longer
105
+ // exists — so rejecting a poisoned write would leave its damage in place.
106
+ const released = clearSupersessionsBy(brainDir, index, id);
101
107
  removeMemory(index, id);
102
108
  writeIndex(index);
103
109
 
@@ -127,6 +133,7 @@ function archiveMemory(brainDir, id, opts = {}) {
127
133
  appendAudit(brainDir, {
128
134
  ts: now, event: 'forget', id, title: entry.title, path: entry.path,
129
135
  origin: entry.origin, salience: entry.salience, reason, forced: force,
136
+ ...(released.length ? { released } : {}),
130
137
  });
131
138
  } catch (err) {
132
139
  auditError = err.message;
@@ -134,6 +141,8 @@ function archiveMemory(brainDir, id, opts = {}) {
134
141
 
135
142
  return {
136
143
  archived: true, id, title: entry.title, memory_count: index.memory_count,
144
+ // Memories this one had superseded, now restored to full recall weight.
145
+ ...(released.length ? { released } : {}),
137
146
  ...(auditError ? { audit_error: auditError } : {}),
138
147
  };
139
148
  }
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