brain-memory 0.1.0-beta.1 → 0.1.0-beta.10

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 CHANGED
@@ -1,13 +1,21 @@
1
- # Brain Memory
1
+ <p align="center">
2
+ <img src="assets/icon.png" alt="Brain Memory" width="128" height="128">
3
+ </p>
2
4
 
3
- [![CI](https://github.com/onurkarali/brain/actions/workflows/ci.yml/badge.svg)](https://github.com/onurkarali/brain/actions/workflows/ci.yml)
5
+ <h1 align="center">Brain Memory</h1>
6
+
7
+ <p align="center">
8
+ <a href="https://github.com/onurkarali/brain/actions/workflows/ci.yml"><img src="https://github.com/onurkarali/brain/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
9
+ <a href="https://www.npmjs.com/package/brain-memory"><img src="https://img.shields.io/npm/v/brain-memory" alt="npm version"></a>
10
+ <a href="https://github.com/onurkarali/brain/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/brain-memory" alt="license"></a>
11
+ </p>
4
12
 
5
13
  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
14
 
7
15
  Works with **Claude Code**, **Gemini CLI**, and **OpenAI Codex CLI**.
8
16
 
9
17
  ```
10
- .brain/
18
+ ~/.brain/
11
19
  ├── professional/
12
20
  │ └── companies/
13
21
  │ └── acme-corp/
@@ -43,7 +51,7 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
43
51
  ## Install
44
52
 
45
53
  ```bash
46
- npx brain-memory
54
+ npx brain-memory@beta
47
55
  ```
48
56
 
49
57
  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.
@@ -57,6 +65,22 @@ npx brain-memory --codex --global # OpenAI Codex CLI, global
57
65
  npx brain-memory --all --global # All runtimes, global
58
66
  ```
59
67
 
68
+ ### Update
69
+
70
+ ```bash
71
+ npx brain-memory@beta update
72
+ ```
73
+
74
+ Auto-detects installed runtimes and refreshes commands + prompt sections. Target specific runtimes with `--claude`, `--gemini`, `--openai`, or `--all`.
75
+
76
+ ### Uninstall
77
+
78
+ ```bash
79
+ npx brain-memory@beta uninstall
80
+ ```
81
+
82
+ Removes commands and prompt sections. Your `~/.brain/` directory (memories) is preserved by default. Add `--delete-data` to remove it too. Use `--yes` to skip confirmation prompts.
83
+
60
84
  ### Manual Install
61
85
 
62
86
  Copy the `commands/brain/` directory to your agent's commands folder:
@@ -85,7 +109,7 @@ Then append the contents of the corresponding prompt file to your agent's instru
85
109
 
86
110
  | Command | Description |
87
111
  |---------|-------------|
88
- | `/brain:init` | Initialize `.brain/` directory structure with default categories |
112
+ | `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
89
113
  | `/brain:memorize [topic]` | Store memories from current session context |
90
114
  | `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
91
115
  | `/brain:review [scope]` | Spaced repetition review session for due memories |
@@ -95,6 +119,38 @@ Then append the contents of the corresponding prompt file to your agent's instru
95
119
  | `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
96
120
  | `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
97
121
  | `/brain:status` | Dashboard with brain health metrics and recommendations |
122
+ | `/brain:sync [subcommand]` | Sync memories via Git remote or export/import for portability |
123
+
124
+ ## Session Lifecycle
125
+
126
+ Brain Memory works automatically in the background — no commands needed for basic context awareness.
127
+
128
+ ### Session Start
129
+
130
+ When a session begins and `~/.brain/` exists, the agent automatically:
131
+
132
+ 1. Reads the brain index and loads the top 3-5 memories relevant to the current project
133
+ 2. Checks the review queue for memories due for spaced repetition
134
+ 3. Outputs a brief status line:
135
+
136
+ ```
137
+ 🧠 Brain active — 42 memories loaded (8 in current project context)
138
+ 📋 3 memories due for review — run /brain:review
139
+ ```
140
+
141
+ The agent silently internalizes relevant memories and references them naturally during the session — no information dump.
142
+
143
+ ### Session End
144
+
145
+ When a session ends, the agent evaluates whether significant decisions, learnings, insights, or experiences occurred. If so, it suggests:
146
+
147
+ ```
148
+ 💡 This session contained notable decisions and learnings.
149
+ Would you like to store them as brain memories?
150
+ Run /brain:memorize to capture them before this context is lost.
151
+ ```
152
+
153
+ The agent never auto-memorizes without user consent. Session context is always saved to `~/.brain/contexts.json` for context-dependent recall.
98
154
 
99
155
  ## How It Works
100
156
 
@@ -117,7 +173,7 @@ Create → Store → Decay → Recall → Reinforce → Review → Sleep → Arc
117
173
 
118
174
  ### Neuroscience Foundations
119
175
 
120
- Brain Memory v2 is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:
176
+ Brain Memory is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:
121
177
 
122
178
  | Brain Mechanism | Implementation |
123
179
  |-----------------|---------------|
@@ -226,8 +282,6 @@ score = 0.38 * relevance
226
282
  - **context_match** (0.14) — How similar the encoding context is to the current session
227
283
  - **salience** (0.08) — Emotional/motivational significance
228
284
 
229
- The formula gracefully degrades for v1 memories missing newer fields — weights are renormalized across available terms.
230
-
231
285
  The agent then decides the response strategy:
232
286
  - **Single strong match** (top score > 0.7) → Return the full memory
233
287
  - **Multiple related** (2-5 candidates > 0.4) → Synthesize a consolidated response
@@ -236,7 +290,7 @@ The agent then decides the response strategy:
236
290
 
237
291
  ### Associative Network
238
292
 
239
- Memories are connected via weighted edges in `.brain/associations.json`:
293
+ Memories are connected via weighted edges in `~/.brain/associations.json`:
240
294
 
241
295
  ```json
242
296
  {
@@ -261,7 +315,7 @@ Memories are connected via weighted edges in `.brain/associations.json`:
261
315
 
262
316
  ### Spaced Reinforcement
263
317
 
264
- Unlike the flat +0.05 boost per recall in v1, spaced reinforcement rewards optimal recall timing:
318
+ Spaced reinforcement rewards optimal recall timing:
265
319
 
266
320
  ```
267
321
  spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
@@ -328,20 +382,39 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
328
382
 
329
383
  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
384
 
331
- ### Migration from v1
385
+ ### Cross-Agent Memory Sharing
386
+
387
+ `~/.brain/` is a single global directory in the user's home folder. All memories are shared across every project and every supported agent automatically. A decision stored by Claude Code in one project is immediately available to Gemini CLI or Codex CLI in any other project — no configuration, no export, no per-project setup. The format is agent-agnostic: plain Markdown files with YAML frontmatter, readable by any tool.
388
+
389
+ To share memories across different machines, use `/brain:sync` (see below).
390
+
391
+ ### Portable Sync
392
+
393
+ `/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
332
394
 
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
395
+ **Git remote** — Push/pull `~/.brain/` to any private Git repository. Works with GitHub, GitLab, Codeberg, or any self-hosted Git server. Uses your existing Git/SSH authentication — no additional credentials needed.
338
396
 
339
- No data is lost. All new scoring gracefully falls back when newer fields are absent.
397
+ **Export/Import** — Pack the entire `~/.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
398
+
399
+ **Key features:**
400
+ - **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
401
+ - **Optional encryption** — AES-256-GCM encryption with a user-provided passphrase. When enabled, all files are encrypted before committing or exporting.
402
+ - **Merge mode** — Import supports merge mode (only import newer files) or overwrite mode.
403
+ - **Zero dependencies** — Uses Node.js built-in `crypto` and the system `git` binary.
404
+
405
+ **Setup:**
406
+ 1. Create a private Git repo (e.g., `gh repo create brain-data --private`)
407
+ 2. Run `/brain:sync setup git@github.com:you/brain-data.git`
408
+ 3. Use `/brain:sync push` and `/brain:sync pull` to keep memories in sync
409
+
410
+ For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
411
+
412
+ Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
340
413
 
341
414
  ## File Structure
342
415
 
343
416
  ```
344
- .brain/
417
+ ~/.brain/
345
418
  ├── index.json # Memory inventory — fast lookup for all memories
346
419
  ├── associations.json # Weighted associative network between memories
347
420
  ├── contexts.json # Session context snapshots for context-dependent recall
@@ -368,16 +441,19 @@ No data is lost. All new scoring gracefully falls back when newer fields are abs
368
441
  │ └── events/
369
442
  ├── _consolidated/ # Merged memories from consolidation
370
443
  │ └── _meta.json
371
- └── _archived/ # Decayed memories (recoverable + searchable)
372
- ├── _meta.json
373
- └── index.json # Searchable archive index
444
+ ├── _archived/ # Decayed memories (recoverable + searchable)
445
+ │ ├── _meta.json
446
+ │ └── index.json # Searchable archive index
447
+ └── .sync/ # Sync state (local only, never pushed)
448
+ ├── config.json # Remote URL, encryption flag
449
+ └── repo/ # Hidden git repo for sync
374
450
  ```
375
451
 
376
452
  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
453
 
378
454
  ## Configuration
379
455
 
380
- Brain configuration lives in `.brain/index.json` under the `config` key:
456
+ Brain configuration lives in `~/.brain/index.json` under the `config` key:
381
457
 
382
458
  ```json
383
459
  {
@@ -413,40 +489,50 @@ Brain configuration lives in `.brain/index.json` under the `config` key:
413
489
  | `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
414
490
  | `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
415
491
 
416
- ## Project Structure
492
+ ## Benchmark
417
493
 
494
+ Empirical benchmarks show that agents with Brain Memory produce **more consistent** and **more successful** outputs across sessions.
495
+
496
+ | Scenario | What it tests | Consistency Improvement | Success Improvement |
497
+ |----------|---------------|:---:|:---:|
498
+ | Multi-Session Continuity | Decisions carry from Session 1 → Session 2 | **+26.2%** | 0% |
499
+ | Cross-Agent Consistency | All agents follow memorized style guide | 0% | 0% |
500
+ | Accumulated Knowledge | 5 sessions of learning → better Session 6 | **+7.3%** | 0% |
501
+ | Error Pattern Learning | Past debugging → faster fix | **+4.8%** | 0% |
502
+ | Preference Retention | Preferences applied without re-stating | **+34.7%** | **+33.3%** |
503
+
504
+ **Per-agent consistency gains (Scenario 1 — Continuity):**
505
+
506
+ | Agent | With Brain | Without Brain | Improvement |
507
+ |-------|:---:|:---:|:---:|
508
+ | Claude Code | 0.944 | 0.645 | +46.4% |
509
+ | Gemini CLI | 0.822 | 0.555 | +48.1% |
510
+ | Codex CLI | 0.767 | 0.545 | +40.7% |
511
+
512
+ **Preference retention (Scenario 5) — the strongest result:**
513
+
514
+ | Agent | With Brain | Without Brain | Notes |
515
+ |-------|:---:|:---:|:---|
516
+ | Claude Code | 0.866 / PASS | 0.359 / **FAIL** | Brain prevented failure |
517
+ | Gemini CLI | 0.800 / PASS | 0.534 / PASS | +49.8% consistency |
518
+ | Codex CLI | 0.934 / PASS | 0.666 / PASS | +40.2% consistency |
519
+
520
+ > Average across 5 scenarios: **+18.3% consistency**, **+33.3% success improvement**. Agents with Brain Memory use more tokens (memory context is injected as prompt), but the consistency and reliability gains justify the cost. In the preference scenario, Claude Code without Brain Memory failed entirely — with Brain Memory, it passed every run.
521
+
522
+ Run the benchmarks yourself:
523
+
524
+ ```bash
525
+ cd benchmark
526
+ cp .env.example .env # Add your API keys
527
+ npm test # Unit tests
528
+ node harness/runner.js # Full benchmark (cloud APIs)
418
529
  ```
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
- ```
530
+
531
+ Full methodology, per-scenario breakdowns, and raw data: [`benchmark/`](benchmark/) | [Detailed Report](benchmark/results/REPORT.md)
532
+
533
+ ## Contributing
534
+
535
+ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
450
536
 
451
537
  ## Inspired By
452
538
 
Binary file