brain-memory 0.3.0 → 0.5.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 +153 -0
- package/README.md +4 -0
- package/SECURITY.md +61 -9
- package/bin/brain.js +24 -3
- package/bin/cloud-sync.js +49 -6
- package/bin/install.js +72 -14
- package/bin/memorize.js +50 -6
- package/bin/port.js +174 -0
- package/bin/recall.js +16 -6
- package/bin/reinforce.js +5 -0
- package/bin/session-start.js +30 -4
- package/bin/verify.js +42 -4
- package/commands/brain/memorize.md +8 -0
- package/commands/brain/sync.md +23 -0
- package/commands/brain/verify.md +10 -2
- package/hooks/citation-check.mjs +94 -0
- package/hooks/hooks.json +11 -0
- package/hooks/lib.mjs +6 -0
- package/hooks/prompt-recall.mjs +24 -3
- package/hooks/session-start.mjs +4 -2
- package/integrations/README.md +4 -0
- package/integrations/agentskills/brain-memory/SKILL.md +9 -5
- package/package.json +10 -5
- package/prompts/antigravity.md +4 -2
- package/prompts/claude.md +4 -2
- package/prompts/copilot.md +4 -2
- package/prompts/kilo.md +4 -2
- package/prompts/openai.md +4 -2
- package/prompts/opencode.md +4 -2
- package/src/adapters.js +240 -0
- package/src/anomaly.js +41 -1
- package/src/cloud-sync.js +123 -11
- package/src/content-lint.js +55 -2
- package/src/export-import.js +1 -1
- package/src/git-sync.js +1 -1
- package/src/index-manager.js +9 -5
- package/src/installer.js +35 -1
- package/src/pinning.js +20 -1
- package/src/provenance.js +34 -0
- package/src/quarantine.js +82 -5
- package/src/receipt.js +9 -4
- package/src/surfaced.js +188 -0
- package/store/CONTRACT.md +244 -0
- package/store/Dockerfile +24 -0
- package/store/README.md +43 -0
- package/store/SELF-HOSTING.md +200 -0
- package/store/bin/brain-store.js +189 -0
- package/store/conformance/conformance.test.js +341 -0
- package/store/conformance/helpers.js +199 -0
- package/store/deploy/Caddyfile +14 -0
- package/store/deploy/connector.Dockerfile +38 -0
- package/store/deploy/docker-compose.yml +83 -0
- package/store/deploy/env.example +19 -0
- package/store/lib/auth.js +174 -0
- package/store/lib/oidc.js +206 -0
- package/store/lib/storage.js +333 -0
- package/store/lib/tar.js +150 -0
- package/store/openapi.yaml +318 -0
- package/store/server.js +465 -0
- package/store/test/mock-issuer.js +104 -0
- package/store/test/oidc.test.js +222 -0
- package/store/test/store.test.js +445 -0
package/src/adapters.js
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Cross-vendor adapters (`brain port`)
|
|
3
|
+
*
|
|
4
|
+
* Pure conversions between brain memories and the formats other memory
|
|
5
|
+
* systems read and write. No I/O here: bin/port.js loads memories, writes
|
|
6
|
+
* files, and sends imports through `brain memorize`, so every import meets the
|
|
7
|
+
* same origin policy, lint and quarantine as any other write.
|
|
8
|
+
*
|
|
9
|
+
* A brain memory, as these functions see it:
|
|
10
|
+
* { id, title, type, content, tags, created, origin }
|
|
11
|
+
* Imports may also carry `saved` (YYYY-MM-DD): when the other system recorded
|
|
12
|
+
* it. That is record time, not valid time, so it is never written as
|
|
13
|
+
* `valid_from`; bin/port.js keeps it in the memory's `source`.
|
|
14
|
+
*
|
|
15
|
+
* Every target is lossier than brain. `FIDELITY` states, per target, which
|
|
16
|
+
* fields survive a round trip, and test/adapters.test.js holds that table to
|
|
17
|
+
* the code.
|
|
18
|
+
*
|
|
19
|
+
* Targets:
|
|
20
|
+
* claude-memory Claude Code's file-based memory: one Markdown file per
|
|
21
|
+
* memory with `name` / `description` / `metadata.type`
|
|
22
|
+
* frontmatter, plus a MEMORY.md index of one-line pointers.
|
|
23
|
+
* markdown One line per memory, `[YYYY-MM-DD] - <title>: <text>` — the
|
|
24
|
+
* shape Claude.ai's memory import accepts as pasted text, and
|
|
25
|
+
* readable anywhere else.
|
|
26
|
+
* agentcore AWS Bedrock AgentCore Memory `BatchCreateMemoryRecords`
|
|
27
|
+
* request bodies (≤100 records each, ≤16,000 chars of text per
|
|
28
|
+
* record). Payloads only — no AWS SDK; send them with your own
|
|
29
|
+
* credentials. Import reads the same shape, or the
|
|
30
|
+
* `memoryRecordSummaries` a list/retrieve call returns.
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
const BRAIN_TYPES = ['decision', 'insight', 'goal', 'experience', 'learning', 'relationship', 'preference', 'observation'];
|
|
34
|
+
|
|
35
|
+
// Claude Code's memory types are about *what the note is for*, not what kind
|
|
36
|
+
// of knowledge it is, so the mapping is many-to-one each way.
|
|
37
|
+
const TO_CLAUDE_TYPE = {
|
|
38
|
+
preference: 'feedback',
|
|
39
|
+
relationship: 'user',
|
|
40
|
+
decision: 'project',
|
|
41
|
+
goal: 'project',
|
|
42
|
+
experience: 'project',
|
|
43
|
+
insight: 'project',
|
|
44
|
+
learning: 'project',
|
|
45
|
+
observation: 'project',
|
|
46
|
+
};
|
|
47
|
+
const FROM_CLAUDE_TYPE = { user: 'relationship', feedback: 'preference', project: 'decision', reference: 'learning' };
|
|
48
|
+
|
|
49
|
+
const AGENTCORE_BATCH = 100;
|
|
50
|
+
const AGENTCORE_MAX_TEXT = 16000;
|
|
51
|
+
|
|
52
|
+
/** Fields that survive brain → target → brain. */
|
|
53
|
+
const FIDELITY = {
|
|
54
|
+
'claude-memory': { title: true, content: true, type: 'mapped', tags: false, created: false },
|
|
55
|
+
markdown: { title: true, content: 'single line', type: false, tags: false, created: 'date only' },
|
|
56
|
+
agentcore: { title: true, content: 'up to 16,000 chars', type: true, tags: false, created: true },
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
function slug(text) {
|
|
60
|
+
return String(text || 'memory').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'memory';
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function oneLine(text) {
|
|
64
|
+
return String(text || '').replace(/\s+/g, ' ').trim();
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function dateOnly(iso) {
|
|
68
|
+
const t = Date.parse(iso);
|
|
69
|
+
return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 10) : null;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** Split `---\nfrontmatter\n---\nbody`; tolerant of a missing block. */
|
|
73
|
+
function splitFrontmatter(text) {
|
|
74
|
+
const m = String(text).match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
|
|
75
|
+
if (!m) return { fm: {}, body: String(text) };
|
|
76
|
+
const fm = {};
|
|
77
|
+
let parent = null;
|
|
78
|
+
for (const line of m[1].split(/\r?\n/)) {
|
|
79
|
+
const nested = line.match(/^\s{2,}([\w-]+):\s*(.*)$/);
|
|
80
|
+
const top = line.match(/^([\w-]+):\s*(.*)$/);
|
|
81
|
+
if (nested && parent) {
|
|
82
|
+
fm[parent] = { ...(typeof fm[parent] === 'object' ? fm[parent] : {}), [nested[1]]: unquote(nested[2]) };
|
|
83
|
+
} else if (top) {
|
|
84
|
+
parent = top[2] === '' ? top[1] : null;
|
|
85
|
+
fm[top[1]] = top[2] === '' ? {} : unquote(top[2]);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return { fm, body: m[2] };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function unquote(v) {
|
|
92
|
+
const s = String(v).trim();
|
|
93
|
+
return /^".*"$|^'.*'$/.test(s) ? s.slice(1, -1) : s;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/* ─────────────────────────── claude-memory ─────────────────────────── */
|
|
97
|
+
|
|
98
|
+
function toClaudeMemory(memories) {
|
|
99
|
+
const files = {};
|
|
100
|
+
const index = ['# Memory Index', ''];
|
|
101
|
+
const used = new Set();
|
|
102
|
+
for (const m of memories) {
|
|
103
|
+
let name = slug(m.title);
|
|
104
|
+
for (let i = 2; used.has(name); i++) name = `${slug(m.title)}-${i}`;
|
|
105
|
+
used.add(name);
|
|
106
|
+
const description = oneLine(m.title).replace(/"/g, "'");
|
|
107
|
+
files[`${name}.md`] = [
|
|
108
|
+
'---',
|
|
109
|
+
`name: ${name}`,
|
|
110
|
+
`description: "${description}"`,
|
|
111
|
+
'metadata:',
|
|
112
|
+
` type: ${TO_CLAUDE_TYPE[m.type] || 'project'}`,
|
|
113
|
+
'---',
|
|
114
|
+
'',
|
|
115
|
+
String(m.content || '').trim(),
|
|
116
|
+
'',
|
|
117
|
+
].join('\n');
|
|
118
|
+
index.push(`- [${description}](${name}.md)`);
|
|
119
|
+
}
|
|
120
|
+
files['MEMORY.md'] = index.join('\n') + '\n';
|
|
121
|
+
return { files };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** @param {Object<string,string>} files - { "<name>.md": text }, MEMORY.md ignored */
|
|
125
|
+
function fromClaudeMemory(files) {
|
|
126
|
+
const out = [];
|
|
127
|
+
for (const [file, text] of Object.entries(files)) {
|
|
128
|
+
if (!file.endsWith('.md') || /(^|\/)MEMORY\.md$/.test(file)) continue;
|
|
129
|
+
const { fm, body } = splitFrontmatter(text);
|
|
130
|
+
const content = body.trim();
|
|
131
|
+
if (!content) continue;
|
|
132
|
+
const type = (fm.metadata && fm.metadata.type) || fm.type;
|
|
133
|
+
out.push({
|
|
134
|
+
title: oneLine(fm.description || fm.name || file.replace(/\.md$/, '')).slice(0, 120),
|
|
135
|
+
type: FROM_CLAUDE_TYPE[type] || 'learning',
|
|
136
|
+
content,
|
|
137
|
+
tags: [],
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
return out;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/* ─────────────────────────── markdown ─────────────────────────── */
|
|
144
|
+
|
|
145
|
+
function toMarkdown(memories) {
|
|
146
|
+
const lines = memories.map((m) => {
|
|
147
|
+
const date = dateOnly(m.created);
|
|
148
|
+
const body = oneLine(m.content);
|
|
149
|
+
return `${date ? `[${date}] - ` : '- '}${oneLine(m.title)}: ${body}`;
|
|
150
|
+
});
|
|
151
|
+
return { text: lines.join('\n') + '\n' };
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
const MD_LINE = /^(?:\[(\d{4}-\d{2}-\d{2})\]\s*-\s*|[-*]\s+)?(.+)$/;
|
|
155
|
+
|
|
156
|
+
function fromMarkdown(text) {
|
|
157
|
+
const out = [];
|
|
158
|
+
for (const raw of String(text).split(/\r?\n/)) {
|
|
159
|
+
const line = raw.trim();
|
|
160
|
+
if (!line || line.startsWith('#')) continue;
|
|
161
|
+
const m = line.match(MD_LINE);
|
|
162
|
+
if (!m) continue;
|
|
163
|
+
const rest = m[2].trim();
|
|
164
|
+
const colon = rest.indexOf(': ');
|
|
165
|
+
const hasTitle = colon > 0 && colon <= 120;
|
|
166
|
+
out.push({
|
|
167
|
+
title: (hasTitle ? rest.slice(0, colon) : rest).slice(0, 120),
|
|
168
|
+
type: 'learning',
|
|
169
|
+
content: hasTitle ? rest.slice(colon + 2) : rest,
|
|
170
|
+
tags: [],
|
|
171
|
+
...(m[1] ? { saved: m[1] } : {}),
|
|
172
|
+
});
|
|
173
|
+
}
|
|
174
|
+
return out;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/* ─────────────────────────── agentcore ─────────────────────────── */
|
|
178
|
+
|
|
179
|
+
function toAgentCore(memories, { namespacePrefix = '/brain' } = {}) {
|
|
180
|
+
const records = memories.map((m) => {
|
|
181
|
+
const text = `${oneLine(m.title)}\n\n${String(m.content || '').trim()}`;
|
|
182
|
+
const t = Date.parse(m.created);
|
|
183
|
+
return {
|
|
184
|
+
requestIdentifier: String(m.id || slug(m.title)).slice(0, 80),
|
|
185
|
+
content: { text: text.slice(0, AGENTCORE_MAX_TEXT) },
|
|
186
|
+
namespaces: [`${namespacePrefix}/${BRAIN_TYPES.includes(m.type) ? m.type : 'learning'}`],
|
|
187
|
+
timestamp: Math.floor((Number.isFinite(t) ? t : Date.now()) / 1000),
|
|
188
|
+
};
|
|
189
|
+
});
|
|
190
|
+
const batches = [];
|
|
191
|
+
for (let i = 0; i < records.length; i += AGENTCORE_BATCH) batches.push({ records: records.slice(i, i + AGENTCORE_BATCH) });
|
|
192
|
+
const truncated = memories.filter((m) => `${oneLine(m.title)}\n\n${String(m.content || '').trim()}`.length > AGENTCORE_MAX_TEXT).length;
|
|
193
|
+
return { batches, truncated };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Accepts `{batches:[{records}]}`, `{records}`, or `{memoryRecordSummaries}`. */
|
|
197
|
+
function fromAgentCore(json) {
|
|
198
|
+
const doc = typeof json === 'string' ? JSON.parse(json) : json;
|
|
199
|
+
const records = [
|
|
200
|
+
...((doc.batches || []).flatMap((b) => b.records || [])),
|
|
201
|
+
...(doc.records || []),
|
|
202
|
+
...(doc.memoryRecordSummaries || []),
|
|
203
|
+
];
|
|
204
|
+
const out = [];
|
|
205
|
+
for (const r of records) {
|
|
206
|
+
const text = String((r.content && r.content.text) || '').trim();
|
|
207
|
+
if (!text) continue;
|
|
208
|
+
const [first, ...rest] = text.split(/\n\n/);
|
|
209
|
+
const ns = (r.namespaces || [])[0] || '';
|
|
210
|
+
const type = ns.split('/').pop();
|
|
211
|
+
const ts = r.timestamp ?? r.createdAt;
|
|
212
|
+
const iso = typeof ts === 'number' ? new Date(ts * 1000).toISOString() : (Date.parse(ts) ? new Date(ts).toISOString() : null);
|
|
213
|
+
out.push({
|
|
214
|
+
title: oneLine(first).slice(0, 120),
|
|
215
|
+
type: BRAIN_TYPES.includes(type) ? type : 'learning',
|
|
216
|
+
content: rest.length ? rest.join('\n\n') : text,
|
|
217
|
+
tags: [],
|
|
218
|
+
...(iso ? { saved: iso.slice(0, 10) } : {}),
|
|
219
|
+
});
|
|
220
|
+
}
|
|
221
|
+
return out;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const ADAPTERS = {
|
|
225
|
+
'claude-memory': { exportTo: toClaudeMemory, importFrom: fromClaudeMemory, input: 'dir' },
|
|
226
|
+
markdown: { exportTo: toMarkdown, importFrom: fromMarkdown, input: 'text' },
|
|
227
|
+
agentcore: { exportTo: toAgentCore, importFrom: fromAgentCore, input: 'json' },
|
|
228
|
+
};
|
|
229
|
+
|
|
230
|
+
module.exports = {
|
|
231
|
+
ADAPTERS,
|
|
232
|
+
FIDELITY,
|
|
233
|
+
toClaudeMemory,
|
|
234
|
+
fromClaudeMemory,
|
|
235
|
+
toMarkdown,
|
|
236
|
+
fromMarkdown,
|
|
237
|
+
toAgentCore,
|
|
238
|
+
fromAgentCore,
|
|
239
|
+
splitFrontmatter,
|
|
240
|
+
};
|
package/src/anomaly.js
CHANGED
|
@@ -18,10 +18,14 @@
|
|
|
18
18
|
* never silently vanish a large slice of the brain.
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
|
+
const fs = require('fs');
|
|
22
|
+
const path = require('path');
|
|
23
|
+
|
|
21
24
|
const { isLowTrust } = require('./provenance');
|
|
22
25
|
const { detectContentDrift } = require('./integrity');
|
|
23
26
|
const { readAudit } = require('./audit');
|
|
24
|
-
const {
|
|
27
|
+
const { lintMemoryContent } = require('./content-lint');
|
|
28
|
+
const { isAuthorizationClaim, listPending, applyQuarantine } = require('./quarantine');
|
|
25
29
|
|
|
26
30
|
// Writes-per-window ceilings by origin. Low-trust origins get tight budgets;
|
|
27
31
|
// agent-inferred is the ambient default and gets headroom.
|
|
@@ -178,6 +182,40 @@ function detectReinforcedLowTrust(index, opts = {}) {
|
|
|
178
182
|
return findings.sort((a, b) => b.access_count - a.access_count);
|
|
179
183
|
}
|
|
180
184
|
|
|
185
|
+
/**
|
|
186
|
+
* Memories that grant the agent a permission but were written before the
|
|
187
|
+
* `authorization_claim` lint existed, so they carry no `authorization` mark
|
|
188
|
+
* and were never gated. Re-lints each unmarked memory's file; marked ones
|
|
189
|
+
* were gated at write time and are skipped.
|
|
190
|
+
*
|
|
191
|
+
* @param {string} brainDir - Path to ~/.brain/
|
|
192
|
+
* @param {Object} index - Parsed index.json
|
|
193
|
+
* @returns {Object[]} [{ kind:'authorization_claim', id, origin, excerpt }]
|
|
194
|
+
*/
|
|
195
|
+
function detectUnmarkedAuthorization(brainDir, index) {
|
|
196
|
+
const findings = [];
|
|
197
|
+
for (const [id, entry] of Object.entries((index && index.memories) || {})) {
|
|
198
|
+
if (entry.authorization || !entry.path) continue;
|
|
199
|
+
let body;
|
|
200
|
+
try {
|
|
201
|
+
body = fs.readFileSync(path.join(brainDir, entry.path), 'utf-8').replace(/^---\n[\s\S]*?\n---\n/, '');
|
|
202
|
+
} catch (_) {
|
|
203
|
+
continue; // a missing file is detectContentDrift's finding, not this one
|
|
204
|
+
}
|
|
205
|
+
const lint = lintMemoryContent({
|
|
206
|
+
title: entry.title, content: body, type: entry.type, cognitive_type: entry.cognitive_type,
|
|
207
|
+
});
|
|
208
|
+
if (!isAuthorizationClaim(lint)) continue;
|
|
209
|
+
findings.push({
|
|
210
|
+
kind: 'authorization_claim',
|
|
211
|
+
id,
|
|
212
|
+
origin: entry.origin || 'agent-inferred',
|
|
213
|
+
excerpt: lint.flags.find((f) => f.severity === 'authorization').excerpt,
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
return findings;
|
|
217
|
+
}
|
|
218
|
+
|
|
181
219
|
/**
|
|
182
220
|
* Run all detectors and (optionally) quarantine the flagged memories.
|
|
183
221
|
*
|
|
@@ -205,6 +243,7 @@ function runAudit(brainDir, deps, opts = {}) {
|
|
|
205
243
|
...detectWriteBursts(auditEvents, { windowHours }),
|
|
206
244
|
...detectLowTrustCliques(index, associations),
|
|
207
245
|
...detectReinforcedLowTrust(index),
|
|
246
|
+
...detectUnmarkedAuthorization(brainDir, index),
|
|
208
247
|
// Store-phase tamper detection. Advisory only — legitimate edits (sleep
|
|
209
248
|
// consolidation, a user fixing a typo) also move the hash, so these
|
|
210
249
|
// findings are reported but never fed to the --apply quarantine path.
|
|
@@ -258,6 +297,7 @@ function runAudit(brainDir, deps, opts = {}) {
|
|
|
258
297
|
}
|
|
259
298
|
|
|
260
299
|
module.exports = {
|
|
300
|
+
detectUnmarkedAuthorization,
|
|
261
301
|
detectWriteBursts,
|
|
262
302
|
detectContentDrift,
|
|
263
303
|
detectLowTrustCliques,
|
package/src/cloud-sync.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Brain Memory — Cloud Sync Engine
|
|
3
3
|
*
|
|
4
|
-
* Push/pull ~/.brain/ memories
|
|
5
|
-
*
|
|
4
|
+
* Push/pull ~/.brain/ memories to a store that implements the Brain store
|
|
5
|
+
* contract (store/CONTRACT.md): Brain Cloud at api.brainmemory.ai by default, or
|
|
6
|
+
* a self-hosted brain-store.
|
|
7
|
+
*
|
|
8
|
+
* Two ways to authenticate: the device-code flow (Brain Cloud), or a static
|
|
9
|
+
* bearer token issued by the store's operator (brain-store).
|
|
6
10
|
*
|
|
7
11
|
* Zero external dependencies — uses Node.js built-in https, fs, child_process.
|
|
8
12
|
*/
|
|
@@ -19,7 +23,7 @@ const CONFIG_FILE = 'config.json';
|
|
|
19
23
|
const DEFAULT_API_URL = 'https://api.brainmemory.ai';
|
|
20
24
|
|
|
21
25
|
// Files/dirs inside ~/.brain/ that should NOT be synced
|
|
22
|
-
const TAR_EXCLUDES = ['.sync', '.cloud', '.DS_Store', '_archived'];
|
|
26
|
+
const TAR_EXCLUDES = ['.sync', '.cloud', '.local', '.DS_Store', '_archived'];
|
|
23
27
|
|
|
24
28
|
// ---------------------------------------------------------------------------
|
|
25
29
|
// HTTP helpers (zero-dependency, works on Node >= 18)
|
|
@@ -109,7 +113,7 @@ async function jsonRequest(url, method, data, token) {
|
|
|
109
113
|
/**
|
|
110
114
|
* Upload a file as multipart/form-data.
|
|
111
115
|
*/
|
|
112
|
-
async function uploadFile(url, filePath, token) {
|
|
116
|
+
async function uploadFile(url, filePath, token, extraHeaders) {
|
|
113
117
|
const boundary = '----BrainCloudUpload' + Date.now();
|
|
114
118
|
const fileContent = fs.readFileSync(filePath);
|
|
115
119
|
const header = Buffer.from(
|
|
@@ -126,6 +130,7 @@ async function uploadFile(url, filePath, token) {
|
|
|
126
130
|
'Content-Type': `multipart/form-data; boundary=${boundary}`,
|
|
127
131
|
'Content-Length': body.length.toString(),
|
|
128
132
|
'Authorization': `Bearer ${token}`,
|
|
133
|
+
...(extraHeaders || {}),
|
|
129
134
|
},
|
|
130
135
|
body,
|
|
131
136
|
});
|
|
@@ -224,6 +229,10 @@ async function getValidToken(brainDir) {
|
|
|
224
229
|
const config = readConfig(brainDir);
|
|
225
230
|
if (!config) throw new Error('Not logged in. Run cloud login first.');
|
|
226
231
|
|
|
232
|
+
// A static token never expires and has nothing to refresh; the store's
|
|
233
|
+
// operator revokes it by rotating it.
|
|
234
|
+
if (config.token_type === 'static') return config.access_token;
|
|
235
|
+
|
|
227
236
|
const now = Math.floor(Date.now() / 1000);
|
|
228
237
|
|
|
229
238
|
// Token still valid (with 30s buffer)
|
|
@@ -347,6 +356,66 @@ async function login(brainDir, apiUrl) {
|
|
|
347
356
|
};
|
|
348
357
|
}
|
|
349
358
|
|
|
359
|
+
/**
|
|
360
|
+
* True when `url` is safe to send a bearer token to: HTTPS, or plain HTTP to
|
|
361
|
+
* this machine only.
|
|
362
|
+
*/
|
|
363
|
+
function isSecureUrl(url) {
|
|
364
|
+
const parsed = new URL(url);
|
|
365
|
+
if (parsed.protocol === 'https:') return true;
|
|
366
|
+
return ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Log in to a store with a static bearer token (self-hosted brain-store).
|
|
371
|
+
*
|
|
372
|
+
* Verifies the token, links the user's first brain (creating one when the
|
|
373
|
+
* account has none), and saves the config. There is no refresh token.
|
|
374
|
+
*
|
|
375
|
+
* @param {string} brainDir
|
|
376
|
+
* @param {string} apiUrl
|
|
377
|
+
* @param {string} token
|
|
378
|
+
* @param {Object} [opts]
|
|
379
|
+
* @param {boolean} [opts.allowHttp] permit plain HTTP to a non-local host
|
|
380
|
+
* @returns {Promise<{user_email: string, brain_id: string, api_url: string}>}
|
|
381
|
+
*/
|
|
382
|
+
async function loginWithToken(brainDir, apiUrl, token, opts = {}) {
|
|
383
|
+
if (!apiUrl) throw new Error('A token login needs the store address: --api-url URL');
|
|
384
|
+
if (!token) throw new Error('No token given.');
|
|
385
|
+
const url = apiUrl.replace(/\/+$/, '');
|
|
386
|
+
if (!opts.allowHttp && !isSecureUrl(url)) {
|
|
387
|
+
throw new Error(
|
|
388
|
+
`Refusing to send a token over plain HTTP to ${new URL(url).host}. ` +
|
|
389
|
+
'Use an https:// address, or pass --allow-http if the network is trusted.'
|
|
390
|
+
);
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
const meRes = await jsonRequest(`${url}/auth/me`, 'GET', null, token);
|
|
394
|
+
if (meRes.status === 401) throw new Error('The store rejected this token.');
|
|
395
|
+
if (meRes.status !== 200) throw new Error(`Login failed (${meRes.status}): ${meRes.data.error || ''}`);
|
|
396
|
+
const user = meRes.data.user || {};
|
|
397
|
+
|
|
398
|
+
const brainsRes = await jsonRequest(`${url}/api/brains`, 'GET', null, token);
|
|
399
|
+
if (brainsRes.status !== 200) throw new Error(`Could not list brains (${brainsRes.status}).`);
|
|
400
|
+
let brainId = Array.isArray(brainsRes.data) && brainsRes.data.length > 0 ? brainsRes.data[0].id : null;
|
|
401
|
+
if (!brainId) {
|
|
402
|
+
const created = await jsonRequest(`${url}/api/brains`, 'POST', { name: 'default' }, token);
|
|
403
|
+
if (created.status !== 201) throw new Error(`Could not create a brain (${created.status}): ${created.data.error || ''}`);
|
|
404
|
+
brainId = created.data.id;
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
const config = {
|
|
408
|
+
api_url: url,
|
|
409
|
+
token_type: 'static',
|
|
410
|
+
access_token: token,
|
|
411
|
+
brain_id: brainId,
|
|
412
|
+
user_email: user.email || user.name || '',
|
|
413
|
+
connected_at: new Date().toISOString(),
|
|
414
|
+
};
|
|
415
|
+
writeConfig(brainDir, config);
|
|
416
|
+
return { user_email: config.user_email, brain_id: brainId, api_url: url };
|
|
417
|
+
}
|
|
418
|
+
|
|
350
419
|
/**
|
|
351
420
|
* Logout — clear stored tokens.
|
|
352
421
|
*
|
|
@@ -380,6 +449,9 @@ function packBrain(brainDir) {
|
|
|
380
449
|
execFileSync('tar', ['czf', tmpFile, ...excludeArgs, '-C', brainDir, '.'], {
|
|
381
450
|
stdio: 'pipe',
|
|
382
451
|
timeout: 120000,
|
|
452
|
+
// macOS tar otherwise adds an AppleDouble "._name" entry beside every file
|
|
453
|
+
// that has extended attributes, which bloats the archive and its file count.
|
|
454
|
+
env: { ...process.env, COPYFILE_DISABLE: '1' },
|
|
383
455
|
});
|
|
384
456
|
|
|
385
457
|
return tmpFile;
|
|
@@ -428,13 +500,38 @@ function copyExtracted(srcDir, destDir) {
|
|
|
428
500
|
// Push / Pull
|
|
429
501
|
// ---------------------------------------------------------------------------
|
|
430
502
|
|
|
503
|
+
/**
|
|
504
|
+
* Thrown when the store holds changes this brain has not pulled. Nothing was
|
|
505
|
+
* uploaded.
|
|
506
|
+
*/
|
|
507
|
+
class PushConflictError extends Error {
|
|
508
|
+
constructor(remoteChecksum, baseChecksum) {
|
|
509
|
+
super(
|
|
510
|
+
'The store has changes you have not pulled, so nothing was uploaded. ' +
|
|
511
|
+
'Run `brain cloud pull` and push again, or `brain cloud push --force` to overwrite the store.'
|
|
512
|
+
);
|
|
513
|
+
this.name = 'PushConflictError';
|
|
514
|
+
this.code = 'PUSH_CONFLICT';
|
|
515
|
+
this.remote_checksum = remoteChecksum || null;
|
|
516
|
+
this.base_checksum = baseChecksum || null;
|
|
517
|
+
}
|
|
518
|
+
}
|
|
519
|
+
|
|
431
520
|
/**
|
|
432
521
|
* Push ~/.brain/ to the cloud.
|
|
433
522
|
*
|
|
523
|
+
* When this brain knows the checksum of the archive it last pulled or pushed,
|
|
524
|
+
* the upload is conditional (`If-Match`): a store that has moved on answers 412
|
|
525
|
+
* and nothing is overwritten. Stores that predate contract 1.1 ignore the header
|
|
526
|
+
* and behave as before.
|
|
527
|
+
*
|
|
434
528
|
* @param {string} brainDir
|
|
529
|
+
* @param {Object} [opts]
|
|
530
|
+
* @param {boolean} [opts.force] upload unconditionally, replacing whatever the store holds
|
|
435
531
|
* @returns {Promise<{size_bytes: number, file_count: number, checksum: string}>}
|
|
532
|
+
* @throws {PushConflictError}
|
|
436
533
|
*/
|
|
437
|
-
async function push(brainDir) {
|
|
534
|
+
async function push(brainDir, opts = {}) {
|
|
438
535
|
const config = readConfig(brainDir);
|
|
439
536
|
if (!config) throw new Error('Not logged in. Run cloud login first.');
|
|
440
537
|
if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
|
|
@@ -448,17 +545,28 @@ async function push(brainDir) {
|
|
|
448
545
|
const tarSize = fs.statSync(tarPath).size;
|
|
449
546
|
const url = `${config.api_url}/api/brains/${config.brain_id}/sync`;
|
|
450
547
|
|
|
451
|
-
const
|
|
548
|
+
const conditional = !opts.force && config.base_checksum
|
|
549
|
+
? { 'If-Match': `"${config.base_checksum}"` }
|
|
550
|
+
: null;
|
|
551
|
+
const res = await uploadFile(url, tarPath, token, conditional);
|
|
552
|
+
|
|
553
|
+
if (res.status === 412) {
|
|
554
|
+
let remote = null;
|
|
555
|
+
try { remote = JSON.parse(res.body).current_checksum; } catch { /* body is advisory */ }
|
|
556
|
+
throw new PushConflictError(remote, config.base_checksum);
|
|
557
|
+
}
|
|
452
558
|
|
|
453
559
|
if (res.status !== 200) {
|
|
454
|
-
|
|
455
|
-
|
|
560
|
+
let message = res.body;
|
|
561
|
+
try { message = JSON.parse(res.body).error || res.body; } catch { /* not JSON */ }
|
|
562
|
+
throw new Error(`Push failed (${res.status}): ${message}`);
|
|
456
563
|
}
|
|
457
564
|
|
|
458
565
|
const result = JSON.parse(res.body);
|
|
459
566
|
|
|
460
|
-
// Update config with last push time
|
|
567
|
+
// Update config with last push time, and remember what the store now holds.
|
|
461
568
|
config.last_push = new Date().toISOString();
|
|
569
|
+
if (result.checksum) config.base_checksum = result.checksum;
|
|
462
570
|
writeConfig(brainDir, config);
|
|
463
571
|
|
|
464
572
|
return { ...result, local_size: tarSize };
|
|
@@ -490,8 +598,9 @@ async function pull(brainDir) {
|
|
|
490
598
|
// Extract into ~/.brain/
|
|
491
599
|
unpackBrain(tmpFile, brainDir);
|
|
492
600
|
|
|
493
|
-
// Update config
|
|
601
|
+
// Update config, and remember which archive this brain is now based on.
|
|
494
602
|
config.last_pull = new Date().toISOString();
|
|
603
|
+
if (checksum) config.base_checksum = checksum;
|
|
495
604
|
writeConfig(brainDir, config);
|
|
496
605
|
|
|
497
606
|
return { size_bytes: size, checksum };
|
|
@@ -507,7 +616,7 @@ async function pull(brainDir) {
|
|
|
507
616
|
// Local entries a cloud restore must never touch: sync/auth infrastructure and
|
|
508
617
|
// _archived/, which is deliberately excluded from cloud pushes (see
|
|
509
618
|
// TAR_EXCLUDES) and so does not exist in the snapshot being restored.
|
|
510
|
-
const RESTORE_PRESERVE = new Set(['.sync', '.cloud', '.DS_Store', '_archived']);
|
|
619
|
+
const RESTORE_PRESERVE = new Set(['.sync', '.cloud', '.local', '.DS_Store', '_archived']);
|
|
511
620
|
|
|
512
621
|
/**
|
|
513
622
|
* List cloud restore points — pre-overwrite snapshots Brain Cloud takes
|
|
@@ -653,7 +762,9 @@ async function status(brainDir) {
|
|
|
653
762
|
|
|
654
763
|
module.exports = {
|
|
655
764
|
login,
|
|
765
|
+
loginWithToken,
|
|
656
766
|
logout,
|
|
767
|
+
PushConflictError,
|
|
657
768
|
push,
|
|
658
769
|
pull,
|
|
659
770
|
listVersions,
|
|
@@ -668,5 +779,6 @@ module.exports = {
|
|
|
668
779
|
packBrain,
|
|
669
780
|
unpackBrain,
|
|
670
781
|
resolvePaths,
|
|
782
|
+
isSecureUrl,
|
|
671
783
|
DEFAULT_API_URL,
|
|
672
784
|
};
|
package/src/content-lint.js
CHANGED
|
@@ -11,6 +11,13 @@
|
|
|
11
11
|
* injection Text that tries to steer the agent against the user. Never
|
|
12
12
|
* downgraded — no legitimate memory says "ignore previous
|
|
13
13
|
* instructions" or pipes a download into a shell.
|
|
14
|
+
* authorization
|
|
15
|
+
* A claim that the agent may act without asking ("the user
|
|
16
|
+
* approved force-pushes", "no need to confirm deploys"). Never
|
|
17
|
+
* downgraded: a writer that invents permission is the failure
|
|
18
|
+
* this catches, and it happens without any attacker. Gated
|
|
19
|
+
* separately from injection by src/quarantine.js — even a
|
|
20
|
+
* user-origin claim needs the user's own words behind it.
|
|
14
21
|
* suspect Directive/imperative content. Downgraded to advisory for
|
|
15
22
|
* type:preference and cognitive_type:procedural memories, which
|
|
16
23
|
* legitimately contain instructions ("always use 2-space
|
|
@@ -20,7 +27,48 @@
|
|
|
20
27
|
* Pure and dependency-free; used at write time by bin/memorize.js.
|
|
21
28
|
*/
|
|
22
29
|
|
|
23
|
-
const SEVERITY_RANK = { none: 0, advisory: 1, suspect: 2,
|
|
30
|
+
const SEVERITY_RANK = { none: 0, advisory: 1, suspect: 2, authorization: 3, injection: 4 };
|
|
31
|
+
|
|
32
|
+
// secret_exfil pairs a transfer verb with a credential noun. Both must be
|
|
33
|
+
// standalone prose words: a verb that is a code literal or half of a compound
|
|
34
|
+
// (`upload`, upload-artifact, post-install) is a name, not an action, and a
|
|
35
|
+
// compound noun (password-reset, token_count) names a feature, not a secret.
|
|
36
|
+
// Without this, ordinary engineering notes ("the password-reset email", "set
|
|
37
|
+
// the destination to `upload`, then the API key…") quarantine as injections.
|
|
38
|
+
// `.env` is matched on its own: it starts with a non-word char, so a leading
|
|
39
|
+
// \b would require a word char before the dot and never match it bare.
|
|
40
|
+
const EXFIL_VERB = '(?<![`_\\-/.])\\b(?:send|post|upload|forward|exfiltrate|transmit|email)(?:s|ed|ing)?\\b(?![`_\\-/])';
|
|
41
|
+
const EXFIL_SECRET = '(?:(?<![`_\\-/])\\b(?:token|password|secret|api.?key|credential|private.?key)s?\\b(?![`_\\-])|(?<![\\w.])\\.env\\b)';
|
|
42
|
+
const EXFIL_GAP = '[^\\n.]{0,80}';
|
|
43
|
+
const SECRET_EXFIL_RE = new RegExp(
|
|
44
|
+
`${EXFIL_VERB}${EXFIL_GAP}${EXFIL_SECRET}|${EXFIL_SECRET}${EXFIL_GAP}${EXFIL_VERB}`,
|
|
45
|
+
'i'
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
// authorization_claim has three shapes, each anchored on who is granting or
|
|
49
|
+
// being granted — never on the bare words "approved"/"authorized", which
|
|
50
|
+
// ordinary notes about OAuth, RBAC and review workflows are full of:
|
|
51
|
+
// 1. a principal granted an *action* ("the user approved force-pushing");
|
|
52
|
+
// approving a design or a PR is a fact, not a permission, so an action
|
|
53
|
+
// verb must follow within the sentence;
|
|
54
|
+
// 2. the agent is told it may act ("you are allowed to", "Claude is
|
|
55
|
+
// permitted to");
|
|
56
|
+
// 3. confirmation is waived ("no need to ask", "pre-approved", "standing
|
|
57
|
+
// permission", "skip the confirmation").
|
|
58
|
+
const AUTHZ_GRANTOR = '\\b(?:the\\s+)?(?:user|owner|maintainer|admin(?:istrator)?|i|we)\\b';
|
|
59
|
+
const AUTHZ_GRANT = '(?:\\s+(?:has|have|had))?(?:\\s+(?:already|explicitly))?\\s+(?:approved|authori[sz]ed|okayed|ok\'d|signed\\s+off\\s+on|green-?lit|allowed|permitted)\\b';
|
|
60
|
+
const AUTHZ_ACTION = '\\b(?:force[\\s-]?push\\w*|push\\w*|deploy\\w*|delet\\w*|drop\\w*|merg\\w*|releas\\w*|publish\\w*|pay\\w*|send\\w*|email\\w*|transfer\\w*|run\\w*|execut\\w*|install\\w*|wip\\w*|rotat\\w*|revok\\w*|purchas\\w*|spend\\w*|skip\\w*|bypass\\w*|disabl\\w*|overwrit\\w*|rm\\b)';
|
|
61
|
+
const AUTHZ_AGENT = '\\b(?:you|the\\s+(?:agent|assistant|bot)|claude|codex|gemini|agents?)\\s+(?:are|is|have\\s+been|has\\s+been)(?:\\s+(?:now|always|explicitly))?\\s+(?:allowed|authori[sz]ed|permitted|cleared|granted\\s+(?:permission|access))\\b';
|
|
62
|
+
const AUTHZ_WAIVER = '\\b(?:no\\s+need\\s+to|(?:do\\s+not|don\'t|doesn\'t|does\\s+not)\\s+need\\s+to|without\\s+needing\\s+to)\\s+(?:ask|confirm|check\\s+with|get\\s+(?:approval|permission|sign-?off))\\b' +
|
|
63
|
+
// Predicate only, and not "pre-approved for": "deploys are pre-approved" is a
|
|
64
|
+
// permission; "pre-approved for a mortgage" and "pre-approved offers" are not.
|
|
65
|
+
'|\\b(?:is|are|was|were|be|been|now)\\s+pre-?(?:approved|authori[sz]ed)\\b(?!\\s+for\\b)' +
|
|
66
|
+
'|\\b(?:standing|blanket)\\s+(?:permission|approval|authori[sz]ation)\\b' +
|
|
67
|
+
'|\\bskip\\s+(?:the\\s+)?(?:confirmation|approval|permission)\\b';
|
|
68
|
+
const AUTHZ_RE = new RegExp(
|
|
69
|
+
`${AUTHZ_GRANTOR}${AUTHZ_GRANT}[^\\n.]{0,60}${AUTHZ_ACTION}|${AUTHZ_AGENT}|${AUTHZ_WAIVER}`,
|
|
70
|
+
'i'
|
|
71
|
+
);
|
|
24
72
|
|
|
25
73
|
// Each rule: name, base severity, and a matcher over the combined text.
|
|
26
74
|
// Patterns are case-insensitive; `m` where line-anchoring matters.
|
|
@@ -38,7 +86,12 @@ const RULES = [
|
|
|
38
86
|
{
|
|
39
87
|
rule: 'secret_exfil',
|
|
40
88
|
severity: 'injection',
|
|
41
|
-
re:
|
|
89
|
+
re: SECRET_EXFIL_RE,
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
rule: 'authorization_claim',
|
|
93
|
+
severity: 'authorization',
|
|
94
|
+
re: AUTHZ_RE,
|
|
42
95
|
},
|
|
43
96
|
{
|
|
44
97
|
rule: 'imperative_directive',
|
package/src/export-import.js
CHANGED
|
@@ -13,7 +13,7 @@ const path = require('path');
|
|
|
13
13
|
const { encrypt, decrypt } = require('./crypto');
|
|
14
14
|
|
|
15
15
|
// Directories inside ~/.brain/ to skip during export
|
|
16
|
-
const EXCLUDED = new Set(['.sync', '.DS_Store']);
|
|
16
|
+
const EXCLUDED = new Set(['.sync', '.local', '.DS_Store']);
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
19
|
* Export the entire ~/.brain/ directory to a single file.
|
package/src/git-sync.js
CHANGED
|
@@ -20,7 +20,7 @@ const CONFIG_FILE = 'config.json';
|
|
|
20
20
|
// Files/dirs inside ~/.brain/ that should NOT be synced. `.cloud` holds Brain
|
|
21
21
|
// Cloud OAuth tokens and pre-restore backups — credentials must never be
|
|
22
22
|
// committed to a git remote.
|
|
23
|
-
const EXCLUDED = new Set(['.sync', '.cloud', '.DS_Store']);
|
|
23
|
+
const EXCLUDED = new Set(['.sync', '.cloud', '.local', '.DS_Store']);
|
|
24
24
|
|
|
25
25
|
/**
|
|
26
26
|
* Check whether `git` is available on PATH.
|
package/src/index-manager.js
CHANGED
|
@@ -38,11 +38,15 @@ const DEFAULT_CONFIG = {
|
|
|
38
38
|
// here or approves them one by one with `brain verify approve`.
|
|
39
39
|
sensitive_topics: false,
|
|
40
40
|
// ASI06 quarantine for low-trust writes: 'off' (never flag), 'flag'
|
|
41
|
-
// (recallable but marked + surfaced for verification
|
|
42
|
-
//
|
|
43
|
-
// is evaluated at read time, so flipping the knob retroactively
|
|
44
|
-
// hides/reveals already-pending memories.
|
|
45
|
-
|
|
41
|
+
// (recallable but marked + surfaced for verification), or 'enforce'
|
|
42
|
+
// (excluded from recall/session-start until approved — the default).
|
|
43
|
+
// Exclusion is evaluated at read time, so flipping the knob retroactively
|
|
44
|
+
// hides/reveals already-pending memories. src/quarantine.js owns the
|
|
45
|
+
// default; keep the two in step.
|
|
46
|
+
quarantine_mode: 'enforce',
|
|
47
|
+
// Most low-trust (tool-output / external) memories one recall result set
|
|
48
|
+
// may hold, approved or not. See capLowTrust in src/provenance.js.
|
|
49
|
+
recall_low_trust_max: 1,
|
|
46
50
|
};
|
|
47
51
|
|
|
48
52
|
/**
|