brain-memory 0.1.0-beta.7 → 0.1.0-beta.8
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/README.md +17 -11
- package/bin/install.js +10 -9
- package/commands/brain/consolidate.md +2 -2
- package/commands/brain/explore.md +2 -2
- package/commands/brain/forget.md +2 -2
- package/commands/brain/init.md +4 -4
- package/commands/brain/memorize.md +5 -5
- package/commands/brain/remember.md +8 -8
- package/commands/brain/review.md +2 -2
- package/commands/brain/sleep.md +4 -4
- package/commands/brain/status.md +5 -5
- package/commands/brain/sunshine.md +13 -13
- package/commands/brain/sync.md +8 -8
- package/package.json +1 -1
- package/prompts/claude.md +10 -10
- package/prompts/gemini.md +10 -10
- package/src/export-import.js +9 -9
- package/src/git-sync.js +26 -26
- package/src/index-manager.js +10 -8
- package/src/installer.js +2 -2
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@ A hierarchical, file-system-based memory plugin for AI coding agents. Inspired b
|
|
|
7
7
|
Works with **Claude Code**, **Gemini CLI**, and **OpenAI Codex CLI**.
|
|
8
8
|
|
|
9
9
|
```
|
|
10
|
-
|
|
10
|
+
~/.brain/
|
|
11
11
|
├── professional/
|
|
12
12
|
│ └── companies/
|
|
13
13
|
│ └── acme-corp/
|
|
@@ -71,7 +71,7 @@ Auto-detects installed runtimes and refreshes commands + prompt sections. Target
|
|
|
71
71
|
npx brain-memory@beta uninstall
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
Removes commands and prompt sections. Your
|
|
74
|
+
Removes commands and prompt sections. Your `~/.brain/` directory (memories) is preserved by default. Add `--delete-data` to remove it too. Use `--yes` to skip confirmation prompts.
|
|
75
75
|
|
|
76
76
|
### Manual Install
|
|
77
77
|
|
|
@@ -101,7 +101,7 @@ Then append the contents of the corresponding prompt file to your agent's instru
|
|
|
101
101
|
|
|
102
102
|
| Command | Description |
|
|
103
103
|
|---------|-------------|
|
|
104
|
-
| `/brain:init` | Initialize
|
|
104
|
+
| `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
|
|
105
105
|
| `/brain:memorize [topic]` | Store memories from current session context |
|
|
106
106
|
| `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
|
|
107
107
|
| `/brain:review [scope]` | Spaced repetition review session for due memories |
|
|
@@ -119,7 +119,7 @@ Brain Memory works automatically in the background — no commands needed for ba
|
|
|
119
119
|
|
|
120
120
|
### Session Start
|
|
121
121
|
|
|
122
|
-
When a session begins and
|
|
122
|
+
When a session begins and `~/.brain/` exists, the agent automatically:
|
|
123
123
|
|
|
124
124
|
1. Reads the brain index and loads the top 3-5 memories relevant to the current project
|
|
125
125
|
2. Checks the review queue for memories due for spaced repetition
|
|
@@ -142,7 +142,7 @@ When a session ends, the agent evaluates whether significant decisions, learning
|
|
|
142
142
|
Run /brain:memorize to capture them before this context is lost.
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
The agent never auto-memorizes without user consent. Session context is always saved to
|
|
145
|
+
The agent never auto-memorizes without user consent. Session context is always saved to `~/.brain/contexts.json` for context-dependent recall.
|
|
146
146
|
|
|
147
147
|
## How It Works
|
|
148
148
|
|
|
@@ -282,7 +282,7 @@ The agent then decides the response strategy:
|
|
|
282
282
|
|
|
283
283
|
### Associative Network
|
|
284
284
|
|
|
285
|
-
Memories are connected via weighted edges in
|
|
285
|
+
Memories are connected via weighted edges in `~/.brain/associations.json`:
|
|
286
286
|
|
|
287
287
|
```json
|
|
288
288
|
{
|
|
@@ -374,13 +374,19 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
|
|
|
374
374
|
|
|
375
375
|
Failed recalls reset the interval to 1 day. Successful recalls extend the interval by the ease factor. This ensures you spend time on memories that need reinforcement, not ones you already know well.
|
|
376
376
|
|
|
377
|
+
### Cross-Agent Memory Sharing
|
|
378
|
+
|
|
379
|
+
`~/.brain/` is a single global directory in the user's home folder. All memories are shared across every project and every supported agent automatically. A decision stored by Claude Code in one project is immediately available to Gemini CLI or Codex CLI in any other project — no configuration, no export, no per-project setup. The format is agent-agnostic: plain Markdown files with YAML frontmatter, readable by any tool.
|
|
380
|
+
|
|
381
|
+
To share memories across different machines, use `/brain:sync` (see below).
|
|
382
|
+
|
|
377
383
|
### Portable Sync
|
|
378
384
|
|
|
379
385
|
`/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
|
|
380
386
|
|
|
381
|
-
**Git remote** — Push/pull
|
|
387
|
+
**Git remote** — Push/pull `~/.brain/` to any private Git repository. Works with GitHub, GitLab, Codeberg, or any self-hosted Git server. Uses your existing Git/SSH authentication — no additional credentials needed.
|
|
382
388
|
|
|
383
|
-
**Export/Import** — Pack the entire
|
|
389
|
+
**Export/Import** — Pack the entire `~/.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
|
|
384
390
|
|
|
385
391
|
**Key features:**
|
|
386
392
|
- **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
|
|
@@ -395,12 +401,12 @@ Failed recalls reset the interval to 1 day. Successful recalls extend the interv
|
|
|
395
401
|
|
|
396
402
|
For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
|
|
397
403
|
|
|
398
|
-
Sync state is stored locally in
|
|
404
|
+
Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
|
|
399
405
|
|
|
400
406
|
## File Structure
|
|
401
407
|
|
|
402
408
|
```
|
|
403
|
-
|
|
409
|
+
~/.brain/
|
|
404
410
|
├── index.json # Memory inventory — fast lookup for all memories
|
|
405
411
|
├── associations.json # Weighted associative network between memories
|
|
406
412
|
├── contexts.json # Session context snapshots for context-dependent recall
|
|
@@ -439,7 +445,7 @@ Subdirectories are created **on demand** — the agent decides placement depth b
|
|
|
439
445
|
|
|
440
446
|
## Configuration
|
|
441
447
|
|
|
442
|
-
Brain configuration lives in
|
|
448
|
+
Brain configuration lives in `~/.brain/index.json` under the `config` key:
|
|
443
449
|
|
|
444
450
|
```json
|
|
445
451
|
{
|
package/bin/install.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
const readline = require('readline');
|
|
4
4
|
const fs = require('fs');
|
|
5
5
|
const path = require('path');
|
|
6
|
+
const os = require('os');
|
|
6
7
|
const {
|
|
7
8
|
RUNTIMES,
|
|
8
9
|
installForRuntime,
|
|
@@ -114,7 +115,7 @@ async function runInstall(flags) {
|
|
|
114
115
|
console.log('');
|
|
115
116
|
const initBrain = await ask(
|
|
116
117
|
rl,
|
|
117
|
-
' Initialize
|
|
118
|
+
' Initialize ~/.brain/ directory? (Y/n): '
|
|
118
119
|
);
|
|
119
120
|
|
|
120
121
|
// Perform installation
|
|
@@ -130,9 +131,9 @@ async function runInstall(flags) {
|
|
|
130
131
|
if (initBrain.trim().toLowerCase() !== 'n') {
|
|
131
132
|
const result = initializeBrain();
|
|
132
133
|
if (result.alreadyExists) {
|
|
133
|
-
console.log('\n
|
|
134
|
+
console.log('\n ~/.brain/ already exists, skipping initialization.');
|
|
134
135
|
} else {
|
|
135
|
-
console.log('\n
|
|
136
|
+
console.log('\n ~/.brain/ initialized successfully.');
|
|
136
137
|
console.log('');
|
|
137
138
|
console.log(' Use /brain:sync to set up portable sync across devices.');
|
|
138
139
|
}
|
|
@@ -265,30 +266,30 @@ async function runUninstall(flags) {
|
|
|
265
266
|
}
|
|
266
267
|
|
|
267
268
|
// Handle .brain/ data
|
|
268
|
-
const brainDir = path.join(
|
|
269
|
+
const brainDir = path.join(os.homedir(), '.brain');
|
|
269
270
|
if (fs.existsSync(brainDir)) {
|
|
270
271
|
if (flags.has('delete-data')) {
|
|
271
272
|
fs.rmSync(brainDir, { recursive: true, force: true });
|
|
272
|
-
console.log('\n Deleted
|
|
273
|
+
console.log('\n Deleted ~/.brain/ directory.');
|
|
273
274
|
} else if (!flags.has('yes') && !flags.has('y')) {
|
|
274
275
|
const rl = createRL();
|
|
275
276
|
try {
|
|
276
277
|
console.log('');
|
|
277
278
|
const answer = await ask(
|
|
278
279
|
rl,
|
|
279
|
-
' Delete
|
|
280
|
+
' Delete ~/.brain/ data directory? This removes all memories. (y/N): '
|
|
280
281
|
);
|
|
281
282
|
if (answer.trim().toLowerCase() === 'y') {
|
|
282
283
|
fs.rmSync(brainDir, { recursive: true, force: true });
|
|
283
|
-
console.log(' Deleted
|
|
284
|
+
console.log(' Deleted ~/.brain/ directory.');
|
|
284
285
|
} else {
|
|
285
|
-
console.log(' Kept
|
|
286
|
+
console.log(' Kept ~/.brain/ directory (your memories are preserved).');
|
|
286
287
|
}
|
|
287
288
|
} finally {
|
|
288
289
|
rl.close();
|
|
289
290
|
}
|
|
290
291
|
} else {
|
|
291
|
-
console.log('\n Kept
|
|
292
|
+
console.log('\n Kept ~/.brain/ directory (use --delete-data to remove memories).');
|
|
292
293
|
}
|
|
293
294
|
}
|
|
294
295
|
|
|
@@ -9,7 +9,7 @@ You are consolidating memories in the Brain Memory system. Consolidation combine
|
|
|
9
9
|
### 1. Determine Scope
|
|
10
10
|
|
|
11
11
|
- If $ARGUMENTS specifies a category path, consolidate within that subtree
|
|
12
|
-
- If $ARGUMENTS is empty, scan the entire
|
|
12
|
+
- If $ARGUMENTS is empty, scan the entire `~/.brain/` for consolidation candidates
|
|
13
13
|
- If $ARGUMENTS is "auto", perform automatic consolidation based on thresholds
|
|
14
14
|
|
|
15
15
|
### 2. Find Consolidation Candidates
|
|
@@ -126,7 +126,7 @@ encoding_context:
|
|
|
126
126
|
|
|
127
127
|
### 7. Archive Source Memories
|
|
128
128
|
|
|
129
|
-
Move the original source memory files to a
|
|
129
|
+
Move the original source memory files to a `~/.brain/_archived/` directory (create if needed), preserving their paths as subdirectories. This keeps them recoverable and searchable via `/brain:remember`.
|
|
130
130
|
|
|
131
131
|
Update `index.json`:
|
|
132
132
|
- Remove archived memory entries from `memories`
|
|
@@ -13,7 +13,7 @@ You are exploring the Brain Memory system's hierarchical structure. This gives t
|
|
|
13
13
|
|
|
14
14
|
### 2. Read Structure
|
|
15
15
|
|
|
16
|
-
Read the directory structure of
|
|
16
|
+
Read the directory structure of `~/.brain/` (or the specified subtree). For each directory, read its `_meta.json` to get metadata.
|
|
17
17
|
|
|
18
18
|
### 3. Display Tree View
|
|
19
19
|
|
|
@@ -24,7 +24,7 @@ Present the brain structure as a visual tree with statistics:
|
|
|
24
24
|
Last updated: <timestamp>
|
|
25
25
|
Total memories: <count>
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
~/.brain/
|
|
28
28
|
├── professional/ (12 memories)
|
|
29
29
|
│ ├── companies/ (8 memories)
|
|
30
30
|
│ │ ├── acme-corp/ (5 memories)
|
package/commands/brain/forget.md
CHANGED
|
@@ -64,8 +64,8 @@ The user must explicitly choose an action. Default to **archive** (safest).
|
|
|
64
64
|
### 5. Execute
|
|
65
65
|
|
|
66
66
|
**Archive:**
|
|
67
|
-
- Move memory files to
|
|
68
|
-
- Add entry to
|
|
67
|
+
- Move memory files to `~/.brain/_archived/<original-path>/`
|
|
68
|
+
- Add entry to `~/.brain/_archived/index.json` with all original metadata:
|
|
69
69
|
```json
|
|
70
70
|
{
|
|
71
71
|
"<memory_id>": {
|
package/commands/brain/init.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# /brain:init — Initialize Brain Memory Structure
|
|
2
2
|
|
|
3
|
-
You are initializing the Brain Memory system. This creates a
|
|
3
|
+
You are initializing the Brain Memory system. This creates a `~/.brain/` directory that serves as a hierarchical, file-system-based memory store inspired by human cognition.
|
|
4
4
|
|
|
5
5
|
## Steps
|
|
6
6
|
|
|
7
7
|
### 1. Check for Existing Brain
|
|
8
8
|
|
|
9
|
-
Check if
|
|
9
|
+
Check if `~/.brain/` directory already exists in the user's home directory.
|
|
10
10
|
|
|
11
11
|
- If it exists, inform the user and ask if they want to reset or keep it.
|
|
12
12
|
- If not, proceed with creation.
|
|
@@ -16,7 +16,7 @@ Check if `.brain/` directory already exists in the current project root.
|
|
|
16
16
|
Create the following structure:
|
|
17
17
|
|
|
18
18
|
```
|
|
19
|
-
|
|
19
|
+
~/.brain/
|
|
20
20
|
├── index.json
|
|
21
21
|
├── associations.json
|
|
22
22
|
├── contexts.json
|
|
@@ -131,7 +131,7 @@ If the user provides custom categories or subcategories, create them with approp
|
|
|
131
131
|
|
|
132
132
|
### 10. Add .brain to .gitignore (Optional)
|
|
133
133
|
|
|
134
|
-
Ask the user if they want
|
|
134
|
+
Ask the user if they want `~/.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
|
|
135
135
|
|
|
136
136
|
### 11. Confirm
|
|
137
137
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:memorize — Store a New Memory
|
|
2
2
|
|
|
3
|
-
You are storing a new memory in the Brain Memory system. Memories are filed into the
|
|
3
|
+
You are storing a new memory in the Brain Memory system. Memories are filed into the `~/.brain/` hierarchical directory structure based on their semantic content.
|
|
4
4
|
|
|
5
5
|
**User input:** $ARGUMENTS
|
|
6
6
|
|
|
@@ -49,7 +49,7 @@ For each memory to store, determine:
|
|
|
49
49
|
|
|
50
50
|
### 3. Determine File Path (Categorization)
|
|
51
51
|
|
|
52
|
-
Choose the most appropriate path in the
|
|
52
|
+
Choose the most appropriate path in the `~/.brain/` hierarchy. This is the most critical step.
|
|
53
53
|
|
|
54
54
|
**Rules for path selection:**
|
|
55
55
|
1. Start with the top-level category: `professional/`, `personal/`, `social/`, `family/`
|
|
@@ -118,12 +118,12 @@ encoding_context:
|
|
|
118
118
|
|
|
119
119
|
### 6. Update Index
|
|
120
120
|
|
|
121
|
-
Read
|
|
121
|
+
Read `~/.brain/index.json` and add an entry:
|
|
122
122
|
|
|
123
123
|
```json
|
|
124
124
|
{
|
|
125
125
|
"<memory_id>": {
|
|
126
|
-
"path": "<relative path from
|
|
126
|
+
"path": "<relative path from ~/.brain/>",
|
|
127
127
|
"title": "<short title>",
|
|
128
128
|
"type": "<memory_type>",
|
|
129
129
|
"cognitive_type": "<episodic|semantic|procedural>",
|
|
@@ -148,7 +148,7 @@ Increment `memory_count`. Update `last_updated`.
|
|
|
148
148
|
|
|
149
149
|
### 7. Update Associations
|
|
150
150
|
|
|
151
|
-
Read
|
|
151
|
+
Read `~/.brain/associations.json` and create edges for this memory:
|
|
152
152
|
|
|
153
153
|
**A. Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
|
|
154
154
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:remember — Recall Relevant Memories
|
|
2
2
|
|
|
3
|
-
You are recalling memories from the Brain Memory system. This command searches the
|
|
3
|
+
You are recalling memories from the Brain Memory system. This command searches the `~/.brain/` hierarchy, scores memories by relevance, strength, associative links, and context match, and returns the most useful memories — either individually or as a consolidated synthesis.
|
|
4
4
|
|
|
5
5
|
**User query:** $ARGUMENTS
|
|
6
6
|
|
|
@@ -27,7 +27,7 @@ recall_context:
|
|
|
27
27
|
|
|
28
28
|
### 3. Search the Brain
|
|
29
29
|
|
|
30
|
-
Read
|
|
30
|
+
Read `~/.brain/index.json` to get the full memory inventory.
|
|
31
31
|
|
|
32
32
|
**Search strategy (in order):**
|
|
33
33
|
|
|
@@ -40,7 +40,7 @@ Collect all candidate memories.
|
|
|
40
40
|
|
|
41
41
|
### 3.5. Spreading Activation
|
|
42
42
|
|
|
43
|
-
Read
|
|
43
|
+
Read `~/.brain/associations.json`. For each candidate memory scoring > 0.3 in initial relevance:
|
|
44
44
|
1. Traverse the association graph up to 2 hops
|
|
45
45
|
2. For each reached memory: `spread_bonus = parent_score * link_weight * 0.5^hop`
|
|
46
46
|
3. Memories NOT in the initial candidates but reached via spreading activation with bonus >= 0.05 are **added** to the candidate pool (they were "reminded" by association)
|
|
@@ -88,7 +88,7 @@ List the top 5-7 memories with titles, paths, types, and effective scores.
|
|
|
88
88
|
Ask the user which ones they'd like to explore in detail.
|
|
89
89
|
|
|
90
90
|
**Case D — No matches in active brain:**
|
|
91
|
-
Search
|
|
91
|
+
Search `~/.brain/_archived/` via the archive index (`_archived/index.json`). If archived matches are found with relevance > 0.3:
|
|
92
92
|
- Present them with a note that they're archived
|
|
93
93
|
- Offer to restore them (move back to active brain with strength +0.10)
|
|
94
94
|
|
|
@@ -134,7 +134,7 @@ Format the output clearly. Include confidence indicators for low-confidence memo
|
|
|
134
134
|
```
|
|
135
135
|
## Recalled Memory: <Title>
|
|
136
136
|
|
|
137
|
-
**Path:**
|
|
137
|
+
**Path:** ~/.brain/<path>
|
|
138
138
|
**Strength:** <decayed_strength> (original: <base_strength>)
|
|
139
139
|
**Type:** <type> (<cognitive_type>) | **Created:** <date> | **Recalled:** <access_count> times
|
|
140
140
|
**Confidence:** <confidence> <show ⚠️ if < 0.5>
|
|
@@ -153,8 +153,8 @@ For consolidated responses (Case B):
|
|
|
153
153
|
<consolidated narrative>
|
|
154
154
|
|
|
155
155
|
### Contributing Memories
|
|
156
|
-
1. **<title>** (
|
|
157
|
-
2. **<title>** (
|
|
156
|
+
1. **<title>** (~/.brain/<path>) — score: <score>, confidence: <confidence>
|
|
157
|
+
2. **<title>** (~/.brain/<path>) — score: <score>, confidence: <confidence>
|
|
158
158
|
...
|
|
159
159
|
|
|
160
160
|
---
|
|
@@ -166,7 +166,7 @@ For archived matches (Case D fallback):
|
|
|
166
166
|
```
|
|
167
167
|
## Found in Archive: <Title>
|
|
168
168
|
|
|
169
|
-
**Path:**
|
|
169
|
+
**Path:** ~/.brain/_archived/<path>
|
|
170
170
|
**Original Strength:** <strength> | **Archived:** <date>
|
|
171
171
|
|
|
172
172
|
<memory content summary>
|
package/commands/brain/review.md
CHANGED
|
@@ -12,7 +12,7 @@ This implements a simplified SM-2 (SuperMemo 2) spaced repetition algorithm. Mem
|
|
|
12
12
|
|
|
13
13
|
### 1. Load Review Queue
|
|
14
14
|
|
|
15
|
-
Read
|
|
15
|
+
Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
|
|
16
16
|
- Scan all memories in `index.json`
|
|
17
17
|
- For memories with `access_count > 0`, calculate initial review schedule
|
|
18
18
|
- For memories never recalled, add with `next_review` = now (immediate first review)
|
|
@@ -41,7 +41,7 @@ For each due memory (process up to 10 per session):
|
|
|
41
41
|
### Review 1 of <N>
|
|
42
42
|
|
|
43
43
|
**Memory:** <title>
|
|
44
|
-
**Path:**
|
|
44
|
+
**Path:** ~/.brain/<path>
|
|
45
45
|
**Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
|
|
46
46
|
**Confidence:** <confidence>
|
|
47
47
|
|
package/commands/brain/sleep.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:sleep — Overnight Memory Reorganization
|
|
2
2
|
|
|
3
|
-
You are performing a **sleep cycle** on the Brain Memory system. Just like the human brain during sleep — where the hippocampus replays recent experiences and the neocortex reorganizes them into long-term structured knowledge — this command restructures, consolidates, prunes, and deepens the
|
|
3
|
+
You are performing a **sleep cycle** on the Brain Memory system. Just like the human brain during sleep — where the hippocampus replays recent experiences and the neocortex reorganizes them into long-term structured knowledge — this command restructures, consolidates, prunes, and deepens the `~/.brain/` hierarchy.
|
|
4
4
|
|
|
5
5
|
**Scope:** $ARGUMENTS
|
|
6
6
|
|
|
@@ -24,7 +24,7 @@ During sleep, the hippocampus replays the day's events. Here, we scan and assess
|
|
|
24
24
|
|
|
25
25
|
### Steps
|
|
26
26
|
|
|
27
|
-
1. Read
|
|
27
|
+
1. Read `~/.brain/index.json` to load all memories
|
|
28
28
|
2. If $ARGUMENTS specifies a category path, limit scope to that subtree. Otherwise, process the entire brain.
|
|
29
29
|
3. For **every** memory, compute the current decayed strength:
|
|
30
30
|
|
|
@@ -327,7 +327,7 @@ During deep sleep, the brain merges related experiences into generalized knowled
|
|
|
327
327
|
|
|
328
328
|
5. For approved consolidations:
|
|
329
329
|
- Write consolidated memory files using the standard format with `type: consolidated`
|
|
330
|
-
- Archive source memories to
|
|
330
|
+
- Archive source memories to `~/.brain/_archived/` and add them to `_archived/index.json`
|
|
331
331
|
- Transfer association edges from source memories to the consolidated memory in `associations.json`
|
|
332
332
|
- Update `index.json` and `_meta.json` files
|
|
333
333
|
|
|
@@ -351,7 +351,7 @@ During sleep, the brain prunes weak synaptic connections to maintain efficiency.
|
|
|
351
351
|
4. Get user approval (default: archive all)
|
|
352
352
|
|
|
353
353
|
5. Execute:
|
|
354
|
-
- Move to
|
|
354
|
+
- Move to `~/.brain/_archived/`, preserving directory structure
|
|
355
355
|
- Add to `_archived/index.json` with original metadata
|
|
356
356
|
- Remove from `index.json` and update `_meta.json` files
|
|
357
357
|
- Remove association edges involving pruned memories from `associations.json`
|
package/commands/brain/status.md
CHANGED
|
@@ -6,13 +6,13 @@ You are displaying a comprehensive overview of the Brain Memory system's current
|
|
|
6
6
|
|
|
7
7
|
### 1. Read Brain State
|
|
8
8
|
|
|
9
|
-
Read
|
|
9
|
+
Read `~/.brain/index.json` to get the full memory inventory. If `~/.brain/` doesn't exist, inform the user and suggest running `/brain:init`.
|
|
10
10
|
|
|
11
11
|
Also read (if they exist):
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
12
|
+
- `~/.brain/associations.json` — for association network stats
|
|
13
|
+
- `~/.brain/review-queue.json` — for review schedule info
|
|
14
|
+
- `~/.brain/_archived/index.json` — for archive stats
|
|
15
|
+
- `~/.brain/.sync/config.json` — for git sync configuration
|
|
16
16
|
|
|
17
17
|
### 2. Compute Statistics
|
|
18
18
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:sunshine — Deep Forensic Memory Erasure
|
|
2
2
|
|
|
3
|
-
You are performing **deep forensic erasure** on a memory in the Brain Memory system. Like the procedure in *Eternal Sunshine of the Spotless Mind*, this command doesn't just delete a memory — it traces every ripple that memory left across the entire
|
|
3
|
+
You are performing **deep forensic erasure** on a memory in the Brain Memory system. Like the procedure in *Eternal Sunshine of the Spotless Mind*, this command doesn't just delete a memory — it traces every ripple that memory left across the entire `~/.brain/` tree and surgically removes or repairs each one. When complete, it's as if the memory never existed.
|
|
4
4
|
|
|
5
5
|
Use this for erasing accidentally stored credentials, removing knowledge of a deprecated anti-pattern that leaked into other memories, or cleaning up after a fully reversed technical decision.
|
|
6
6
|
|
|
@@ -32,12 +32,12 @@ If no target is provided, ask the user what memory they want to erase.
|
|
|
32
32
|
|
|
33
33
|
Search for the target memory:
|
|
34
34
|
|
|
35
|
-
1. Read
|
|
35
|
+
1. Read `~/.brain/index.json` and search `memories` by:
|
|
36
36
|
- Exact ID match
|
|
37
37
|
- Title substring match (case-insensitive)
|
|
38
38
|
- Path substring match
|
|
39
|
-
2. If not found in active memories, check
|
|
40
|
-
3. If still not found, check
|
|
39
|
+
2. If not found in active memories, check `~/.brain/_archived/index.json`
|
|
40
|
+
3. If still not found, check `~/.brain/_erased.json` — if found there, report:
|
|
41
41
|
```
|
|
42
42
|
Memory was previously erased on <date>.
|
|
43
43
|
Reason: <reason or "unspecified">
|
|
@@ -50,10 +50,10 @@ Once located, read the full memory file to capture its ID, title, path, tags, `r
|
|
|
50
50
|
|
|
51
51
|
### 3. Trace All References (Blast Radius Scan)
|
|
52
52
|
|
|
53
|
-
Scan the entire
|
|
53
|
+
Scan the entire `~/.brain/` tree for every trace of the target memory. Track 8 reference types:
|
|
54
54
|
|
|
55
55
|
**3a. `related` arrays in other memories' frontmatter:**
|
|
56
|
-
Parse the YAML frontmatter of every `.md` memory file in
|
|
56
|
+
Parse the YAML frontmatter of every `.md` memory file in `~/.brain/`. For each file whose `related` array contains the target ID, record:
|
|
57
57
|
- File path
|
|
58
58
|
- Current `related` array contents
|
|
59
59
|
|
|
@@ -70,22 +70,22 @@ Among all memory files with `type: consolidated`, check if their `consolidated_f
|
|
|
70
70
|
- Number of other sources remaining
|
|
71
71
|
|
|
72
72
|
**3d. Association edges (`associations.json`):**
|
|
73
|
-
Read
|
|
73
|
+
Read `~/.brain/associations.json`. Find all edges involving the target ID:
|
|
74
74
|
- Outgoing: `edges[target_id][*]`
|
|
75
75
|
- Incoming: `edges[*][target_id]`
|
|
76
76
|
Record each edge with its neighbor, weight, and origin.
|
|
77
77
|
|
|
78
78
|
**3e. Context sessions (`contexts.json`):**
|
|
79
|
-
Read
|
|
79
|
+
Read `~/.brain/contexts.json`. Search all sessions for the target ID in:
|
|
80
80
|
- `memories_created` arrays
|
|
81
81
|
- `memories_recalled` arrays
|
|
82
82
|
Record each session timestamp and which array contained the reference.
|
|
83
83
|
|
|
84
84
|
**3f. Review queue (`review-queue.json`):**
|
|
85
|
-
Read
|
|
85
|
+
Read `~/.brain/review-queue.json`. Check if any item has `memory_id` equal to the target ID.
|
|
86
86
|
|
|
87
87
|
**3g. Archive index (`_archived/index.json`):**
|
|
88
|
-
Read
|
|
88
|
+
Read `~/.brain/_archived/index.json`. Check if the target ID exists as a key in `memories`.
|
|
89
89
|
|
|
90
90
|
**3h. Crystallization comments:**
|
|
91
91
|
Search all memory files for HTML comments matching the pattern:
|
|
@@ -230,13 +230,13 @@ For each directory in the target's path, read the `_meta.json` and decrement `me
|
|
|
230
230
|
- Clean up empty parent directories (but never delete top-level category directories)
|
|
231
231
|
|
|
232
232
|
**7g. Remove archived copy:**
|
|
233
|
-
If an archived copy exists at
|
|
233
|
+
If an archived copy exists at `~/.brain/_archived/<original-path>`, delete it.
|
|
234
234
|
- If `--sensitive`: overwrite with null bytes before deletion
|
|
235
235
|
- Clean up empty directories in `_archived/`
|
|
236
236
|
|
|
237
237
|
### 8. Write Audit Log
|
|
238
238
|
|
|
239
|
-
Unless `--no-trace` is set, write or append to
|
|
239
|
+
Unless `--no-trace` is set, write or append to `~/.brain/_erased.json`:
|
|
240
240
|
|
|
241
241
|
```json
|
|
242
242
|
{
|
|
@@ -317,7 +317,7 @@ Print a summary:
|
|
|
317
317
|
|
|
318
318
|
7. **Empty `related` arrays after cleanup**: Leave as `related: []`. Do not remove the field entirely — it maintains schema consistency.
|
|
319
319
|
|
|
320
|
-
8. **Memory referenced by memories outside
|
|
320
|
+
8. **Memory referenced by memories outside `~/.brain/`**: This command only operates within `~/.brain/`. If external files (e.g., `CLAUDE.md`, project docs) reference the memory, note this limitation in the summary.
|
|
321
321
|
|
|
322
322
|
9. **Multiple memories matching a title substring**: Present all matches with their IDs, paths, and strengths. Ask the user to select the specific memory to erase.
|
|
323
323
|
|
package/commands/brain/sync.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# /brain:sync — Portable Sync
|
|
2
2
|
|
|
3
|
-
You are managing synchronization for the Brain Memory system. This enables manual push/pull of
|
|
3
|
+
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.
|
|
4
4
|
|
|
5
5
|
**CRITICAL RULES:**
|
|
6
6
|
- NEVER auto-sync — always require explicit user action
|
|
@@ -15,7 +15,7 @@ Parse the user's input to determine the subcommand:
|
|
|
15
15
|
- `push` → Commit and push local changes to remote
|
|
16
16
|
- `pull` → Fetch and merge remote changes to local
|
|
17
17
|
- `status` → Show sync state (ahead/behind)
|
|
18
|
-
- `export [path]` → Export
|
|
18
|
+
- `export [path]` → Export ~/.brain/ to an encrypted single file
|
|
19
19
|
- `import <path>` → Import from an export file
|
|
20
20
|
- `disconnect` → Remove sync configuration
|
|
21
21
|
|
|
@@ -28,9 +28,9 @@ If no subcommand is given, show available subcommands.
|
|
|
28
28
|
### Steps
|
|
29
29
|
|
|
30
30
|
1. **Check prerequisites:**
|
|
31
|
-
- Verify
|
|
31
|
+
- Verify `~/.brain/` exists. If not, suggest `/brain:init` first.
|
|
32
32
|
- Verify `git` is available (`checkGitAvailable()` from `src/git-sync.js`).
|
|
33
|
-
- Check if sync is already configured (
|
|
33
|
+
- Check if sync is already configured (`~/.brain/.sync/config.json`). If so, ask if they want to reconfigure.
|
|
34
34
|
|
|
35
35
|
2. **Get remote URL** (if not provided):
|
|
36
36
|
- Ask for the Git remote URL (SSH or HTTPS).
|
|
@@ -46,7 +46,7 @@ If no subcommand is given, show available subcommands.
|
|
|
46
46
|
|
|
47
47
|
4. **Initialize sync:**
|
|
48
48
|
- Call `initSyncRepo()` and `configureRemote()` from `src/git-sync.js`.
|
|
49
|
-
- Write config to
|
|
49
|
+
- Write config to `~/.brain/.sync/config.json` via `writeSyncConfig()`.
|
|
50
50
|
|
|
51
51
|
5. **Show result:**
|
|
52
52
|
```
|
|
@@ -207,7 +207,7 @@ If no subcommand is given, show available subcommands.
|
|
|
207
207
|
|
|
208
208
|
1. **Show current config** (remote URL).
|
|
209
209
|
2. **Ask for confirmation:** "This will remove sync configuration. Your remote data will NOT be deleted."
|
|
210
|
-
3. **Remove
|
|
210
|
+
3. **Remove `~/.brain/.sync/` directory.**
|
|
211
211
|
4. **Confirm:** "✓ Sync disconnected. Remote repository is untouched."
|
|
212
212
|
|
|
213
213
|
---
|
|
@@ -217,6 +217,6 @@ If no subcommand is given, show available subcommands.
|
|
|
217
217
|
- Git sync engine: `src/git-sync.js`
|
|
218
218
|
- Export/import: `src/export-import.js`
|
|
219
219
|
- Crypto utilities: `src/crypto.js`
|
|
220
|
-
- Sync config stored in
|
|
221
|
-
- Hidden git repo at
|
|
220
|
+
- Sync config stored in `~/.brain/.sync/config.json` (local only)
|
|
221
|
+
- Hidden git repo at `~/.brain/.sync/repo/` — never interferes with the project's own git
|
|
222
222
|
- All git operations use `execFileSync` — no npm dependencies
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "brain-memory",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.8",
|
|
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",
|
package/prompts/claude.md
CHANGED
|
@@ -4,7 +4,7 @@ This project uses the **Brain Memory** plugin — a hierarchical, file-system-ba
|
|
|
4
4
|
|
|
5
5
|
## Memory Location
|
|
6
6
|
|
|
7
|
-
All memories are stored in
|
|
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
8
|
|
|
9
9
|
## How It Works
|
|
10
10
|
|
|
@@ -37,7 +37,7 @@ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `
|
|
|
37
37
|
| observation | 0.40 | 0.950 | Casual facts or notices |
|
|
38
38
|
|
|
39
39
|
### Associative Network
|
|
40
|
-
Memories are connected via weighted edges in
|
|
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
41
|
|
|
42
42
|
### Context-Dependent Recall
|
|
43
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.
|
|
@@ -64,12 +64,12 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
64
64
|
|
|
65
65
|
**IMPORTANT: Perform these steps automatically at the beginning of every session.**
|
|
66
66
|
|
|
67
|
-
If
|
|
67
|
+
If `~/.brain/index.json` exists:
|
|
68
68
|
|
|
69
69
|
1. **Read the index** to understand the current brain state (memory count, categories)
|
|
70
70
|
2. **Identify high-value memories** — the top 3-5 memories by effective strength that are relevant to the current project context
|
|
71
71
|
3. **Silently internalize** these memories so you can reference them naturally during the session — do NOT dump memory contents
|
|
72
|
-
4. **Check review queue** — read
|
|
72
|
+
4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
|
|
73
73
|
5. **Capture session context** — note the current project name, inferred topics, and task type for context-dependent recall
|
|
74
74
|
6. **Output a brief status** (1-3 lines):
|
|
75
75
|
|
|
@@ -110,24 +110,24 @@ If the session contained meaningful content in any of these categories, suggest:
|
|
|
110
110
|
- Do NOT auto-memorize without user consent
|
|
111
111
|
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
112
112
|
- Only suggest when there is genuinely valuable context worth preserving
|
|
113
|
-
- Always save session context to
|
|
113
|
+
- Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
|
|
114
114
|
|
|
115
115
|
## When Recalling Memories
|
|
116
116
|
|
|
117
117
|
When the user asks you to "remember" something, or when context from past sessions would be helpful:
|
|
118
|
-
1. Check
|
|
119
|
-
2. Load
|
|
118
|
+
1. Check `~/.brain/index.json` for relevant memories
|
|
119
|
+
2. Load `~/.brain/associations.json` for spreading activation
|
|
120
120
|
3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
|
|
121
121
|
4. Return strong individual matches or synthesize from multiple related memories
|
|
122
122
|
5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
|
|
123
123
|
6. Strengthen Hebbian links between co-retrieved memories
|
|
124
|
-
7. If no active matches, search the archive (
|
|
124
|
+
7. If no active matches, search the archive (`~/.brain/_archived/`)
|
|
125
125
|
|
|
126
126
|
## Portable Sync
|
|
127
127
|
|
|
128
128
|
Brain memories can be synced across devices in two ways:
|
|
129
129
|
|
|
130
|
-
1. **Git remote** — Push/pull
|
|
131
|
-
2. **Export/Import** — Pack the entire
|
|
130
|
+
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`.
|
|
131
|
+
2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
|
|
132
132
|
|
|
133
133
|
Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
|
package/prompts/gemini.md
CHANGED
|
@@ -4,7 +4,7 @@ This project uses the **Brain Memory** plugin — a hierarchical, file-system-ba
|
|
|
4
4
|
|
|
5
5
|
## Memory Location
|
|
6
6
|
|
|
7
|
-
All memories are stored in
|
|
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
8
|
|
|
9
9
|
## How It Works
|
|
10
10
|
|
|
@@ -37,7 +37,7 @@ Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `
|
|
|
37
37
|
| observation | 0.40 | 0.950 | Casual facts or notices |
|
|
38
38
|
|
|
39
39
|
### Associative Network
|
|
40
|
-
Memories are connected via weighted edges in
|
|
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
41
|
|
|
42
42
|
### Context-Dependent Recall
|
|
43
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.
|
|
@@ -65,12 +65,12 @@ Commands are available via `/brain:` prefix:
|
|
|
65
65
|
|
|
66
66
|
**IMPORTANT: Perform these steps automatically at the beginning of every session.**
|
|
67
67
|
|
|
68
|
-
If
|
|
68
|
+
If `~/.brain/index.json` exists:
|
|
69
69
|
|
|
70
70
|
1. **Read the index** to understand the current brain state (memory count, categories)
|
|
71
71
|
2. **Identify high-value memories** — the top 3-5 memories by effective strength that are relevant to the current project context
|
|
72
72
|
3. **Silently internalize** these memories so you can reference them naturally during the session — do NOT dump memory contents
|
|
73
|
-
4. **Check review queue** — read
|
|
73
|
+
4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
|
|
74
74
|
5. **Capture session context** — note the current project name, inferred topics, and task type for context-dependent recall
|
|
75
75
|
6. **Output a brief status** (1-3 lines):
|
|
76
76
|
|
|
@@ -111,24 +111,24 @@ If the session contained meaningful content in any of these categories, suggest:
|
|
|
111
111
|
- Do NOT auto-memorize without user consent
|
|
112
112
|
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
113
113
|
- Only suggest when there is genuinely valuable context worth preserving
|
|
114
|
-
- Always save session context to
|
|
114
|
+
- Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
|
|
115
115
|
|
|
116
116
|
## When Recalling Memories
|
|
117
117
|
|
|
118
118
|
When the user asks you to "remember" something, or when context from past sessions would be helpful:
|
|
119
|
-
1. Check
|
|
120
|
-
2. Load
|
|
119
|
+
1. Check `~/.brain/index.json` for relevant memories
|
|
120
|
+
2. Load `~/.brain/associations.json` for spreading activation
|
|
121
121
|
3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
|
|
122
122
|
4. Return strong individual matches or synthesize from multiple related memories
|
|
123
123
|
5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
|
|
124
124
|
6. Strengthen Hebbian links between co-retrieved memories
|
|
125
|
-
7. If no active matches, search the archive (
|
|
125
|
+
7. If no active matches, search the archive (`~/.brain/_archived/`)
|
|
126
126
|
|
|
127
127
|
## Portable Sync
|
|
128
128
|
|
|
129
129
|
Brain memories can be synced across devices in two ways:
|
|
130
130
|
|
|
131
|
-
1. **Git remote** — Push/pull
|
|
132
|
-
2. **Export/Import** — Pack the entire
|
|
131
|
+
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`.
|
|
132
|
+
2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
|
|
133
133
|
|
|
134
134
|
Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
|
package/src/export-import.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Brain Memory — Export / Import
|
|
3
3
|
*
|
|
4
4
|
* Single-file encrypted export/import for portable memory transfers.
|
|
5
|
-
* Pack all
|
|
5
|
+
* Pack all ~/.brain/ files into one JSON blob, optionally AES-256-GCM encrypt,
|
|
6
6
|
* and write a single .brain-export file. Import reverses the process.
|
|
7
7
|
*
|
|
8
8
|
* Zero external dependencies — uses only Node.js built-in fs and crypto.
|
|
@@ -12,20 +12,20 @@ const fs = require('fs');
|
|
|
12
12
|
const path = require('path');
|
|
13
13
|
const { encrypt, decrypt } = require('./crypto');
|
|
14
14
|
|
|
15
|
-
// Directories inside
|
|
15
|
+
// Directories inside ~/.brain/ to skip during export
|
|
16
16
|
const EXCLUDED = new Set(['.sync', '.DS_Store']);
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
|
-
* Export the entire
|
|
19
|
+
* Export the entire ~/.brain/ directory to a single file.
|
|
20
20
|
*
|
|
21
|
-
* @param {string} brainDir - Absolute path to
|
|
21
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
22
22
|
* @param {string} outputPath - Destination file path
|
|
23
23
|
* @param {string|null} [passphrase] - If provided, encrypt the export
|
|
24
24
|
* @returns {{ fileCount: number, outputPath: string }}
|
|
25
25
|
*/
|
|
26
26
|
function exportBrain(brainDir, outputPath, passphrase) {
|
|
27
27
|
if (!fs.existsSync(brainDir)) {
|
|
28
|
-
throw new Error('
|
|
28
|
+
throw new Error('~/.brain/ directory not found. Run /brain:init first.');
|
|
29
29
|
}
|
|
30
30
|
|
|
31
31
|
const files = {};
|
|
@@ -47,7 +47,7 @@ function exportBrain(brainDir, outputPath, passphrase) {
|
|
|
47
47
|
* Recursively collect all files from brainDir into a flat { relativePath: content } map.
|
|
48
48
|
*
|
|
49
49
|
* @param {string} dir - Current directory to scan
|
|
50
|
-
* @param {string} brainDir - Root
|
|
50
|
+
* @param {string} brainDir - Root ~/.brain/ directory
|
|
51
51
|
* @param {Object} files - Accumulator object
|
|
52
52
|
*/
|
|
53
53
|
function collectFiles(dir, brainDir, files) {
|
|
@@ -69,10 +69,10 @@ function collectFiles(dir, brainDir, files) {
|
|
|
69
69
|
}
|
|
70
70
|
|
|
71
71
|
/**
|
|
72
|
-
* Import memories from a .brain-export file into
|
|
72
|
+
* Import memories from a .brain-export file into ~/.brain/.
|
|
73
73
|
*
|
|
74
74
|
* @param {string} inputPath - Path to the export file
|
|
75
|
-
* @param {string} brainDir - Absolute path to
|
|
75
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
76
76
|
* @param {string|null} [passphrase] - Decryption passphrase (if the export is encrypted)
|
|
77
77
|
* @param {Object} [options]
|
|
78
78
|
* @param {string} [options.mode='overwrite'] - 'overwrite' replaces all files; 'merge' only imports newer files
|
|
@@ -142,7 +142,7 @@ function importBrain(inputPath, brainDir, passphrase, options = {}) {
|
|
|
142
142
|
* Preview what an import would do without writing any files.
|
|
143
143
|
*
|
|
144
144
|
* @param {string} inputPath - Path to the export file
|
|
145
|
-
* @param {string} brainDir - Absolute path to
|
|
145
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
146
146
|
* @param {string|null} [passphrase] - Decryption passphrase
|
|
147
147
|
* @returns {{ totalFiles: number, newFiles: string[], existingFiles: string[], exportedAt: string }}
|
|
148
148
|
*/
|
package/src/git-sync.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Brain Memory — Git Sync Engine
|
|
3
3
|
*
|
|
4
|
-
* Push/pull
|
|
5
|
-
* A hidden git repo lives at
|
|
4
|
+
* Push/pull ~/.brain/ memories via any Git remote (GitHub, GitLab, Codeberg, etc.).
|
|
5
|
+
* A hidden git repo lives at ~/.brain/.sync/repo/ — the project's own git history
|
|
6
6
|
* is never touched.
|
|
7
7
|
*
|
|
8
8
|
* Zero external dependencies — uses child_process.execFileSync to call the git binary.
|
|
@@ -17,7 +17,7 @@ const SYNC_DIR = '.sync';
|
|
|
17
17
|
const REPO_DIR = 'repo';
|
|
18
18
|
const CONFIG_FILE = 'config.json';
|
|
19
19
|
|
|
20
|
-
// Files/dirs inside
|
|
20
|
+
// Files/dirs inside ~/.brain/ that should NOT be synced
|
|
21
21
|
const EXCLUDED = new Set(['.sync', '.DS_Store']);
|
|
22
22
|
|
|
23
23
|
/**
|
|
@@ -37,7 +37,7 @@ function checkGitAvailable() {
|
|
|
37
37
|
/**
|
|
38
38
|
* Run a git command inside the sync repo.
|
|
39
39
|
*
|
|
40
|
-
* @param {string} repoDir - Absolute path to
|
|
40
|
+
* @param {string} repoDir - Absolute path to ~/.brain/.sync/repo/
|
|
41
41
|
* @param {string[]} args - Git arguments
|
|
42
42
|
* @param {Object} [opts] - Extra execFileSync options
|
|
43
43
|
* @returns {string} stdout (trimmed)
|
|
@@ -45,7 +45,7 @@ function checkGitAvailable() {
|
|
|
45
45
|
function git(repoDir, args, opts = {}) {
|
|
46
46
|
// Explicitly set GIT_DIR and GIT_WORK_TREE to prevent git from walking up
|
|
47
47
|
// the directory tree and finding the parent project's .git directory.
|
|
48
|
-
// Without this, if
|
|
48
|
+
// Without this, if ~/.brain/.sync/repo/.git doesn't exist yet (first push or
|
|
49
49
|
// failed init), git operations would silently affect the parent project repo.
|
|
50
50
|
const env = {
|
|
51
51
|
...process.env,
|
|
@@ -64,7 +64,7 @@ function git(repoDir, args, opts = {}) {
|
|
|
64
64
|
/**
|
|
65
65
|
* Resolve paths for sync infrastructure.
|
|
66
66
|
*
|
|
67
|
-
* @param {string} brainDir - Absolute path to
|
|
67
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
68
68
|
* @returns {{ syncDir: string, repoDir: string, configPath: string }}
|
|
69
69
|
*/
|
|
70
70
|
function resolvePaths(brainDir) {
|
|
@@ -75,9 +75,9 @@ function resolvePaths(brainDir) {
|
|
|
75
75
|
}
|
|
76
76
|
|
|
77
77
|
/**
|
|
78
|
-
* Initialize a git repo inside
|
|
78
|
+
* Initialize a git repo inside ~/.brain/.sync/repo/.
|
|
79
79
|
*
|
|
80
|
-
* @param {string} brainDir - Absolute path to
|
|
80
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
81
81
|
* @returns {{ repoDir: string }} Created repo path
|
|
82
82
|
*/
|
|
83
83
|
function initSyncRepo(brainDir) {
|
|
@@ -94,7 +94,7 @@ function initSyncRepo(brainDir) {
|
|
|
94
94
|
/**
|
|
95
95
|
* Configure (or update) the remote URL for the sync repo.
|
|
96
96
|
*
|
|
97
|
-
* @param {string} brainDir - Absolute path to
|
|
97
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
98
98
|
* @param {string} remoteUrl - Git remote URL (SSH or HTTPS)
|
|
99
99
|
*/
|
|
100
100
|
function configureRemote(brainDir, remoteUrl) {
|
|
@@ -111,11 +111,11 @@ function configureRemote(brainDir, remoteUrl) {
|
|
|
111
111
|
}
|
|
112
112
|
|
|
113
113
|
/**
|
|
114
|
-
* Copy
|
|
114
|
+
* Copy ~/.brain/ files into the sync repo, excluding .sync/.
|
|
115
115
|
* If encryption is enabled, files are encrypted before writing.
|
|
116
116
|
*
|
|
117
|
-
* @param {string} brainDir - Absolute path to
|
|
118
|
-
* @param {string} repoDir - Absolute path to
|
|
117
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
118
|
+
* @param {string} repoDir - Absolute path to ~/.brain/.sync/repo/
|
|
119
119
|
* @param {string|null} passphrase - Encryption passphrase or null
|
|
120
120
|
*/
|
|
121
121
|
function copyBrainToRepo(brainDir, repoDir, passphrase) {
|
|
@@ -126,7 +126,7 @@ function copyBrainToRepo(brainDir, repoDir, passphrase) {
|
|
|
126
126
|
fs.rmSync(path.join(repoDir, entry), { recursive: true, force: true });
|
|
127
127
|
}
|
|
128
128
|
|
|
129
|
-
// Recursively copy
|
|
129
|
+
// Recursively copy ~/.brain/ → repo/
|
|
130
130
|
copyDir(brainDir, repoDir, brainDir, passphrase);
|
|
131
131
|
}
|
|
132
132
|
|
|
@@ -163,11 +163,11 @@ function copyDir(srcDir, destDir, brainDir, passphrase) {
|
|
|
163
163
|
}
|
|
164
164
|
|
|
165
165
|
/**
|
|
166
|
-
* Copy files from the sync repo back into
|
|
166
|
+
* Copy files from the sync repo back into ~/.brain/.
|
|
167
167
|
* If encryption is enabled, files are decrypted after reading.
|
|
168
168
|
*
|
|
169
|
-
* @param {string} repoDir - Absolute path to
|
|
170
|
-
* @param {string} brainDir - Absolute path to
|
|
169
|
+
* @param {string} repoDir - Absolute path to ~/.brain/.sync/repo/
|
|
170
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
171
171
|
* @param {string|null} passphrase - Decryption passphrase or null
|
|
172
172
|
*/
|
|
173
173
|
function copyRepoToBrain(repoDir, brainDir, passphrase) {
|
|
@@ -202,7 +202,7 @@ function copyRepoDir(srcDir, destDir, repoDir, passphrase) {
|
|
|
202
202
|
/**
|
|
203
203
|
* Get a summary of local vs remote sync status.
|
|
204
204
|
*
|
|
205
|
-
* @param {string} brainDir - Absolute path to
|
|
205
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
206
206
|
* @returns {{ configured: boolean, remote: string|null, branch: string|null, ahead: number, behind: number, lastPush: string|null }}
|
|
207
207
|
*/
|
|
208
208
|
function getStatus(brainDir) {
|
|
@@ -244,9 +244,9 @@ function getStatus(brainDir) {
|
|
|
244
244
|
}
|
|
245
245
|
|
|
246
246
|
/**
|
|
247
|
-
* Push
|
|
247
|
+
* Push ~/.brain/ contents to the remote.
|
|
248
248
|
*
|
|
249
|
-
* @param {string} brainDir - Absolute path to
|
|
249
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
250
250
|
* @param {string} [message] - Commit message (defaults to timestamp)
|
|
251
251
|
* @param {string} [passphrase] - Encryption passphrase (if configured)
|
|
252
252
|
* @returns {{ committed: boolean, pushed: boolean, message: string }}
|
|
@@ -302,9 +302,9 @@ function push(brainDir, message, passphrase) {
|
|
|
302
302
|
}
|
|
303
303
|
|
|
304
304
|
/**
|
|
305
|
-
* Pull remote changes into
|
|
305
|
+
* Pull remote changes into ~/.brain/.
|
|
306
306
|
*
|
|
307
|
-
* @param {string} brainDir - Absolute path to
|
|
307
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
308
308
|
* @param {string} [passphrase] - Decryption passphrase (if configured)
|
|
309
309
|
* @returns {{ pulled: boolean, message: string }}
|
|
310
310
|
*/
|
|
@@ -329,7 +329,7 @@ function pull(brainDir, passphrase) {
|
|
|
329
329
|
} catch (err) {
|
|
330
330
|
// Could be first pull (nothing to pull), or merge conflict
|
|
331
331
|
if (err.message && err.message.includes('Not possible to fast-forward')) {
|
|
332
|
-
return { pulled: false, message: 'Merge conflict detected. Push your local changes first, or manually resolve in
|
|
332
|
+
return { pulled: false, message: 'Merge conflict detected. Push your local changes first, or manually resolve in ~/.brain/.sync/repo/' };
|
|
333
333
|
}
|
|
334
334
|
// First clone — try to set up tracking
|
|
335
335
|
try {
|
|
@@ -351,7 +351,7 @@ function pull(brainDir, passphrase) {
|
|
|
351
351
|
}
|
|
352
352
|
|
|
353
353
|
/**
|
|
354
|
-
* Read sync config from
|
|
354
|
+
* Read sync config from ~/.brain/.sync/config.json.
|
|
355
355
|
*
|
|
356
356
|
* @param {string} configPath - Absolute path to config.json
|
|
357
357
|
* @returns {Object|null}
|
|
@@ -365,7 +365,7 @@ function readConfig(configPath) {
|
|
|
365
365
|
}
|
|
366
366
|
|
|
367
367
|
/**
|
|
368
|
-
* Write sync config to
|
|
368
|
+
* Write sync config to ~/.brain/.sync/config.json.
|
|
369
369
|
*
|
|
370
370
|
* @param {string} configPath - Absolute path to config.json
|
|
371
371
|
* @param {Object} config
|
|
@@ -378,7 +378,7 @@ function writeConfig(configPath, config) {
|
|
|
378
378
|
/**
|
|
379
379
|
* Read the sync config for a brain directory.
|
|
380
380
|
*
|
|
381
|
-
* @param {string} brainDir - Absolute path to
|
|
381
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
382
382
|
* @returns {Object|null}
|
|
383
383
|
*/
|
|
384
384
|
function getSyncConfig(brainDir) {
|
|
@@ -389,7 +389,7 @@ function getSyncConfig(brainDir) {
|
|
|
389
389
|
/**
|
|
390
390
|
* Write the sync config for a brain directory.
|
|
391
391
|
*
|
|
392
|
-
* @param {string} brainDir - Absolute path to
|
|
392
|
+
* @param {string} brainDir - Absolute path to ~/.brain/
|
|
393
393
|
* @param {Object} config
|
|
394
394
|
*/
|
|
395
395
|
function writeSyncConfig(brainDir, config) {
|
package/src/index-manager.js
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Brain Memory — Index Manager
|
|
3
3
|
*
|
|
4
|
-
* Utilities for reading, updating, and maintaining the
|
|
4
|
+
* Utilities for reading, updating, and maintaining the ~/.brain/index.json
|
|
5
5
|
* file. Used by hooks and external integrations.
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
8
|
const fs = require('fs');
|
|
9
9
|
const path = require('path');
|
|
10
|
+
const os = require('os');
|
|
10
11
|
|
|
11
|
-
const DEFAULT_BRAIN_DIR = '.brain';
|
|
12
|
+
const DEFAULT_BRAIN_DIR = path.join(os.homedir(), '.brain');
|
|
12
13
|
const INDEX_FILE = 'index.json';
|
|
13
14
|
const ASSOCIATIONS_FILE = 'associations.json';
|
|
14
15
|
const CONTEXTS_FILE = 'contexts.json';
|
|
@@ -18,11 +19,12 @@ const ARCHIVE_INDEX_FILE = '_archived/index.json';
|
|
|
18
19
|
/**
|
|
19
20
|
* Resolve the brain directory path.
|
|
20
21
|
*
|
|
21
|
-
* @param {string} [
|
|
22
|
-
* @returns {string} Absolute path to
|
|
22
|
+
* @param {string} [overrideBase] - Override base directory (for testing)
|
|
23
|
+
* @returns {string} Absolute path to ~/.brain/ (or overrideBase/.brain/ if provided)
|
|
23
24
|
*/
|
|
24
|
-
function getBrainDir(
|
|
25
|
-
return path.join(
|
|
25
|
+
function getBrainDir(overrideBase) {
|
|
26
|
+
if (overrideBase) return path.join(overrideBase, '.brain');
|
|
27
|
+
return DEFAULT_BRAIN_DIR;
|
|
26
28
|
}
|
|
27
29
|
|
|
28
30
|
/**
|
|
@@ -106,7 +108,7 @@ function generateId() {
|
|
|
106
108
|
/**
|
|
107
109
|
* Read a _meta.json file from a brain subdirectory.
|
|
108
110
|
*
|
|
109
|
-
* @param {string} categoryPath - Relative path within
|
|
111
|
+
* @param {string} categoryPath - Relative path within ~/.brain/
|
|
110
112
|
* @param {string} [projectRoot] - Project root directory
|
|
111
113
|
* @returns {Object|null} Parsed meta or null
|
|
112
114
|
*/
|
|
@@ -119,7 +121,7 @@ function readMeta(categoryPath, projectRoot) {
|
|
|
119
121
|
/**
|
|
120
122
|
* Write a _meta.json file to a brain subdirectory.
|
|
121
123
|
*
|
|
122
|
-
* @param {string} categoryPath - Relative path within
|
|
124
|
+
* @param {string} categoryPath - Relative path within ~/.brain/
|
|
123
125
|
* @param {Object} meta - Meta object to write
|
|
124
126
|
* @param {string} [projectRoot] - Project root directory
|
|
125
127
|
*/
|
package/src/installer.js
CHANGED
|
@@ -210,8 +210,8 @@ function installForRuntime(runtime, scope) {
|
|
|
210
210
|
injectPrompt(promptTarget, config.promptFile, config.promptSource);
|
|
211
211
|
}
|
|
212
212
|
|
|
213
|
-
function initializeBrain(
|
|
214
|
-
const brainDir = path.join(
|
|
213
|
+
function initializeBrain(overrideBase) {
|
|
214
|
+
const brainDir = path.join(overrideBase || os.homedir(), '.brain');
|
|
215
215
|
|
|
216
216
|
if (fs.existsSync(brainDir)) {
|
|
217
217
|
return { alreadyExists: true };
|