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 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,56 @@ 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
+ ### Ambient Session Tracking
144
+
145
+ Throughout the session, the agent maintains a running mental log of notable events — decisions made, things learned, insights realized, significant experiences. This is purely internal awareness with no file writes. It ensures that early-session events aren't forgotten by the time the session ends.
146
+
147
+ ### Periodic Memory Checkpoint
148
+
149
+ Every ~10 substantive interactions (file edits, architecture decisions, debugging breakthroughs), the agent evaluates whether memorizable content has accumulated. If so, it appends a brief reminder to its next response:
150
+
151
+ ```
152
+ 🧠 Notable decisions and learnings this session — /brain:memorize when ready
153
+ ```
154
+
155
+ This never interrupts your flow — it's a one-liner appended to an existing response, at most once per ~10 interactions. The counter resets after you run `/brain:memorize`.
156
+
157
+ ### Session End
158
+
159
+ When a session ends, the agent performs two steps in order:
160
+
161
+ 1. **Saves session context** to `~/.brain/contexts.json` — always, even for trivial sessions. This includes a `notable_unsaved` field listing items you didn't memorize, so future sessions can reference what happened.
162
+
163
+ 2. **Suggests memorization** if the session contained meaningful decisions, learnings, or insights:
164
+
165
+ ```
166
+ 💡 This session contained notable decisions and learnings.
167
+ Would you like to store them as brain memories?
168
+ Run /brain:memorize to capture them before this context is lost.
169
+ ```
170
+
171
+ The agent never auto-memorizes without user consent. Context is saved proactively — the agent doesn't wait for an explicit goodbye signal.
98
172
 
99
173
  ## How It Works
100
174
 
@@ -117,7 +191,7 @@ Create → Store → Decay → Recall → Reinforce → Review → Sleep → Arc
117
191
 
118
192
  ### Neuroscience Foundations
119
193
 
120
- Brain Memory v2 is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:
194
+ Brain Memory is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:
121
195
 
122
196
  | Brain Mechanism | Implementation |
123
197
  |-----------------|---------------|
@@ -226,8 +300,6 @@ score = 0.38 * relevance
226
300
  - **context_match** (0.14) — How similar the encoding context is to the current session
227
301
  - **salience** (0.08) — Emotional/motivational significance
228
302
 
229
- The formula gracefully degrades for v1 memories missing newer fields — weights are renormalized across available terms.
230
-
231
303
  The agent then decides the response strategy:
232
304
  - **Single strong match** (top score > 0.7) → Return the full memory
233
305
  - **Multiple related** (2-5 candidates > 0.4) → Synthesize a consolidated response
@@ -236,7 +308,7 @@ The agent then decides the response strategy:
236
308
 
237
309
  ### Associative Network
238
310
 
239
- Memories are connected via weighted edges in `.brain/associations.json`:
311
+ Memories are connected via weighted edges in `~/.brain/associations.json`:
240
312
 
241
313
  ```json
242
314
  {
@@ -261,7 +333,7 @@ Memories are connected via weighted edges in `.brain/associations.json`:
261
333
 
262
334
  ### Spaced Reinforcement
263
335
 
264
- Unlike the flat +0.05 boost per recall in v1, spaced reinforcement rewards optimal recall timing:
336
+ Spaced reinforcement rewards optimal recall timing:
265
337
 
266
338
  ```
267
339
  spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
@@ -328,20 +400,39 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
328
400
 
329
401
  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
402
 
331
- ### Migration from v1
403
+ ### Cross-Agent Memory Sharing
404
+
405
+ `~/.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.
406
+
407
+ To share memories across different machines, use `/brain:sync` (see below).
408
+
409
+ ### Portable Sync
410
+
411
+ `/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
412
+
413
+ **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.
414
+
415
+ **Export/Import** — Pack the entire `~/.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
416
+
417
+ **Key features:**
418
+ - **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
419
+ - **Optional encryption** — AES-256-GCM encryption with a user-provided passphrase. When enabled, all files are encrypted before committing or exporting.
420
+ - **Merge mode** — Import supports merge mode (only import newer files) or overwrite mode.
421
+ - **Zero dependencies** — Uses Node.js built-in `crypto` and the system `git` binary.
422
+
423
+ **Setup:**
424
+ 1. Create a private Git repo (e.g., `gh repo create brain-data --private`)
425
+ 2. Run `/brain:sync setup git@github.com:you/brain-data.git`
426
+ 3. Use `/brain:sync push` and `/brain:sync pull` to keep memories in sync
332
427
 
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
428
+ For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
338
429
 
339
- No data is lost. All new scoring gracefully falls back when newer fields are absent.
430
+ Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
340
431
 
341
432
  ## File Structure
342
433
 
343
434
  ```
344
- .brain/
435
+ ~/.brain/
345
436
  ├── index.json # Memory inventory — fast lookup for all memories
346
437
  ├── associations.json # Weighted associative network between memories
347
438
  ├── contexts.json # Session context snapshots for context-dependent recall
@@ -368,16 +459,19 @@ No data is lost. All new scoring gracefully falls back when newer fields are abs
368
459
  │ └── events/
369
460
  ├── _consolidated/ # Merged memories from consolidation
370
461
  │ └── _meta.json
371
- └── _archived/ # Decayed memories (recoverable + searchable)
372
- ├── _meta.json
373
- └── index.json # Searchable archive index
462
+ ├── _archived/ # Decayed memories (recoverable + searchable)
463
+ │ ├── _meta.json
464
+ │ └── index.json # Searchable archive index
465
+ └── .sync/ # Sync state (local only, never pushed)
466
+ ├── config.json # Remote URL, encryption flag
467
+ └── repo/ # Hidden git repo for sync
374
468
  ```
375
469
 
376
470
  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
471
 
378
472
  ## Configuration
379
473
 
380
- Brain configuration lives in `.brain/index.json` under the `config` key:
474
+ Brain configuration lives in `~/.brain/index.json` under the `config` key:
381
475
 
382
476
  ```json
383
477
  {
@@ -413,40 +507,50 @@ Brain configuration lives in `.brain/index.json` under the `config` key:
413
507
  | `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
414
508
  | `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
415
509
 
416
- ## Project Structure
510
+ ## Benchmark
417
511
 
512
+ Empirical benchmarks show that agents with Brain Memory produce **more consistent** and **more successful** outputs across sessions.
513
+
514
+ | Scenario | What it tests | Consistency Improvement | Success Improvement |
515
+ |----------|---------------|:---:|:---:|
516
+ | Multi-Session Continuity | Decisions carry from Session 1 → Session 2 | **+26.2%** | 0% |
517
+ | Cross-Agent Consistency | All agents follow memorized style guide | 0% | 0% |
518
+ | Accumulated Knowledge | 5 sessions of learning → better Session 6 | **+7.3%** | 0% |
519
+ | Error Pattern Learning | Past debugging → faster fix | **+4.8%** | 0% |
520
+ | Preference Retention | Preferences applied without re-stating | **+34.7%** | **+33.3%** |
521
+
522
+ **Per-agent consistency gains (Scenario 1 — Continuity):**
523
+
524
+ | Agent | With Brain | Without Brain | Improvement |
525
+ |-------|:---:|:---:|:---:|
526
+ | Claude Code | 0.944 | 0.645 | +46.4% |
527
+ | Gemini CLI | 0.822 | 0.555 | +48.1% |
528
+ | Codex CLI | 0.767 | 0.545 | +40.7% |
529
+
530
+ **Preference retention (Scenario 5) — the strongest result:**
531
+
532
+ | Agent | With Brain | Without Brain | Notes |
533
+ |-------|:---:|:---:|:---|
534
+ | Claude Code | 0.866 / PASS | 0.359 / **FAIL** | Brain prevented failure |
535
+ | Gemini CLI | 0.800 / PASS | 0.534 / PASS | +49.8% consistency |
536
+ | Codex CLI | 0.934 / PASS | 0.666 / PASS | +40.2% consistency |
537
+
538
+ > 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.
539
+
540
+ Run the benchmarks yourself:
541
+
542
+ ```bash
543
+ cd benchmark
544
+ cp .env.example .env # Add your API keys
545
+ npm test # Unit tests
546
+ node harness/runner.js # Full benchmark (cloud APIs)
418
547
  ```
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
- ```
548
+
549
+ Full methodology, per-scenario breakdowns, and raw data: [`benchmark/`](benchmark/) | [Detailed Report](benchmark/results/REPORT.md)
550
+
551
+ ## Contributing
552
+
553
+ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
450
554
 
451
555
  ## Inspired By
452
556
 
Binary file