brain-memory 0.1.0-beta.9 → 0.2.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 (82) hide show
  1. package/CHANGELOG.md +632 -0
  2. package/README.md +390 -84
  3. package/SECURITY.md +100 -0
  4. package/assets/brand/README.md +28 -0
  5. package/assets/brand/icon-dark.svg +19 -0
  6. package/assets/brand/icon-light.svg +20 -0
  7. package/assets/brand/linkedin_cover.png +0 -0
  8. package/assets/brand/linkedin_cover_light.png +0 -0
  9. package/assets/brand/mark-dark.svg +19 -0
  10. package/assets/brand/mark-light.svg +20 -0
  11. package/assets/brand/png/icon-dark-1024.png +0 -0
  12. package/assets/brand/png/icon-dark-128.png +0 -0
  13. package/assets/brand/png/icon-dark-256.png +0 -0
  14. package/assets/brand/png/icon-dark-512.png +0 -0
  15. package/assets/brand/png/icon-dark-64.png +0 -0
  16. package/assets/brand/png/icon-light-1024.png +0 -0
  17. package/assets/brand/png/icon-light-128.png +0 -0
  18. package/assets/brand/png/icon-light-256.png +0 -0
  19. package/assets/brand/png/icon-light-512.png +0 -0
  20. package/assets/brand/png/icon-light-64.png +0 -0
  21. package/assets/brand/png/mark-dark-1024.png +0 -0
  22. package/assets/brand/png/mark-light-1024.png +0 -0
  23. package/assets/icon.png +0 -0
  24. package/assets/icon.svg +19 -0
  25. package/bin/audit.js +93 -0
  26. package/bin/brain.js +132 -0
  27. package/bin/cloud-sync.js +150 -0
  28. package/bin/forget.js +172 -0
  29. package/bin/import.js +132 -0
  30. package/bin/install.js +63 -31
  31. package/bin/memorize.js +670 -0
  32. package/bin/pin.js +44 -0
  33. package/bin/recall.js +319 -0
  34. package/bin/reinforce.js +191 -0
  35. package/bin/restore.js +122 -0
  36. package/bin/session-start.js +352 -0
  37. package/bin/skill.js +67 -0
  38. package/bin/unpin.js +38 -0
  39. package/bin/verify.js +186 -0
  40. package/commands/brain/forget.md +243 -13
  41. package/commands/brain/import.md +125 -0
  42. package/commands/brain/memorize.md +108 -130
  43. package/commands/brain/pin.md +79 -0
  44. package/commands/brain/remember.md +59 -100
  45. package/commands/brain/skills.md +60 -0
  46. package/commands/brain/sleep.md +93 -6
  47. package/commands/brain/status.md +15 -6
  48. package/commands/brain/sync.md +181 -17
  49. package/commands/brain/verify.md +63 -0
  50. package/integrations/README.md +29 -0
  51. package/integrations/agentskills/brain-memory/SKILL.md +115 -0
  52. package/integrations/agentskills/brain-memory/scripts/session-start.mjs +34 -0
  53. package/package.json +19 -7
  54. package/prompts/antigravity.md +222 -0
  55. package/prompts/claude.md +128 -40
  56. package/prompts/copilot.md +224 -0
  57. package/prompts/kilo.md +223 -0
  58. package/prompts/openai.md +133 -45
  59. package/prompts/opencode.md +221 -0
  60. package/src/anomaly.js +260 -0
  61. package/src/audit.js +71 -0
  62. package/src/cloud-sync.js +672 -0
  63. package/src/content-lint.js +118 -0
  64. package/src/export-import.js +45 -7
  65. package/src/git-sync.js +170 -11
  66. package/src/harvest.js +562 -0
  67. package/src/index-manager.js +250 -11
  68. package/src/installer.js +250 -29
  69. package/src/pinning.js +146 -0
  70. package/src/provenance.js +79 -0
  71. package/src/quarantine.js +111 -0
  72. package/src/receipt.js +87 -0
  73. package/src/scorer.js +137 -12
  74. package/src/skills.js +208 -0
  75. package/src/temporal.js +228 -0
  76. package/src/tfidf.js +520 -0
  77. package/commands/brain/consolidate.md +0 -153
  78. package/commands/brain/explore.md +0 -79
  79. package/commands/brain/init.md +0 -149
  80. package/commands/brain/review.md +0 -130
  81. package/commands/brain/sunshine.md +0 -337
  82. package/prompts/gemini.md +0 -134
@@ -0,0 +1,221 @@
1
+ # Brain Memory System
2
+
3
+ This project uses the **Brain Memory** plugin — a hierarchical, file-system-based memory system that mimics human cognition with neuroscience-inspired mechanisms including associative networks, spreading activation, context-dependent recall, spaced reinforcement, and cognitive memory types.
4
+
5
+ ## Memory Location
6
+
7
+ All memories are stored in a single global `~/.brain/` directory in the user's home folder, shared across all projects and all supported AI agents. The directory uses a deep nested structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
8
+
9
+ ## How It Works
10
+
11
+ ### Memory Format
12
+ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `cognitive_type` (episodic/semantic/procedural), `created`, `last_accessed`, `access_count`, `recall_history`, `strength` (0.0-1.0), `decay_rate` (per day), `salience` (0.0-1.0), `confidence` (0.0-1.0), `tags`, `related` memory IDs, `source`, and `encoding_context`.
13
+
14
+ ### Strength & Decay Model
15
+ - Memories have a base `strength` set at creation based on their impact/type/cognitive type
16
+ - Strength decays over time: `effective = strength * (decay_rate ^ days_since_access)`
17
+ - Recalled memories get **stronger** via spaced reinforcement — the longer since last recall, the bigger the boost
18
+ - Memories become progressively more forgetting-resistant with each recall (decay_rate improves)
19
+ - Weak memories can be consolidated into stronger combined memories
20
+ - During sleep, global synaptic homeostasis prevents strength inflation
21
+
22
+ ### Cognitive Types
23
+ - **Episodic** — Event-specific memories. Higher initial strength, faster decay. The details fade but lessons persist.
24
+ - **Semantic** — Abstracted knowledge. Default decay. Stable long-term storage.
25
+ - **Procedural** — Skills and workflows. Lower initial strength but extremely slow decay once established.
26
+
27
+ ### Memory Types & Default Strengths
28
+ | Type | Strength | Decay/day | Description |
29
+ |------|----------|-----------|-------------|
30
+ | decision | 0.85 | 0.995 | Choices made and rationale |
31
+ | insight | 0.90 | 0.997 | Deep realizations, patterns |
32
+ | goal | 0.80 | 0.993 | Objectives and aspirations |
33
+ | experience | 0.75 | 0.985 | Notable events or processes |
34
+ | learning | 0.70 | 0.990 | New knowledge acquired |
35
+ | relationship | 0.70 | 0.997 | Connections between entities |
36
+ | preference | 0.60 | 0.998 | User preferences and style |
37
+ | observation | 0.40 | 0.950 | Casual facts or notices |
38
+
39
+ ### Associative Network
40
+ Memories are connected via weighted edges in `~/.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
41
+
42
+ ### Context-Dependent Recall
43
+ Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
44
+
45
+ ### Salience & Confidence
46
+ - **Salience** (0.0-1.0): Emotional/motivational significance. High-salience memories (>= 0.7) are never auto-pruned.
47
+ - **Confidence** (0.0-1.0): Epistemic certainty. Low-confidence memories are flagged during recall.
48
+
49
+ ## Available Commands
50
+
51
+ The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end; you rarely type them.
52
+
53
+ **Core**
54
+ - `/brain:remember [query]` — Recall relevant memories with spreading activation and context matching
55
+ - `/brain:memorize [topic]` — Store memories from the current context
56
+ - `/brain:status` — Dashboard with brain health overview
57
+ - `/brain:pin [id|query]` — Pin a memory to the always-present tier (toggle — also unpins, e.g. `--off`)
58
+ - `/brain:forget [target]` — Decay or archive memories (`--deep` = forensic erasure of every reference)
59
+
60
+ **Cold start**
61
+ - `/brain:import [--project P] [--since 30d]` — Seed a new brain from transcripts your agents already wrote
62
+
63
+ **Sync & skills**
64
+ - `/brain:sync [subcommand]` — Sync via Brain Cloud, Git remote, or export/import (auto-initializes on first run)
65
+ - `/brain:skills [list|show|add|use|remove|export]` — Manage procedural skills
66
+
67
+ **Maintenance (usually automatic — runs in the background)**
68
+ - `/brain:sleep [scope]` — Full maintenance cycle: replay, homeostasis, propagation, crystallization, reorganize, consolidate, prune, review reinforcement, REM dreaming, expertise detection
69
+
70
+ ## Session Start Behavior
71
+
72
+ **Perform these steps at session start — but keep it lightweight.**
73
+
74
+ If `~/.brain/index.json` exists:
75
+
76
+ 1. **Run the session-start aggregator** — one deterministic, budget-bounded call:
77
+ ```bash
78
+ brain session-start --project "<current project>"
79
+ ```
80
+ It returns JSON with `memory_count`, `pinned` (always-apply conventions/preferences), `skills_index` (available procedural skills — name + description only), `context_recall` (memories relevant to this project), `due_for_review`, `pending_verification` (unverified low-trust writes awaiting review), `low_confidence_alerts`, and `budget`. If `~/.brain/index.json` is absent it returns an empty payload.
81
+ 2. **Silently internalize** the payload — treat `pinned` facts as active constraints, note which `skills_index` skills exist (load a skill's full `SKILL.md` only when a task matches it), and keep `context_recall` in mind. Do **NOT** dump contents.
82
+ 3. **Output a single status line:**
83
+
84
+ ```
85
+ ◉ Brain active — <N> memories (<M> in project context)
86
+ ```
87
+
88
+ Only add extra lines if actionable:
89
+ - `📋 <X> due for review` — if `due_for_review > 0`
90
+ - `⚠️ <N> low-confidence memories used frequently` — if `low_confidence_alerts` is non-empty
91
+ - `⌛ <N> pinned memories expired` — if `expired_pins > 0` (their validity window closed; update or unpin them)
92
+ - `⊘ <N> pending verification` — if `pending_verification > 0` (memories from untrusted sources are quarantined for review — resolve with `brain verify list`)
93
+
94
+ The aggregator is budget-bounded (`~/.brain/config.json`) and never exceeds the working-memory token budget, so just internalize whatever it returns. **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them.
95
+
96
+ ## Ambient Session Tracking
97
+
98
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
99
+
100
+ Track these categories as they happen:
101
+ - **Decisions** — Architecture choices, technology selections, trade-off resolutions
102
+ - **Learnings** — New patterns, debugging insights, API discoveries
103
+ - **Insights** — Realizations about the codebase, project, or process
104
+ - **Experiences** — Significant events like incidents, deployments, milestones
105
+ - **Goals** — New objectives discussed or planned
106
+
107
+ **Why this matters:** Without active tracking, you can only evaluate what happened at session end — by which point early-session events may be forgotten or the user may have already left. By tracking as events occur, nothing is lost.
108
+
109
+ ## Periodic Memory Checkpoint
110
+
111
+ **Every ~10 substantive interactions** (file edits, architecture decisions, debugging breakthroughs, significant discussions — not trivial reads or simple answers), silently evaluate whether your ambient tracking log contains memorizable content.
112
+
113
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
114
+
115
+ ```
116
+ ◉ Notable <type(s)> this session — /brain:memorize when ready
117
+ ```
118
+
119
+ **Rules:**
120
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
121
+ - **At most once per ~10 substantive interactions** — no spamming
122
+ - **Reset the counter** after the user runs `/brain:memorize`
123
+ - **Don't mention if nothing notable** has accumulated
124
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
125
+
126
+ ## Session End Behavior
127
+
128
+ When a session is ending (user says bye/thanks/done, conversation wraps up, or you sense the interaction is concluding), perform these steps **in order**:
129
+
130
+ ### Step 1: Save Session Context (ALWAYS — do this first)
131
+
132
+ **Immediately** append a session summary to `~/.brain/contexts.json`, even for trivial sessions. Context tracking is cheap and provides valuable recall signals for future sessions.
133
+
134
+ ```json
135
+ {
136
+ "session_id": "<timestamp-based-id>",
137
+ "started": "<session start ISO timestamp>",
138
+ "ended": "<session end ISO timestamp>",
139
+ "project": "<current project name>",
140
+ "topics": ["<key topics discussed>"],
141
+ "task_type": "<primary task type>",
142
+ "memories_created": ["<IDs of memories stored this session>"],
143
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
144
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
145
+ }
146
+ ```
147
+
148
+ Keep only the last 20 session entries. The `notable_unsaved` field preserves what happened even if the user didn't memorize — future sessions can reference it.
149
+
150
+ ### Step 2: Suggest Memorization (if warranted)
151
+
152
+ If the session contained meaningful content based on your ambient tracking:
153
+
154
+ ```
155
+ 💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
156
+ Run /brain:memorize to capture them before this context is lost.
157
+ ```
158
+
159
+ **Rules:**
160
+ - Do NOT auto-memorize without user consent
161
+ - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
162
+ - Only suggest when there is genuinely valuable context worth preserving
163
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
164
+
165
+ ## When Recalling Memories
166
+
167
+ When the user asks you to "remember" something, or when context from past sessions would be helpful, use the **deterministic recall engine** instead of manually computing scores:
168
+
169
+ 1. Run `brain recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
170
+ 2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
171
+ 3. Read the top-scoring memory files and present results
172
+ 4. Run `brain reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
173
+ 5. If no matches, search the archive (`~/.brain/_archived/`)
174
+
175
+ The recall engine ensures **identical scoring across all agents** — Claude, Gemini, Codex, and OpenCode all get the same rankings for the same query.
176
+
177
+ ## Recall Receipts
178
+
179
+ Every memory returned by `brain recall` and by the session-start payload (each `context_recall` and `pinned` entry) carries a pre-minted `receipt` field: `◉ memory: "<title>" (<type>, <age>)`. Receipts make memory visibly fire — the user sees exactly which memory shaped an answer. Low-trust memories (origin `tool-output` or `external`) carry a trailing `⚠ <origin>` marker in their receipt — keep it when copying; it is the visible warning that the fact came from outside the user/agent dialogue. Memories still pending verification carry a further `⊘ unverified` segment — keep that too, and caveat any answer that leans on an unverified memory. A memory whose validity window has closed carries `⌛ expired`: it is no longer true, so answer with "that was the case until <date>" rather than stating it as current.
180
+
181
+ - When recalled or pinned memories **materially shaped your answer**, end the response with their `receipt` lines, copied **verbatim** — max 3 lines, at the very end.
182
+ - Only receipt what actually influenced the output. Pinned memories get a receipt only when they were decisive for this specific answer — they are always present, and receipting them every turn is spam.
183
+ - No memory used → no receipt line. Never fabricate a receipt for a memory the engine did not return; only lines provided in `receipt` fields.
184
+
185
+ ## Time-Aware Memory (Bitemporal)
186
+
187
+ Every memory has two independent clocks, and conflating them is how an agent confidently states a fact that stopped being true months ago:
188
+
189
+ - **Record time** — `created`: when the brain learned it. Always present.
190
+ - **Valid time** — `valid_from` / `valid_until`: when the fact *was true*. Optional, half-open `[from, until)`. Absent means unbounded.
191
+
192
+ So "we deploy to Fly.io" (recorded in June) and "we deploy to Render" (recorded in August) are not a contradiction to resolve — they are one fact with a boundary.
193
+
194
+ **When storing.** Pass `valid_from` / `valid_until` whenever the user frames a fact in time — "until the end of Q3", "starting in March", "for the duration of the contract". Don't invent bounds for facts stated as simply true. Superseding sets the boundary for you: when B `supersedes` A, A's `valid_until` is stamped with B's start, so a plain supersede already produces a correct window.
195
+
196
+ **When recalling.** Results carry `valid_from`/`valid_until`, and `expired: true` once the window has closed. An expired memory is demoted, never dropped — surface it as history ("that was true until <valid_until>"), never as the current answer. Two flags travel back in time:
197
+
198
+ - `brain recall "<query>" --as-of 2026-03-01` — **valid time**: what was *true* then, using everything known now. Superseded memories inside their window rank undemoted, because at that instant they were simply the truth.
199
+ - `brain recall "<query>" --as-known-of 2026-03-01` — **record time**: what the brain had *recorded* by then.
200
+
201
+ Pass both to reconstruct exactly what the brain believed, and when. Use them whenever the user asks a dated question ("what were we using back in March?", "when did that change?") instead of guessing from timestamps.
202
+
203
+ **Expired pins.** A pinned memory whose window has closed is dropped from the always-apply tier and counted in `expired_pins` — it is no longer an active constraint. Mention the count so the user can update or unpin it.
204
+
205
+ ## Unverified Memories (Quarantine)
206
+
207
+ Writes whose content came from outside the user/agent dialogue (origin `tool-output` or `external`) — and any write whose content looks instruction-shaped — land in a **pending-verification** state. By default they stay recallable but are visibly marked (`quarantine_pending` in results, `⊘ unverified` on receipts); they can never be pinned, and their trust weighting already stops them from outranking user-asserted memories.
208
+
209
+ - When a recalled memory carries `quarantine_pending`, treat it as a claim, not a fact — caveat answers that depend on it.
210
+ - When session start reports `pending_verification > 0`, mention it in the status line so the user can review.
211
+ - Resolve with the deterministic CLI: `brain verify list` → `brain verify approve <id>` (clears the flag, keeps origin + trust weighting) or `brain verify reject <id>` (archives it). Never approve on your own judgment — approval is the user's call.
212
+ - `brain audit [--window 7d]` scans for anomalous write patterns (bursts, co-tagged low-trust cliques, quiet reinforcement); `--apply` quarantines what it finds. It runs automatically as sleep Phase 0.
213
+
214
+ ## Portable Sync
215
+
216
+ Brain memories can be synced across devices in two ways:
217
+
218
+ 1. **Git remote** — Push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
219
+ 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
220
+
221
+ Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
package/src/anomaly.js ADDED
@@ -0,0 +1,260 @@
1
+ /**
2
+ * Brain Memory — Anomalous-Write Detection (OWASP ASI06: forensics)
3
+ *
4
+ * The detection half of the poisoning defense: provenance clamps and trust
5
+ * weighting bound what a planted memory can claim; this module notices the
6
+ * write *patterns* an attack leaves behind, so `brain restore` has a trigger.
7
+ *
8
+ * Three deterministic detectors over audit.log + index.json + associations.json:
9
+ * write_burst Unusually many writes from one origin in a window.
10
+ * low_trust_clique Co-tagged clusters of low-trust memories — planted
11
+ * writes auto-link via tag_overlap edges and would
12
+ * self-amplify through spreading activation.
13
+ * reinforced_low_trust Low-trust memories quietly accumulating recall
14
+ * reinforcement without ever being verified.
15
+ *
16
+ * Origin-based quarantine is write-time only; findings here are the ONLY
17
+ * retroactive path to flagging, and --apply is capped so an audit run can
18
+ * never silently vanish a large slice of the brain.
19
+ */
20
+
21
+ const { isLowTrust } = require('./provenance');
22
+ const { readAudit } = require('./audit');
23
+ const { listPending, applyQuarantine } = require('./quarantine');
24
+
25
+ // Writes-per-window ceilings by origin. Low-trust origins get tight budgets;
26
+ // agent-inferred is the ambient default and gets headroom.
27
+ const BURST_THRESHOLDS = {
28
+ external: 5,
29
+ 'tool-output': 10,
30
+ 'agent-inferred': 30,
31
+ };
32
+
33
+ const DEFAULT_WINDOW_HOURS = 24;
34
+ const DEFAULT_MAX_APPLY = 20;
35
+
36
+ /**
37
+ * Sliding-window write bursts per origin over `memorize` audit events.
38
+ *
39
+ * @param {Object[]} auditEvents - Records from readAudit (oldest first)
40
+ * @param {Object} [opts] - { windowHours }
41
+ * @returns {Object[]} [{ kind:'write_burst', origin, count, threshold, window_start, ids }]
42
+ */
43
+ function detectWriteBursts(auditEvents, opts = {}) {
44
+ const windowMs = (opts.windowHours || DEFAULT_WINDOW_HOURS) * 3600 * 1000;
45
+ const byOrigin = new Map();
46
+ for (const rec of auditEvents) {
47
+ if (rec.event !== 'memorize' || !rec.ts) continue;
48
+ const t = Date.parse(rec.ts);
49
+ if (Number.isNaN(t)) continue;
50
+ const origin = rec.origin || 'agent-inferred';
51
+ if (!byOrigin.has(origin)) byOrigin.set(origin, []);
52
+ byOrigin.get(origin).push({ t, ts: rec.ts, id: rec.id });
53
+ }
54
+
55
+ const findings = [];
56
+ for (const [origin, writes] of byOrigin) {
57
+ const threshold = BURST_THRESHOLDS[origin];
58
+ if (!threshold) continue; // user writes are never a burst
59
+ writes.sort((a, b) => a.t - b.t);
60
+ // Slide a window over the sorted writes; report the densest violation once.
61
+ let best = null;
62
+ let lo = 0;
63
+ for (let hi = 0; hi < writes.length; hi++) {
64
+ while (writes[hi].t - writes[lo].t > windowMs) lo++;
65
+ const count = hi - lo + 1;
66
+ if (count > threshold && (!best || count > best.count)) {
67
+ best = { lo, hi, count };
68
+ }
69
+ }
70
+ if (best) {
71
+ findings.push({
72
+ kind: 'write_burst',
73
+ origin,
74
+ count: best.count,
75
+ threshold,
76
+ window_start: writes[best.lo].ts,
77
+ ids: writes.slice(best.lo, best.hi + 1).map((w) => w.id).filter(Boolean),
78
+ });
79
+ }
80
+ }
81
+ return findings;
82
+ }
83
+
84
+ /**
85
+ * Connected components of tag_overlap edges whose endpoints are BOTH
86
+ * low-trust and unvetted — the shape a batch of co-tagged planted writes
87
+ * leaves in the association graph.
88
+ *
89
+ * @param {Object} index - Parsed index.json
90
+ * @param {Object} associations - Parsed associations.json
91
+ * @param {Object} [opts] - { minSize }
92
+ * @returns {Object[]} [{ kind:'low_trust_clique', size, ids, shared_tags }]
93
+ */
94
+ function detectLowTrustCliques(index, associations, opts = {}) {
95
+ const minSize = opts.minSize || 3;
96
+ const memories = (index && index.memories) || {};
97
+ const edges = (associations && associations.edges) || {};
98
+
99
+ const suspicious = (id) => {
100
+ const e = memories[id];
101
+ return e && isLowTrust(e.origin) && !e.vetted;
102
+ };
103
+
104
+ // Adjacency restricted to tag_overlap edges between suspicious nodes.
105
+ const adj = new Map();
106
+ for (const [src, targets] of Object.entries(edges)) {
107
+ if (!suspicious(src)) continue;
108
+ for (const [dst, edge] of Object.entries(targets)) {
109
+ if (edge.origin !== 'tag_overlap' || !suspicious(dst)) continue;
110
+ if (!adj.has(src)) adj.set(src, new Set());
111
+ if (!adj.has(dst)) adj.set(dst, new Set());
112
+ adj.get(src).add(dst);
113
+ adj.get(dst).add(src);
114
+ }
115
+ }
116
+
117
+ const seen = new Set();
118
+ const findings = [];
119
+ for (const start of adj.keys()) {
120
+ if (seen.has(start)) continue;
121
+ const component = [];
122
+ const stack = [start];
123
+ seen.add(start);
124
+ while (stack.length) {
125
+ const id = stack.pop();
126
+ component.push(id);
127
+ for (const next of adj.get(id) || []) {
128
+ if (!seen.has(next)) { seen.add(next); stack.push(next); }
129
+ }
130
+ }
131
+ if (component.length < minSize) continue;
132
+
133
+ const tagCounts = new Map();
134
+ for (const id of component) {
135
+ for (const tag of (memories[id].tags || [])) {
136
+ tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
137
+ }
138
+ }
139
+ const shared = [...tagCounts.entries()]
140
+ .filter(([, n]) => n >= 2)
141
+ .sort((a, b) => b[1] - a[1])
142
+ .map(([tag]) => tag)
143
+ .slice(0, 5);
144
+
145
+ findings.push({
146
+ kind: 'low_trust_clique',
147
+ size: component.length,
148
+ ids: component.sort(),
149
+ shared_tags: shared,
150
+ });
151
+ }
152
+ return findings;
153
+ }
154
+
155
+ /**
156
+ * Low-trust memories that keep getting recalled and reinforced without ever
157
+ * being verified — quiet entrenchment through use.
158
+ *
159
+ * @param {Object} index - Parsed index.json
160
+ * @param {Object} [opts] - { minAccess }
161
+ * @returns {Object[]} [{ kind:'reinforced_low_trust', id, origin, access_count }]
162
+ */
163
+ function detectReinforcedLowTrust(index, opts = {}) {
164
+ const minAccess = opts.minAccess || 5;
165
+ const findings = [];
166
+ for (const [id, entry] of Object.entries((index && index.memories) || {})) {
167
+ if (!isLowTrust(entry.origin)) continue;
168
+ if (entry.vetted || entry.pinned) continue;
169
+ if ((entry.access_count || 0) < minAccess) continue;
170
+ findings.push({
171
+ kind: 'reinforced_low_trust',
172
+ id,
173
+ origin: entry.origin,
174
+ access_count: entry.access_count,
175
+ });
176
+ }
177
+ return findings.sort((a, b) => b.access_count - a.access_count);
178
+ }
179
+
180
+ /**
181
+ * Run all detectors and (optionally) quarantine the flagged memories.
182
+ *
183
+ * `proposed_quarantine` is the union of finding ids minus vetted, pinned,
184
+ * user-origin, and already-quarantined entries. With `apply`, at most
185
+ * `maxApply` ids are flagged per run (`truncated: true` reports the cut) —
186
+ * an audit can propose broadly but never mass-quarantine.
187
+ *
188
+ * @param {string} brainDir - Path to ~/.brain/
189
+ * @param {Object} deps - { index, associations, appendAudit, writeIndex } injected by the CLI
190
+ * @param {Object} [opts] - { windowHours, apply, maxApply, now }
191
+ * @returns {Object} { generated_at, window_hours, findings, pending_verification,
192
+ * proposed_quarantine, applied?, truncated }
193
+ */
194
+ function runAudit(brainDir, deps, opts = {}) {
195
+ const windowHours = opts.windowHours || DEFAULT_WINDOW_HOURS;
196
+ const maxApply = opts.maxApply || DEFAULT_MAX_APPLY;
197
+ const now = opts.now || new Date().toISOString();
198
+ const { index, associations } = deps;
199
+
200
+ const sinceIso = new Date(Date.parse(now) - windowHours * 3600 * 1000).toISOString();
201
+ const auditEvents = readAudit(brainDir, { since: sinceIso, events: ['memorize'] });
202
+
203
+ const findings = [
204
+ ...detectWriteBursts(auditEvents, { windowHours }),
205
+ ...detectLowTrustCliques(index, associations),
206
+ ...detectReinforcedLowTrust(index),
207
+ ];
208
+
209
+ const memories = (index && index.memories) || {};
210
+ const proposed = new Set();
211
+ for (const f of findings) {
212
+ for (const id of f.ids || (f.id ? [f.id] : [])) {
213
+ const e = memories[id];
214
+ if (!e) continue;
215
+ if (e.vetted || e.pinned || e.quarantined) continue;
216
+ if (e.origin === 'user') continue;
217
+ proposed.add(id);
218
+ }
219
+ }
220
+ const proposedList = [...proposed].sort();
221
+
222
+ const result = {
223
+ generated_at: now,
224
+ window_hours: windowHours,
225
+ findings,
226
+ pending_verification: listPending(index).length,
227
+ proposed_quarantine: proposedList,
228
+ truncated: false,
229
+ };
230
+
231
+ if (opts.apply && proposedList.length > 0) {
232
+ const toApply = proposedList.slice(0, maxApply);
233
+ result.truncated = proposedList.length > maxApply;
234
+ result.applied = [];
235
+ for (const id of toApply) {
236
+ const reasons = findings
237
+ .filter((f) => (f.ids || [f.id]).includes(id))
238
+ .map((f) => `anomaly:${f.kind}`);
239
+ const r = applyQuarantine(brainDir, index, id, [...new Set(reasons)], now);
240
+ if (!r.error) {
241
+ result.applied.push(id);
242
+ deps.appendAudit(brainDir, {
243
+ ts: now, event: 'audit_quarantine', id, reasons: [...new Set(reasons)],
244
+ });
245
+ }
246
+ }
247
+ if (result.applied.length > 0) deps.writeIndex(index);
248
+ result.pending_verification = listPending(index).length;
249
+ }
250
+
251
+ return result;
252
+ }
253
+
254
+ module.exports = {
255
+ detectWriteBursts,
256
+ detectLowTrustCliques,
257
+ detectReinforcedLowTrust,
258
+ runAudit,
259
+ BURST_THRESHOLDS,
260
+ };
package/src/audit.js ADDED
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Brain Memory — Audit Trail
3
+ *
4
+ * Single owner of the append-only provenance log (~/.brain/audit.log), one
5
+ * JSON object per line, mode 0600. Written for every event that changes what
6
+ * the brain believes (memorize, forget, restore, verify, quarantine), so a
7
+ * fact that later turns out to be planted can be traced to the write that
8
+ * introduced it — even if the memory file itself was since edited,
9
+ * consolidated by a sleep cycle, or deleted.
10
+ *
11
+ * The log is deliberately carried forward through restores (src/git-sync.js,
12
+ * src/cloud-sync.js) and never rolled back: forensics must survive recovery.
13
+ */
14
+
15
+ const fs = require('fs');
16
+ const path = require('path');
17
+
18
+ const AUDIT_FILE = 'audit.log';
19
+
20
+ /**
21
+ * Append one record to the audit log. Stamps `ts` (ISO) when absent.
22
+ *
23
+ * @param {string} brainDir - Path to ~/.brain/
24
+ * @param {Object} record - Event record; `event` names the event type
25
+ */
26
+ function appendAudit(brainDir, record) {
27
+ const rec = record.ts ? record : { ts: new Date().toISOString(), ...record };
28
+ fs.appendFileSync(
29
+ path.join(brainDir, AUDIT_FILE),
30
+ JSON.stringify(rec) + '\n',
31
+ { mode: 0o600 }
32
+ );
33
+ }
34
+
35
+ /**
36
+ * Read audit records, oldest first. Tolerant by design: a missing log returns
37
+ * [], and unparseable lines (a torn trailing line from a crash mid-append, or
38
+ * hand-edited damage) are skipped rather than failing the whole read — the
39
+ * log has to stay useful precisely when something already went wrong.
40
+ *
41
+ * @param {string} brainDir - Path to ~/.brain/
42
+ * @param {Object} [opts] - { since?: ISO string|Date, events?: string[], limit?: number }
43
+ * `since` keeps records with ts >= since; `events` filters by event type;
44
+ * `limit` keeps the most recent N after filtering.
45
+ * @returns {Object[]} Parsed records
46
+ */
47
+ function readAudit(brainDir, opts = {}) {
48
+ const { since, events, limit } = opts;
49
+ let raw;
50
+ try {
51
+ raw = fs.readFileSync(path.join(brainDir, AUDIT_FILE), 'utf-8');
52
+ } catch (_) {
53
+ return [];
54
+ }
55
+
56
+ const sinceIso = since instanceof Date ? since.toISOString() : since;
57
+ const eventSet = events ? new Set(events) : null;
58
+ const out = [];
59
+ for (const line of raw.split('\n')) {
60
+ if (!line.trim()) continue;
61
+ let rec;
62
+ try { rec = JSON.parse(line); } catch (_) { continue; }
63
+ if (eventSet && !eventSet.has(rec.event)) continue;
64
+ if (sinceIso && (!rec.ts || rec.ts < sinceIso)) continue;
65
+ out.push(rec);
66
+ }
67
+ if (limit && out.length > limit) return out.slice(out.length - limit);
68
+ return out;
69
+ }
70
+
71
+ module.exports = { appendAudit, readAudit, AUDIT_FILE };