brain-memory 0.1.0-beta.35 → 0.1.0-beta.36

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 CHANGED
@@ -6,6 +6,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.1.0-beta.36] - 2026-08-07
10
+
11
+ ### Added
12
+
13
+ - **Trust-weighted recall — origin now decides how far a memory's score can
14
+ reach.** beta.34 labelled every write with an origin and capped what
15
+ untrusted origins may claim; this release closes the read side. Recall
16
+ multiplies each memory's composite score by an origin trust factor (`user`
17
+ 1.0, `agent-inferred` 0.95, `tool-output` 0.85, `external` 0.75), and
18
+ spreading-activation *sources* are damped by the same factor — so a clique
19
+ of co-tagged planted memories (which auto-link through tag overlap) cannot
20
+ amplify itself past something the user said directly. Trust bounds volume,
21
+ not relevance: a genuinely more relevant external memory can still win; it
22
+ just can't win on bulk. Missing origin weighs as the memorize default, so
23
+ pre-provenance brains rank exactly as before.
24
+ - **Low-trust results are visibly marked.** `brain recall` and
25
+ `brain session-start` return `origin` and a `low_trust` flag on every
26
+ result, and receipts for `tool-output`/`external` memories carry a trailing
27
+ warning — `◉ memory: "…" (learning, 3d ago, ⚠ external)` — so a fact
28
+ absorbed from a web page can never quietly pass as something you said.
29
+ Trusted receipts are byte-identical to the existing format.
30
+ - **Connector: `brain_memorize` accepts `origin`.** The remote MCP tool passes
31
+ a validated origin through to the engine, with tool-description guidance
32
+ that `user` is reserved for facts the human explicitly stated or asked to
33
+ remember.
34
+ - **`brain restore` — an undo button for the whole brain.**
35
+ `brain restore --list` shows restore points; `--to <point>` rolls
36
+ `~/.brain/` back to one. Two sources: the Git sync history
37
+ (`--from git`, default — one point per push) and Brain Cloud's server-side
38
+ pre-push snapshots (`--from cloud`, listed via the new
39
+ `GET /api/brains/{id}/versions` endpoint). Every restore is undoable:
40
+ the git path first commits the current state as a safety snapshot (unsynced
41
+ work included), the cloud path writes a local backup under
42
+ `~/.brain/.cloud/`. `audit.log` is deliberately carried *forward* through
43
+ restores — the append-only trail records history through a rollback, never
44
+ gets rolled back by one — and each restore is itself logged there.
45
+
9
46
  ## [0.1.0-beta.35] - 2026-08-01
10
47
 
11
48
  ### Added
package/README.md CHANGED
@@ -41,6 +41,7 @@ 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
45
  - **Associative network** — Memories link to each other with weighted connections. Recalling one activates related ones automatically
45
46
  - **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
46
47
  - **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
@@ -622,6 +623,17 @@ export BRAIN_DIR="$HOME/Google Drive/brain" # or Dropbox, iCloud Drive, OneDri
622
623
 
623
624
  For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
624
625
 
626
+ **Restore — an undo button for your whole brain.** Every push is a restore point, and the CLI can roll the entire brain back to any of them:
627
+
628
+ ```bash
629
+ brain restore --list # list restore points (the Git sync history)
630
+ brain restore --to <commit> # roll ~/.brain/ back to that point
631
+ brain restore --list --from cloud # list Brain Cloud's pre-push snapshots
632
+ brain restore --to <version> --from cloud # restore from a cloud snapshot
633
+ ```
634
+
635
+ Before touching anything, restore preserves your *current* state — the Git path commits it as a safety snapshot, the cloud path writes a local backup under `~/.brain/.cloud/` — so a restore is always undoable, even for work you never pushed. (Brain Cloud also snapshots the brain it's about to replace on every push, server-side.) The append-only `audit.log` is carried forward through restores (never rolled back), and every restore is itself logged there. Restore granularity follows push frequency: push often for finer-grained history.
636
+
625
637
  Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
626
638
 
627
639
  ### Brain in Claude apps (web & mobile) — beta
package/bin/brain.js CHANGED
@@ -34,6 +34,7 @@ const DELEGATED = {
34
34
  unpin: 'unpin.js',
35
35
  skill: 'skill.js',
36
36
  import: 'import.js',
37
+ restore: 'restore.js',
37
38
  };
38
39
 
39
40
  // install.js finds its positional subcommand from process.argv itself, so it is
@@ -69,6 +70,10 @@ Cold start
69
70
 
70
71
  Sync
71
72
  cloud <login|logout|push|pull|status>
73
+ restore --list [--from git|cloud]
74
+ List restore points (Git history or Cloud snapshots)
75
+ restore --to <point> [--from git|cloud]
76
+ Roll the whole brain back to a restore point
72
77
 
73
78
  Setup
74
79
  install Interactive installer (default when no command)
package/bin/memorize.js CHANGED
@@ -74,34 +74,11 @@ const COGNITIVE_ADJUSTMENTS = {
74
74
  // --- Provenance (OWASP ASI06: memory poisoning) ---
75
75
  //
76
76
  // Where a memory came from decides how much it is allowed to entrench itself.
77
- // The failure mode this defends against: content the agent *read* (an email, a
78
- // web page, a tool result) persuades it to write a fact, and that fact then
79
- // hardens — pinned into every session, exempt from decay, immune to pruning,
80
- // and never flagged as uncertain. See MemGhost (arXiv:2607.05189).
81
- //
82
- // `origin` is asserted by the caller, so it does not defend against a fully
83
- // hostile agent — but the dominant real case is an *honest* agent relaying
84
- // poisoned content, and there it holds. The pin/stable restriction is the part
85
- // that holds regardless: entrenchment is simply not reachable from this path
86
- // without an explicit user origin.
87
- const ORIGIN_POLICY = {
88
- // The user asked for this directly, in-session.
89
- user: { max_salience: 1.0, max_confidence: 1.0, allow_entrench: true, decay_multiplier: 1.0 },
90
- // The agent inferred or summarized it from session context. Default.
91
- 'agent-inferred': { max_salience: 0.6, max_confidence: 0.8, allow_entrench: false, decay_multiplier: 1.0 },
92
- // Derived from tool output — file reads, command results, MCP responses.
93
- 'tool-output': { max_salience: 0.5, max_confidence: 0.6, allow_entrench: false, decay_multiplier: 0.997 },
94
- // Derived from untrusted external content — email, web pages, issue text.
95
- external: { max_salience: 0.4, max_confidence: 0.4, allow_entrench: false, decay_multiplier: 0.99 },
96
- };
97
-
98
- // Absent origin means the agent didn't tell us — assume the weaker claim, never
99
- // the stronger one. A memory that deserves `user` is one keystroke away.
100
- const DEFAULT_ORIGIN = 'agent-inferred';
101
-
102
- // Salience >= 0.7 is exempt from auto-pruning, so every non-user ceiling sits
103
- // below it: an unattended poisoned memory must remain collectable.
104
- const PRUNE_EXEMPT_SALIENCE = 0.7;
77
+ // The policy table lives in src/provenance.js (shared with the recall-side
78
+ // trust weighting in src/scorer.js). The pin/stable restriction is the part
79
+ // that holds regardless of caller honesty: entrenchment is simply not
80
+ // reachable from this path without an explicit user origin.
81
+ const { ORIGIN_POLICY, DEFAULT_ORIGIN } = require('../src/provenance');
105
82
 
106
83
  // --- Args ---
107
84
 
package/bin/recall.js CHANGED
@@ -40,6 +40,7 @@ const {
40
40
  } = require('../src/scorer');
41
41
 
42
42
  const { receiptFor } = require('../src/receipt');
43
+ const { DEFAULT_ORIGIN, isLowTrust } = require('../src/provenance');
43
44
 
44
45
  // Minimum relevance (or spreading bonus) for a memory to appear in explicit-
45
46
  // query results. Filters the zero/near-zero-relevance memories that would
@@ -144,6 +145,7 @@ function main() {
144
145
  const top = args.top || 10;
145
146
  const results = ranked.slice(0, top).map((mem) => {
146
147
  const title = mem.title || path.basename(mem.path, '.md');
148
+ const origin = mem.origin || DEFAULT_ORIGIN;
147
149
  return {
148
150
  id: mem.id,
149
151
  title,
@@ -155,6 +157,10 @@ function main() {
155
157
  context_match: mem.context_match,
156
158
  spreading_bonus: mem.spreading_bonus,
157
159
  confidence: mem.confidence,
160
+ // Provenance travels with every result so the agent can answer
161
+ // "where did you get that?" without opening the memory file.
162
+ origin,
163
+ ...(isLowTrust(origin) ? { low_trust: true } : {}),
158
164
  tags: mem.tags,
159
165
  // Recall receipt — the engine mints it, agents copy it verbatim when
160
166
  // this memory materially shapes an answer (so it can't be hallucinated).
package/bin/restore.js ADDED
@@ -0,0 +1,130 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * brain restore — roll the whole brain back to a previous restore point.
5
+ *
6
+ * Two sources of restore points:
7
+ * git (default) Commits in the Git sync history (~/.brain/.sync/repo/) —
8
+ * one per push, plus a pre-restore safety snapshot taken
9
+ * automatically before every restore.
10
+ * cloud Brain Cloud's pre-overwrite snapshots — one is taken
11
+ * server-side before every `brain cloud push` commit.
12
+ *
13
+ * Usage:
14
+ * brain restore --list [--from git|cloud] [--limit N]
15
+ * brain restore --to <commit|version> [--from git|cloud] [--passphrase <p>]
16
+ *
17
+ * Both sources are undoable: git commits a safety snapshot first; cloud writes
18
+ * a local pre-restore backup under ~/.brain/.cloud/. audit.log is carried
19
+ * forward through every restore, and every restore is itself logged there.
20
+ * Output: JSON.
21
+ */
22
+
23
+ const fs = require('fs');
24
+ const path = require('path');
25
+
26
+ const { listRestorePoints, restoreTo } = require('../src/git-sync');
27
+ const { getBrainDir, readIndex } = require('../src/index-manager');
28
+ const { readSearchIndex, writeSearchIndex, rebuildIndex, isSearchIndexStale } = require('../src/tfidf');
29
+
30
+ function parseArgs(argv) {
31
+ const args = { list: false, to: null, from: 'git', limit: 20, passphrase: null };
32
+ for (let i = 0; i < argv.length; i++) {
33
+ switch (argv[i]) {
34
+ case '--list': args.list = true; break;
35
+ case '--to': args.to = argv[++i]; break;
36
+ case '--from': args.from = argv[++i]; break;
37
+ case '--limit': args.limit = parseInt(argv[++i], 10) || 20; break;
38
+ case '--passphrase': args.passphrase = argv[++i]; break;
39
+ default: break;
40
+ }
41
+ }
42
+ return args;
43
+ }
44
+
45
+ /** Append-only audit trail — same format and mode as memorize's write log. */
46
+ function appendAuditLog(brainDir, record) {
47
+ fs.appendFileSync(
48
+ path.join(brainDir, 'audit.log'),
49
+ JSON.stringify(record) + '\n',
50
+ { mode: 0o600 }
51
+ );
52
+ }
53
+
54
+ /**
55
+ * The restored search index normally matches the restored index.json, but
56
+ * rebuild defensively when it drifted (matches recall.js's staleness rule).
57
+ */
58
+ function reindexIfStale(brainDir) {
59
+ try {
60
+ const index = readIndex();
61
+ let searchIndex = null;
62
+ try { searchIndex = readSearchIndex(brainDir); } catch { searchIndex = null; }
63
+ if (index && isSearchIndexStale(searchIndex, index)) {
64
+ writeSearchIndex(brainDir, rebuildIndex(brainDir, index));
65
+ return true;
66
+ }
67
+ } catch { /* index unreadable — surfaced by the next recall, not here */ }
68
+ return false;
69
+ }
70
+
71
+ async function main(argv) {
72
+ const args = parseArgs(argv || process.argv.slice(2));
73
+ const brainDir = getBrainDir();
74
+
75
+ if (args.from !== 'git' && args.from !== 'cloud') {
76
+ console.error(JSON.stringify({ error: `Unknown source "${args.from}" (expected git or cloud)` }));
77
+ process.exit(1);
78
+ }
79
+
80
+ try {
81
+ if (args.list) {
82
+ if (args.from === 'cloud') {
83
+ const cloud = require('../src/cloud-sync');
84
+ const versions = await cloud.listVersions(brainDir);
85
+ console.log(JSON.stringify({ source: 'cloud', restore_points: versions.slice(0, args.limit), total: versions.length }, null, 2));
86
+ } else {
87
+ const points = listRestorePoints(brainDir, args.limit);
88
+ console.log(JSON.stringify({ source: 'git', restore_points: points, total: points.length }, null, 2));
89
+ }
90
+ return;
91
+ }
92
+
93
+ if (!args.to) {
94
+ console.error(JSON.stringify({
95
+ error: 'Usage: brain restore --list [--from git|cloud] | brain restore --to <point> [--from git|cloud] [--passphrase <p>]',
96
+ }));
97
+ process.exit(1);
98
+ }
99
+
100
+ let result;
101
+ if (args.from === 'cloud') {
102
+ const cloud = require('../src/cloud-sync');
103
+ result = await cloud.restoreVersion(brainDir, args.to);
104
+ } else {
105
+ result = restoreTo(brainDir, args.to, args.passphrase || undefined);
106
+ }
107
+
108
+ const reindexed = reindexIfStale(brainDir);
109
+
110
+ appendAuditLog(brainDir, {
111
+ ts: new Date().toISOString(),
112
+ event: 'restore',
113
+ source: args.from,
114
+ ...(args.from === 'cloud'
115
+ ? { restored_version: result.restored_version, backup: result.backup }
116
+ : { restored_to: result.restored_to, safety_commit: result.safety_commit, restore_commit: result.restore_commit }),
117
+ });
118
+
119
+ console.log(JSON.stringify({ source: args.from, ...result, reindexed }, null, 2));
120
+ } catch (err) {
121
+ console.error(JSON.stringify({ error: err.message }));
122
+ process.exit(1);
123
+ }
124
+ }
125
+
126
+ if (require.main === module) {
127
+ main(process.argv.slice(2));
128
+ }
129
+
130
+ module.exports = { main, parseArgs };
@@ -43,6 +43,7 @@ const {
43
43
  const { rankMemories } = require('../src/scorer');
44
44
  const { advertisedSummaries } = require('../src/skills');
45
45
  const { receiptFor } = require('../src/receipt');
46
+ const { DEFAULT_ORIGIN, isLowTrust } = require('../src/provenance');
46
47
 
47
48
  function parseArgs(argv) {
48
49
  const args = { project: null, topics: null, task: null, top: 5 };
@@ -235,12 +236,15 @@ function computeSessionStart(projectRoot, args = {}) {
235
236
  excluded++;
236
237
  continue;
237
238
  }
239
+ const origin = mem.origin || DEFAULT_ORIGIN;
238
240
  context_recall.push({
239
241
  id: mem.id,
240
242
  title,
241
243
  path: mem.path,
242
244
  type: mem.type,
243
245
  score: mem.score,
246
+ origin,
247
+ ...(isLowTrust(origin) ? { low_trust: true } : {}),
244
248
  token_estimate: est,
245
249
  receipt,
246
250
  });
@@ -39,7 +39,7 @@ If the brain-memory package is installed globally, use:
39
39
  brain recall "$ARGUMENTS" --project "<project>" --task "<task_type>" --top 10
40
40
  ```
41
41
 
42
- The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, and salience using the v4 formula. All scoring is deterministic — same query always produces the same ranking. Each result also carries a pre-minted `receipt` line (`◉ memory: "<title>" (<type>, <age>)`) — keep it for step 6.
42
+ The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, salience, and **origin trust** (memories sourced from tool output or external content are down-weighted and flagged `low_trust`) using the v4 formula. All scoring is deterministic — same query always produces the same ranking. Each result also carries a pre-minted `receipt` line (`◉ memory: "<title>" (<type>, <age>)`; low-trust origins add a trailing `⚠ <origin>` marker) — keep it for step 6.
43
43
 
44
44
  ### 3. Read Top Memories
45
45
 
@@ -85,7 +85,7 @@ This deterministically applies:
85
85
 
86
86
  ### 6. Present Results
87
87
 
88
- Format the output clearly. Include confidence indicators for low-confidence memories.
88
+ Format the output clearly. Include confidence indicators for low-confidence memories. When a result has `low_trust: true`, say so explicitly (e.g. "⚠ sourced from external content — verify before relying on it") rather than presenting it as established fact.
89
89
 
90
90
  ```
91
91
  ## Recalled Memory: <Title>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.35",
3
+ "version": "0.1.0-beta.36",
4
4
  "description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -44,7 +44,7 @@
44
44
  "url": "git+https://github.com/omelas-tech/brain.git"
45
45
  },
46
46
  "scripts": {
47
- "test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/receipt.test.js test/recall.test.js test/recall-cli.test.js test/forget.test.js test/functional.test.js test/erasure.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/cloud-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/memorize.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js test/harvest.test.js",
47
+ "test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/receipt.test.js test/recall.test.js test/recall-cli.test.js test/forget.test.js test/functional.test.js test/erasure.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/restore.test.js test/trust-recall.test.js test/cloud-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js test/session-start.test.js test/memorize.test.js test/pinning.test.js test/skills.test.js test/contradiction.test.js test/harvest.test.js",
48
48
  "test:integrations": "npm run test:integrations:openclaw && npm run test:integrations:copilot && npm run test:integrations:kilo && npm run test:integrations:hermes",
49
49
  "test:integrations:openclaw": "node --test integrations/openclaw/test/*.test.mjs",
50
50
  "test:integrations:copilot": "node --test integrations/copilot/test/*.test.mjs",
@@ -175,7 +175,7 @@ The recall engine ensures **identical scoring across all agents** — Claude, Ge
175
175
 
176
176
  ## Recall Receipts
177
177
 
178
- 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.
178
+ 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.
179
179
 
180
180
  - 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.
181
181
  - 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.
package/prompts/claude.md CHANGED
@@ -174,7 +174,7 @@ The recall engine ensures **identical scoring across all agents** — Claude, Ge
174
174
 
175
175
  ## Recall Receipts
176
176
 
177
- 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.
177
+ 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.
178
178
 
179
179
  - 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.
180
180
  - 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.
@@ -177,7 +177,7 @@ The recall engine ensures **identical scoring across all agents** — Claude, Co
177
177
 
178
178
  ## Recall Receipts
179
179
 
180
- 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.
180
+ 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.
181
181
 
182
182
  - 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.
183
183
  - 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.
package/prompts/kilo.md CHANGED
@@ -176,7 +176,7 @@ The recall engine ensures **identical scoring across all agents** — Claude, Ge
176
176
 
177
177
  ## Recall Receipts
178
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.
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.
180
180
 
181
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
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.
package/prompts/openai.md CHANGED
@@ -175,7 +175,7 @@ The recall engine ensures **identical scoring across all agents** — Claude, Ge
175
175
 
176
176
  ## Recall Receipts
177
177
 
178
- 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.
178
+ 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.
179
179
 
180
180
  - 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.
181
181
  - 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.
@@ -174,7 +174,7 @@ The recall engine ensures **identical scoring across all agents** — Claude, Ge
174
174
 
175
175
  ## Recall Receipts
176
176
 
177
- 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.
177
+ 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.
178
178
 
179
179
  - 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.
180
180
  - 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.
package/src/cloud-sync.js CHANGED
@@ -456,6 +456,98 @@ async function pull(brainDir) {
456
456
  }
457
457
  }
458
458
 
459
+ // ---------------------------------------------------------------------------
460
+ // Versions / Restore
461
+ // ---------------------------------------------------------------------------
462
+
463
+ // Local entries a cloud restore must never touch: sync/auth infrastructure and
464
+ // _archived/, which is deliberately excluded from cloud pushes (see
465
+ // TAR_EXCLUDES) and so does not exist in the snapshot being restored.
466
+ const RESTORE_PRESERVE = new Set(['.sync', '.cloud', '.DS_Store', '_archived']);
467
+
468
+ /**
469
+ * List cloud restore points — pre-overwrite snapshots Brain Cloud takes
470
+ * automatically before every push commit. Newest first.
471
+ *
472
+ * @param {string} brainDir
473
+ * @returns {Promise<Array<{version: string, date: string}>>}
474
+ */
475
+ async function listVersions(brainDir) {
476
+ const config = readConfig(brainDir);
477
+ if (!config) throw new Error('Not logged in. Run cloud login first.');
478
+ if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
479
+
480
+ const token = await getValidToken(brainDir);
481
+ const res = await jsonRequest(
482
+ `${config.api_url}/api/brains/${config.brain_id}/versions`,
483
+ 'GET', null, token
484
+ );
485
+ if (res.status !== 200) {
486
+ throw new Error(`Failed to list versions (${res.status}): ${res.data.error || ''}`);
487
+ }
488
+ return res.data.versions || [];
489
+ }
490
+
491
+ /**
492
+ * Restore ~/.brain/ from a cloud version snapshot.
493
+ *
494
+ * Before touching anything, the current brain is packed into a local backup
495
+ * under .cloud/ (kept for the last 5 restores) so the restore is undoable even
496
+ * without the git sync path. audit.log is carried forward across the swap —
497
+ * the append-only trail records history through a restore, never rolls back.
498
+ * The cloud's live brain is NOT modified; push when satisfied with the result.
499
+ *
500
+ * @param {string} brainDir
501
+ * @param {string} version - Snapshot name from listVersions()
502
+ * @returns {Promise<{restored_version: string, size_bytes: number, backup: string}>}
503
+ */
504
+ async function restoreVersion(brainDir, version) {
505
+ const config = readConfig(brainDir);
506
+ if (!config) throw new Error('Not logged in. Run cloud login first.');
507
+ if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
508
+ if (!version) throw new Error('No version given. List them with versions first.');
509
+
510
+ const token = await getValidToken(brainDir);
511
+ const url = `${config.api_url}/api/brains/${config.brain_id}/sync?version=${encodeURIComponent(version)}`;
512
+ const tmpFile = path.join(os.tmpdir(), `brain-restore-${Date.now()}.tar.gz`);
513
+
514
+ try {
515
+ await downloadFile(url, tmpFile, token);
516
+ const size = fs.statSync(tmpFile).size;
517
+
518
+ // Local safety backup of the CURRENT state (the download above already
519
+ // succeeded, so a failure past this point can always be rolled forward).
520
+ const { cloudDir } = resolvePaths(brainDir);
521
+ fs.mkdirSync(cloudDir, { recursive: true });
522
+ const backupName = `pre-restore-${new Date().toISOString().replace(/[:.]/g, '')}.tar.gz`;
523
+ const backupPath = path.join(cloudDir, backupName);
524
+ const packed = packBrain(brainDir);
525
+ fs.copyFileSync(packed, backupPath);
526
+ try { fs.unlinkSync(packed); } catch { /* ignore */ }
527
+ const backups = fs.readdirSync(cloudDir).filter((n) => n.startsWith('pre-restore-')).sort();
528
+ while (backups.length > 5) fs.rmSync(path.join(cloudDir, backups.shift()), { force: true });
529
+
530
+ // Carry the append-only audit trail across the swap.
531
+ const auditPath = path.join(brainDir, 'audit.log');
532
+ let auditTrail = null;
533
+ try { auditTrail = fs.readFileSync(auditPath); } catch { auditTrail = null; }
534
+
535
+ for (const entry of fs.readdirSync(brainDir)) {
536
+ if (RESTORE_PRESERVE.has(entry)) continue;
537
+ fs.rmSync(path.join(brainDir, entry), { recursive: true, force: true });
538
+ }
539
+ unpackBrain(tmpFile, brainDir);
540
+ if (auditTrail !== null) fs.writeFileSync(auditPath, auditTrail, { mode: 0o600 });
541
+
542
+ config.last_pull = new Date().toISOString();
543
+ writeConfig(brainDir, config);
544
+
545
+ return { restored_version: version, size_bytes: size, backup: backupPath };
546
+ } finally {
547
+ try { fs.unlinkSync(tmpFile); } catch { /* ignore */ }
548
+ }
549
+ }
550
+
459
551
  // ---------------------------------------------------------------------------
460
552
  // Status
461
553
  // ---------------------------------------------------------------------------
@@ -520,6 +612,8 @@ module.exports = {
520
612
  logout,
521
613
  push,
522
614
  pull,
615
+ listVersions,
616
+ restoreVersion,
523
617
  status,
524
618
  readConfig,
525
619
  writeConfig,
package/src/git-sync.js CHANGED
@@ -381,6 +381,119 @@ function pull(brainDir, passphrase) {
381
381
  return { pulled: true, hasConflicts: false, message: `Pulled successfully at ${config.lastPull}` };
382
382
  }
383
383
 
384
+ /**
385
+ * List restore points — the commits in the sync repo's history, newest first.
386
+ *
387
+ * A restore point exists for every push (and every pre-restore safety
388
+ * snapshot), so granularity follows how often the brain is pushed.
389
+ *
390
+ * @param {string} brainDir - Absolute path to ~/.brain/
391
+ * @param {number} [limit=20] - Maximum entries to return
392
+ * @returns {Array<{ commit: string, date: string, message: string }>}
393
+ */
394
+ function listRestorePoints(brainDir, limit = 20) {
395
+ const { repoDir, configPath } = resolvePaths(brainDir);
396
+ const config = readConfig(configPath);
397
+ if (!config) throw new Error('Sync not configured. Run /brain:sync setup first.');
398
+ if (!fs.existsSync(path.join(repoDir, '.git'))) return [];
399
+
400
+ let out;
401
+ try {
402
+ out = git(repoDir, ['log', '--pretty=format:%H%x09%cI%x09%s', '-n', String(limit)]);
403
+ } catch {
404
+ return []; // repo initialized but no commits yet
405
+ }
406
+ if (!out) return [];
407
+ return out.split('\n').map((line) => {
408
+ const [commit, date, ...subject] = line.split('\t');
409
+ return { commit, date, message: subject.join('\t') };
410
+ });
411
+ }
412
+
413
+ /**
414
+ * Remove everything inside ~/.brain/ except the excluded infrastructure
415
+ * entries (.sync/), so a restore can't leave orphaned post-snapshot files
416
+ * behind. Only called after the current state is committed to sync history.
417
+ */
418
+ function clearBrainDir(brainDir) {
419
+ for (const entry of fs.readdirSync(brainDir)) {
420
+ if (EXCLUDED.has(entry)) continue;
421
+ fs.rmSync(path.join(brainDir, entry), { recursive: true, force: true });
422
+ }
423
+ }
424
+
425
+ /**
426
+ * Restore ~/.brain/ to a previous restore point.
427
+ *
428
+ * History only moves forward: the current brain state is first committed as a
429
+ * pre-restore safety snapshot (when it differs from HEAD), then the target
430
+ * tree is materialized as a NEW commit on main — so the restore itself is
431
+ * always undoable via another restore.
432
+ *
433
+ * @param {string} brainDir - Absolute path to ~/.brain/
434
+ * @param {string} ref - Commit hash (or any git ref) to restore to
435
+ * @param {string} [passphrase] - Encryption passphrase (if configured)
436
+ * @returns {{ restored_to: string, safety_commit: string|null, restore_commit: string }}
437
+ */
438
+ function restoreTo(brainDir, ref, passphrase) {
439
+ const { repoDir, configPath } = resolvePaths(brainDir);
440
+ const config = readConfig(configPath);
441
+ if (!config) throw new Error('Sync not configured. Run /brain:sync setup first.');
442
+
443
+ const pass = config.encrypt ? passphrase : null;
444
+ if (config.encrypt && !passphrase) {
445
+ throw new Error('Encryption is enabled but no passphrase provided.');
446
+ }
447
+ if (!fs.existsSync(path.join(repoDir, '.git'))) {
448
+ throw new Error('No sync history yet — push at least once before restoring.');
449
+ }
450
+
451
+ // Validate the ref up front (also resolves short hashes / dates via git).
452
+ let target;
453
+ try {
454
+ target = git(repoDir, ['rev-parse', '--verify', `${ref}^{commit}`]);
455
+ } catch {
456
+ throw new Error(`Unknown restore point "${ref}". Use --list to see available points.`);
457
+ }
458
+
459
+ // Safety snapshot: commit the CURRENT brain state before touching anything,
460
+ // so even unsynced work survives the restore in history.
461
+ copyBrainToRepo(brainDir, repoDir, pass);
462
+ git(repoDir, ['add', '-A']);
463
+ let safetyCommit = null;
464
+ if (git(repoDir, ['status', '--porcelain'])) {
465
+ git(repoDir, ['commit', '-m', `pre-restore snapshot ${new Date().toISOString()}`]);
466
+ safetyCommit = git(repoDir, ['rev-parse', 'HEAD']);
467
+ }
468
+
469
+ // Materialize the target tree in the worktree and commit it forward.
470
+ // Wipe first so files absent in the target don't survive, then let
471
+ // `git add -A` stage those deletions alongside the checked-out content.
472
+ for (const entry of fs.readdirSync(repoDir)) {
473
+ if (entry === '.git') continue;
474
+ fs.rmSync(path.join(repoDir, entry), { recursive: true, force: true });
475
+ }
476
+ git(repoDir, ['checkout', target, '--', '.']);
477
+ git(repoDir, ['add', '-A']);
478
+ if (git(repoDir, ['status', '--porcelain'])) {
479
+ git(repoDir, ['commit', '-m', `restore to ${target.slice(0, 12)}`]);
480
+ }
481
+ const restoreCommit = git(repoDir, ['rev-parse', 'HEAD']);
482
+
483
+ // Only now mutate the live brain — the snapshot above makes this recoverable.
484
+ // audit.log is deliberately carried across the swap: the append-only trail
485
+ // must record history *through* a restore, not be rolled back by one.
486
+ const auditPath = path.join(brainDir, 'audit.log');
487
+ let auditTrail = null;
488
+ try { auditTrail = fs.readFileSync(auditPath); } catch { auditTrail = null; }
489
+
490
+ clearBrainDir(brainDir);
491
+ copyRepoToBrain(repoDir, brainDir, pass);
492
+ if (auditTrail !== null) fs.writeFileSync(auditPath, auditTrail, { mode: 0o600 });
493
+
494
+ return { restored_to: target, safety_commit: safetyCommit, restore_commit: restoreCommit };
495
+ }
496
+
384
497
  /**
385
498
  * Read sync config from ~/.brain/.sync/config.json.
386
499
  *
@@ -435,6 +548,8 @@ module.exports = {
435
548
  getStatus,
436
549
  push,
437
550
  pull,
551
+ listRestorePoints,
552
+ restoreTo,
438
553
  getSyncConfig,
439
554
  writeSyncConfig,
440
555
  // Internal — exported for testing
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Brain Memory — Provenance Policy (OWASP ASI06: memory poisoning)
3
+ *
4
+ * Single source of truth for what a memory's origin allows it to claim — at
5
+ * write time (bin/memorize.js clamps salience/confidence and refuses
6
+ * entrenchment) and at recall time (src/scorer.js weighs trust into ranking,
7
+ * bin/recall.js and bin/session-start.js flag low-trust results).
8
+ *
9
+ * The failure mode this defends against: content the agent *read* (an email, a
10
+ * web page, a tool result) persuades it to write a fact, and that fact then
11
+ * hardens — pinned into every session, exempt from decay, immune to pruning,
12
+ * never flagged as uncertain, and boosted by its own planted neighbors at
13
+ * recall. See MemGhost (arXiv:2607.05189).
14
+ *
15
+ * `origin` is asserted by the caller, so it does not defend against a fully
16
+ * hostile agent — but the dominant real case is an *honest* agent relaying
17
+ * poisoned content, and there it holds.
18
+ */
19
+
20
+ const ORIGIN_POLICY = {
21
+ // The user asked for this directly, in-session.
22
+ user: { max_salience: 1.0, max_confidence: 1.0, allow_entrench: true, decay_multiplier: 1.0, trust_factor: 1.0 },
23
+ // The agent inferred or summarized it from session context. Default.
24
+ 'agent-inferred': { max_salience: 0.6, max_confidence: 0.8, allow_entrench: false, decay_multiplier: 1.0, trust_factor: 0.95 },
25
+ // Derived from tool output — file reads, command results, MCP responses.
26
+ 'tool-output': { max_salience: 0.5, max_confidence: 0.6, allow_entrench: false, decay_multiplier: 0.997, trust_factor: 0.85 },
27
+ // Derived from untrusted external content — email, web pages, issue text.
28
+ external: { max_salience: 0.4, max_confidence: 0.4, allow_entrench: false, decay_multiplier: 0.99, trust_factor: 0.75 },
29
+ };
30
+
31
+ // Absent origin means the agent didn't tell us — assume the weaker claim, never
32
+ // the stronger one. A memory that deserves `user` is one keystroke away.
33
+ const DEFAULT_ORIGIN = 'agent-inferred';
34
+
35
+ // Salience >= 0.7 is exempt from auto-pruning, so every non-user ceiling sits
36
+ // below it: an unattended poisoned memory must remain collectable.
37
+ const PRUNE_EXEMPT_SALIENCE = 0.7;
38
+
39
+ // Origins whose content came from outside the user/agent dialogue — surfaced
40
+ // with a low_trust flag at recall and a ⚠ marker on receipts.
41
+ const LOW_TRUST_ORIGINS = new Set(['tool-output', 'external']);
42
+
43
+ /**
44
+ * Recall-time trust weight for an origin (0.75-1.0).
45
+ *
46
+ * Applied as a multiplier on the composite recall score and on spreading-
47
+ * activation source strength. Trust bounds *entrenchment and volume*, not
48
+ * relevance: a genuinely more relevant external memory can still rank first —
49
+ * it just can't get there on bulk or clique self-amplification.
50
+ *
51
+ * Unknown/missing origins weigh as DEFAULT_ORIGIN: legacy memories (written
52
+ * before origin existed) rank exactly as if memorize had stamped its default,
53
+ * so their relative order is unchanged.
54
+ *
55
+ * @param {string} [origin] - Memory origin (frontmatter/index `origin` field)
56
+ * @returns {number} Trust factor
57
+ */
58
+ function trustFactor(origin) {
59
+ const policy = ORIGIN_POLICY[origin] || ORIGIN_POLICY[DEFAULT_ORIGIN];
60
+ return policy.trust_factor;
61
+ }
62
+
63
+ /**
64
+ * Whether an origin is low-trust (content sourced outside the dialogue).
65
+ *
66
+ * @param {string} [origin] - Memory origin
67
+ * @returns {boolean}
68
+ */
69
+ function isLowTrust(origin) {
70
+ return LOW_TRUST_ORIGINS.has(origin);
71
+ }
72
+
73
+ module.exports = {
74
+ ORIGIN_POLICY,
75
+ DEFAULT_ORIGIN,
76
+ PRUNE_EXEMPT_SALIENCE,
77
+ trustFactor,
78
+ isLowTrust,
79
+ };
package/src/receipt.js CHANGED
@@ -9,6 +9,11 @@
9
9
  *
10
10
  * Format: ◉ memory: "<title>" (<type>, <age>)
11
11
  *
12
+ * Low-trust origins (tool-output, external — see src/provenance.js) carry a
13
+ * trailing warning segment so a poisoned-source memory is visibly marked
14
+ * wherever its receipt appears: ◉ memory: "<title>" (<type>, <age>, ⚠ external)
15
+ * User/agent-inferred receipts are byte-identical to the base format.
16
+ *
12
17
  * Age is derived from the memory's `created` timestamp (falling back to
13
18
  * `last_accessed`; omitted entirely when neither parses):
14
19
  * today | yesterday | <N>d ago (2-30 days) | <N>mo ago (31-364 days,
@@ -17,6 +22,8 @@
17
22
  * Deterministic: `now` is injectable for tests.
18
23
  */
19
24
 
25
+ const { isLowTrust } = require('./provenance');
26
+
20
27
  const MS_PER_DAY = 24 * 60 * 60 * 1000;
21
28
  const DAYS_PER_MONTH = 30.44; // mean Gregorian month
22
29
  const DAYS_PER_YEAR = 365.25;
@@ -59,10 +66,11 @@ function receiptFor(memoryLike, nowFn) {
59
66
 
60
67
  const type = typeof mem.type === 'string' && mem.type ? mem.type : 'memory';
61
68
  const age = ageLabel(mem.created ?? mem.last_accessed ?? NaN, now);
69
+ const trust = isLowTrust(mem.origin) ? `, ⚠ ${mem.origin}` : '';
62
70
 
63
71
  return age
64
- ? `◉ memory: "${title}" (${type}, ${age})`
65
- : `◉ memory: "${title}" (${type})`;
72
+ ? `◉ memory: "${title}" (${type}, ${age}${trust})`
73
+ : `◉ memory: "${title}" (${type}${trust})`;
66
74
  }
67
75
 
68
76
  module.exports = { receiptFor, ageLabel };
package/src/scorer.js CHANGED
@@ -7,6 +7,8 @@
7
7
  * by external tools.
8
8
  */
9
9
 
10
+ const { trustFactor } = require('./provenance');
11
+
10
12
  /**
11
13
  * Compute the effective (decayed) strength of a memory.
12
14
  *
@@ -407,9 +409,14 @@ function rankMemories(memories, relevanceFn, options = {}) {
407
409
  const sources = options.relevanceFloor != null
408
410
  ? scored.filter((m) => m.relevance >= options.relevanceFloor)
409
411
  : scored;
412
+ // Source strength is damped by origin trust: a clique of co-tagged
413
+ // low-trust memories (planted writes auto-link via tag_overlap edges)
414
+ // must not self-amplify past trusted memories through activation alone.
410
415
  const scoredSummary = sources.map((m) => ({
411
416
  id: m.id,
412
- score: 0.55 * m.relevance + 0.30 * m.decayed_strength + 0.15 * m.recency_bonus,
417
+ score:
418
+ (0.55 * m.relevance + 0.30 * m.decayed_strength + 0.15 * m.recency_bonus) *
419
+ trustFactor(m.origin),
413
420
  }));
414
421
 
415
422
  const bonuses = computeSpreadingActivationBatch(
@@ -446,12 +453,16 @@ function rankMemories(memories, relevanceFn, options = {}) {
446
453
  if (mem.context_match > 0) extras.contextMatch = mem.context_match;
447
454
  if (mem.salience != null) extras.salience = mem.salience;
448
455
 
456
+ // Origin trust multiplies the composite: trust bounds entrenchment and
457
+ // volume, not relevance — a clearly more relevant low-trust memory can
458
+ // still win, but it can't win on bulk. Missing origin weighs as the
459
+ // memorize default, so legacy memories keep their relative order.
449
460
  const score = fin(computeRecallScore(
450
461
  mem.relevance,
451
462
  mem.decayed_strength,
452
463
  mem.recency_bonus,
453
464
  extras
454
- ));
465
+ )) * trustFactor(mem.origin);
455
466
 
456
467
  return {
457
468
  ...mem,