brain-memory 0.1.0-beta.3 → 0.1.0-beta.31
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 +339 -0
- package/README.md +400 -94
- package/SECURITY.md +61 -0
- package/assets/brand/README.md +28 -0
- package/assets/brand/icon-dark.svg +19 -0
- package/assets/brand/icon-light.svg +20 -0
- package/assets/brand/linkedin_cover.png +0 -0
- package/assets/brand/linkedin_cover_light.png +0 -0
- package/assets/brand/mark-dark.svg +19 -0
- package/assets/brand/mark-light.svg +20 -0
- package/assets/brand/png/icon-dark-1024.png +0 -0
- package/assets/brand/png/icon-dark-128.png +0 -0
- package/assets/brand/png/icon-dark-256.png +0 -0
- package/assets/brand/png/icon-dark-512.png +0 -0
- package/assets/brand/png/icon-dark-64.png +0 -0
- package/assets/brand/png/icon-light-1024.png +0 -0
- package/assets/brand/png/icon-light-128.png +0 -0
- package/assets/brand/png/icon-light-256.png +0 -0
- package/assets/brand/png/icon-light-512.png +0 -0
- package/assets/brand/png/icon-light-64.png +0 -0
- package/assets/brand/png/mark-dark-1024.png +0 -0
- package/assets/brand/png/mark-light-1024.png +0 -0
- package/assets/icon.png +0 -0
- package/assets/icon.svg +19 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +150 -0
- package/bin/forget.js +122 -0
- package/bin/install.js +229 -254
- package/bin/memorize.js +458 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +259 -0
- package/bin/reinforce.js +187 -0
- package/bin/session-start.js +298 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/forget.md +245 -15
- package/commands/brain/memorize.md +76 -144
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +48 -105
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +69 -28
- package/commands/brain/status.md +24 -10
- package/commands/brain/sync.md +386 -0
- package/package.json +22 -8
- package/prompts/antigravity.md +180 -0
- package/prompts/claude.md +124 -20
- package/prompts/openai.md +124 -20
- package/prompts/opencode.md +179 -0
- package/src/cloud-sync.js +534 -0
- package/src/crypto.js +130 -0
- package/src/export-import.js +200 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +219 -18
- package/src/installer.js +444 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +45 -11
- package/src/skills.js +208 -0
- package/src/tfidf.js +520 -0
- package/commands/brain/consolidate.md +0 -153
- package/commands/brain/explore.md +0 -79
- package/commands/brain/init.md +0 -157
- package/commands/brain/review.md +0 -130
- package/commands/brain/sunshine.md +0 -337
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
- package/prompts/gemini.md +0 -76
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Sync memories via Git remote, Brain Cloud, or export/import
|
|
3
|
+
argument-hint: "[subcommand]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /brain:sync — Portable Sync
|
|
7
|
+
|
|
8
|
+
You are managing synchronization for the Brain Memory system. This enables manual push/pull of `~/.brain/` memories via any Git remote, plus encrypted single-file export/import for portable transfers.
|
|
9
|
+
|
|
10
|
+
**CRITICAL RULES:**
|
|
11
|
+
- NEVER auto-sync — always require explicit user action
|
|
12
|
+
- NEVER silently overwrite files on pull/import — show a preview first
|
|
13
|
+
- NEVER display passphrases or secrets in output
|
|
14
|
+
- Push operations execute immediately (no confirmation) — the user said "push"
|
|
15
|
+
- Pull/import operations warn before overwriting local data
|
|
16
|
+
|
|
17
|
+
## First run — auto-initialize if missing
|
|
18
|
+
|
|
19
|
+
The installer normally creates `~/.brain/` at install time. If `~/.brain/index.json` is
|
|
20
|
+
**missing** when any sync subcommand runs, create the standard structure first (no separate
|
|
21
|
+
init command is needed), then continue:
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
~/.brain/
|
|
25
|
+
├── index.json # { version: 2, memory_count: 0, memories: {}, config: {…} }
|
|
26
|
+
├── associations.json # { version: 1, edges: {} }
|
|
27
|
+
├── contexts.json # { version: 1, sessions: [] }
|
|
28
|
+
├── review-queue.json # { version: 1, items: [] }
|
|
29
|
+
├── professional/_meta.json
|
|
30
|
+
├── personal/_meta.json
|
|
31
|
+
├── social/_meta.json
|
|
32
|
+
├── family/_meta.json
|
|
33
|
+
├── _consolidated/_meta.json
|
|
34
|
+
└── _archived/index.json # { version: 1, archived_count: 0, memories: {} }
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Each `_meta.json` is `{ "category": "<name>", "description": "<from defaults>", "created":
|
|
38
|
+
"<ISO>", "memory_count": 0, "subcategories": [] }`. The `index.json` `config` block carries the
|
|
39
|
+
standard decay/association defaults (max_depth 6, consolidation_threshold 0.3, association_config
|
|
40
|
+
with spreading-activation depth 2, etc.). After creating the structure, proceed with the
|
|
41
|
+
requested subcommand.
|
|
42
|
+
|
|
43
|
+
## Subcommands
|
|
44
|
+
|
|
45
|
+
Parse the user's input to determine the subcommand:
|
|
46
|
+
|
|
47
|
+
**Cloud Sync (Brain Cloud API):**
|
|
48
|
+
- `cloud login [--api-url URL]` → Authenticate via device code flow
|
|
49
|
+
- `cloud push` → Upload ~/.brain/ to Brain Cloud
|
|
50
|
+
- `cloud pull` → Download from Brain Cloud to ~/.brain/
|
|
51
|
+
- `cloud status` → Show cloud connection info
|
|
52
|
+
- `cloud logout` → Clear stored credentials
|
|
53
|
+
|
|
54
|
+
**Git Sync (any Git remote):**
|
|
55
|
+
- `setup <url>` → Configure a Git remote for sync
|
|
56
|
+
- `push` → Commit and push local changes to remote
|
|
57
|
+
- `pull` → Fetch and merge remote changes to local
|
|
58
|
+
- `status` → Show sync state (ahead/behind)
|
|
59
|
+
- `export [path]` → Export ~/.brain/ to an encrypted single file
|
|
60
|
+
- `import <path>` → Import from an export file
|
|
61
|
+
- `disconnect` → Remove sync configuration
|
|
62
|
+
|
|
63
|
+
If no subcommand is given, show available subcommands.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## `/brain:sync cloud login [--api-url URL]`
|
|
68
|
+
|
|
69
|
+
### Steps
|
|
70
|
+
|
|
71
|
+
1. **Check if already logged in:**
|
|
72
|
+
- Read `~/.brain/.cloud/config.json` via `readConfig()` from `src/cloud-sync.js`.
|
|
73
|
+
- If already connected, show current user and ask if they want to re-authenticate.
|
|
74
|
+
|
|
75
|
+
2. **Start device code flow:**
|
|
76
|
+
- Run `brain cloud login` (or call `login()` from `src/cloud-sync.js`).
|
|
77
|
+
- This calls `POST /auth/device/request` and returns a user code + verification URL.
|
|
78
|
+
|
|
79
|
+
3. **Display instructions to user:**
|
|
80
|
+
```
|
|
81
|
+
🔐 Brain Cloud Login
|
|
82
|
+
|
|
83
|
+
Open this URL in your browser:
|
|
84
|
+
<verify_url>
|
|
85
|
+
|
|
86
|
+
Your code: <user_code>
|
|
87
|
+
|
|
88
|
+
Waiting for approval...
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
4. **Wait for approval:**
|
|
92
|
+
- The CLI polls `POST /auth/device/poll` every 5 seconds.
|
|
93
|
+
- Once approved, tokens are saved to `~/.brain/.cloud/config.json`.
|
|
94
|
+
|
|
95
|
+
5. **Show result:**
|
|
96
|
+
```
|
|
97
|
+
✓ Logged in as <email>
|
|
98
|
+
Brain ID: <brain_id>
|
|
99
|
+
API: <api_url>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## `/brain:sync cloud push`
|
|
105
|
+
|
|
106
|
+
### Prerequisites
|
|
107
|
+
|
|
108
|
+
Check that the `brain` CLI is available (run `brain --version`). If not:
|
|
109
|
+
```
|
|
110
|
+
brain CLI is not installed. Install it with:
|
|
111
|
+
npm install -g brain-memory
|
|
112
|
+
```
|
|
113
|
+
Then return — do not attempt the push.
|
|
114
|
+
|
|
115
|
+
### Steps
|
|
116
|
+
|
|
117
|
+
1. **Check logged in.** If not, suggest `cloud login`.
|
|
118
|
+
|
|
119
|
+
2. **Execute push immediately** — no confirmation needed:
|
|
120
|
+
- Run `brain cloud push`.
|
|
121
|
+
- Show result:
|
|
122
|
+
```
|
|
123
|
+
✓ Push complete!
|
|
124
|
+
Size: <size>
|
|
125
|
+
Files: <count>
|
|
126
|
+
Checksum: <checksum>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## `/brain:sync cloud pull`
|
|
132
|
+
|
|
133
|
+
### Steps
|
|
134
|
+
|
|
135
|
+
1. **Check logged in.**
|
|
136
|
+
|
|
137
|
+
2. **Warn about overwrite:**
|
|
138
|
+
```
|
|
139
|
+
📥 Cloud Pull Preview:
|
|
140
|
+
Source: <api_url>
|
|
141
|
+
⚠️ This will overwrite local files with the cloud version.
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
3. **Ask for confirmation.**
|
|
145
|
+
|
|
146
|
+
4. **Execute pull:**
|
|
147
|
+
- Run `brain cloud pull` (or call `pull()` from `src/cloud-sync.js`).
|
|
148
|
+
- Downloads tar.gz from `GET /api/brains/{id}/sync` and extracts to `~/.brain/`.
|
|
149
|
+
- Show result:
|
|
150
|
+
```
|
|
151
|
+
✓ Pull complete!
|
|
152
|
+
Size: <size>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
5. **Rebuild index:**
|
|
156
|
+
- After pull, run the index manager to rebuild `~/.brain/index.json`.
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## `/brain:sync cloud status`
|
|
161
|
+
|
|
162
|
+
### Steps
|
|
163
|
+
|
|
164
|
+
1. **Read cloud config** using `readConfig()` from `src/cloud-sync.js`.
|
|
165
|
+
|
|
166
|
+
2. **Fetch live status** (if connected) by calling `status()` from `src/cloud-sync.js`.
|
|
167
|
+
|
|
168
|
+
3. **Display dashboard:**
|
|
169
|
+
```
|
|
170
|
+
☁️ Brain Cloud Status
|
|
171
|
+
─────────────────────────
|
|
172
|
+
API: <api_url or "not connected">
|
|
173
|
+
User: <email>
|
|
174
|
+
Brain ID: <brain_id>
|
|
175
|
+
Cloud Size: <size>
|
|
176
|
+
Cloud Files: <count>
|
|
177
|
+
Last Push: <timestamp or "never">
|
|
178
|
+
Last Pull: <timestamp or "never">
|
|
179
|
+
Last Synced: <timestamp or "never">
|
|
180
|
+
Connected: <timestamp>
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## `/brain:sync cloud logout`
|
|
186
|
+
|
|
187
|
+
### Steps
|
|
188
|
+
|
|
189
|
+
1. **Show current connection** (API URL, email).
|
|
190
|
+
2. **Ask for confirmation:** "This will clear your stored credentials. Cloud data will NOT be deleted."
|
|
191
|
+
3. **Remove `~/.brain/.cloud/` directory.**
|
|
192
|
+
4. **Confirm:** "✓ Logged out. Cloud data is untouched."
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## `/brain:sync setup <url>`
|
|
197
|
+
|
|
198
|
+
### Steps
|
|
199
|
+
|
|
200
|
+
1. **Check prerequisites:**
|
|
201
|
+
- Verify `~/.brain/` exists. If not, auto-initialize it first (see "First run" above).
|
|
202
|
+
- Verify `git` is available (`checkGitAvailable()` from `src/git-sync.js`).
|
|
203
|
+
- Check if sync is already configured (`~/.brain/.sync/config.json`). If so, ask if they want to reconfigure.
|
|
204
|
+
|
|
205
|
+
2. **Get remote URL** (if not provided):
|
|
206
|
+
- Ask for the Git remote URL (SSH or HTTPS).
|
|
207
|
+
- Auto-detect `gh` CLI: if available, offer to create a private repo with `gh repo create brain-data --private`.
|
|
208
|
+
- Examples:
|
|
209
|
+
- `git@github.com:user/brain-data.git`
|
|
210
|
+
- `https://github.com/user/brain-data.git`
|
|
211
|
+
- `git@gitlab.com:user/brain-data.git`
|
|
212
|
+
|
|
213
|
+
3. **Ask about encryption** (optional):
|
|
214
|
+
- "Would you like to encrypt memories before pushing? (recommended for sensitive data)"
|
|
215
|
+
- If yes, ask for a passphrase (will be needed on every push/pull and on other devices).
|
|
216
|
+
|
|
217
|
+
4. **Initialize sync:**
|
|
218
|
+
- Call `initSyncRepo()` and `configureRemote()` from `src/git-sync.js`.
|
|
219
|
+
- Write config to `~/.brain/.sync/config.json` via `writeSyncConfig()`.
|
|
220
|
+
|
|
221
|
+
5. **Show result:**
|
|
222
|
+
```
|
|
223
|
+
✓ Git sync configured!
|
|
224
|
+
Remote: <remote-url>
|
|
225
|
+
Branch: main
|
|
226
|
+
Encryption: <enabled/disabled>
|
|
227
|
+
|
|
228
|
+
Use /brain:sync push to upload your memories.
|
|
229
|
+
Use /brain:sync pull to download from remote.
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## `/brain:sync push`
|
|
235
|
+
|
|
236
|
+
### Steps
|
|
237
|
+
|
|
238
|
+
1. **Check sync is configured.** If not, suggest `/brain:sync setup`.
|
|
239
|
+
|
|
240
|
+
2. **Check status** via `getStatus()`. If behind > 0, warn: "Remote has newer changes. Consider pulling first." and stop.
|
|
241
|
+
|
|
242
|
+
3. **Execute push immediately** — no confirmation needed:
|
|
243
|
+
- If encryption is enabled, ask for passphrase.
|
|
244
|
+
- Call `push()` from `src/git-sync.js`.
|
|
245
|
+
- Show result:
|
|
246
|
+
```
|
|
247
|
+
✓ Push complete!
|
|
248
|
+
Committed: <message>
|
|
249
|
+
Remote: <remote-url>
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## `/brain:sync pull`
|
|
255
|
+
|
|
256
|
+
### Steps
|
|
257
|
+
|
|
258
|
+
1. **Check sync is configured.**
|
|
259
|
+
|
|
260
|
+
2. **Preview:**
|
|
261
|
+
- Call `getStatus()` to show ahead/behind count.
|
|
262
|
+
```
|
|
263
|
+
📥 Pull Preview:
|
|
264
|
+
Remote: <remote-url>
|
|
265
|
+
Status: <behind> new commits to pull
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
3. **Ask for confirmation.**
|
|
269
|
+
|
|
270
|
+
4. **Execute pull:**
|
|
271
|
+
- If encryption is enabled, ask for passphrase.
|
|
272
|
+
- Call `pull()` from `src/git-sync.js`.
|
|
273
|
+
- Show result:
|
|
274
|
+
```
|
|
275
|
+
✓ Pull complete!
|
|
276
|
+
Updated <count> files from remote.
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## `/brain:sync status`
|
|
282
|
+
|
|
283
|
+
### Steps
|
|
284
|
+
|
|
285
|
+
1. **Read sync config** using `getSyncConfig()` from `src/git-sync.js`.
|
|
286
|
+
|
|
287
|
+
2. **Display dashboard:**
|
|
288
|
+
```
|
|
289
|
+
🔄 Sync Status
|
|
290
|
+
─────────────────────
|
|
291
|
+
Remote: <remote-url or "not configured">
|
|
292
|
+
Branch: <branch>
|
|
293
|
+
Encryption: <enabled/disabled>
|
|
294
|
+
Last Push: <timestamp or "never">
|
|
295
|
+
Last Pull: <timestamp or "never">
|
|
296
|
+
Ahead: <count> commits
|
|
297
|
+
Behind: <count> commits
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## `/brain:sync export [path]`
|
|
303
|
+
|
|
304
|
+
### Steps
|
|
305
|
+
|
|
306
|
+
1. **Determine output path:**
|
|
307
|
+
- Default: `.brain-export` in the current directory.
|
|
308
|
+
- User can specify a custom path.
|
|
309
|
+
|
|
310
|
+
2. **Ask about encryption:**
|
|
311
|
+
- "Would you like to encrypt the export? (recommended)"
|
|
312
|
+
- If yes, ask for a passphrase.
|
|
313
|
+
|
|
314
|
+
3. **Execute export:**
|
|
315
|
+
- Call `exportBrain()` from `src/export-import.js`.
|
|
316
|
+
- Show result:
|
|
317
|
+
```
|
|
318
|
+
✓ Brain exported!
|
|
319
|
+
File: <output-path>
|
|
320
|
+
Memories: <count> files packed
|
|
321
|
+
Encrypted: <yes/no>
|
|
322
|
+
Size: <file-size>
|
|
323
|
+
|
|
324
|
+
Transfer this file to another machine and run /brain:sync import <path>
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
## `/brain:sync import <path>`
|
|
330
|
+
|
|
331
|
+
### Steps
|
|
332
|
+
|
|
333
|
+
1. **Preview the import:**
|
|
334
|
+
- Call `previewImport()` from `src/export-import.js`.
|
|
335
|
+
- Display:
|
|
336
|
+
```
|
|
337
|
+
📦 Import Preview:
|
|
338
|
+
File: <path>
|
|
339
|
+
Exported at: <date>
|
|
340
|
+
Total files: <count>
|
|
341
|
+
New: <count> (will be created)
|
|
342
|
+
Existing: <count> (will be overwritten)
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
2. **Ask for import mode:**
|
|
346
|
+
- **Overwrite** (default): Replace all matching files with the imported versions.
|
|
347
|
+
- **Merge**: Only import files newer than local versions.
|
|
348
|
+
|
|
349
|
+
3. **If encrypted, ask for passphrase.**
|
|
350
|
+
|
|
351
|
+
4. **Ask for confirmation.**
|
|
352
|
+
|
|
353
|
+
5. **Execute import:**
|
|
354
|
+
- Call `importBrain()` from `src/export-import.js`.
|
|
355
|
+
- Show result:
|
|
356
|
+
```
|
|
357
|
+
✓ Import complete!
|
|
358
|
+
Imported: <count> files
|
|
359
|
+
Skipped: <count> (merge mode, local was newer)
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
## `/brain:sync disconnect`
|
|
365
|
+
|
|
366
|
+
### Steps
|
|
367
|
+
|
|
368
|
+
1. **Show current config** (remote URL).
|
|
369
|
+
2. **Ask for confirmation:** "This will remove sync configuration. Your remote data will NOT be deleted."
|
|
370
|
+
3. **Remove `~/.brain/.sync/` directory.**
|
|
371
|
+
4. **Confirm:** "✓ Sync disconnected. Remote repository is untouched."
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## Key Implementation Notes
|
|
376
|
+
|
|
377
|
+
- **Cloud sync engine**: `src/cloud-sync.js` — API client for Brain Cloud
|
|
378
|
+
- **Cloud CLI**: `bin/cloud-sync.js` — installed as `brain cloud` command
|
|
379
|
+
- **Cloud config**: stored in `~/.brain/.cloud/config.json` (tokens, brain ID, API URL)
|
|
380
|
+
- **Cloud protocol**: tar.gz archives uploaded/downloaded via REST API
|
|
381
|
+
- Git sync engine: `src/git-sync.js`
|
|
382
|
+
- Export/import: `src/export-import.js`
|
|
383
|
+
- Crypto utilities: `src/crypto.js`
|
|
384
|
+
- Git sync config stored in `~/.brain/.sync/config.json` (local only)
|
|
385
|
+
- Hidden git repo at `~/.brain/.sync/repo/` — never interferes with the project's own git
|
|
386
|
+
- All operations use Node.js built-ins only — no npm runtime dependencies
|
package/package.json
CHANGED
|
@@ -1,43 +1,57 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "brain-memory",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.31",
|
|
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",
|
|
7
7
|
"gemini-cli",
|
|
8
8
|
"openai-codex",
|
|
9
|
+
"opencode",
|
|
9
10
|
"memory",
|
|
10
11
|
"ai-agent",
|
|
11
12
|
"context-engineering",
|
|
12
|
-
"hierarchical-memory"
|
|
13
|
+
"hierarchical-memory",
|
|
14
|
+
"neuroscience",
|
|
15
|
+
"spaced-repetition",
|
|
16
|
+
"file-based",
|
|
17
|
+
"slash-commands"
|
|
13
18
|
],
|
|
14
19
|
"author": {
|
|
15
20
|
"name": "Onur Karali",
|
|
16
21
|
"email": "onur@omelas.tech"
|
|
17
22
|
},
|
|
18
|
-
"homepage": "https://
|
|
23
|
+
"homepage": "https://brainmemory.ai/",
|
|
19
24
|
"bugs": {
|
|
20
|
-
"url": "https://github.com/
|
|
25
|
+
"url": "https://github.com/omelas-tech/brain/issues"
|
|
21
26
|
},
|
|
22
27
|
"bin": {
|
|
23
|
-
"brain
|
|
28
|
+
"brain": "bin/brain.js"
|
|
24
29
|
},
|
|
25
30
|
"files": [
|
|
31
|
+
"assets/",
|
|
26
32
|
"bin/",
|
|
27
33
|
"commands/",
|
|
28
34
|
"prompts/",
|
|
29
35
|
"templates/",
|
|
30
|
-
"hooks/",
|
|
31
36
|
"src/",
|
|
32
37
|
"README.md",
|
|
38
|
+
"SECURITY.md",
|
|
39
|
+
"CHANGELOG.md",
|
|
33
40
|
"LICENSE"
|
|
34
41
|
],
|
|
35
42
|
"repository": {
|
|
36
43
|
"type": "git",
|
|
37
|
-
"url": "git+https://github.com/
|
|
44
|
+
"url": "git+https://github.com/omelas-tech/brain.git"
|
|
38
45
|
},
|
|
39
46
|
"scripts": {
|
|
40
|
-
"test": "node --test test/index-manager.test.js test/scorer.test.js test/functional.test.js test/
|
|
47
|
+
"test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.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",
|
|
48
|
+
"prerelease": "npm test",
|
|
49
|
+
"changelog": "node scripts/release.mjs",
|
|
50
|
+
"changelog:status": "node scripts/release.mjs status",
|
|
51
|
+
"release:beta": "npm version prerelease --preid beta && npm publish --tag beta && npm dist-tag add brain-memory@$(node -p \"require('./package.json').version\") latest",
|
|
52
|
+
"release:patch": "npm version patch && npm publish",
|
|
53
|
+
"release:minor": "npm version minor && npm publish",
|
|
54
|
+
"release:major": "npm version major && npm publish"
|
|
41
55
|
},
|
|
42
56
|
"license": "MIT",
|
|
43
57
|
"engines": {
|
|
@@ -0,0 +1,180 @@
|
|
|
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 `~/.brain/` with a deep nested directory 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 skills are available via `/brain-` prefix:
|
|
52
|
+
The everyday loop is **ambient** — `remember` and `memorize` run automatically at session start/end; you rarely type them.
|
|
53
|
+
|
|
54
|
+
Core:
|
|
55
|
+
- `/brain-remember [query]` — Recall relevant memories with spreading activation and context matching
|
|
56
|
+
- `/brain-memorize [topic]` — Store memories from the current context
|
|
57
|
+
- `/brain-status` — Dashboard with brain health overview
|
|
58
|
+
- `/brain-pin [id|query]` — Pin a memory to the always-present tier (toggle — also unpins, e.g. `--off`)
|
|
59
|
+
- `/brain-forget [target]` — Decay or archive memories (`--deep` = forensic erasure of every reference)
|
|
60
|
+
|
|
61
|
+
Sync & skills:
|
|
62
|
+
- `/brain-sync [subcommand]` — Sync via Brain Cloud, Git remote, or export/import (auto-initializes on first run)
|
|
63
|
+
- `/brain-skills [list|show|add|use|remove|export]` — Manage procedural skills
|
|
64
|
+
|
|
65
|
+
Maintenance (usually automatic — runs in the background):
|
|
66
|
+
- `/brain-sleep [scope]` — Full maintenance cycle: replay, homeostasis, propagation, crystallization, reorganize, consolidate, prune, review reinforcement, REM dreaming, expertise detection
|
|
67
|
+
|
|
68
|
+
## Session Start Behavior
|
|
69
|
+
|
|
70
|
+
**Perform these steps at session start — but keep it lightweight.**
|
|
71
|
+
|
|
72
|
+
If `~/.brain/index.json` exists:
|
|
73
|
+
|
|
74
|
+
1. **Run the session-start aggregator** — one deterministic, budget-bounded call:
|
|
75
|
+
```bash
|
|
76
|
+
brain session-start --project "<current project>"
|
|
77
|
+
```
|
|
78
|
+
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.
|
|
79
|
+
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.
|
|
80
|
+
3. **Output a single status line:**
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
◉ Brain active — <N> memories (<M> in project context)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Only add extra lines if actionable:
|
|
87
|
+
- `📋 <X> due for review` — if `due_for_review > 0`
|
|
88
|
+
- `⚠️ <N> low-confidence memories used frequently` — if `low_confidence_alerts` is non-empty
|
|
89
|
+
|
|
90
|
+
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.
|
|
91
|
+
|
|
92
|
+
## Ambient Session Tracking
|
|
93
|
+
|
|
94
|
+
**Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
|
|
95
|
+
|
|
96
|
+
Track these categories as they happen:
|
|
97
|
+
- **Decisions** — Architecture choices, technology selections, trade-off resolutions
|
|
98
|
+
- **Learnings** — New patterns, debugging insights, API discoveries
|
|
99
|
+
- **Insights** — Realizations about the codebase, project, or process
|
|
100
|
+
- **Experiences** — Significant events like incidents, deployments, milestones
|
|
101
|
+
- **Goals** — New objectives discussed or planned
|
|
102
|
+
|
|
103
|
+
**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.
|
|
104
|
+
|
|
105
|
+
## Periodic Memory Checkpoint
|
|
106
|
+
|
|
107
|
+
**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.
|
|
108
|
+
|
|
109
|
+
If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
◉ Notable <type(s)> this session — /brain-memorize when ready
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Rules:**
|
|
116
|
+
- **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
|
|
117
|
+
- **At most once per ~10 substantive interactions** — no spamming
|
|
118
|
+
- **Reset the counter** after the user runs `/brain-memorize`
|
|
119
|
+
- **Don't mention if nothing notable** has accumulated
|
|
120
|
+
- **Be specific about types** — say "decisions and learnings" not just "notable content"
|
|
121
|
+
|
|
122
|
+
## Session End Behavior
|
|
123
|
+
|
|
124
|
+
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**:
|
|
125
|
+
|
|
126
|
+
### Step 1: Save Session Context (ALWAYS — do this first)
|
|
127
|
+
|
|
128
|
+
**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.
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"session_id": "<timestamp-based-id>",
|
|
133
|
+
"started": "<session start ISO timestamp>",
|
|
134
|
+
"ended": "<session end ISO timestamp>",
|
|
135
|
+
"project": "<current project name>",
|
|
136
|
+
"topics": ["<key topics discussed>"],
|
|
137
|
+
"task_type": "<primary task type>",
|
|
138
|
+
"memories_created": ["<IDs of memories stored this session>"],
|
|
139
|
+
"memories_recalled": ["<IDs of memories retrieved this session>"],
|
|
140
|
+
"notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
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.
|
|
145
|
+
|
|
146
|
+
### Step 2: Suggest Memorization (if warranted)
|
|
147
|
+
|
|
148
|
+
If the session contained meaningful content based on your ambient tracking:
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
|
|
152
|
+
Run /brain-memorize to capture them before this context is lost.
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
**Rules:**
|
|
156
|
+
- Do NOT auto-memorize without user consent
|
|
157
|
+
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
158
|
+
- Only suggest when there is genuinely valuable context worth preserving
|
|
159
|
+
- **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
|
|
160
|
+
|
|
161
|
+
## When Recalling Memories
|
|
162
|
+
|
|
163
|
+
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:
|
|
164
|
+
|
|
165
|
+
1. Run `brain recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
|
|
166
|
+
2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
|
|
167
|
+
3. Read the top-scoring memory files and present results
|
|
168
|
+
4. Run `brain reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
|
|
169
|
+
5. If no matches, search the archive (`~/.brain/_archived/`)
|
|
170
|
+
|
|
171
|
+
The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
|
|
172
|
+
|
|
173
|
+
## Portable Sync
|
|
174
|
+
|
|
175
|
+
Brain memories can be synced across devices in two ways:
|
|
176
|
+
|
|
177
|
+
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`.
|
|
178
|
+
2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain-sync export` and `/brain-sync import <path>`.
|
|
179
|
+
|
|
180
|
+
Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
|