brain-memory 0.1.0-beta.1
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/LICENSE +21 -0
- package/README.md +466 -0
- package/bin/install.js +361 -0
- package/commands/brain/consolidate.md +153 -0
- package/commands/brain/explore.md +79 -0
- package/commands/brain/forget.md +115 -0
- package/commands/brain/init.md +157 -0
- package/commands/brain/memorize.md +176 -0
- package/commands/brain/remember.md +176 -0
- package/commands/brain/review.md +130 -0
- package/commands/brain/sleep.md +535 -0
- package/commands/brain/status.md +122 -0
- package/commands/brain/sunshine.md +337 -0
- package/hooks/session-end.md +48 -0
- package/hooks/session-start.md +48 -0
- package/package.json +46 -0
- package/prompts/claude.md +75 -0
- package/prompts/gemini.md +76 -0
- package/prompts/openai.md +76 -0
- package/src/index-manager.js +401 -0
- package/src/scorer.js +452 -0
- package/templates/default-categories.json +82 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Onur Karali
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,466 @@
|
|
|
1
|
+
# Brain Memory
|
|
2
|
+
|
|
3
|
+
[](https://github.com/onurkarali/brain/actions/workflows/ci.yml)
|
|
4
|
+
|
|
5
|
+
A hierarchical, file-system-based memory plugin for AI coding agents. Inspired by human neuroscience — memories are organized into deep nested life-domain categories, connected via associative networks, strengthened through spaced recall, and naturally decay over time.
|
|
6
|
+
|
|
7
|
+
Works with **Claude Code**, **Gemini CLI**, and **OpenAI Codex CLI**.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
.brain/
|
|
11
|
+
├── professional/
|
|
12
|
+
│ └── companies/
|
|
13
|
+
│ └── acme-corp/
|
|
14
|
+
│ └── projects/
|
|
15
|
+
│ └── alpha-launch.md ⚡ 0.88
|
|
16
|
+
├── personal/
|
|
17
|
+
│ └── education/
|
|
18
|
+
│ └── typescript-generics.md ⚡ 0.72
|
|
19
|
+
├── social/
|
|
20
|
+
│ └── communities/
|
|
21
|
+
│ └── open-source-contrib.md ⚡ 0.65
|
|
22
|
+
└── family/
|
|
23
|
+
└── events/
|
|
24
|
+
└── annual-reunion-planning.md ⚡ 0.55
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Why Brain Memory?
|
|
28
|
+
|
|
29
|
+
Existing AI memory solutions use flat databases with tag-based retrieval. Brain Memory is different:
|
|
30
|
+
|
|
31
|
+
- **The directory tree IS the semantic structure** — `professional/companies/acme/projects/` tells the agent everything about context without vector search
|
|
32
|
+
- **Human-inspectable** — Browse your "brain" in any file explorer
|
|
33
|
+
- **Git-friendly** — Full version history of how memories evolve
|
|
34
|
+
- **Strength + decay** — Recalled memories get stronger, forgotten ones fade. Just like your brain
|
|
35
|
+
- **Associative network** — Memories link to each other with weighted connections. Recalling one activates related ones automatically
|
|
36
|
+
- **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
|
|
37
|
+
- **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
|
|
38
|
+
- **Cognitive types** — Episodic, semantic, and procedural memories each decay differently, just like in the brain
|
|
39
|
+
- **On-demand depth** — Subcategories are created as needed, not pre-defined
|
|
40
|
+
- **Consolidation** — Weak related memories merge into stronger combined knowledge
|
|
41
|
+
- **Zero dependencies** — Pure file I/O, no databases, no servers, no embeddings required
|
|
42
|
+
|
|
43
|
+
## Install
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx brain-memory
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The interactive installer asks which runtime(s) to configure (Claude Code, Gemini CLI, OpenAI Codex CLI, or all) and whether to install globally or for the current project.
|
|
50
|
+
|
|
51
|
+
### Non-interactive
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npx brain-memory --claude --global # Claude Code, global
|
|
55
|
+
npx brain-memory --gemini --local # Gemini CLI, local project
|
|
56
|
+
npx brain-memory --codex --global # OpenAI Codex CLI, global
|
|
57
|
+
npx brain-memory --all --global # All runtimes, global
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Manual Install
|
|
61
|
+
|
|
62
|
+
Copy the `commands/brain/` directory to your agent's commands folder:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# Claude Code
|
|
66
|
+
cp -r commands/brain/ ~/.claude/commands/brain/
|
|
67
|
+
|
|
68
|
+
# Gemini CLI
|
|
69
|
+
cp -r commands/brain/ ~/.gemini/commands/brain/
|
|
70
|
+
|
|
71
|
+
# OpenAI Codex CLI (each command becomes a skill)
|
|
72
|
+
for f in commands/brain/*.md; do
|
|
73
|
+
name=$(basename "$f" .md)
|
|
74
|
+
mkdir -p ~/.codex/skills/brain-"$name"
|
|
75
|
+
cp "$f" ~/.codex/skills/brain-"$name"/SKILL.md
|
|
76
|
+
done
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Then append the contents of the corresponding prompt file to your agent's instructions file:
|
|
80
|
+
- `prompts/claude.md` → `CLAUDE.md`
|
|
81
|
+
- `prompts/gemini.md` → `GEMINI.md`
|
|
82
|
+
- `prompts/openai.md` → `AGENTS.md`
|
|
83
|
+
|
|
84
|
+
## Commands
|
|
85
|
+
|
|
86
|
+
| Command | Description |
|
|
87
|
+
|---------|-------------|
|
|
88
|
+
| `/brain:init` | Initialize `.brain/` directory structure with default categories |
|
|
89
|
+
| `/brain:memorize [topic]` | Store memories from current session context |
|
|
90
|
+
| `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
|
|
91
|
+
| `/brain:review [scope]` | Spaced repetition review session for due memories |
|
|
92
|
+
| `/brain:explore [category]` | Browse the brain hierarchy with visual tree view |
|
|
93
|
+
| `/brain:consolidate [scope]` | Merge related weak memories into stronger combined ones |
|
|
94
|
+
| `/brain:forget [target]` | Decay, archive, or remove memories |
|
|
95
|
+
| `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
|
|
96
|
+
| `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
|
|
97
|
+
| `/brain:status` | Dashboard with brain health metrics and recommendations |
|
|
98
|
+
|
|
99
|
+
## How It Works
|
|
100
|
+
|
|
101
|
+
### Memory Lifecycle
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
Create → Store → Decay → Recall → Reinforce → Review → Sleep → Archive
|
|
105
|
+
↑ │
|
|
106
|
+
└── Associations ────┘
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
1. **Create** — When you use `/brain:memorize`, the agent analyzes the session and extracts significant decisions, learnings, insights, or experiences
|
|
110
|
+
2. **Store** — Each memory is filed into the hierarchy at the appropriate depth, with YAML frontmatter tracking metadata. Association edges are created to related memories.
|
|
111
|
+
3. **Decay** — Memories naturally weaken over time: `effective_strength = base_strength * (decay_rate ^ days_since_access)`
|
|
112
|
+
4. **Recall** — `/brain:remember` searches, scores with spreading activation and context matching, and returns the best memories. Archived memories are searched as a fallback.
|
|
113
|
+
5. **Reinforce** — Each recall applies spaced reinforcement (longer gaps = bigger boosts) and improves the memory's decay resistance
|
|
114
|
+
6. **Review** — `/brain:review` implements SM-2 spaced repetition, surfacing memories at optimal intervals for long-term retention
|
|
115
|
+
7. **Sleep** — `/brain:sleep` performs a 9-phase maintenance cycle inspired by real neuroscience
|
|
116
|
+
8. **Archive** — Fully decayed memories move to `_archived/` (recoverable and searchable) or can be permanently deleted
|
|
117
|
+
|
|
118
|
+
### Neuroscience Foundations
|
|
119
|
+
|
|
120
|
+
Brain Memory v2 is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:
|
|
121
|
+
|
|
122
|
+
| Brain Mechanism | Implementation |
|
|
123
|
+
|-----------------|---------------|
|
|
124
|
+
| **Spreading activation** | Recalling memory A automatically surfaces linked memories B and C via weighted association graph |
|
|
125
|
+
| **Hebbian learning** | "Neurons that fire together wire together" — memories recalled together strengthen mutual links |
|
|
126
|
+
| **Context-dependent recall** | Memories encoded in a similar context (project, task type) are scored higher at retrieval |
|
|
127
|
+
| **Spacing effect** | Longer intervals between recalls produce larger strength boosts; cramming yields diminishing returns |
|
|
128
|
+
| **Ebbinghaus decay** | Exponential forgetting curve with per-memory decay rates |
|
|
129
|
+
| **Episodic → Semantic** | Event-specific memories crystallize into abstract principles during sleep |
|
|
130
|
+
| **Synaptic homeostasis (SHY)** | Global strength downscaling during sleep prevents inflation, then selectively re-boosts important memories |
|
|
131
|
+
| **REM dreaming** | Creative cross-domain association discovery via analogical reasoning |
|
|
132
|
+
| **Memory reconsolidation** | Recent knowledge updates and reshapes older related memories during sleep |
|
|
133
|
+
| **Cue-dependent forgetting** | Archival preserves availability — memories aren't deleted, just moved to `_archived/` |
|
|
134
|
+
| **Targeted forgetting** | Deep erasure that traces and removes all references, like how the brain can selectively erase specific memory traces |
|
|
135
|
+
|
|
136
|
+
### Memory Types
|
|
137
|
+
|
|
138
|
+
| Type | Base Strength | Daily Decay | Use Case |
|
|
139
|
+
|------|:---:|:---:|---|
|
|
140
|
+
| `insight` | 0.90 | 0.997 | Deep realizations, patterns discovered |
|
|
141
|
+
| `decision` | 0.85 | 0.995 | Choices made and their rationale |
|
|
142
|
+
| `goal` | 0.80 | 0.993 | Objectives and aspirations |
|
|
143
|
+
| `experience` | 0.75 | 0.985 | Notable events or processes |
|
|
144
|
+
| `learning` | 0.70 | 0.990 | New knowledge acquired |
|
|
145
|
+
| `relationship` | 0.70 | 0.997 | Connections between people/things |
|
|
146
|
+
| `preference` | 0.60 | 0.998 | User style and preferences |
|
|
147
|
+
| `observation` | 0.40 | 0.950 | Casual facts or notices |
|
|
148
|
+
|
|
149
|
+
### Cognitive Types
|
|
150
|
+
|
|
151
|
+
Each memory is also classified by how the brain processes it:
|
|
152
|
+
|
|
153
|
+
| Cognitive Type | Strength Modifier | Decay Behavior | Example |
|
|
154
|
+
|----------------|:-:|---|---|
|
|
155
|
+
| **Episodic** | +0.10 | Faster decay — event details fade | "The deploy failed Tuesday because of X" |
|
|
156
|
+
| **Semantic** | default | Standard decay — stable knowledge | "React hooks must follow rules of hooks" |
|
|
157
|
+
| **Procedural** | -0.10 | Very slow decay — skills persist | "Steps to debug memory leaks" |
|
|
158
|
+
|
|
159
|
+
During sleep, frequently-recalled episodic memories are **crystallized** into semantic memories — the specific event fades but the lesson persists. This mirrors how humans extract general principles from repeated experiences.
|
|
160
|
+
|
|
161
|
+
### Memory File Format
|
|
162
|
+
|
|
163
|
+
Each memory is a Markdown file with YAML frontmatter:
|
|
164
|
+
|
|
165
|
+
```markdown
|
|
166
|
+
---
|
|
167
|
+
id: mem_20260213_a3f2c1
|
|
168
|
+
type: decision
|
|
169
|
+
cognitive_type: semantic
|
|
170
|
+
created: 2026-02-13T14:30:00Z
|
|
171
|
+
last_accessed: 2026-02-13T14:30:00Z
|
|
172
|
+
access_count: 3
|
|
173
|
+
recall_history: ["2026-02-13T14:30:00Z", "2026-02-13T18:00:00Z", "2026-02-14T09:00:00Z"]
|
|
174
|
+
strength: 0.92
|
|
175
|
+
decay_rate: 0.995
|
|
176
|
+
salience: 0.8
|
|
177
|
+
confidence: 0.9
|
|
178
|
+
tags: [architecture, microservices, scaling]
|
|
179
|
+
related: [mem_20260210_b4e5d6]
|
|
180
|
+
source: project-alpha-session
|
|
181
|
+
encoding_context:
|
|
182
|
+
project: project-alpha
|
|
183
|
+
topics: [architecture, scaling, kafka]
|
|
184
|
+
task_type: designing
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
# Chose Event-Driven Architecture for Project Alpha
|
|
188
|
+
|
|
189
|
+
We decided to use event-driven architecture with Kafka instead of synchronous
|
|
190
|
+
REST calls between services, because the traffic analysis showed 10x burst
|
|
191
|
+
patterns that would overwhelm synchronous endpoints.
|
|
192
|
+
|
|
193
|
+
## Context
|
|
194
|
+
|
|
195
|
+
Sprint planning for Q2, evaluating scaling strategy for the notification system.
|
|
196
|
+
|
|
197
|
+
## Key Details
|
|
198
|
+
|
|
199
|
+
- Kafka chosen over RabbitMQ for its replay capability
|
|
200
|
+
- Event schema registry added to prevent breaking changes
|
|
201
|
+
- Estimated 3-week implementation vs 1-week for REST (but REST would need rework at scale)
|
|
202
|
+
|
|
203
|
+
## Connections
|
|
204
|
+
|
|
205
|
+
Related to the capacity planning decision (mem_20260210_b4e5d6) where we
|
|
206
|
+
identified the 10x burst pattern in notification traffic.
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Scoring Formula
|
|
210
|
+
|
|
211
|
+
When recalling memories, each candidate is scored using a 6-factor formula:
|
|
212
|
+
|
|
213
|
+
```
|
|
214
|
+
score = 0.38 * relevance
|
|
215
|
+
+ 0.18 * decayed_strength
|
|
216
|
+
+ 0.08 * recency_bonus
|
|
217
|
+
+ 0.14 * spreading_bonus
|
|
218
|
+
+ 0.14 * context_match
|
|
219
|
+
+ 0.08 * salience
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
- **relevance** (0.38) — How well the memory matches the query
|
|
223
|
+
- **decayed_strength** (0.18) — Base strength after time decay
|
|
224
|
+
- **recency_bonus** (0.08) — Linear bonus that fades over one year
|
|
225
|
+
- **spreading_bonus** (0.14) — Activation received from linked memories in the association graph
|
|
226
|
+
- **context_match** (0.14) — How similar the encoding context is to the current session
|
|
227
|
+
- **salience** (0.08) — Emotional/motivational significance
|
|
228
|
+
|
|
229
|
+
The formula gracefully degrades for v1 memories missing newer fields — weights are renormalized across available terms.
|
|
230
|
+
|
|
231
|
+
The agent then decides the response strategy:
|
|
232
|
+
- **Single strong match** (top score > 0.7) → Return the full memory
|
|
233
|
+
- **Multiple related** (2-5 candidates > 0.4) → Synthesize a consolidated response
|
|
234
|
+
- **Many weak** (>5, all < 0.4) → List candidates for the user to choose
|
|
235
|
+
- **No active matches** → Search the archive, then suggest alternatives
|
|
236
|
+
|
|
237
|
+
### Associative Network
|
|
238
|
+
|
|
239
|
+
Memories are connected via weighted edges in `.brain/associations.json`:
|
|
240
|
+
|
|
241
|
+
```json
|
|
242
|
+
{
|
|
243
|
+
"edges": {
|
|
244
|
+
"mem_20260213_a3f2c1": {
|
|
245
|
+
"mem_20260210_b4e5d6": {
|
|
246
|
+
"weight": 0.45,
|
|
247
|
+
"co_retrievals": 3,
|
|
248
|
+
"last_activated": "2026-02-14T09:00:00Z",
|
|
249
|
+
"origin": "co_retrieval"
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
**Spreading activation**: When you recall memory A, activation spreads along weighted edges to surface related memories B and C — even if they didn't match the query directly. Activation decays by 50% per hop, up to 2 hops deep.
|
|
257
|
+
|
|
258
|
+
**Hebbian learning**: When multiple memories are recalled together, their mutual edge weights are strengthened: `new_weight = min(1.0, weight + 0.10 * (1.0 - weight))`. Memories that fire together wire together.
|
|
259
|
+
|
|
260
|
+
**Link dynamics**: Edges decay over time (`weight * 0.998^days`) and are pruned below 0.05 during sleep. New links are created automatically when memories share 2+ tags (weight 0.10) or are explicitly related (weight 0.20).
|
|
261
|
+
|
|
262
|
+
### Spaced Reinforcement
|
|
263
|
+
|
|
264
|
+
Unlike the flat +0.05 boost per recall in v1, spaced reinforcement rewards optimal recall timing:
|
|
265
|
+
|
|
266
|
+
```
|
|
267
|
+
spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
|
|
268
|
+
diminishingFactor = 1.0 / (1.0 + 0.1 * recallCount)
|
|
269
|
+
boost = 0.05 * spacingMultiplier * diminishingFactor
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
| Scenario | Boost |
|
|
273
|
+
|----------|:---:|
|
|
274
|
+
| 1 day gap, first recall | +0.05 |
|
|
275
|
+
| 7 day gap | +0.08 |
|
|
276
|
+
| 30 day gap | +0.10 |
|
|
277
|
+
| Same day, 20th recall (cramming) | +0.02 |
|
|
278
|
+
|
|
279
|
+
Each recall also improves the memory's decay rate: `new_rate = rate + 0.10 * (0.999 - rate)`. Memories become progressively more forgetting-resistant with each retrieval.
|
|
280
|
+
|
|
281
|
+
### Salience & Confidence
|
|
282
|
+
|
|
283
|
+
**Salience** (0.0-1.0) captures emotional/motivational significance. High-salience memories (>= 0.7) are **never auto-pruned** — they must be explicitly forgotten via `/brain:forget`. They also serve as anchors during consolidation.
|
|
284
|
+
|
|
285
|
+
**Confidence** (0.0-1.0) tracks epistemic certainty. Set at encoding based on source quality, reduced when contradictions are found during Knowledge Propagation (-0.20), boosted during validations (+0.10). Low-confidence memories are flagged during recall.
|
|
286
|
+
|
|
287
|
+
### Consolidation
|
|
288
|
+
|
|
289
|
+
When memories decay below the threshold (default: 0.3), they become candidates for consolidation. The agent groups related weak memories by path proximity, tag overlap, and temporal closeness, then merges them into a single stronger memory:
|
|
290
|
+
|
|
291
|
+
```
|
|
292
|
+
consolidated_strength = max(source_strengths) + 0.15 (capped at 1.0)
|
|
293
|
+
consolidated_decay = min(source_decay_rates) (slowest decay wins)
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
The highest-salience memory in each group serves as the anchor — its framing and key details take priority in the synthesis. Original memories are moved to `_archived/` (recoverable and searchable).
|
|
297
|
+
|
|
298
|
+
### Sleep Cycle
|
|
299
|
+
|
|
300
|
+
`/brain:sleep` is the brain's overnight maintenance — inspired by how human brains reorganize memories during sleep. It runs nine phases:
|
|
301
|
+
|
|
302
|
+
1. **Replay** — Scans all memories and computes current decayed strengths, categorizing into tiers (Strong / Moderate / Weak / Fading)
|
|
303
|
+
2. **Synaptic Homeostasis** — If mean strength exceeds 0.5, proportionally scales down ALL strengths to prevent inflation, then selectively re-boosts high-salience, recently-accessed, and frequently-recalled memories. Based on Tononi & Cirelli's SHY hypothesis.
|
|
304
|
+
3. **Knowledge Propagation** — Evaluates recent memories against the hierarchy (ancestors, descendants, siblings, tag-related, association-linked) and updates existing memories through enrichment, contradiction detection, validation, obsolescence marking, and cross-referencing. Based on memory reconsolidation research.
|
|
305
|
+
4. **Semantic Crystallization** — Finds frequently-recalled episodic memories and extracts generalizable principles into new semantic memories. The event details begin fading but the lesson persists.
|
|
306
|
+
5. **Reorganize** — Detects flat clusters (3+ related memories at the same level) and restructures them into deeper sub-categories automatically
|
|
307
|
+
6. **Consolidate** — Merges weak related memories into stronger combined knowledge with salience anchoring
|
|
308
|
+
7. **Prune** — Archives memories that have faded below 0.1 strength (salience-protected memories are exempt)
|
|
309
|
+
8. **REM Dreaming** — Selects random memories from different categories and discovers creative cross-domain connections via analogical reasoning. Scored by novelty, utility, and surprise.
|
|
310
|
+
9. **Expertise Detection** — Identifies dense knowledge areas and generates expertise profiles, then populates the spaced repetition review queue
|
|
311
|
+
|
|
312
|
+
| Expertise Level | Score | Meaning |
|
|
313
|
+
|-------|:---:|---------|
|
|
314
|
+
| Awareness | 0.2 - 0.4 | Surface familiarity |
|
|
315
|
+
| Working Knowledge | 0.4 - 0.6 | Competent with reference |
|
|
316
|
+
| Deep Knowledge | 0.6 - 0.8 | Strong command, can reason about trade-offs |
|
|
317
|
+
| Expert | 0.8 - 1.0 | Mastery — dense, frequently-recalled, long-standing |
|
|
318
|
+
|
|
319
|
+
Each expertise area gets an `_expertise.md` profile documenting what you know well, knowledge gaps, and contributing memories. Sleep can target a specific subtree (e.g., `/brain:sleep professional/skills`) or process the entire brain.
|
|
320
|
+
|
|
321
|
+
### Spaced Repetition Review
|
|
322
|
+
|
|
323
|
+
`/brain:review` implements the SM-2 algorithm to surface memories at optimal intervals for long-term retention. The review queue is generated during sleep and tracks:
|
|
324
|
+
|
|
325
|
+
- **Interval** — Time until next review (grows exponentially with successful recalls)
|
|
326
|
+
- **Ease factor** — How easily the memory is recalled (adjusts based on recall quality 1-5)
|
|
327
|
+
- **Review count** — Total number of review sessions
|
|
328
|
+
|
|
329
|
+
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.
|
|
330
|
+
|
|
331
|
+
### Migration from v1
|
|
332
|
+
|
|
333
|
+
Existing v1 brains upgrade automatically. The first `/brain:sleep` after upgrade runs a migration phase that:
|
|
334
|
+
- Creates `associations.json` from existing `related` fields
|
|
335
|
+
- Backfills `recall_history` from `access_count`
|
|
336
|
+
- Sets sensible defaults for new fields (`cognitive_type: semantic`, `salience: 0.5`, `confidence: 0.8`)
|
|
337
|
+
- Bumps `index.json` version to 2
|
|
338
|
+
|
|
339
|
+
No data is lost. All new scoring gracefully falls back when newer fields are absent.
|
|
340
|
+
|
|
341
|
+
## File Structure
|
|
342
|
+
|
|
343
|
+
```
|
|
344
|
+
.brain/
|
|
345
|
+
├── index.json # Memory inventory — fast lookup for all memories
|
|
346
|
+
├── associations.json # Weighted associative network between memories
|
|
347
|
+
├── contexts.json # Session context snapshots for context-dependent recall
|
|
348
|
+
├── review-queue.json # Spaced repetition scheduling
|
|
349
|
+
├── professional/ # Work, career, technical skills
|
|
350
|
+
│ ├── _meta.json # Category metadata and stats
|
|
351
|
+
│ ├── _expertise.md # Generated expertise profile
|
|
352
|
+
│ ├── companies/ # On-demand: created when first needed
|
|
353
|
+
│ │ └── <company>/
|
|
354
|
+
│ │ ├── projects/
|
|
355
|
+
│ │ └── decisions/
|
|
356
|
+
│ ├── skills/
|
|
357
|
+
│ └── career/
|
|
358
|
+
├── personal/ # Education, health, hobbies, goals
|
|
359
|
+
│ ├── _meta.json
|
|
360
|
+
│ ├── education/
|
|
361
|
+
│ ├── health/
|
|
362
|
+
│ └── goals/
|
|
363
|
+
├── social/ # Communities, networks, collaborations
|
|
364
|
+
│ ├── _meta.json
|
|
365
|
+
│ └── communities/
|
|
366
|
+
├── family/ # Family relationships and events
|
|
367
|
+
│ ├── _meta.json
|
|
368
|
+
│ └── events/
|
|
369
|
+
├── _consolidated/ # Merged memories from consolidation
|
|
370
|
+
│ └── _meta.json
|
|
371
|
+
└── _archived/ # Decayed memories (recoverable + searchable)
|
|
372
|
+
├── _meta.json
|
|
373
|
+
└── index.json # Searchable archive index
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
Subdirectories are created **on demand** — the agent decides placement depth based on how specific the memory is. A generic career thought lands in `professional/`, but a specific deployment incident goes to `professional/companies/acme/projects/alpha/`.
|
|
377
|
+
|
|
378
|
+
## Configuration
|
|
379
|
+
|
|
380
|
+
Brain configuration lives in `.brain/index.json` under the `config` key:
|
|
381
|
+
|
|
382
|
+
```json
|
|
383
|
+
{
|
|
384
|
+
"config": {
|
|
385
|
+
"max_depth": 6,
|
|
386
|
+
"consolidation_threshold": 0.3,
|
|
387
|
+
"decay_check_interval_days": 7,
|
|
388
|
+
"strength_boost_on_recall": 0.05,
|
|
389
|
+
"auto_consolidate": true,
|
|
390
|
+
"propagation_window_days": 7,
|
|
391
|
+
"association_config": {
|
|
392
|
+
"co_retrieval_boost": 0.10,
|
|
393
|
+
"link_decay_rate": 0.998,
|
|
394
|
+
"link_prune_threshold": 0.05,
|
|
395
|
+
"spreading_activation_depth": 2,
|
|
396
|
+
"spreading_activation_decay": 0.5
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
| Setting | Default | Description |
|
|
403
|
+
|---------|---------|-------------|
|
|
404
|
+
| `max_depth` | 6 | Maximum directory nesting depth |
|
|
405
|
+
| `consolidation_threshold` | 0.3 | Strength below which memories are consolidation candidates |
|
|
406
|
+
| `decay_check_interval_days` | 7 | How often to suggest decay maintenance |
|
|
407
|
+
| `strength_boost_on_recall` | 0.05 | Base strength increase per recall event |
|
|
408
|
+
| `auto_consolidate` | true | Suggest consolidation when candidates are found |
|
|
409
|
+
| `propagation_window_days` | 7 | How far back to look for recent memories during knowledge propagation |
|
|
410
|
+
| `association_config.co_retrieval_boost` | 0.10 | Hebbian reinforcement increment for co-retrieved memories |
|
|
411
|
+
| `association_config.link_decay_rate` | 0.998 | Daily decay factor for association edge weights |
|
|
412
|
+
| `association_config.link_prune_threshold` | 0.05 | Minimum weight before an association link is pruned |
|
|
413
|
+
| `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
|
|
414
|
+
| `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
|
|
415
|
+
|
|
416
|
+
## Project Structure
|
|
417
|
+
|
|
418
|
+
```
|
|
419
|
+
brain/
|
|
420
|
+
├── bin/
|
|
421
|
+
│ └── install.js # Interactive installer (npx brain-memory)
|
|
422
|
+
├── commands/
|
|
423
|
+
│ └── brain/ # Slash command definitions
|
|
424
|
+
│ ├── init.md
|
|
425
|
+
│ ├── memorize.md
|
|
426
|
+
│ ├── remember.md
|
|
427
|
+
│ ├── review.md
|
|
428
|
+
│ ├── explore.md
|
|
429
|
+
│ ├── consolidate.md
|
|
430
|
+
│ ├── forget.md
|
|
431
|
+
│ ├── sunshine.md
|
|
432
|
+
│ ├── sleep.md
|
|
433
|
+
│ └── status.md
|
|
434
|
+
├── prompts/
|
|
435
|
+
│ ├── claude.md # CLAUDE.md content (injected by installer)
|
|
436
|
+
│ ├── gemini.md # GEMINI.md content (injected by installer)
|
|
437
|
+
│ └── openai.md # AGENTS.md content (injected by installer)
|
|
438
|
+
├── hooks/
|
|
439
|
+
│ ├── session-start.md # Ambient memory loading + review notifications
|
|
440
|
+
│ └── session-end.md # Auto-memorize suggestion + context capture
|
|
441
|
+
├── templates/
|
|
442
|
+
│ └── default-categories.json # Default brain category definitions
|
|
443
|
+
├── src/
|
|
444
|
+
│ ├── scorer.js # Decay, spreading activation, context matching, spaced reinforcement
|
|
445
|
+
│ └── index-manager.js # Index, associations, contexts, review queue, archive CRUD
|
|
446
|
+
├── CLAUDE.md # Development guide for this repo
|
|
447
|
+
├── package.json
|
|
448
|
+
└── README.md
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
## Inspired By
|
|
452
|
+
|
|
453
|
+
- [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents
|
|
454
|
+
- [Memory in the Age of AI Agents](https://arxiv.org/abs/2512.13564) — Comprehensive survey on agent memory architectures
|
|
455
|
+
- [Mem0](https://arxiv.org/pdf/2504.19413) — Human-like memory reinforcement and decay
|
|
456
|
+
- [MemOS](https://arxiv.org/pdf/2507.03724) — Memory lifecycle state management
|
|
457
|
+
- [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve) — Exponential memory decay
|
|
458
|
+
- [Spreading activation](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory
|
|
459
|
+
- [Hebbian theory](https://en.wikipedia.org/wiki/Hebbian_theory) — "Neurons that fire together wire together"
|
|
460
|
+
- [Synaptic homeostasis hypothesis](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function
|
|
461
|
+
- [SM-2 algorithm](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — Spaced repetition scheduling
|
|
462
|
+
- [Memory reconsolidation](https://en.wikipedia.org/wiki/Memory_consolidation#Reconsolidation) — How recalling memories makes them temporarily malleable
|
|
463
|
+
|
|
464
|
+
## License
|
|
465
|
+
|
|
466
|
+
MIT
|