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.
- package/CHANGELOG.md +216 -0
- package/README.md +34 -5
- package/bin/audit.js +18 -1
- package/bin/brain +4 -0
- package/bin/forget.js +10 -1
- package/bin/import.js +1 -1
- package/bin/install.js +10 -0
- package/bin/memorize.js +99 -21
- package/bin/recall.js +64 -13
- package/bin/reinforce.js +34 -1
- package/bin/session-start.js +32 -4
- package/bin/skill.js +8 -2
- package/bin/verify.js +35 -3
- package/commands/brain/import.md +1 -1
- package/commands/brain/memorize.md +45 -4
- package/commands/brain/remember.md +10 -1
- package/commands/brain/skills.md +29 -0
- package/commands/brain/sleep.md +1 -1
- package/commands/brain/verify.md +6 -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 +5 -3
- package/prompts/antigravity.md +26 -2
- package/prompts/claude.md +26 -2
- package/prompts/copilot.md +26 -2
- package/prompts/kilo.md +26 -2
- package/prompts/openai.md +26 -2
- package/prompts/opencode.md +26 -2
- package/src/anomaly.js +7 -0
- 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 +14 -4
- package/src/scorer.js +75 -7
- package/src/sensitivity.js +134 -0
- package/src/skill-verify.js +191 -0
- package/src/skills.js +63 -0
- 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
|
|
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
|
|
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
|
|
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
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.
|
|
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
|
|