brain-memory 0.1.0-beta.2 → 0.1.0-beta.20

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 (44) hide show
  1. package/README.md +270 -72
  2. package/assets/icon.png +0 -0
  3. package/assets/icon.svg +27 -0
  4. package/bin/brain.js +111 -0
  5. package/bin/cloud-sync.js +149 -0
  6. package/bin/install.js +217 -242
  7. package/bin/memorize.js +433 -0
  8. package/bin/pin.js +44 -0
  9. package/bin/recall.js +237 -0
  10. package/bin/reinforce.js +187 -0
  11. package/bin/session-start.js +292 -0
  12. package/bin/skill.js +67 -0
  13. package/bin/unpin.js +38 -0
  14. package/commands/brain/consolidate.md +7 -2
  15. package/commands/brain/explore.md +7 -2
  16. package/commands/brain/forget.md +7 -2
  17. package/commands/brain/init.md +8 -12
  18. package/commands/brain/memorize.md +76 -144
  19. package/commands/brain/pin.md +37 -0
  20. package/commands/brain/remember.md +48 -105
  21. package/commands/brain/review.md +7 -2
  22. package/commands/brain/skills.md +60 -0
  23. package/commands/brain/sleep.md +68 -27
  24. package/commands/brain/status.md +19 -5
  25. package/commands/brain/sunshine.md +18 -13
  26. package/commands/brain/sync.md +360 -0
  27. package/commands/brain/unpin.md +26 -0
  28. package/package.json +18 -8
  29. package/prompts/claude.md +115 -12
  30. package/prompts/gemini.md +115 -12
  31. package/prompts/openai.md +113 -10
  32. package/prompts/opencode.md +178 -0
  33. package/src/cloud-sync.js +524 -0
  34. package/src/crypto.js +130 -0
  35. package/src/export-import.js +185 -0
  36. package/src/git-sync.js +444 -0
  37. package/src/index-manager.js +205 -18
  38. package/src/installer.js +384 -0
  39. package/src/pinning.js +124 -0
  40. package/src/scorer.js +6 -2
  41. package/src/skills.js +208 -0
  42. package/src/tfidf.js +408 -0
  43. package/hooks/session-end.md +0 -48
  44. package/hooks/session-start.md +0 -48
@@ -0,0 +1,178 @@
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
+ - `/brain:init` — Initialize the brain structure
52
+ - `/brain:memorize [topic]` — Store memories from current context
53
+ - `/brain:remember [query]` — Recall relevant memories with spreading activation and context matching
54
+ - `/brain:review [scope]` — Spaced repetition review session for due memories
55
+ - `/brain:explore [category]` — Browse the brain hierarchy
56
+ - `/brain:consolidate [scope]` — Merge related weak memories into stronger ones
57
+ - `/brain:forget [target]` — Decay or archive memories
58
+ - `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
59
+ - `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
60
+ - `/brain:status` — Dashboard with brain health overview
61
+ - `/brain:sync [subcommand]` — Sync memories via Git remote or export/import for portability
62
+ - `/brain:pin [id|query]` — Pin a memory to the always-present tier (CoALA Phase 1)
63
+ - `/brain:unpin [id|query]` — Remove a memory from the always-present tier
64
+ - `/brain:skills [list|show|add|use|remove|export]` — Manage procedural skills (CoALA Phase 2)
65
+
66
+ ## Session Start Behavior
67
+
68
+ **Perform these steps at session start — but keep it lightweight.**
69
+
70
+ If `~/.brain/index.json` exists:
71
+
72
+ 1. **Run the session-start aggregator** — one deterministic, budget-bounded call:
73
+ ```bash
74
+ brain session-start --project "<current project>"
75
+ ```
76
+ 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`, `low_confidence_alerts`, and `budget`. If `~/.brain/index.json` is absent it returns an empty payload.
77
+ 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.
78
+ 3. **Output a single status line:**
79
+
80
+ ```
81
+ 🧠 Brain active — <N> memories (<M> in project context)
82
+ ```
83
+
84
+ Only add extra lines if actionable:
85
+ - `📋 <X> due for review` — if `due_for_review > 0`
86
+ - `⚠️ <N> low-confidence memories used frequently` — if `low_confidence_alerts` is non-empty
87
+
88
+ 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.
89
+
90
+ ## Ambient Session Tracking
91
+
92
+ **Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
93
+
94
+ Track these categories as they happen:
95
+ - **Decisions** — Architecture choices, technology selections, trade-off resolutions
96
+ - **Learnings** — New patterns, debugging insights, API discoveries
97
+ - **Insights** — Realizations about the codebase, project, or process
98
+ - **Experiences** — Significant events like incidents, deployments, milestones
99
+ - **Goals** — New objectives discussed or planned
100
+
101
+ **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.
102
+
103
+ ## Periodic Memory Checkpoint
104
+
105
+ **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.
106
+
107
+ If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
108
+
109
+ ```
110
+ 🧠 Notable <type(s)> this session — /brain:memorize when ready
111
+ ```
112
+
113
+ **Rules:**
114
+ - **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
115
+ - **At most once per ~10 substantive interactions** — no spamming
116
+ - **Reset the counter** after the user runs `/brain:memorize`
117
+ - **Don't mention if nothing notable** has accumulated
118
+ - **Be specific about types** — say "decisions and learnings" not just "notable content"
119
+
120
+ ## Session End Behavior
121
+
122
+ 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**:
123
+
124
+ ### Step 1: Save Session Context (ALWAYS — do this first)
125
+
126
+ **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.
127
+
128
+ ```json
129
+ {
130
+ "session_id": "<timestamp-based-id>",
131
+ "started": "<session start ISO timestamp>",
132
+ "ended": "<session end ISO timestamp>",
133
+ "project": "<current project name>",
134
+ "topics": ["<key topics discussed>"],
135
+ "task_type": "<primary task type>",
136
+ "memories_created": ["<IDs of memories stored this session>"],
137
+ "memories_recalled": ["<IDs of memories retrieved this session>"],
138
+ "notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
139
+ }
140
+ ```
141
+
142
+ 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.
143
+
144
+ ### Step 2: Suggest Memorization (if warranted)
145
+
146
+ If the session contained meaningful content based on your ambient tracking:
147
+
148
+ ```
149
+ 💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
150
+ Run /brain:memorize to capture them before this context is lost.
151
+ ```
152
+
153
+ **Rules:**
154
+ - Do NOT auto-memorize without user consent
155
+ - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
156
+ - Only suggest when there is genuinely valuable context worth preserving
157
+ - **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
158
+
159
+ ## When Recalling Memories
160
+
161
+ 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:
162
+
163
+ 1. Run `brain recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
164
+ 2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
165
+ 3. Read the top-scoring memory files and present results
166
+ 4. Run `brain reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
167
+ 5. If no matches, search the archive (`~/.brain/_archived/`)
168
+
169
+ The recall engine ensures **identical scoring across all agents** — Claude, Gemini, Codex, and OpenCode all get the same rankings for the same query.
170
+
171
+ ## Portable Sync
172
+
173
+ Brain memories can be synced across devices in two ways:
174
+
175
+ 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`.
176
+ 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
177
+
178
+ Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
@@ -0,0 +1,524 @@
1
+ /**
2
+ * Brain Memory — Cloud Sync Engine
3
+ *
4
+ * Push/pull ~/.brain/ memories via the Brain Cloud API (api.brainmemory.work).
5
+ * Uses the device code OAuth flow for CLI authentication.
6
+ *
7
+ * Zero external dependencies — uses Node.js built-in https, fs, child_process.
8
+ */
9
+
10
+ const { execFileSync } = require('child_process');
11
+ const fs = require('fs');
12
+ const path = require('path');
13
+ const os = require('os');
14
+ const https = require('https');
15
+ const http = require('http');
16
+
17
+ const CLOUD_DIR = '.cloud';
18
+ const CONFIG_FILE = 'config.json';
19
+ const DEFAULT_API_URL = 'https://api.brainmemory.work';
20
+
21
+ // Files/dirs inside ~/.brain/ that should NOT be synced
22
+ const TAR_EXCLUDES = ['.sync', '.cloud', '.DS_Store', '_archived'];
23
+
24
+ // ---------------------------------------------------------------------------
25
+ // HTTP helpers (zero-dependency, works on Node >= 18)
26
+ // ---------------------------------------------------------------------------
27
+
28
+ /**
29
+ * Make an HTTP(S) request. Returns { status, headers, body }.
30
+ *
31
+ * @param {string} url
32
+ * @param {Object} [opts]
33
+ * @param {string} [opts.method='GET']
34
+ * @param {Object} [opts.headers]
35
+ * @param {Buffer|string} [opts.body]
36
+ * @returns {Promise<{status: number, headers: Object, body: string}>}
37
+ */
38
+ function request(url, opts = {}, _redirectCount = 0) {
39
+ return new Promise((resolve, reject) => {
40
+ if (_redirectCount > 5) return reject(new Error('Too many redirects'));
41
+
42
+ const parsed = new URL(url);
43
+ const mod = parsed.protocol === 'https:' ? https : http;
44
+ const reqOpts = {
45
+ method: opts.method || 'GET',
46
+ hostname: parsed.hostname,
47
+ port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
48
+ path: parsed.pathname + parsed.search,
49
+ headers: opts.headers || {},
50
+ };
51
+
52
+ const req = mod.request(reqOpts, (res) => {
53
+ // Follow redirects
54
+ if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
55
+ const redirectUrl = new URL(res.headers.location, url).href;
56
+ // For 307/308, preserve method and body; for 301/302, switch to GET
57
+ const newOpts = [307, 308].includes(res.statusCode)
58
+ ? opts
59
+ : { ...opts, method: 'GET', body: undefined };
60
+ res.resume(); // drain the response
61
+ return resolve(request(redirectUrl, newOpts, _redirectCount + 1));
62
+ }
63
+
64
+ const chunks = [];
65
+ res.on('data', (chunk) => chunks.push(chunk));
66
+ res.on('end', () => {
67
+ resolve({
68
+ status: res.statusCode,
69
+ headers: res.headers,
70
+ body: Buffer.concat(chunks).toString('utf8'),
71
+ });
72
+ });
73
+ });
74
+
75
+ req.on('error', reject);
76
+ req.setTimeout(60000, () => { req.destroy(new Error('Request timed out')); });
77
+
78
+ if (opts.body) req.write(opts.body);
79
+ req.end();
80
+ });
81
+ }
82
+
83
+ /**
84
+ * JSON POST/PUT helper.
85
+ */
86
+ async function jsonRequest(url, method, data, token) {
87
+ const headers = { 'Content-Type': 'application/json' };
88
+ if (token) headers['Authorization'] = `Bearer ${token}`;
89
+ const body = data != null ? JSON.stringify(data) : undefined;
90
+ if (body) headers['Content-Length'] = Buffer.byteLength(body).toString();
91
+ const res = await request(url, { method, headers, body });
92
+ try {
93
+ return { status: res.status, data: JSON.parse(res.body) };
94
+ } catch {
95
+ throw new Error(`Non-JSON response (${res.status}) from ${method} ${url}: ${res.body.slice(0, 200)}`);
96
+ }
97
+ }
98
+
99
+ /**
100
+ * Upload a file as multipart/form-data.
101
+ */
102
+ async function uploadFile(url, filePath, token) {
103
+ const boundary = '----BrainCloudUpload' + Date.now();
104
+ const fileContent = fs.readFileSync(filePath);
105
+ const header = Buffer.from(
106
+ `--${boundary}\r\n` +
107
+ `Content-Disposition: form-data; name="brain"; filename="brain.tar.gz"\r\n` +
108
+ `Content-Type: application/gzip\r\n\r\n`
109
+ );
110
+ const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
111
+ const body = Buffer.concat([header, fileContent, footer]);
112
+
113
+ return request(url, {
114
+ method: 'PUT',
115
+ headers: {
116
+ 'Content-Type': `multipart/form-data; boundary=${boundary}`,
117
+ 'Content-Length': body.length.toString(),
118
+ 'Authorization': `Bearer ${token}`,
119
+ },
120
+ body,
121
+ });
122
+ }
123
+
124
+ /**
125
+ * Download a file from URL, save to disk.
126
+ */
127
+ function downloadFile(url, destPath, token, _redirectCount = 0) {
128
+ return new Promise((resolve, reject) => {
129
+ if (_redirectCount > 5) return reject(new Error('Too many redirects'));
130
+
131
+ const parsed = new URL(url);
132
+ const mod = parsed.protocol === 'https:' ? https : http;
133
+ const reqOpts = {
134
+ method: 'GET',
135
+ hostname: parsed.hostname,
136
+ port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
137
+ path: parsed.pathname + parsed.search,
138
+ headers: { 'Authorization': `Bearer ${token}` },
139
+ };
140
+
141
+ const req = mod.request(reqOpts, (res) => {
142
+ // Follow redirects
143
+ if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
144
+ const redirectUrl = new URL(res.headers.location, url).href;
145
+ res.resume();
146
+ return resolve(downloadFile(redirectUrl, destPath, token, _redirectCount + 1));
147
+ }
148
+
149
+ if (res.statusCode !== 200) {
150
+ const chunks = [];
151
+ res.on('data', (c) => chunks.push(c));
152
+ res.on('end', () => {
153
+ reject(new Error(`Download failed (${res.statusCode}): ${Buffer.concat(chunks).toString()}`));
154
+ });
155
+ return;
156
+ }
157
+
158
+ const ws = fs.createWriteStream(destPath);
159
+ res.pipe(ws);
160
+ ws.on('finish', () => {
161
+ ws.close();
162
+ resolve({ checksum: res.headers['x-checksum'] || null });
163
+ });
164
+ ws.on('error', reject);
165
+ });
166
+
167
+ req.on('error', reject);
168
+ req.setTimeout(300000, () => { req.destroy(new Error('Download timed out')); });
169
+ req.end();
170
+ });
171
+ }
172
+
173
+ // ---------------------------------------------------------------------------
174
+ // Config management — stored at ~/.brain/.cloud/config.json
175
+ // ---------------------------------------------------------------------------
176
+
177
+ function resolvePaths(brainDir) {
178
+ const cloudDir = path.join(brainDir, CLOUD_DIR);
179
+ const configPath = path.join(cloudDir, CONFIG_FILE);
180
+ return { cloudDir, configPath };
181
+ }
182
+
183
+ function readConfig(brainDir) {
184
+ const { configPath } = resolvePaths(brainDir);
185
+ try {
186
+ return JSON.parse(fs.readFileSync(configPath, 'utf8'));
187
+ } catch {
188
+ return null;
189
+ }
190
+ }
191
+
192
+ function writeConfig(brainDir, config) {
193
+ const { cloudDir, configPath } = resolvePaths(brainDir);
194
+ fs.mkdirSync(cloudDir, { recursive: true });
195
+ fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
196
+ }
197
+
198
+ function deleteConfig(brainDir) {
199
+ const { cloudDir } = resolvePaths(brainDir);
200
+ fs.rmSync(cloudDir, { recursive: true, force: true });
201
+ }
202
+
203
+ // ---------------------------------------------------------------------------
204
+ // Token management
205
+ // ---------------------------------------------------------------------------
206
+
207
+ /**
208
+ * Get a valid access token, refreshing if needed.
209
+ *
210
+ * @param {string} brainDir
211
+ * @returns {Promise<string>} access token
212
+ */
213
+ async function getValidToken(brainDir) {
214
+ const config = readConfig(brainDir);
215
+ if (!config) throw new Error('Not logged in. Run cloud login first.');
216
+
217
+ const now = Math.floor(Date.now() / 1000);
218
+
219
+ // Token still valid (with 30s buffer)
220
+ if (config.expires_at && now < config.expires_at - 30) {
221
+ return config.access_token;
222
+ }
223
+
224
+ // Try refresh
225
+ if (!config.refresh_token) {
226
+ throw new Error('Session expired and no refresh token. Run cloud login again.');
227
+ }
228
+
229
+ const res = await jsonRequest(
230
+ `${config.api_url}/auth/refresh`,
231
+ 'POST',
232
+ { refresh_token: config.refresh_token }
233
+ );
234
+
235
+ if (res.status !== 200) {
236
+ throw new Error('Token refresh failed. Run cloud login again.');
237
+ }
238
+
239
+ config.access_token = res.data.access_token;
240
+ config.refresh_token = res.data.refresh_token;
241
+ config.expires_at = res.data.expires_at;
242
+ writeConfig(brainDir, config);
243
+
244
+ return config.access_token;
245
+ }
246
+
247
+ // ---------------------------------------------------------------------------
248
+ // Device code auth flow
249
+ // ---------------------------------------------------------------------------
250
+
251
+ /**
252
+ * Start the device code login flow.
253
+ * Returns the device code info so the caller can display it to the user.
254
+ *
255
+ * @param {string} apiUrl
256
+ * @returns {Promise<{device_code: string, user_code: string, verify_url: string, expires_in: number}>}
257
+ */
258
+ async function requestDeviceCode(apiUrl) {
259
+ const res = await jsonRequest(`${apiUrl}/auth/device/request`, 'POST', {});
260
+ if (res.status !== 200) {
261
+ throw new Error(`Failed to request device code: ${JSON.stringify(res.data)}`);
262
+ }
263
+ return res.data;
264
+ }
265
+
266
+ /**
267
+ * Poll for device code approval.
268
+ *
269
+ * @param {string} apiUrl
270
+ * @param {string} deviceCode
271
+ * @param {number} interval - Poll interval in ms (default 5000)
272
+ * @param {number} timeout - Max wait in ms (default 600000 = 10 min)
273
+ * @returns {Promise<{access_token: string, refresh_token: string, expires_at: number}>}
274
+ */
275
+ async function pollDeviceCode(apiUrl, deviceCode, interval = 5000, timeout = 600000) {
276
+ const deadline = Date.now() + timeout;
277
+
278
+ while (Date.now() < deadline) {
279
+ const res = await jsonRequest(`${apiUrl}/auth/device/poll`, 'POST', { device_code: deviceCode });
280
+
281
+ if (res.status === 200 && res.data.status === 'approved' && res.data.tokens) {
282
+ return res.data.tokens;
283
+ }
284
+
285
+ if (res.status === 404 || (res.data && res.data.error && res.data.error.includes('expired'))) {
286
+ throw new Error('Device code expired. Try again.');
287
+ }
288
+
289
+ // Still pending — wait and retry
290
+ await new Promise((r) => setTimeout(r, interval));
291
+ }
292
+
293
+ throw new Error('Login timed out. Try again.');
294
+ }
295
+
296
+ /**
297
+ * Full login flow: request code, poll, save config.
298
+ *
299
+ * @param {string} brainDir
300
+ * @param {string} [apiUrl]
301
+ * @returns {Promise<{user_code: string, verify_url: string, waitForApproval: () => Promise<void>}>}
302
+ */
303
+ async function login(brainDir, apiUrl) {
304
+ const url = apiUrl || DEFAULT_API_URL;
305
+ const codeInfo = await requestDeviceCode(url);
306
+
307
+ return {
308
+ user_code: codeInfo.user_code,
309
+ verify_url: codeInfo.verify_url,
310
+ expires_in: codeInfo.expires_in,
311
+ waitForApproval: async () => {
312
+ const tokens = await pollDeviceCode(url, codeInfo.device_code);
313
+
314
+ // Fetch user info + default brain
315
+ const meRes = await jsonRequest(`${url}/auth/me`, 'GET', null, tokens.access_token);
316
+ let userEmail = '';
317
+ if (meRes.status === 200 && meRes.data.user) {
318
+ userEmail = meRes.data.user.email;
319
+ }
320
+
321
+ const brainsRes = await jsonRequest(`${url}/api/brains`, 'GET', null, tokens.access_token);
322
+ let brainId = null;
323
+ if (brainsRes.status === 200 && Array.isArray(brainsRes.data) && brainsRes.data.length > 0) {
324
+ brainId = brainsRes.data[0].id;
325
+ }
326
+
327
+ writeConfig(brainDir, {
328
+ api_url: url,
329
+ access_token: tokens.access_token,
330
+ refresh_token: tokens.refresh_token,
331
+ expires_at: tokens.expires_at,
332
+ brain_id: brainId,
333
+ user_email: userEmail,
334
+ connected_at: new Date().toISOString(),
335
+ });
336
+ },
337
+ };
338
+ }
339
+
340
+ /**
341
+ * Logout — clear stored tokens.
342
+ *
343
+ * @param {string} brainDir
344
+ */
345
+ function logout(brainDir) {
346
+ deleteConfig(brainDir);
347
+ }
348
+
349
+ // ---------------------------------------------------------------------------
350
+ // Tar helpers
351
+ // ---------------------------------------------------------------------------
352
+
353
+ function packBrain(brainDir) {
354
+ const tmpFile = path.join(os.tmpdir(), `brain-upload-${Date.now()}.tar.gz`);
355
+ const excludeArgs = TAR_EXCLUDES.flatMap((e) => ['--exclude', e]);
356
+
357
+ execFileSync('tar', ['czf', tmpFile, ...excludeArgs, '-C', brainDir, '.'], {
358
+ stdio: 'pipe',
359
+ timeout: 120000,
360
+ });
361
+
362
+ return tmpFile;
363
+ }
364
+
365
+ function unpackBrain(tarPath, brainDir) {
366
+ // Extract into brain dir, overwriting existing files
367
+ execFileSync('tar', ['xzf', tarPath, '-C', brainDir], {
368
+ stdio: 'pipe',
369
+ timeout: 120000,
370
+ });
371
+ }
372
+
373
+ // ---------------------------------------------------------------------------
374
+ // Push / Pull
375
+ // ---------------------------------------------------------------------------
376
+
377
+ /**
378
+ * Push ~/.brain/ to the cloud.
379
+ *
380
+ * @param {string} brainDir
381
+ * @returns {Promise<{size_bytes: number, file_count: number, checksum: string}>}
382
+ */
383
+ async function push(brainDir) {
384
+ const config = readConfig(brainDir);
385
+ if (!config) throw new Error('Not logged in. Run cloud login first.');
386
+ if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
387
+
388
+ const token = await getValidToken(brainDir);
389
+
390
+ // Pack ~/.brain/ into tar.gz
391
+ const tarPath = packBrain(brainDir);
392
+
393
+ try {
394
+ const tarSize = fs.statSync(tarPath).size;
395
+ const url = `${config.api_url}/api/brains/${config.brain_id}/sync`;
396
+
397
+ const res = await uploadFile(url, tarPath, token);
398
+
399
+ if (res.status !== 200) {
400
+ const data = JSON.parse(res.body);
401
+ throw new Error(`Push failed (${res.status}): ${data.error || res.body}`);
402
+ }
403
+
404
+ const result = JSON.parse(res.body);
405
+
406
+ // Update config with last push time
407
+ config.last_push = new Date().toISOString();
408
+ writeConfig(brainDir, config);
409
+
410
+ return { ...result, local_size: tarSize };
411
+ } finally {
412
+ // Clean up temp file
413
+ try { fs.unlinkSync(tarPath); } catch { /* ignore */ }
414
+ }
415
+ }
416
+
417
+ /**
418
+ * Pull from the cloud into ~/.brain/.
419
+ *
420
+ * @param {string} brainDir
421
+ * @returns {Promise<{size_bytes: number, checksum: string|null}>}
422
+ */
423
+ async function pull(brainDir) {
424
+ const config = readConfig(brainDir);
425
+ if (!config) throw new Error('Not logged in. Run cloud login first.');
426
+ if (!config.brain_id) throw new Error('No brain linked. Run cloud login again.');
427
+
428
+ const token = await getValidToken(brainDir);
429
+ const url = `${config.api_url}/api/brains/${config.brain_id}/sync`;
430
+ const tmpFile = path.join(os.tmpdir(), `brain-download-${Date.now()}.tar.gz`);
431
+
432
+ try {
433
+ const { checksum } = await downloadFile(url, tmpFile, token);
434
+ const size = fs.statSync(tmpFile).size;
435
+
436
+ // Extract into ~/.brain/
437
+ unpackBrain(tmpFile, brainDir);
438
+
439
+ // Update config
440
+ config.last_pull = new Date().toISOString();
441
+ writeConfig(brainDir, config);
442
+
443
+ return { size_bytes: size, checksum };
444
+ } finally {
445
+ try { fs.unlinkSync(tmpFile); } catch { /* ignore */ }
446
+ }
447
+ }
448
+
449
+ // ---------------------------------------------------------------------------
450
+ // Status
451
+ // ---------------------------------------------------------------------------
452
+
453
+ /**
454
+ * Get cloud sync status.
455
+ *
456
+ * @param {string} brainDir
457
+ * @returns {Promise<Object>}
458
+ */
459
+ async function status(brainDir) {
460
+ const config = readConfig(brainDir);
461
+ if (!config) {
462
+ return { connected: false };
463
+ }
464
+
465
+ let brain = null;
466
+ let user = null;
467
+
468
+ try {
469
+ const token = await getValidToken(brainDir);
470
+
471
+ const meRes = await jsonRequest(`${config.api_url}/auth/me`, 'GET', null, token);
472
+ if (meRes.status === 200) {
473
+ user = meRes.data.user;
474
+ }
475
+
476
+ if (config.brain_id) {
477
+ const brainRes = await jsonRequest(
478
+ `${config.api_url}/api/brains/${config.brain_id}`,
479
+ 'GET', null, token
480
+ );
481
+ if (brainRes.status === 200) {
482
+ brain = brainRes.data;
483
+ }
484
+ }
485
+ } catch {
486
+ // Token may be expired — still report config
487
+ }
488
+
489
+ return {
490
+ connected: true,
491
+ api_url: config.api_url,
492
+ user_email: config.user_email || (user && user.email) || null,
493
+ brain_id: config.brain_id,
494
+ brain_name: brain ? brain.name : null,
495
+ brain_size: brain ? brain.size_bytes : null,
496
+ brain_files: brain ? brain.file_count : null,
497
+ last_synced: brain && brain.last_synced_at ? brain.last_synced_at : null,
498
+ last_push: config.last_push || null,
499
+ last_pull: config.last_pull || null,
500
+ connected_at: config.connected_at || null,
501
+ };
502
+ }
503
+
504
+ // ---------------------------------------------------------------------------
505
+ // Exports
506
+ // ---------------------------------------------------------------------------
507
+
508
+ module.exports = {
509
+ login,
510
+ logout,
511
+ push,
512
+ pull,
513
+ status,
514
+ readConfig,
515
+ writeConfig,
516
+ // Internal — exported for testing
517
+ requestDeviceCode,
518
+ pollDeviceCode,
519
+ getValidToken,
520
+ packBrain,
521
+ unpackBrain,
522
+ resolvePaths,
523
+ DEFAULT_API_URL,
524
+ };