brain-memory 0.1.0-beta.1 → 0.1.0-beta.11
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 +158 -54
- package/assets/icon.png +0 -0
- package/bin/install.js +200 -230
- package/bin/recall.js +211 -0
- package/bin/reinforce.js +179 -0
- 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 -12
- package/commands/brain/memorize.md +64 -21
- package/commands/brain/remember.md +43 -105
- package/commands/brain/review.md +2 -2
- package/commands/brain/sleep.md +4 -23
- package/commands/brain/status.md +15 -5
- package/commands/brain/sunshine.md +13 -13
- package/commands/brain/sync.md +222 -0
- package/package.json +16 -5
- package/prompts/claude.md +122 -12
- package/prompts/gemini.md +122 -12
- package/prompts/openai.md +120 -10
- package/src/crypto.js +130 -0
- package/src/export-import.js +185 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +94 -18
- package/src/installer.js +361 -0
- package/src/tfidf.js +408 -0
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
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.11",
|
|
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",
|
|
@@ -9,7 +9,11 @@
|
|
|
9
9
|
"memory",
|
|
10
10
|
"ai-agent",
|
|
11
11
|
"context-engineering",
|
|
12
|
-
"hierarchical-memory"
|
|
12
|
+
"hierarchical-memory",
|
|
13
|
+
"neuroscience",
|
|
14
|
+
"spaced-repetition",
|
|
15
|
+
"file-based",
|
|
16
|
+
"slash-commands"
|
|
13
17
|
],
|
|
14
18
|
"author": {
|
|
15
19
|
"name": "Onur Karali",
|
|
@@ -20,14 +24,16 @@
|
|
|
20
24
|
"url": "https://github.com/onurkarali/brain/issues"
|
|
21
25
|
},
|
|
22
26
|
"bin": {
|
|
23
|
-
"brain-memory": "bin/install.js"
|
|
27
|
+
"brain-memory": "bin/install.js",
|
|
28
|
+
"brain-recall": "bin/recall.js",
|
|
29
|
+
"brain-reinforce": "bin/reinforce.js"
|
|
24
30
|
},
|
|
25
31
|
"files": [
|
|
32
|
+
"assets/",
|
|
26
33
|
"bin/",
|
|
27
34
|
"commands/",
|
|
28
35
|
"prompts/",
|
|
29
36
|
"templates/",
|
|
30
|
-
"hooks/",
|
|
31
37
|
"src/",
|
|
32
38
|
"README.md",
|
|
33
39
|
"LICENSE"
|
|
@@ -37,7 +43,12 @@
|
|
|
37
43
|
"url": "git+https://github.com/onurkarali/brain.git"
|
|
38
44
|
},
|
|
39
45
|
"scripts": {
|
|
40
|
-
"test": "node --test
|
|
46
|
+
"test": "node --test test/index-manager.test.js test/scorer.test.js test/tfidf.test.js test/recall.test.js test/functional.test.js test/sunshine.test.js test/stress.test.js test/crypto.test.js test/git-sync.test.js test/export-import.test.js test/install.test.js test/prompts.test.js",
|
|
47
|
+
"prerelease": "npm test",
|
|
48
|
+
"release:beta": "npm version prerelease --preid beta && npm publish --tag beta && npm dist-tag add brain-memory@$(node -p \"require('./package.json').version\") latest",
|
|
49
|
+
"release:patch": "npm version patch && npm publish",
|
|
50
|
+
"release:minor": "npm version minor && npm publish",
|
|
51
|
+
"release:major": "npm version major && npm publish"
|
|
41
52
|
},
|
|
42
53
|
"license": "MIT",
|
|
43
54
|
"engines": {
|
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.
|
|
@@ -58,18 +58,128 @@ Memories store their encoding context (project, topics, task type). During recal
|
|
|
58
58
|
- `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
59
59
|
- `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
60
60
|
- `/brain:status` — Dashboard with brain health overview
|
|
61
|
+
- `/brain:sync [subcommand]` — Sync memories via Git remote or export/import for portability
|
|
61
62
|
|
|
62
|
-
##
|
|
63
|
+
## Session Start Behavior
|
|
63
64
|
|
|
64
|
-
|
|
65
|
+
**IMPORTANT: Perform these steps automatically at the beginning of every session.**
|
|
66
|
+
|
|
67
|
+
If `~/.brain/index.json` exists:
|
|
68
|
+
|
|
69
|
+
1. **Read the index** to understand the current brain state (memory count, categories)
|
|
70
|
+
2. **Run the recall engine** to deterministically identify relevant memories for the current project:
|
|
71
|
+
```bash
|
|
72
|
+
brain-recall --context --project "<current project>" --top 5
|
|
73
|
+
```
|
|
74
|
+
This uses TF-IDF + the v4 scoring formula to find the most relevant memories — no guessing.
|
|
75
|
+
3. **Silently internalize** the returned memories so you can reference them naturally during the session — do NOT dump memory contents
|
|
76
|
+
4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
|
|
77
|
+
5. **Output a brief status** (1-3 lines):
|
|
78
|
+
|
|
79
|
+
If memories are due for review:
|
|
80
|
+
```
|
|
81
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
82
|
+
📋 <X> memories due for review — run /brain:review
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Otherwise:
|
|
86
|
+
```
|
|
87
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
If any frequently-used memories (access_count >= 3) have confidence < 0.5:
|
|
91
|
+
```
|
|
92
|
+
⚠️ <N> frequently-used memories have low confidence — consider verifying
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
|
|
96
|
+
|
|
97
|
+
## Ambient Session Tracking
|
|
98
|
+
|
|
99
|
+
**Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
|
|
100
|
+
|
|
101
|
+
Track these categories as they happen:
|
|
102
|
+
- **Decisions** — Architecture choices, technology selections, trade-off resolutions
|
|
103
|
+
- **Learnings** — New patterns, debugging insights, API discoveries
|
|
104
|
+
- **Insights** — Realizations about the codebase, project, or process
|
|
105
|
+
- **Experiences** — Significant events like incidents, deployments, milestones
|
|
106
|
+
- **Goals** — New objectives discussed or planned
|
|
107
|
+
|
|
108
|
+
**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.
|
|
109
|
+
|
|
110
|
+
## Periodic Memory Checkpoint
|
|
111
|
+
|
|
112
|
+
**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.
|
|
113
|
+
|
|
114
|
+
If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
🧠 Notable <type(s)> this session — /brain:memorize when ready
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
**Rules:**
|
|
121
|
+
- **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
|
|
122
|
+
- **At most once per ~10 substantive interactions** — no spamming
|
|
123
|
+
- **Reset the counter** after the user runs `/brain:memorize`
|
|
124
|
+
- **Don't mention if nothing notable** has accumulated
|
|
125
|
+
- **Be specific about types** — say "decisions and learnings" not just "notable content"
|
|
126
|
+
|
|
127
|
+
## Session End Behavior
|
|
128
|
+
|
|
129
|
+
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**:
|
|
130
|
+
|
|
131
|
+
### Step 1: Save Session Context (ALWAYS — do this first)
|
|
132
|
+
|
|
133
|
+
**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.
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{
|
|
137
|
+
"session_id": "<timestamp-based-id>",
|
|
138
|
+
"started": "<session start ISO timestamp>",
|
|
139
|
+
"ended": "<session end ISO timestamp>",
|
|
140
|
+
"project": "<current project name>",
|
|
141
|
+
"topics": ["<key topics discussed>"],
|
|
142
|
+
"task_type": "<primary task type>",
|
|
143
|
+
"memories_created": ["<IDs of memories stored this session>"],
|
|
144
|
+
"memories_recalled": ["<IDs of memories retrieved this session>"],
|
|
145
|
+
"notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
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.
|
|
150
|
+
|
|
151
|
+
### Step 2: Suggest Memorization (if warranted)
|
|
152
|
+
|
|
153
|
+
If the session contained meaningful content based on your ambient tracking:
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
|
|
157
|
+
Run /brain:memorize to capture them before this context is lost.
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Rules:**
|
|
161
|
+
- Do NOT auto-memorize without user consent
|
|
162
|
+
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
163
|
+
- Only suggest when there is genuinely valuable context worth preserving
|
|
164
|
+
- **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
|
|
65
165
|
|
|
66
166
|
## When Recalling Memories
|
|
67
167
|
|
|
68
|
-
When the user asks you to "remember" something, or when context from past sessions would be helpful:
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
168
|
+
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:
|
|
169
|
+
|
|
170
|
+
1. Run `brain-recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
|
|
171
|
+
2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
|
|
172
|
+
3. Read the top-scoring memory files and present results
|
|
173
|
+
4. Run `brain-reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
|
|
174
|
+
5. If no matches, search the archive (`~/.brain/_archived/`)
|
|
175
|
+
|
|
176
|
+
The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
|
|
177
|
+
|
|
178
|
+
## Portable Sync
|
|
179
|
+
|
|
180
|
+
Brain memories can be synced across devices in two ways:
|
|
181
|
+
|
|
182
|
+
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`.
|
|
183
|
+
2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
|
|
184
|
+
|
|
185
|
+
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.
|
|
@@ -59,18 +59,128 @@ Commands are available via `/brain:` prefix:
|
|
|
59
59
|
- `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
60
60
|
- `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
61
61
|
- `/brain:status` — Dashboard with brain health overview
|
|
62
|
+
- `/brain:sync [subcommand]` — Sync memories via Git remote or export/import for portability
|
|
62
63
|
|
|
63
|
-
##
|
|
64
|
+
## Session Start Behavior
|
|
64
65
|
|
|
65
|
-
|
|
66
|
+
**IMPORTANT: Perform these steps automatically at the beginning of every session.**
|
|
67
|
+
|
|
68
|
+
If `~/.brain/index.json` exists:
|
|
69
|
+
|
|
70
|
+
1. **Read the index** to understand the current brain state (memory count, categories)
|
|
71
|
+
2. **Run the recall engine** to deterministically identify relevant memories for the current project:
|
|
72
|
+
```bash
|
|
73
|
+
brain-recall --context --project "<current project>" --top 5
|
|
74
|
+
```
|
|
75
|
+
This uses TF-IDF + the v4 scoring formula to find the most relevant memories — no guessing.
|
|
76
|
+
3. **Silently internalize** the returned memories so you can reference them naturally during the session — do NOT dump memory contents
|
|
77
|
+
4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
|
|
78
|
+
5. **Output a brief status** (1-3 lines):
|
|
79
|
+
|
|
80
|
+
If memories are due for review:
|
|
81
|
+
```
|
|
82
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
83
|
+
📋 <X> memories due for review — run /brain:review
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Otherwise:
|
|
87
|
+
```
|
|
88
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
If any frequently-used memories (access_count >= 3) have confidence < 0.5:
|
|
92
|
+
```
|
|
93
|
+
⚠️ <N> frequently-used memories have low confidence — consider verifying
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
|
|
97
|
+
|
|
98
|
+
## Ambient Session Tracking
|
|
99
|
+
|
|
100
|
+
**Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
|
|
101
|
+
|
|
102
|
+
Track these categories as they happen:
|
|
103
|
+
- **Decisions** — Architecture choices, technology selections, trade-off resolutions
|
|
104
|
+
- **Learnings** — New patterns, debugging insights, API discoveries
|
|
105
|
+
- **Insights** — Realizations about the codebase, project, or process
|
|
106
|
+
- **Experiences** — Significant events like incidents, deployments, milestones
|
|
107
|
+
- **Goals** — New objectives discussed or planned
|
|
108
|
+
|
|
109
|
+
**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.
|
|
110
|
+
|
|
111
|
+
## Periodic Memory Checkpoint
|
|
112
|
+
|
|
113
|
+
**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.
|
|
114
|
+
|
|
115
|
+
If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
🧠 Notable <type(s)> this session — /brain:memorize when ready
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Rules:**
|
|
122
|
+
- **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
|
|
123
|
+
- **At most once per ~10 substantive interactions** — no spamming
|
|
124
|
+
- **Reset the counter** after the user runs `/brain:memorize`
|
|
125
|
+
- **Don't mention if nothing notable** has accumulated
|
|
126
|
+
- **Be specific about types** — say "decisions and learnings" not just "notable content"
|
|
127
|
+
|
|
128
|
+
## Session End Behavior
|
|
129
|
+
|
|
130
|
+
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**:
|
|
131
|
+
|
|
132
|
+
### Step 1: Save Session Context (ALWAYS — do this first)
|
|
133
|
+
|
|
134
|
+
**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.
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"session_id": "<timestamp-based-id>",
|
|
139
|
+
"started": "<session start ISO timestamp>",
|
|
140
|
+
"ended": "<session end ISO timestamp>",
|
|
141
|
+
"project": "<current project name>",
|
|
142
|
+
"topics": ["<key topics discussed>"],
|
|
143
|
+
"task_type": "<primary task type>",
|
|
144
|
+
"memories_created": ["<IDs of memories stored this session>"],
|
|
145
|
+
"memories_recalled": ["<IDs of memories retrieved this session>"],
|
|
146
|
+
"notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
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.
|
|
151
|
+
|
|
152
|
+
### Step 2: Suggest Memorization (if warranted)
|
|
153
|
+
|
|
154
|
+
If the session contained meaningful content based on your ambient tracking:
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
|
|
158
|
+
Run /brain:memorize to capture them before this context is lost.
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**Rules:**
|
|
162
|
+
- Do NOT auto-memorize without user consent
|
|
163
|
+
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
164
|
+
- Only suggest when there is genuinely valuable context worth preserving
|
|
165
|
+
- **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
|
|
66
166
|
|
|
67
167
|
## When Recalling Memories
|
|
68
168
|
|
|
69
|
-
When the user asks you to "remember" something, or when context from past sessions would be helpful:
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
169
|
+
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:
|
|
170
|
+
|
|
171
|
+
1. Run `brain-recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
|
|
172
|
+
2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
|
|
173
|
+
3. Read the top-scoring memory files and present results
|
|
174
|
+
4. Run `brain-reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
|
|
175
|
+
5. If no matches, search the archive (`~/.brain/_archived/`)
|
|
176
|
+
|
|
177
|
+
The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
|
|
178
|
+
|
|
179
|
+
## Portable Sync
|
|
180
|
+
|
|
181
|
+
Brain memories can be synced across devices in two ways:
|
|
182
|
+
|
|
183
|
+
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`.
|
|
184
|
+
2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
|
|
185
|
+
|
|
186
|
+
Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
|
package/prompts/openai.md
CHANGED
|
@@ -59,18 +59,128 @@ Brain skills are available via `/brain-` prefix:
|
|
|
59
59
|
- `/brain-sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
|
|
60
60
|
- `/brain-sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
|
|
61
61
|
- `/brain-status` — Dashboard with brain health overview
|
|
62
|
+
- `/brain-sync [subcommand]` — Sync memories via Git remote or export/import for portability
|
|
62
63
|
|
|
63
|
-
##
|
|
64
|
+
## Session Start Behavior
|
|
64
65
|
|
|
65
|
-
|
|
66
|
+
**IMPORTANT: Perform these steps automatically at the beginning of every session.**
|
|
67
|
+
|
|
68
|
+
If `.brain/index.json` exists in the current project:
|
|
69
|
+
|
|
70
|
+
1. **Read the index** to understand the current brain state (memory count, categories)
|
|
71
|
+
2. **Run the recall engine** to deterministically identify relevant memories for the current project:
|
|
72
|
+
```bash
|
|
73
|
+
brain-recall --context --project "<current project>" --top 5
|
|
74
|
+
```
|
|
75
|
+
This uses TF-IDF + the v4 scoring formula to find the most relevant memories — no guessing.
|
|
76
|
+
3. **Silently internalize** the returned memories so you can reference them naturally during the session — do NOT dump memory contents
|
|
77
|
+
4. **Check review queue** — read `.brain/review-queue.json` if it exists for memories due for review
|
|
78
|
+
5. **Output a brief status** (1-3 lines):
|
|
79
|
+
|
|
80
|
+
If memories are due for review:
|
|
81
|
+
```
|
|
82
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
83
|
+
📋 <X> memories due for review — run /brain-review
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Otherwise:
|
|
87
|
+
```
|
|
88
|
+
🧠 Brain active — <N> memories loaded (<M> in current project context)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
If any frequently-used memories (access_count >= 3) have confidence < 0.5:
|
|
92
|
+
```
|
|
93
|
+
⚠️ <N> frequently-used memories have low confidence — consider verifying
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
|
|
97
|
+
|
|
98
|
+
## Ambient Session Tracking
|
|
99
|
+
|
|
100
|
+
**Throughout the session, maintain a running mental log of notable events.** This requires no file writes — just internal awareness.
|
|
101
|
+
|
|
102
|
+
Track these categories as they happen:
|
|
103
|
+
- **Decisions** — Architecture choices, technology selections, trade-off resolutions
|
|
104
|
+
- **Learnings** — New patterns, debugging insights, API discoveries
|
|
105
|
+
- **Insights** — Realizations about the codebase, project, or process
|
|
106
|
+
- **Experiences** — Significant events like incidents, deployments, milestones
|
|
107
|
+
- **Goals** — New objectives discussed or planned
|
|
108
|
+
|
|
109
|
+
**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.
|
|
110
|
+
|
|
111
|
+
## Periodic Memory Checkpoint
|
|
112
|
+
|
|
113
|
+
**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.
|
|
114
|
+
|
|
115
|
+
If notable items have accumulated, append a **brief one-liner** at the end of your next natural response:
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
🧠 Notable <type(s)> this session — /brain-memorize when ready
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Rules:**
|
|
122
|
+
- **Never interrupt flow** — only append to the end of a response the user is already receiving, never send as a standalone message
|
|
123
|
+
- **At most once per ~10 substantive interactions** — no spamming
|
|
124
|
+
- **Reset the counter** after the user runs `/brain-memorize`
|
|
125
|
+
- **Don't mention if nothing notable** has accumulated
|
|
126
|
+
- **Be specific about types** — say "decisions and learnings" not just "notable content"
|
|
127
|
+
|
|
128
|
+
## Session End Behavior
|
|
129
|
+
|
|
130
|
+
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**:
|
|
131
|
+
|
|
132
|
+
### Step 1: Save Session Context (ALWAYS — do this first)
|
|
133
|
+
|
|
134
|
+
**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.
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"session_id": "<timestamp-based-id>",
|
|
139
|
+
"started": "<session start ISO timestamp>",
|
|
140
|
+
"ended": "<session end ISO timestamp>",
|
|
141
|
+
"project": "<current project name>",
|
|
142
|
+
"topics": ["<key topics discussed>"],
|
|
143
|
+
"task_type": "<primary task type>",
|
|
144
|
+
"memories_created": ["<IDs of memories stored this session>"],
|
|
145
|
+
"memories_recalled": ["<IDs of memories retrieved this session>"],
|
|
146
|
+
"notable_unsaved": ["<brief descriptions of notable items NOT yet memorized>"]
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
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.
|
|
151
|
+
|
|
152
|
+
### Step 2: Suggest Memorization (if warranted)
|
|
153
|
+
|
|
154
|
+
If the session contained meaningful content based on your ambient tracking:
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
|
|
158
|
+
Run /brain-memorize to capture them before this context is lost.
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**Rules:**
|
|
162
|
+
- Do NOT auto-memorize without user consent
|
|
163
|
+
- Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
|
|
164
|
+
- Only suggest when there is genuinely valuable context worth preserving
|
|
165
|
+
- **Do not wait for explicit session-end signals** — if the conversation appears to be wrapping up, save context proactively
|
|
66
166
|
|
|
67
167
|
## When Recalling Memories
|
|
68
168
|
|
|
69
|
-
When the user asks you to "remember" something, or when context from past sessions would be helpful:
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
169
|
+
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:
|
|
170
|
+
|
|
171
|
+
1. Run `brain-recall "<query>" --project <project> --task <task_type> --top 10` (or `node <install-path>/bin/recall.js`)
|
|
172
|
+
2. The engine computes TF-IDF relevance, decayed strength, spreading activation, context match, and salience — all deterministically
|
|
173
|
+
3. Read the top-scoring memory files and present results
|
|
174
|
+
4. Run `brain-reinforce <mem_id1> <mem_id2> ...` to apply spaced reinforcement and Hebbian co-retrieval strengthening
|
|
175
|
+
5. If no matches, search the archive (`.brain/_archived/`)
|
|
176
|
+
|
|
177
|
+
The recall engine ensures **identical scoring across all agents** — Claude, Gemini, and Codex all get the same rankings for the same query.
|
|
178
|
+
|
|
179
|
+
## Portable Sync
|
|
180
|
+
|
|
181
|
+
Brain memories can be synced across devices in two ways:
|
|
182
|
+
|
|
183
|
+
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`.
|
|
184
|
+
2. **Export/Import** — Pack the entire `.brain/` into a single portable file for manual transfer. Run `/brain-sync export` and `/brain-sync import <path>`.
|
|
185
|
+
|
|
186
|
+
Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.
|
package/src/crypto.js
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Brain Memory — Crypto Utilities
|
|
3
|
+
*
|
|
4
|
+
* AES-256-GCM encryption for memory export/import and encrypted sync.
|
|
5
|
+
* Zero external dependencies — uses only Node.js built-in crypto.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
const crypto = require('crypto');
|
|
9
|
+
|
|
10
|
+
const PBKDF2_ITERATIONS = 100000;
|
|
11
|
+
const PBKDF2_DIGEST = 'sha512';
|
|
12
|
+
const KEY_LENGTH = 32; // 256 bits
|
|
13
|
+
const IV_LENGTH = 12; // 96 bits for GCM
|
|
14
|
+
const SALT_LENGTH = 32;
|
|
15
|
+
const AUTH_TAG_LENGTH = 16;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Derive an AES-256 key from a passphrase using PBKDF2.
|
|
19
|
+
*
|
|
20
|
+
* @param {string} passphrase - User-provided passphrase
|
|
21
|
+
* @param {Buffer} salt - 32-byte salt
|
|
22
|
+
* @returns {Buffer} 32-byte derived key
|
|
23
|
+
*/
|
|
24
|
+
function deriveKey(passphrase, salt) {
|
|
25
|
+
return crypto.pbkdf2Sync(passphrase, salt, PBKDF2_ITERATIONS, KEY_LENGTH, PBKDF2_DIGEST);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Encrypt a UTF-8 string with AES-256-GCM.
|
|
30
|
+
*
|
|
31
|
+
* Output format: salt (32) + iv (12) + authTag (16) + ciphertext
|
|
32
|
+
*
|
|
33
|
+
* @param {string} plaintext - UTF-8 string to encrypt
|
|
34
|
+
* @param {string} passphrase - Passphrase (key derived via PBKDF2)
|
|
35
|
+
* @returns {Buffer} Encrypted buffer
|
|
36
|
+
*/
|
|
37
|
+
function encrypt(plaintext, passphrase) {
|
|
38
|
+
const salt = crypto.randomBytes(SALT_LENGTH);
|
|
39
|
+
const key = deriveKey(passphrase, salt);
|
|
40
|
+
const iv = crypto.randomBytes(IV_LENGTH);
|
|
41
|
+
|
|
42
|
+
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
|
|
43
|
+
const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
|
|
44
|
+
const authTag = cipher.getAuthTag();
|
|
45
|
+
|
|
46
|
+
return Buffer.concat([salt, iv, authTag, encrypted]);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Decrypt an AES-256-GCM encrypted buffer back to a UTF-8 string.
|
|
51
|
+
*
|
|
52
|
+
* @param {Buffer} encrypted - Buffer produced by encrypt()
|
|
53
|
+
* @param {string} passphrase - Same passphrase used for encryption
|
|
54
|
+
* @returns {string} Decrypted UTF-8 string
|
|
55
|
+
* @throws {Error} If passphrase is wrong or data is tampered
|
|
56
|
+
*/
|
|
57
|
+
function decrypt(encrypted, passphrase) {
|
|
58
|
+
if (encrypted.length < SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH) {
|
|
59
|
+
throw new Error('Invalid encrypted data: too short');
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const salt = encrypted.subarray(0, SALT_LENGTH);
|
|
63
|
+
const iv = encrypted.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
|
|
64
|
+
const authTag = encrypted.subarray(SALT_LENGTH + IV_LENGTH, SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
|
|
65
|
+
const ciphertext = encrypted.subarray(SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
|
|
66
|
+
|
|
67
|
+
const key = deriveKey(passphrase, salt);
|
|
68
|
+
const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
|
|
69
|
+
decipher.setAuthTag(authTag);
|
|
70
|
+
|
|
71
|
+
return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Encrypt a Buffer with AES-256-GCM.
|
|
76
|
+
*
|
|
77
|
+
* Output format: salt (32) + iv (12) + authTag (16) + ciphertext
|
|
78
|
+
*
|
|
79
|
+
* @param {Buffer} buffer - Raw buffer to encrypt
|
|
80
|
+
* @param {string} passphrase - Passphrase
|
|
81
|
+
* @returns {Buffer} Encrypted buffer
|
|
82
|
+
*/
|
|
83
|
+
function encryptBuffer(buffer, passphrase) {
|
|
84
|
+
const salt = crypto.randomBytes(SALT_LENGTH);
|
|
85
|
+
const key = deriveKey(passphrase, salt);
|
|
86
|
+
const iv = crypto.randomBytes(IV_LENGTH);
|
|
87
|
+
|
|
88
|
+
const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
|
|
89
|
+
const encrypted = Buffer.concat([cipher.update(buffer), cipher.final()]);
|
|
90
|
+
const authTag = cipher.getAuthTag();
|
|
91
|
+
|
|
92
|
+
return Buffer.concat([salt, iv, authTag, encrypted]);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Decrypt a Buffer encrypted with encryptBuffer().
|
|
97
|
+
*
|
|
98
|
+
* @param {Buffer} encrypted - Buffer produced by encryptBuffer()
|
|
99
|
+
* @param {string} passphrase - Same passphrase used for encryption
|
|
100
|
+
* @returns {Buffer} Decrypted buffer
|
|
101
|
+
* @throws {Error} If passphrase is wrong or data is tampered
|
|
102
|
+
*/
|
|
103
|
+
function decryptBuffer(encrypted, passphrase) {
|
|
104
|
+
if (encrypted.length < SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH) {
|
|
105
|
+
throw new Error('Invalid encrypted data: too short');
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const salt = encrypted.subarray(0, SALT_LENGTH);
|
|
109
|
+
const iv = encrypted.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
|
|
110
|
+
const authTag = encrypted.subarray(SALT_LENGTH + IV_LENGTH, SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
|
|
111
|
+
const ciphertext = encrypted.subarray(SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
|
|
112
|
+
|
|
113
|
+
const key = deriveKey(passphrase, salt);
|
|
114
|
+
const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
|
|
115
|
+
decipher.setAuthTag(authTag);
|
|
116
|
+
|
|
117
|
+
return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
module.exports = {
|
|
121
|
+
deriveKey,
|
|
122
|
+
encrypt,
|
|
123
|
+
decrypt,
|
|
124
|
+
encryptBuffer,
|
|
125
|
+
decryptBuffer,
|
|
126
|
+
PBKDF2_ITERATIONS,
|
|
127
|
+
SALT_LENGTH,
|
|
128
|
+
IV_LENGTH,
|
|
129
|
+
AUTH_TAG_LENGTH,
|
|
130
|
+
};
|