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 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
+ [![CI](https://github.com/onurkarali/brain/actions/workflows/ci.yml/badge.svg)](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