brain-memory 0.2.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 +139 -0
- package/README.md +27 -3
- package/bin/audit.js +18 -1
- package/bin/brain +4 -0
- 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/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 +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/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/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,145 @@ 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
|
+
|
|
9
148
|
## [0.2.0] - 2026-08-18
|
|
10
149
|
|
|
11
150
|
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/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/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
|
|
package/bin/memorize.js
CHANGED
|
@@ -38,6 +38,8 @@ const {
|
|
|
38
38
|
const { addDocument, createSearchIndex, readSearchIndex, writeSearchIndex } = require('../src/tfidf');
|
|
39
39
|
const { appendAudit } = require('../src/audit');
|
|
40
40
|
const { lintMemoryContent } = require('../src/content-lint');
|
|
41
|
+
const { contentHash } = require('../src/integrity');
|
|
42
|
+
const { proposeSupersessions } = require('../src/contradiction');
|
|
41
43
|
const { quarantineDecision } = require('../src/quarantine');
|
|
42
44
|
const {
|
|
43
45
|
validateValidity,
|
|
@@ -88,6 +90,7 @@ const COGNITIVE_ADJUSTMENTS = {
|
|
|
88
90
|
// that holds regardless of caller honesty: entrenchment is simply not
|
|
89
91
|
// reachable from this path without an explicit user origin.
|
|
90
92
|
const { ORIGIN_POLICY, DEFAULT_ORIGIN } = require('../src/provenance');
|
|
93
|
+
const { sensitivityDecision, SENSITIVE_OPT_OUT_REASON } = require('../src/sensitivity');
|
|
91
94
|
|
|
92
95
|
// --- Args ---
|
|
93
96
|
|
|
@@ -222,6 +225,8 @@ function buildMemoryFileContent(mem, id, now, origin, originDecayMultiplier, qua
|
|
|
222
225
|
// (when it was recorded). Emitted only when the author bounded it.
|
|
223
226
|
if (mem.valid_from) fmLines.push(`valid_from: "${mem.valid_from}"`);
|
|
224
227
|
if (mem.valid_until) fmLines.push(`valid_until: "${mem.valid_until}"`);
|
|
228
|
+
// Consent tier (src/sensitivity.js) — only non-standard levels are written.
|
|
229
|
+
if (mem.sensitivity && mem.sensitivity !== 'standard') fmLines.push(`sensitivity: "${mem.sensitivity}"`);
|
|
225
230
|
fmLines.push(
|
|
226
231
|
`tags: [${(mem.tags || []).map(t => `"${t}"`).join(', ')}]`,
|
|
227
232
|
`related: [${(mem.related || []).map(r => `"${r}"`).join(', ')}]`,
|
|
@@ -277,6 +282,7 @@ function buildIndexEntry(mem, id, strength, decayRate, now, origin, quarantine)
|
|
|
277
282
|
if (mem.supersedes && mem.supersedes.length) entry.supersedes = mem.supersedes;
|
|
278
283
|
if (mem.valid_from) entry.valid_from = mem.valid_from;
|
|
279
284
|
if (mem.valid_until) entry.valid_until = mem.valid_until;
|
|
285
|
+
if (mem.sensitivity && mem.sensitivity !== 'standard') entry.sensitivity = mem.sensitivity;
|
|
280
286
|
return entry;
|
|
281
287
|
}
|
|
282
288
|
|
|
@@ -486,6 +492,31 @@ async function main() {
|
|
|
486
492
|
const lint = lintMemoryContent(mem);
|
|
487
493
|
const quarantine = quarantineDecision({ origin, lintResult: lint, config });
|
|
488
494
|
|
|
495
|
+
// Sensitive-topic consent (src/sensitivity.js). `blocked` content is
|
|
496
|
+
// refused outright; `sensitive` content is stored only after the user
|
|
497
|
+
// opted in — otherwise it lands quarantined and hidden, and approving it
|
|
498
|
+
// is the per-item consent. Evaluated after the origin gate so a refusal
|
|
499
|
+
// names the real reason, and before anything reaches disk.
|
|
500
|
+
const sensitivity = sensitivityDecision(mem, config);
|
|
501
|
+
if (sensitivity.error) {
|
|
502
|
+
console.error(JSON.stringify({ error: `${sensitivity.error} — memory: ${JSON.stringify(rawMem.title)}` }));
|
|
503
|
+
process.exit(1);
|
|
504
|
+
}
|
|
505
|
+
if (sensitivity.action === 'refuse') {
|
|
506
|
+
console.error(JSON.stringify({
|
|
507
|
+
error: `Refused: content classified "blocked" (${sensitivity.categories.join(', ') || 'declared by caller'}) — ` +
|
|
508
|
+
`identification numbers, criminal history and immigration status are never stored — memory: ${JSON.stringify(rawMem.title)}`,
|
|
509
|
+
sensitivity: 'blocked',
|
|
510
|
+
categories: sensitivity.categories,
|
|
511
|
+
}));
|
|
512
|
+
process.exit(1);
|
|
513
|
+
}
|
|
514
|
+
if (sensitivity.action === 'quarantine') {
|
|
515
|
+
quarantine.quarantined = true;
|
|
516
|
+
quarantine.reasons = [...quarantine.reasons, SENSITIVE_OPT_OUT_REASON];
|
|
517
|
+
}
|
|
518
|
+
mem.sensitivity = sensitivity.level;
|
|
519
|
+
|
|
489
520
|
// Generate ID
|
|
490
521
|
const id = generateId();
|
|
491
522
|
newIds.push(id);
|
|
@@ -523,6 +554,7 @@ async function main() {
|
|
|
523
554
|
clamped: policy.clamps.map((c) => c.field),
|
|
524
555
|
...(lint.flags.length ? { lint: lint.flags.map((f) => f.rule) } : {}),
|
|
525
556
|
...(quarantine.quarantined ? { quarantined: true, quarantine_reasons: quarantine.reasons } : {}),
|
|
557
|
+
...(mem.sensitivity !== 'standard' ? { sensitivity: mem.sensitivity, sensitivity_categories: sensitivity.categories } : {}),
|
|
526
558
|
});
|
|
527
559
|
} catch (err) {
|
|
528
560
|
auditErrors.push({ id, error: err.message });
|
|
@@ -530,6 +562,12 @@ async function main() {
|
|
|
530
562
|
|
|
531
563
|
// Update index
|
|
532
564
|
const indexEntry = buildIndexEntry(mem, id, strength, decay_rate, now, origin, quarantine);
|
|
565
|
+
// Integrity baseline (OWASP ASI06, Store phase): record what this memory
|
|
566
|
+
// said the moment the brain agreed with it, hashed from the exact bytes
|
|
567
|
+
// just written. `brain audit` compares against this to catch edits that
|
|
568
|
+
// never came through a write path — the one poisoning route every other
|
|
569
|
+
// defense here is blind to. See src/integrity.js.
|
|
570
|
+
indexEntry.content_hash = contentHash(fileContent);
|
|
533
571
|
addMemory(index, id, indexEntry);
|
|
534
572
|
|
|
535
573
|
// CoALA Phase 1: register a born-pinned memory in the pinned manifest
|
|
@@ -579,14 +617,17 @@ async function main() {
|
|
|
579
617
|
reinforceEdge(associations, id, overlapId, 'tag_overlap', 0.10);
|
|
580
618
|
}
|
|
581
619
|
|
|
582
|
-
// Tier B §10.2: surface potential contradictions
|
|
583
|
-
//
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
620
|
+
// Tier B §10.2: surface potential contradictions so the agent can
|
|
621
|
+
// adjudicate — never auto-resolved here. Each proposal carries the
|
|
622
|
+
// `valid_until` a supersede would stamp, so the agent can offer the
|
|
623
|
+
// boundary ("shall I mark the old one as ended on <date>?") instead of
|
|
624
|
+
// leaving two unbounded facts competing in every future recall.
|
|
625
|
+
const potentialConflicts = proposeSupersessions(
|
|
626
|
+
index,
|
|
627
|
+
{ ...mem, created: now },
|
|
628
|
+
tagOverlaps,
|
|
629
|
+
{ now },
|
|
630
|
+
);
|
|
590
631
|
|
|
591
632
|
// Update search index
|
|
592
633
|
addDocument(searchIndex, id, {
|
|
@@ -620,6 +661,10 @@ async function main() {
|
|
|
620
661
|
? { quarantine_pending: true, quarantine_reasons: quarantine.reasons }
|
|
621
662
|
: {}),
|
|
622
663
|
...(lint.flags.length ? { lint_flags: lint.flags.map((f) => f.rule) } : {}),
|
|
664
|
+
// Consent tier. `sensitive_opt_out` means the memory is stored but hidden
|
|
665
|
+
// until the user opts in (config) or approves it (`brain verify approve`).
|
|
666
|
+
...(mem.sensitivity !== 'standard' ? { sensitivity: mem.sensitivity } : {}),
|
|
667
|
+
...(sensitivity.action === 'quarantine' ? { sensitive_opt_out: true } : {}),
|
|
623
668
|
...(supersededNow.length ? { superseded: supersededNow } : {}),
|
|
624
669
|
// Held back until verification — surfaced so the agent can tell the user
|
|
625
670
|
// the replacement it asked for has not taken effect yet.
|
package/bin/recall.js
CHANGED
|
@@ -47,6 +47,7 @@ const {
|
|
|
47
47
|
const { receiptFor } = require('../src/receipt');
|
|
48
48
|
const { DEFAULT_ORIGIN, isLowTrust } = require('../src/provenance');
|
|
49
49
|
const { parseInstant } = require('../src/temporal');
|
|
50
|
+
const { isSensitiveHidden } = require('../src/sensitivity');
|
|
50
51
|
|
|
51
52
|
// Minimum relevance (or spreading bonus) for a memory to appear in explicit-
|
|
52
53
|
// query results. Filters the zero/near-zero-relevance memories that would
|
|
@@ -85,19 +86,32 @@ function main() {
|
|
|
85
86
|
process.exit(1);
|
|
86
87
|
}
|
|
87
88
|
|
|
88
|
-
let
|
|
89
|
+
let results;
|
|
89
90
|
try {
|
|
90
|
-
|
|
91
|
+
results = computeRecall(args);
|
|
91
92
|
} catch (err) {
|
|
92
93
|
console.error(JSON.stringify({
|
|
93
94
|
error: `Corrupt index.json in ~/.brain/ — ${err.message}. Fix the JSON manually or restore from sync/backup.`,
|
|
94
95
|
}));
|
|
95
96
|
process.exit(1);
|
|
96
97
|
}
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
98
|
+
|
|
99
|
+
console.log(JSON.stringify(results, null, 2));
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Rank memories for a query — the engine behind `brain recall`, callable
|
|
104
|
+
* in-process (plugin hooks, tests) with byte-identical scoring to the CLI.
|
|
105
|
+
* Throws when index.json is corrupt; returns [] for an empty brain.
|
|
106
|
+
*
|
|
107
|
+
* @param {Object} args - { query, project, task, topics, top, context, asOf, asKnownOf }
|
|
108
|
+
* @param {string} [projectRoot] - Filesystem root whose .brain/ to read
|
|
109
|
+
* @returns {Object[]} scored results, best first
|
|
110
|
+
*/
|
|
111
|
+
function computeRecall(args, projectRoot) {
|
|
112
|
+
const brainDir = getBrainDir(projectRoot);
|
|
113
|
+
const index = readIndex(projectRoot);
|
|
114
|
+
if (!index || !index.memories || Object.keys(index.memories).length === 0) return [];
|
|
101
115
|
|
|
102
116
|
// Ensure search index exists
|
|
103
117
|
let searchIndex;
|
|
@@ -129,9 +143,13 @@ function main() {
|
|
|
129
143
|
// verification) memories are excluded here — before ranking — which also
|
|
130
144
|
// removes them as spreading-activation sources. readConfig tolerates a
|
|
131
145
|
// missing/corrupt config.json (falls back to the 'flag' default).
|
|
132
|
-
const
|
|
146
|
+
const config = readConfig(projectRoot);
|
|
147
|
+
const quarantineMode = config.quarantine_mode || 'flag';
|
|
148
|
+
// Sensitive-topic memories are hidden until the user opts in (config) or
|
|
149
|
+
// approves them individually — consent is evaluated at read time too.
|
|
133
150
|
const memories = Object.entries(index.memories)
|
|
134
151
|
.filter(([, entry]) => quarantineMode !== 'enforce' || !entry.quarantined)
|
|
152
|
+
.filter(([, entry]) => !isSensitiveHidden(entry, config))
|
|
135
153
|
.map(([id, entry]) => ({
|
|
136
154
|
id,
|
|
137
155
|
...entry,
|
|
@@ -140,7 +158,7 @@ function main() {
|
|
|
140
158
|
// Load associations for spreading activation
|
|
141
159
|
let associations;
|
|
142
160
|
try {
|
|
143
|
-
associations = readAssociations();
|
|
161
|
+
associations = readAssociations(projectRoot);
|
|
144
162
|
} catch (_) {
|
|
145
163
|
associations = null;
|
|
146
164
|
}
|
|
@@ -149,7 +167,7 @@ function main() {
|
|
|
149
167
|
const recallContext = {};
|
|
150
168
|
if (args.project) recallContext.project = args.project;
|
|
151
169
|
if (args.task) recallContext.task_type = args.task;
|
|
152
|
-
if (args.topics) recallContext.topics = args.topics.split(',');
|
|
170
|
+
if (args.topics) recallContext.topics = String(args.topics).split(',');
|
|
153
171
|
|
|
154
172
|
// Rank using scorer.js with TF-IDF as the relevance function
|
|
155
173
|
const ranked = rankMemories(
|
|
@@ -168,7 +186,7 @@ function main() {
|
|
|
168
186
|
|
|
169
187
|
// Return top N
|
|
170
188
|
const top = args.top || 10;
|
|
171
|
-
|
|
189
|
+
return ranked.slice(0, top).map((mem) => {
|
|
172
190
|
const title = mem.title || path.basename(mem.path, '.md');
|
|
173
191
|
const origin = mem.origin || DEFAULT_ORIGIN;
|
|
174
192
|
return {
|
|
@@ -199,14 +217,13 @@ function main() {
|
|
|
199
217
|
...(mem.valid_from ? { valid_from: mem.valid_from } : {}),
|
|
200
218
|
...(mem.valid_until ? { valid_until: mem.valid_until } : {}),
|
|
201
219
|
...(mem.temporal_state === 'expired' ? { expired: true } : {}),
|
|
220
|
+
...(mem.sensitivity && mem.sensitivity !== 'standard' ? { sensitivity: mem.sensitivity } : {}),
|
|
202
221
|
tags: mem.tags,
|
|
203
222
|
// Recall receipt — the engine mints it, agents copy it verbatim when
|
|
204
223
|
// this memory materially shapes an answer (so it can't be hallucinated).
|
|
205
224
|
receipt: receiptFor({ ...mem, title }),
|
|
206
225
|
};
|
|
207
226
|
});
|
|
208
|
-
|
|
209
|
-
console.log(JSON.stringify(results, null, 2));
|
|
210
227
|
}
|
|
211
228
|
|
|
212
229
|
/**
|
|
@@ -316,4 +333,6 @@ function parseArgs(argv) {
|
|
|
316
333
|
return args;
|
|
317
334
|
}
|
|
318
335
|
|
|
319
|
-
main();
|
|
336
|
+
if (require.main === module) main();
|
|
337
|
+
|
|
338
|
+
module.exports = { main, computeRecall, parseArgs, RELEVANCE_FLOOR };
|
package/bin/reinforce.js
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
* - Spaced reinforcement boost to each memory's strength
|
|
16
16
|
* - Decay rate improvement (more forgetting-resistant)
|
|
17
17
|
* - access_count++, last_accessed = now
|
|
18
|
+
* - recall_history entry (timestamp + interval + strength delta), capped
|
|
18
19
|
* - Hebbian co-retrieval: strengthens association edges between all pairs
|
|
19
20
|
* - Updates index.json, associations.json, and memory files
|
|
20
21
|
*/
|
|
@@ -38,6 +39,10 @@ const {
|
|
|
38
39
|
improveDecayRate,
|
|
39
40
|
} = require('../src/scorer');
|
|
40
41
|
|
|
42
|
+
// Recall-history rows kept per memory. Enough to fit an interval curve;
|
|
43
|
+
// small enough that a hot memory's frontmatter stays cheap to parse.
|
|
44
|
+
const RECALL_HISTORY_MAX = 50;
|
|
45
|
+
|
|
41
46
|
function main() {
|
|
42
47
|
const args = parseArgs(process.argv.slice(2));
|
|
43
48
|
|
|
@@ -86,12 +91,35 @@ function main() {
|
|
|
86
91
|
entry.last_accessed = nowISO;
|
|
87
92
|
entry.access_count = accessCount + 1;
|
|
88
93
|
|
|
94
|
+
// Recall history: one row per reinforcement, capped.
|
|
95
|
+
//
|
|
96
|
+
// `access_count` says a memory was recalled N times; it cannot say *when*,
|
|
97
|
+
// and the interval is the entire signal. Spaced reinforcement is built on
|
|
98
|
+
// the premise that longer gaps produce larger, more durable boosts — but
|
|
99
|
+
// without the timestamps that premise is unfalsifiable, and the decay
|
|
100
|
+
// constants stay hand-set forever because there is nothing to fit them to.
|
|
101
|
+
// This is the series that makes calibration possible (see
|
|
102
|
+
// benchmark/harness/decay-calibration.js).
|
|
103
|
+
//
|
|
104
|
+
// Bounded at RECALL_HISTORY_MAX: a frequently-recalled memory would
|
|
105
|
+
// otherwise grow an unbounded array inside a file that is read on every
|
|
106
|
+
// recall. Oldest rows drop first; the recent intervals carry the signal.
|
|
107
|
+
const history = Array.isArray(entry.recall_history) ? entry.recall_history : [];
|
|
108
|
+
history.push({
|
|
109
|
+
at: nowISO,
|
|
110
|
+
days_since_last: Math.round(daysSince * 100) / 100,
|
|
111
|
+
strength_before: oldStrength,
|
|
112
|
+
strength_after: entry.strength,
|
|
113
|
+
});
|
|
114
|
+
entry.recall_history = history.slice(-RECALL_HISTORY_MAX);
|
|
115
|
+
|
|
89
116
|
// Update the memory file's frontmatter on disk
|
|
90
117
|
updateMemoryFile(brainDir, entry.path, {
|
|
91
118
|
strength: entry.strength,
|
|
92
119
|
decay_rate: entry.decay_rate,
|
|
93
120
|
last_accessed: nowISO,
|
|
94
121
|
access_count: entry.access_count,
|
|
122
|
+
recall_history: entry.recall_history,
|
|
95
123
|
});
|
|
96
124
|
|
|
97
125
|
reinforced.push({
|
|
@@ -157,7 +185,12 @@ function updateMemoryFile(brainDir, memPath, updates) {
|
|
|
157
185
|
// Update each field in the YAML
|
|
158
186
|
for (const [key, value] of Object.entries(updates)) {
|
|
159
187
|
const regex = new RegExp(`^(${key}:\\s*).*$`, 'm');
|
|
160
|
-
|
|
188
|
+
// Arrays and objects must be JSON-encoded: `String(value)` renders an
|
|
189
|
+
// array of objects as "[object Object]", which is both lossy and invalid
|
|
190
|
+
// YAML. JSON is a YAML subset, so a flow-style array round-trips cleanly.
|
|
191
|
+
const formatted = typeof value === 'string'
|
|
192
|
+
? `"${value}"`
|
|
193
|
+
: (value !== null && typeof value === 'object' ? JSON.stringify(value) : String(value));
|
|
161
194
|
if (regex.test(frontmatter)) {
|
|
162
195
|
frontmatter = frontmatter.replace(regex, `$1${formatted}`);
|
|
163
196
|
}
|