brain-memory 0.1.0-beta.2 → 0.1.0-beta.21
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 +272 -72
- package/assets/icon.png +0 -0
- package/assets/icon.svg +27 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +149 -0
- package/bin/install.js +217 -242
- package/bin/memorize.js +436 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +237 -0
- package/bin/reinforce.js +187 -0
- package/bin/session-start.js +292 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/consolidate.md +7 -2
- package/commands/brain/explore.md +7 -2
- package/commands/brain/forget.md +7 -2
- package/commands/brain/init.md +8 -12
- package/commands/brain/memorize.md +76 -144
- package/commands/brain/pin.md +37 -0
- package/commands/brain/remember.md +48 -105
- package/commands/brain/review.md +7 -2
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +68 -27
- package/commands/brain/status.md +19 -5
- package/commands/brain/sunshine.md +18 -13
- package/commands/brain/sync.md +360 -0
- package/commands/brain/unpin.md +26 -0
- package/package.json +18 -8
- package/prompts/claude.md +115 -12
- package/prompts/gemini.md +115 -12
- package/prompts/openai.md +113 -10
- package/prompts/opencode.md +178 -0
- package/src/cloud-sync.js +534 -0
- package/src/crypto.js +130 -0
- package/src/export-import.js +200 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +205 -18
- package/src/installer.js +384 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +8 -2
- package/src/skills.js +208 -0
- package/src/tfidf.js +408 -0
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
package/README.md
CHANGED
|
@@ -1,13 +1,21 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/icon.png" alt="Brain Memory" width="128" height="128">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">Brain Memory</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://github.com/omelas-tech/brain/actions/workflows/ci.yml"><img src="https://github.com/omelas-tech/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/omelas-tech/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
|
-
Works with **Claude Code**, **Gemini CLI**,
|
|
15
|
+
Works with **Claude Code**, **Gemini CLI**, **OpenAI Codex CLI**, and **OpenCode**.
|
|
8
16
|
|
|
9
17
|
```
|
|
10
|
-
|
|
18
|
+
~/.brain/
|
|
11
19
|
├── professional/
|
|
12
20
|
│ └── companies/
|
|
13
21
|
│ └── acme-corp/
|
|
@@ -36,6 +44,8 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
|
|
|
36
44
|
- **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
|
|
37
45
|
- **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
|
|
38
46
|
- **Cognitive types** — Episodic, semantic, and procedural memories each decay differently, just like in the brain
|
|
47
|
+
- **Always-present knowledge** — Pin critical conventions and preferences so they load every session, bypassing recall and never decaying — the facts your agent must never miss
|
|
48
|
+
- **Procedural skills** — Reusable how-to workflows with progressive disclosure, learned automatically from repeated experience and exportable to your agent's native skills
|
|
39
49
|
- **On-demand depth** — Subcategories are created as needed, not pre-defined
|
|
40
50
|
- **Consolidation** — Weak related memories merge into stronger combined knowledge
|
|
41
51
|
- **Zero dependencies** — Pure file I/O, no databases, no servers, no embeddings required
|
|
@@ -43,20 +53,46 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
|
|
|
43
53
|
## Install
|
|
44
54
|
|
|
45
55
|
```bash
|
|
46
|
-
|
|
56
|
+
npm install -g brain-memory@beta
|
|
57
|
+
brain
|
|
47
58
|
```
|
|
48
59
|
|
|
49
|
-
The
|
|
60
|
+
The first command installs the package globally — this gives you both the interactive setup wizard and the `brain` CLI (`brain recall`, `brain memorize`, `brain reinforce`, …) that agents rely on for deterministic scoring.
|
|
61
|
+
|
|
62
|
+
The second command runs the setup wizard, which 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
63
|
|
|
51
64
|
### Non-interactive
|
|
52
65
|
|
|
53
66
|
```bash
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
67
|
+
brain --claude --global # Claude Code, global
|
|
68
|
+
brain --gemini --local # Gemini CLI, local project
|
|
69
|
+
brain --codex --global # OpenAI Codex CLI, global
|
|
70
|
+
brain --opencode --global # OpenCode, global
|
|
71
|
+
brain --all --global # All runtimes, global
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Update
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npm install -g brain-memory@beta
|
|
78
|
+
brain update
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The first command updates the package and the `brain` CLI. The second command refreshes the slash command prompts for your installed runtimes. Target specific runtimes with `--claude`, `--gemini`, `--openai`, or `--all`.
|
|
82
|
+
|
|
83
|
+
> **Upgrading from an older version?** The separate binaries (`brain-recall`, `brain-memorize`, `brain-reinforce`, `brain-cloud`, `brain-memory`) were unified into a single `brain` dispatcher — use `brain recall`, `brain memorize`, `brain reinforce`, `brain cloud <…>` instead. Run `brain update` to refresh your runtime prompts to the new command surface.
|
|
84
|
+
|
|
85
|
+
> **Why not `npx`?** `npx` runs the setup wizard in a temporary directory that is discarded after execution. The `brain` CLI (`brain recall`, `brain memorize`, `brain reinforce`) won't be available in your PATH, which means agents will fall back to less reliable manual file operations. Always use `npm install -g` to ensure everything works correctly.
|
|
86
|
+
|
|
87
|
+
### Uninstall
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
brain uninstall
|
|
91
|
+
npm uninstall -g brain-memory
|
|
58
92
|
```
|
|
59
93
|
|
|
94
|
+
The first command removes slash commands and prompt sections from your agent configs. The second removes the package and CLI tools. Your `~/.brain/` directory (memories) is preserved by default. Add `--delete-data` to the uninstall command to remove it too. Use `--yes` to skip confirmation prompts.
|
|
95
|
+
|
|
60
96
|
### Manual Install
|
|
61
97
|
|
|
62
98
|
Copy the `commands/brain/` directory to your agent's commands folder:
|
|
@@ -85,9 +121,11 @@ Then append the contents of the corresponding prompt file to your agent's instru
|
|
|
85
121
|
|
|
86
122
|
| Command | Description |
|
|
87
123
|
|---------|-------------|
|
|
88
|
-
| `/brain:init` | Initialize
|
|
89
|
-
| `/brain:memorize [topic]` | Store memories from current session context |
|
|
124
|
+
| `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
|
|
125
|
+
| `/brain:memorize [topic] [--sync]` | Store memories from current session context (add `--sync` to auto-push) |
|
|
90
126
|
| `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
|
|
127
|
+
| `/brain:pin [id\|query]` | Pin a memory to the always-present tier — loads every session, never decays |
|
|
128
|
+
| `/brain:unpin [id\|query]` | Remove a memory from the always-present tier |
|
|
91
129
|
| `/brain:review [scope]` | Spaced repetition review session for due memories |
|
|
92
130
|
| `/brain:explore [category]` | Browse the brain hierarchy with visual tree view |
|
|
93
131
|
| `/brain:consolidate [scope]` | Merge related weak memories into stronger combined ones |
|
|
@@ -95,6 +133,58 @@ Then append the contents of the corresponding prompt file to your agent's instru
|
|
|
95
133
|
| `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
|
|
96
134
|
| `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
|
|
97
135
|
| `/brain:status` | Dashboard with brain health metrics and recommendations |
|
|
136
|
+
| `/brain:skills [list\|show\|add\|use\|remove\|export]` | Manage procedural skills — reusable how-to workflows with progressive disclosure |
|
|
137
|
+
| `/brain:sync [subcommand]` | Sync memories via Git remote or export/import for portability |
|
|
138
|
+
|
|
139
|
+
## Session Lifecycle
|
|
140
|
+
|
|
141
|
+
Brain Memory works automatically in the background — no commands needed for basic context awareness.
|
|
142
|
+
|
|
143
|
+
### Session Start
|
|
144
|
+
|
|
145
|
+
When a session begins and `~/.brain/` exists, the agent makes a single `brain session-start` call. This aggregator returns one deterministic, **token-budget-bounded** payload so the brain can never bloat the context window (the budget lives in `~/.brain/config.json`):
|
|
146
|
+
|
|
147
|
+
1. **Pinned memories** — always-present conventions and preferences, injected verbatim regardless of recall score
|
|
148
|
+
2. **Skills index** — the name + description of each available procedural skill (~100 tokens each; full instructions are loaded only when a task matches)
|
|
149
|
+
3. **Context recall** — the top memories relevant to the current project
|
|
150
|
+
4. **Review queue + low-confidence alerts**, then a brief status line:
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
🧠 Brain active — 42 memories loaded (8 in current project context)
|
|
154
|
+
📋 3 memories due for review — run /brain:review
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The agent treats pinned facts as active constraints, notes which skills exist, silently internalizes relevant memories, and references them naturally during the session — no information dump.
|
|
158
|
+
|
|
159
|
+
### Ambient Session Tracking
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
### Periodic Memory Checkpoint
|
|
164
|
+
|
|
165
|
+
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:
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
🧠 Notable decisions and learnings this session — /brain:memorize when ready
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
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`.
|
|
172
|
+
|
|
173
|
+
### Session End
|
|
174
|
+
|
|
175
|
+
When a session ends, the agent performs two steps in order:
|
|
176
|
+
|
|
177
|
+
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.
|
|
178
|
+
|
|
179
|
+
2. **Suggests memorization** if the session contained meaningful decisions, learnings, or insights:
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
💡 This session contained notable decisions and learnings.
|
|
183
|
+
Would you like to store them as brain memories?
|
|
184
|
+
Run /brain:memorize to capture them before this context is lost.
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The agent never auto-memorizes without user consent. Context is saved proactively — the agent doesn't wait for an explicit goodbye signal.
|
|
98
188
|
|
|
99
189
|
## How It Works
|
|
100
190
|
|
|
@@ -117,7 +207,7 @@ Create → Store → Decay → Recall → Reinforce → Review → Sleep → Arc
|
|
|
117
207
|
|
|
118
208
|
### Neuroscience Foundations
|
|
119
209
|
|
|
120
|
-
Brain Memory
|
|
210
|
+
Brain Memory is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:
|
|
121
211
|
|
|
122
212
|
| Brain Mechanism | Implementation |
|
|
123
213
|
|-----------------|---------------|
|
|
@@ -158,6 +248,38 @@ Each memory is also classified by how the brain processes it:
|
|
|
158
248
|
|
|
159
249
|
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
250
|
|
|
251
|
+
### Always-Present Memories (Pinning)
|
|
252
|
+
|
|
253
|
+
Recall is probabilistic — a stored preference only applies if scoring happens to surface it. For the facts an agent must **never** miss (coding conventions, standing decisions, hard constraints), that's not good enough. Pinning fixes it:
|
|
254
|
+
|
|
255
|
+
- **`pinned`** — the memory is injected at **every** session start regardless of recall score, and is **decay-exempt** (it never fades). Scope it `global` (loads everywhere) or `project:<name>` (loads only in that project).
|
|
256
|
+
- **`stable`** — an independent flag that exempts a memory from decay and pruning **without** forcing it to always load — for timeless facts you recall on demand but don't want to fade.
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
brain pin <id> --scope global --priority 1 # or: /brain:pin always use tabs
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Pinned and stable memories are skipped by sleep-cycle homeostasis and pruning, and `/brain:memorize` proactively proposes pinning durable conventions. The always-present set is budget-capped (`pin_budget_tokens`) so it can't crowd out the context window. This maps cleanly to the **semantic memory** type in the [CoALA](https://arxiv.org/abs/2309.02427) agent-memory model — knowledge that is always in context — decomposed into two orthogonal properties (always-loaded vs. non-decaying).
|
|
263
|
+
|
|
264
|
+
### Procedural Skills
|
|
265
|
+
|
|
266
|
+
Procedural memory is *how* to do things — reusable, step-by-step workflows stored as `~/.brain/_skills/<name>/SKILL.md`. To keep them from flooding the context window, skills use **three-level progressive disclosure**:
|
|
267
|
+
|
|
268
|
+
| Level | When | What loads |
|
|
269
|
+
|-------|------|------------|
|
|
270
|
+
| **L0** | Every session start | Only each skill's name + description (~100 tokens) |
|
|
271
|
+
| **L1** | A task matches a skill | The full `SKILL.md` step-by-step instructions |
|
|
272
|
+
| **L2** | A step needs them | Referenced `resources/` (templates, scripts) |
|
|
273
|
+
|
|
274
|
+
```bash
|
|
275
|
+
brain skill list # advertised skills (L0)
|
|
276
|
+
brain skill show structured-code-review # full instructions (L1)
|
|
277
|
+
brain skill use structured-code-review # record outcome (--failed weakens it)
|
|
278
|
+
brain skill export structured-code-review --target claude # → native .claude/skills/
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Skills strengthen on successful `use` and weaken on `--failed` — one that fails too often demotes itself out of the advertised L0 index. And they aren't only hand-authored: during sleep, Brain **crystallizes** recurring task-solving patterns from repeated experience into new skills (user-confirmed). Finally, `brain skill export` emits a skill in your agent's **native** format so it becomes directly executable.
|
|
282
|
+
|
|
161
283
|
### Memory File Format
|
|
162
284
|
|
|
163
285
|
Each memory is a Markdown file with YAML frontmatter:
|
|
@@ -226,8 +348,6 @@ score = 0.38 * relevance
|
|
|
226
348
|
- **context_match** (0.14) — How similar the encoding context is to the current session
|
|
227
349
|
- **salience** (0.08) — Emotional/motivational significance
|
|
228
350
|
|
|
229
|
-
The formula gracefully degrades for v1 memories missing newer fields — weights are renormalized across available terms.
|
|
230
|
-
|
|
231
351
|
The agent then decides the response strategy:
|
|
232
352
|
- **Single strong match** (top score > 0.7) → Return the full memory
|
|
233
353
|
- **Multiple related** (2-5 candidates > 0.4) → Synthesize a consolidated response
|
|
@@ -236,7 +356,7 @@ The agent then decides the response strategy:
|
|
|
236
356
|
|
|
237
357
|
### Associative Network
|
|
238
358
|
|
|
239
|
-
Memories are connected via weighted edges in
|
|
359
|
+
Memories are connected via weighted edges in `~/.brain/associations.json`:
|
|
240
360
|
|
|
241
361
|
```json
|
|
242
362
|
{
|
|
@@ -261,7 +381,7 @@ Memories are connected via weighted edges in `.brain/associations.json`:
|
|
|
261
381
|
|
|
262
382
|
### Spaced Reinforcement
|
|
263
383
|
|
|
264
|
-
|
|
384
|
+
Spaced reinforcement rewards optimal recall timing:
|
|
265
385
|
|
|
266
386
|
```
|
|
267
387
|
spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
|
|
@@ -328,24 +448,52 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
|
|
|
328
448
|
|
|
329
449
|
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
450
|
|
|
331
|
-
###
|
|
451
|
+
### Cross-Agent Memory Sharing
|
|
452
|
+
|
|
453
|
+
`~/.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, OpenAI Codex CLI, or OpenCode 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.
|
|
454
|
+
|
|
455
|
+
Brain Memory is **model-agnostic** as well as agent-portable: because memory is plain files rather than embeddings welded to a particular model, the LLM underneath your agent can be anything — GPT, Claude, Gemini, or any model routed through a gateway — and your memory is unaffected. **Switch your model or switch your agent, and you keep remembering and pick up exactly where you left off.**
|
|
456
|
+
|
|
457
|
+
To share memories across different machines, use `/brain:sync` (see below).
|
|
458
|
+
|
|
459
|
+
### Portable Sync
|
|
460
|
+
|
|
461
|
+
`/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
|
|
462
|
+
|
|
463
|
+
**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.
|
|
332
464
|
|
|
333
|
-
|
|
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
|
|
465
|
+
**Export/Import** — Pack the entire `~/.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
|
|
338
466
|
|
|
339
|
-
|
|
467
|
+
**Key features:**
|
|
468
|
+
- **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
|
|
469
|
+
- **Optional encryption** — AES-256-GCM encryption with a user-provided passphrase. When enabled, all files are encrypted before committing or exporting.
|
|
470
|
+
- **Merge mode** — Import supports merge mode (only import newer files) or overwrite mode.
|
|
471
|
+
- **Zero dependencies** — Uses Node.js built-in `crypto` and the system `git` binary.
|
|
472
|
+
|
|
473
|
+
**Setup:**
|
|
474
|
+
1. Create a private Git repo (e.g., `gh repo create brain-data --private`)
|
|
475
|
+
2. Run `/brain:sync setup git@github.com:you/brain-data.git`
|
|
476
|
+
3. Use `/brain:sync push` and `/brain:sync pull` to keep memories in sync
|
|
477
|
+
|
|
478
|
+
For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
|
|
479
|
+
|
|
480
|
+
Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
|
|
340
481
|
|
|
341
482
|
## File Structure
|
|
342
483
|
|
|
343
484
|
```
|
|
344
|
-
|
|
485
|
+
~/.brain/
|
|
345
486
|
├── index.json # Memory inventory — fast lookup for all memories
|
|
487
|
+
├── config.json # Working-memory token budgets (session-start injection)
|
|
346
488
|
├── associations.json # Weighted associative network between memories
|
|
347
489
|
├── contexts.json # Session context snapshots for context-dependent recall
|
|
348
490
|
├── review-queue.json # Spaced repetition scheduling
|
|
491
|
+
├── pinned.json # Always-present tier manifest (pinned memory IDs + scope)
|
|
492
|
+
├── skills-index.json # Advertised procedural skills (L0 — name + description)
|
|
493
|
+
├── _skills/ # Procedural skills
|
|
494
|
+
│ └── <skill-name>/
|
|
495
|
+
│ ├── SKILL.md # Advertised description + step-by-step instructions
|
|
496
|
+
│ └── resources/ # Optional templates/scripts (loaded only at execution)
|
|
349
497
|
├── professional/ # Work, career, technical skills
|
|
350
498
|
│ ├── _meta.json # Category metadata and stats
|
|
351
499
|
│ ├── _expertise.md # Generated expertise profile
|
|
@@ -368,16 +516,19 @@ No data is lost. All new scoring gracefully falls back when newer fields are abs
|
|
|
368
516
|
│ └── events/
|
|
369
517
|
├── _consolidated/ # Merged memories from consolidation
|
|
370
518
|
│ └── _meta.json
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
519
|
+
├── _archived/ # Decayed memories (recoverable + searchable)
|
|
520
|
+
│ ├── _meta.json
|
|
521
|
+
│ └── index.json # Searchable archive index
|
|
522
|
+
└── .sync/ # Sync state (local only, never pushed)
|
|
523
|
+
├── config.json # Remote URL, encryption flag
|
|
524
|
+
└── repo/ # Hidden git repo for sync
|
|
374
525
|
```
|
|
375
526
|
|
|
376
527
|
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
528
|
|
|
378
529
|
## Configuration
|
|
379
530
|
|
|
380
|
-
Brain configuration lives in
|
|
531
|
+
Brain configuration lives in `~/.brain/index.json` under the `config` key:
|
|
381
532
|
|
|
382
533
|
```json
|
|
383
534
|
{
|
|
@@ -413,53 +564,102 @@ Brain configuration lives in `.brain/index.json` under the `config` key:
|
|
|
413
564
|
| `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
|
|
414
565
|
| `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
|
|
415
566
|
|
|
416
|
-
|
|
567
|
+
### Working-Memory Budget
|
|
568
|
+
|
|
569
|
+
A separate `~/.brain/config.json` (created lazily with safe defaults) caps how much the brain injects into the context window at session start, so the always-present tier can never crowd out your actual work:
|
|
417
570
|
|
|
571
|
+
```json
|
|
572
|
+
{
|
|
573
|
+
"working_memory_budget_tokens": 3000,
|
|
574
|
+
"pin_budget_tokens": 1500,
|
|
575
|
+
"skills_index_budget_tokens": 800,
|
|
576
|
+
"recall_budget_tokens": 700
|
|
577
|
+
}
|
|
418
578
|
```
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
579
|
+
|
|
580
|
+
| Setting | Default | Description |
|
|
581
|
+
|---------|---------|-------------|
|
|
582
|
+
| `working_memory_budget_tokens` | 3000 | Total token ceiling for the whole `brain session-start` payload |
|
|
583
|
+
| `pin_budget_tokens` | 1500 | Sub-budget for pinned, always-present memories |
|
|
584
|
+
| `skills_index_budget_tokens` | 800 | Sub-budget for the advertised skills index (L0) |
|
|
585
|
+
| `recall_budget_tokens` | 700 | Sub-budget for context-relevant recalled memories |
|
|
586
|
+
|
|
587
|
+
Token counts use a dependency-free heuristic stored on each memory at write time. When pins exceed their budget they're selected by `--priority` then strength, and the overflow is reported rather than silently dropped.
|
|
588
|
+
|
|
589
|
+
## Benchmark
|
|
590
|
+
|
|
591
|
+
Brain Memory ships with a controlled benchmark suite grounded in the 2025-2026 SOTA in long-term-memory evaluation. The system itself is a direct implementation of the [**CoALA**](https://arxiv.org/abs/2309.02427) agent-memory model (Sumers et al., 2023) — Pinned Tier maps to CoALA's *semantic* memory, procedural skills to *procedural* memory.
|
|
592
|
+
|
|
593
|
+
**Six scenarios**, each describable in one sentence:
|
|
594
|
+
|
|
595
|
+
| Id | Pitch | Tests |
|
|
596
|
+
|---|---|---|
|
|
597
|
+
| **A** *Noisy Project Folder* | "Your brain has 200 memories from 6 projects — does it find the 3 relevant ones?" | Retrieval under distractors (LongMemEval-S analog) |
|
|
598
|
+
| **B** *Three Sessions, One Decision* | "Postgres Monday, gRPC rewrite Wednesday, new resource Friday — still Postgres?" | Multi-session continuity + Pinned Tier ablation |
|
|
599
|
+
| **C** *The Contradiction Test* | "Tabs, then spaces, then tabs again — which version wins?" | Decay-weighted recency + contradiction handling |
|
|
600
|
+
| **D** *Skill Progressive Disclosure* | "Five skills indexed, one needed — does brain load just the one?" | CoALA Phase-2 L0/L1/L2 token efficiency |
|
|
601
|
+
| **E** *Continual Coding* | "Five bugs in order — does bug 5 finish faster than bug 1?" | Forward transfer; agent writes memories between tasks |
|
|
602
|
+
| **F** *Abstention* | "No deployment target in memory — does the agent ask or invent?" | Confabulation resistance |
|
|
603
|
+
|
|
604
|
+
**Methodology highlights** — cross-family LLM judge (Claude judges Gemini and vice-versa) with explicit rubric and position-swap; deterministic 200-memory distractor haystack; real `brain session-start` / `brain recall` integration; tokens-per-successful-task as the headline efficiency metric.
|
|
605
|
+
|
|
606
|
+
> Preliminary smoke results (1 run × Scenario A × Gemini Flash, May 2026): `brain-real` resolves the task at **27.8K tokens-per-success**, vs **50.8K** for naïve context-dump and **86.3K** for brain with pinning disabled — a ~3× token economy improvement attributable directly to the Pinned Tier. Full multi-run results are in progress.
|
|
607
|
+
|
|
608
|
+
Run the benchmarks yourself:
|
|
609
|
+
|
|
610
|
+
```bash
|
|
611
|
+
cd benchmark
|
|
612
|
+
cp .env.example .env # Add your API keys
|
|
613
|
+
npm test # Unit tests
|
|
614
|
+
node harness/runner.js # Full benchmark (cloud APIs)
|
|
449
615
|
```
|
|
450
616
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
617
|
+
Live methodology and per-scenario detail: [brainmemory.ai/docs/benchmarks](https://brainmemory.ai/docs/benchmarks) · Source: [`benchmark/`](benchmark/)
|
|
618
|
+
|
|
619
|
+
## Contributing
|
|
620
|
+
|
|
621
|
+
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
|
|
622
|
+
|
|
623
|
+
## References
|
|
624
|
+
|
|
625
|
+
Brain Memory's architecture and benchmark methodology are grounded in the following work.
|
|
626
|
+
|
|
627
|
+
### Foundations — the agent-memory model Brain implements
|
|
628
|
+
|
|
629
|
+
- [**CoALA — Cognitive Architectures for Language Agents**](https://arxiv.org/abs/2309.02427) (arxiv 2309.02427) — Sumers, Yao, Narasimhan, Griffiths. The agent-memory taxonomy Brain implements directly. Pinned Tier → semantic memory, Skills → procedural memory, session-start aggregator → working memory.
|
|
630
|
+
- [**MemGPT — LLMs as Operating Systems**](https://arxiv.org/abs/2310.08560) (arxiv 2310.08560) — Packer et al. Paging-style memory management.
|
|
631
|
+
- [**Generative Agents — Interactive Simulacra of Human Behavior**](https://arxiv.org/abs/2304.03442) (arxiv 2304.03442) — Park et al. Recency · importance · relevance retrieval blend.
|
|
632
|
+
- [**Memory in the Age of AI Agents**](https://arxiv.org/abs/2512.13564) (arxiv 2512.13564) — Comprehensive survey on agent memory architectures.
|
|
633
|
+
- [**Mem0**](https://arxiv.org/abs/2504.19413) (arxiv 2504.19413) — Human-like memory reinforcement and decay.
|
|
634
|
+
- [**MemOS**](https://arxiv.org/abs/2507.03724) (arxiv 2507.03724) — Memory lifecycle state management.
|
|
635
|
+
|
|
636
|
+
### Memory benchmarks (the suite this work follows)
|
|
637
|
+
|
|
638
|
+
- [**LongMemEval**](https://arxiv.org/abs/2410.10813) (arxiv 2410.10813) — distractor haystacks (S / M / Oracle), abstention category, GPT-4o judge with 97% human agreement.
|
|
639
|
+
- [**MemoryAgentBench**](https://arxiv.org/abs/2507.05257) (arxiv 2507.05257) — four-competency framework; FactConsolidation inspired Scenario C.
|
|
640
|
+
- [**SWE-Bench-CL**](https://arxiv.org/abs/2507.00014) (arxiv 2507.00014) — repo-scoped chronological evaluation; template for Scenario E.
|
|
641
|
+
- [**LoCoMo**](https://arxiv.org/abs/2402.17753) (arxiv 2402.17753) — long-conversation memory benchmark.
|
|
642
|
+
- [**MIRIX**](https://arxiv.org/abs/2507.07957) (arxiv 2507.07957) — realistic synthetic-but-grounded memory benchmarks.
|
|
643
|
+
|
|
644
|
+
### Methodology — judging and benchmark hygiene
|
|
645
|
+
|
|
646
|
+
- [**Preference Leakage in LLM-as-judge**](https://arxiv.org/abs/2502.01534) (arxiv 2502.01534) — drives cross-family judging.
|
|
647
|
+
- [**When Judgment Becomes Noise — position bias**](https://arxiv.org/abs/2509.20293) (arxiv 2509.20293) — drives position-swap mitigation.
|
|
648
|
+
- [**Silent Judge — shortcut bias**](https://arxiv.org/abs/2509.26072) (arxiv 2509.26072) — drives rubric-based judging.
|
|
649
|
+
- [**LastingBench**](https://arxiv.org/abs/2506.21614) (arxiv 2506.21614) — benchmark-leakage defense.
|
|
650
|
+
|
|
651
|
+
### Neuroscience
|
|
652
|
+
|
|
653
|
+
- [**Ebbinghaus forgetting curve**](https://en.wikipedia.org/wiki/Forgetting_curve) — exponential memory decay.
|
|
654
|
+
- [**Spreading activation**](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory.
|
|
655
|
+
- [**Hebbian theory**](https://en.wikipedia.org/wiki/Hebbian_theory) — "neurons that fire together wire together."
|
|
656
|
+
- [**Synaptic homeostasis hypothesis**](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function.
|
|
657
|
+
- [**SM-2 algorithm**](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — spaced repetition scheduling.
|
|
658
|
+
- [**Memory reconsolidation**](https://en.wikipedia.org/wiki/Memory_consolidation#Reconsolidation) — recalling memories makes them temporarily malleable.
|
|
659
|
+
|
|
660
|
+
### Related projects
|
|
661
|
+
|
|
662
|
+
- [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents.
|
|
463
663
|
|
|
464
664
|
## License
|
|
465
665
|
|
package/assets/icon.png
ADDED
|
Binary file
|
package/assets/icon.svg
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024">
|
|
2
|
+
<defs>
|
|
3
|
+
<radialGradient id="bm-glow" cx="50%" cy="50%" r="50%">
|
|
4
|
+
<stop offset="0%" stop-color="#FFD27A" stop-opacity="0.9"/>
|
|
5
|
+
<stop offset="100%" stop-color="#E8A33D" stop-opacity="0"/>
|
|
6
|
+
</radialGradient>
|
|
7
|
+
</defs>
|
|
8
|
+
<rect x="0" y="0" width="1024" height="1024" rx="224" ry="224" fill="#07090A"/>
|
|
9
|
+
<circle cx="512" cy="512" r="384" fill="url(#bm-glow)" opacity="0.7"/>
|
|
10
|
+
<g stroke="#E8A33D" stroke-width="38" stroke-linecap="round">
|
|
11
|
+
<line x1="512" y1="512" x2="256" y2="256" stroke-opacity="0.4"/>
|
|
12
|
+
<line x1="512" y1="512" x2="800" y2="256" stroke-opacity="0.82"/>
|
|
13
|
+
<line x1="512" y1="512" x2="864" y2="544" stroke-opacity="0.5"/>
|
|
14
|
+
<line x1="512" y1="512" x2="768" y2="800" stroke-opacity="0.75"/>
|
|
15
|
+
<line x1="512" y1="512" x2="256" y2="736" stroke-opacity="0.4"/>
|
|
16
|
+
<line x1="512" y1="512" x2="192" y2="512" stroke-opacity="0.35"/>
|
|
17
|
+
</g>
|
|
18
|
+
<circle cx="256" cy="256" r="51" fill="#9A6E28"/>
|
|
19
|
+
<circle cx="864" cy="544" r="45" fill="#DCA044"/>
|
|
20
|
+
<circle cx="768" cy="800" r="61" fill="#F0B24A"/>
|
|
21
|
+
<circle cx="256" cy="736" r="51" fill="#A9762E"/>
|
|
22
|
+
<circle cx="192" cy="512" r="42" fill="#8A6022"/>
|
|
23
|
+
<circle cx="800" cy="256" r="83" fill="#FFDD8C"/>
|
|
24
|
+
<circle cx="672" cy="368" r="42" fill="#FFF0CC"/>
|
|
25
|
+
<circle cx="512" cy="512" r="118" fill="#FFF2D2"/>
|
|
26
|
+
<circle cx="512" cy="512" r="61" fill="#FFFFFF"/>
|
|
27
|
+
</svg>
|
package/bin/brain.js
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* brain — unified CLI dispatcher for the Brain Memory system.
|
|
5
|
+
*
|
|
6
|
+
* Routes subcommands to their implementations, replacing the former per-binary
|
|
7
|
+
* surface (brain-recall, brain-reinforce, brain-memorize, brain-cloud). Each
|
|
8
|
+
* delegate module still runs on load and remains invokable as `node bin/<file>`,
|
|
9
|
+
* so direct invocation and the existing test suite are unaffected.
|
|
10
|
+
*
|
|
11
|
+
* Usage:
|
|
12
|
+
* brain Interactive installer (also: brain install)
|
|
13
|
+
* brain install|update|uninstall [flags]
|
|
14
|
+
* brain recall "<query>" [--project P] [--task T] [--top N] [--context] [--reindex]
|
|
15
|
+
* brain memorize [--sync] Store memories from a JSON payload on stdin
|
|
16
|
+
* brain reinforce <id> [<id>...] Spaced reinforcement + Hebbian co-retrieval
|
|
17
|
+
* brain cloud <login|logout|push|pull|status>
|
|
18
|
+
* brain --help | brain --version
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const path = require('path');
|
|
22
|
+
|
|
23
|
+
const VERSION = require('../package.json').version;
|
|
24
|
+
|
|
25
|
+
// Subcommands whose modules read process.argv.slice(2) directly. We strip the
|
|
26
|
+
// leading subcommand token, then require the module (which executes on load).
|
|
27
|
+
const DELEGATED = {
|
|
28
|
+
recall: 'recall.js',
|
|
29
|
+
reinforce: 'reinforce.js',
|
|
30
|
+
memorize: 'memorize.js',
|
|
31
|
+
cloud: 'cloud-sync.js',
|
|
32
|
+
'session-start': 'session-start.js',
|
|
33
|
+
pin: 'pin.js',
|
|
34
|
+
unpin: 'unpin.js',
|
|
35
|
+
skill: 'skill.js',
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
// install.js finds its positional subcommand from process.argv itself, so it is
|
|
39
|
+
// required without stripping anything. Bare `brain` also routes here, preserving
|
|
40
|
+
// `npx brain-memory` via npm's single-bin fallback.
|
|
41
|
+
const INSTALLER = new Set(['install', 'update', 'uninstall']);
|
|
42
|
+
|
|
43
|
+
const HELP = `🧠 brain — Brain Memory CLI
|
|
44
|
+
|
|
45
|
+
Usage: brain <command> [options]
|
|
46
|
+
|
|
47
|
+
Memory
|
|
48
|
+
recall "<query>" [--project P] [--task T] [--top N]
|
|
49
|
+
Deterministic recall (TF-IDF + decay + spreading)
|
|
50
|
+
recall --context Session-start recall from project context
|
|
51
|
+
recall --reindex Rebuild the search index
|
|
52
|
+
memorize [--sync] Store memories from a JSON payload on stdin
|
|
53
|
+
reinforce <id> [<id>...] Spaced reinforcement + Hebbian co-retrieval
|
|
54
|
+
pin <id> [--scope global|project:<name>] [--priority N]
|
|
55
|
+
Pin a memory into the always-present tier
|
|
56
|
+
unpin <id> Remove a memory from the always-present tier
|
|
57
|
+
skill <list|show|use|add|remove|export>
|
|
58
|
+
Manage procedural skills (progressive disclosure)
|
|
59
|
+
session-start [--project P] [--task T] [--top N]
|
|
60
|
+
Budget-bounded startup payload (agent-invoked)
|
|
61
|
+
|
|
62
|
+
Sync
|
|
63
|
+
cloud <login|logout|push|pull|status>
|
|
64
|
+
|
|
65
|
+
Setup
|
|
66
|
+
install Interactive installer (default when no command)
|
|
67
|
+
update Update an existing installation
|
|
68
|
+
uninstall [--delete-data] Remove the installation
|
|
69
|
+
|
|
70
|
+
Other
|
|
71
|
+
--help, -h Show this help
|
|
72
|
+
--version, -v Show version
|
|
73
|
+
`;
|
|
74
|
+
|
|
75
|
+
function main() {
|
|
76
|
+
const sub = process.argv[2];
|
|
77
|
+
|
|
78
|
+
if (sub === '--version' || sub === '-v') {
|
|
79
|
+
console.log(VERSION);
|
|
80
|
+
return;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
if (sub === '--help' || sub === '-h' || sub === 'help') {
|
|
84
|
+
console.log(HELP);
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// Bare `brain` or an installer subcommand → run the installer.
|
|
89
|
+
if (sub === undefined || INSTALLER.has(sub)) {
|
|
90
|
+
require(path.join(__dirname, 'install.js'));
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const file = DELEGATED[sub];
|
|
95
|
+
if (file) {
|
|
96
|
+
process.argv.splice(2, 1); // drop the subcommand token
|
|
97
|
+
const mod = require(path.join(__dirname, file));
|
|
98
|
+
// Modules guarded with `require.main === module` (e.g. session-start) export
|
|
99
|
+
// a main() that we must invoke; legacy modules already ran on require.
|
|
100
|
+
if (mod && typeof mod.main === 'function') {
|
|
101
|
+
mod.main(process.argv.slice(2));
|
|
102
|
+
}
|
|
103
|
+
return;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
console.error(`Unknown command: ${sub}\n`);
|
|
107
|
+
console.error(HELP);
|
|
108
|
+
process.exit(1);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
main();
|