brain-memory 0.1.0-beta.14 → 0.1.0-beta.16
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 +85 -16
- package/assets/icon.png +0 -0
- package/assets/icon.svg +21 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +8 -8
- package/bin/memorize.js +61 -7
- package/bin/pin.js +44 -0
- package/bin/recall.js +5 -5
- package/bin/reinforce.js +3 -3
- package/bin/session-start.js +292 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/memorize.md +18 -4
- package/commands/brain/pin.md +32 -0
- package/commands/brain/remember.md +3 -3
- package/commands/brain/skill.md +55 -0
- package/commands/brain/sleep.md +59 -4
- package/commands/brain/sync.md +6 -6
- package/commands/brain/unpin.md +21 -0
- package/package.json +3 -7
- package/prompts/claude.md +13 -11
- package/prompts/gemini.md +13 -11
- package/prompts/openai.md +13 -11
- package/prompts/opencode.md +13 -11
- package/src/index-manager.js +111 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +6 -2
- package/src/skills.js +208 -0
package/README.md
CHANGED
|
@@ -44,6 +44,8 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
|
|
|
44
44
|
- **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
|
|
45
45
|
- **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
|
|
46
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
|
|
47
49
|
- **On-demand depth** — Subcategories are created as needed, not pre-defined
|
|
48
50
|
- **Consolidation** — Weak related memories merge into stronger combined knowledge
|
|
49
51
|
- **Zero dependencies** — Pure file I/O, no databases, no servers, no embeddings required
|
|
@@ -52,38 +54,40 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
|
|
|
52
54
|
|
|
53
55
|
```bash
|
|
54
56
|
npm install -g brain-memory@beta
|
|
55
|
-
brain
|
|
57
|
+
brain
|
|
56
58
|
```
|
|
57
59
|
|
|
58
|
-
The first command installs the package globally — this gives you both the interactive setup wizard and the CLI
|
|
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.
|
|
59
61
|
|
|
60
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.
|
|
61
63
|
|
|
62
64
|
### Non-interactive
|
|
63
65
|
|
|
64
66
|
```bash
|
|
65
|
-
brain
|
|
66
|
-
brain
|
|
67
|
-
brain
|
|
68
|
-
brain
|
|
69
|
-
brain
|
|
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
|
|
70
72
|
```
|
|
71
73
|
|
|
72
74
|
### Update
|
|
73
75
|
|
|
74
76
|
```bash
|
|
75
77
|
npm install -g brain-memory@beta
|
|
76
|
-
brain
|
|
78
|
+
brain update
|
|
77
79
|
```
|
|
78
80
|
|
|
79
|
-
The first command updates the package and CLI
|
|
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`.
|
|
80
82
|
|
|
81
|
-
> **
|
|
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.
|
|
82
86
|
|
|
83
87
|
### Uninstall
|
|
84
88
|
|
|
85
89
|
```bash
|
|
86
|
-
brain
|
|
90
|
+
brain uninstall
|
|
87
91
|
npm uninstall -g brain-memory
|
|
88
92
|
```
|
|
89
93
|
|
|
@@ -120,6 +124,8 @@ Then append the contents of the corresponding prompt file to your agent's instru
|
|
|
120
124
|
| `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
|
|
121
125
|
| `/brain:memorize [topic] [--sync]` | Store memories from current session context (add `--sync` to auto-push) |
|
|
122
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 |
|
|
123
129
|
| `/brain:review [scope]` | Spaced repetition review session for due memories |
|
|
124
130
|
| `/brain:explore [category]` | Browse the brain hierarchy with visual tree view |
|
|
125
131
|
| `/brain:consolidate [scope]` | Merge related weak memories into stronger combined ones |
|
|
@@ -127,6 +133,7 @@ Then append the contents of the corresponding prompt file to your agent's instru
|
|
|
127
133
|
| `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
|
|
128
134
|
| `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
|
|
129
135
|
| `/brain:status` | Dashboard with brain health metrics and recommendations |
|
|
136
|
+
| `/brain:skill [list\|show\|add\|use\|remove\|export]` | Manage procedural skills — reusable how-to workflows with progressive disclosure |
|
|
130
137
|
| `/brain:sync [subcommand]` | Sync memories via Git remote or export/import for portability |
|
|
131
138
|
|
|
132
139
|
## Session Lifecycle
|
|
@@ -135,18 +142,19 @@ Brain Memory works automatically in the background — no commands needed for ba
|
|
|
135
142
|
|
|
136
143
|
### Session Start
|
|
137
144
|
|
|
138
|
-
When a session begins and `~/.brain/` exists, the agent
|
|
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`):
|
|
139
146
|
|
|
140
|
-
1.
|
|
141
|
-
2.
|
|
142
|
-
3.
|
|
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:
|
|
143
151
|
|
|
144
152
|
```
|
|
145
153
|
🧠 Brain active — 42 memories loaded (8 in current project context)
|
|
146
154
|
📋 3 memories due for review — run /brain:review
|
|
147
155
|
```
|
|
148
156
|
|
|
149
|
-
The agent silently internalizes relevant memories and references them naturally during the session — no information dump.
|
|
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.
|
|
150
158
|
|
|
151
159
|
### Ambient Session Tracking
|
|
152
160
|
|
|
@@ -240,6 +248,38 @@ Each memory is also classified by how the brain processes it:
|
|
|
240
248
|
|
|
241
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.
|
|
242
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
|
+
|
|
243
283
|
### Memory File Format
|
|
244
284
|
|
|
245
285
|
Each memory is a Markdown file with YAML frontmatter:
|
|
@@ -442,9 +482,16 @@ Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the rem
|
|
|
442
482
|
```
|
|
443
483
|
~/.brain/
|
|
444
484
|
├── index.json # Memory inventory — fast lookup for all memories
|
|
485
|
+
├── config.json # Working-memory token budgets (session-start injection)
|
|
445
486
|
├── associations.json # Weighted associative network between memories
|
|
446
487
|
├── contexts.json # Session context snapshots for context-dependent recall
|
|
447
488
|
├── review-queue.json # Spaced repetition scheduling
|
|
489
|
+
├── pinned.json # Always-present tier manifest (pinned memory IDs + scope)
|
|
490
|
+
├── skills-index.json # Advertised procedural skills (L0 — name + description)
|
|
491
|
+
├── _skills/ # Procedural skills
|
|
492
|
+
│ └── <skill-name>/
|
|
493
|
+
│ ├── SKILL.md # Advertised description + step-by-step instructions
|
|
494
|
+
│ └── resources/ # Optional templates/scripts (loaded only at execution)
|
|
448
495
|
├── professional/ # Work, career, technical skills
|
|
449
496
|
│ ├── _meta.json # Category metadata and stats
|
|
450
497
|
│ ├── _expertise.md # Generated expertise profile
|
|
@@ -515,6 +562,28 @@ Brain configuration lives in `~/.brain/index.json` under the `config` key:
|
|
|
515
562
|
| `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
|
|
516
563
|
| `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
|
|
517
564
|
|
|
565
|
+
### Working-Memory Budget
|
|
566
|
+
|
|
567
|
+
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:
|
|
568
|
+
|
|
569
|
+
```json
|
|
570
|
+
{
|
|
571
|
+
"working_memory_budget_tokens": 3000,
|
|
572
|
+
"pin_budget_tokens": 1500,
|
|
573
|
+
"skills_index_budget_tokens": 800,
|
|
574
|
+
"recall_budget_tokens": 700
|
|
575
|
+
}
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
| Setting | Default | Description |
|
|
579
|
+
|---------|---------|-------------|
|
|
580
|
+
| `working_memory_budget_tokens` | 3000 | Total token ceiling for the whole `brain session-start` payload |
|
|
581
|
+
| `pin_budget_tokens` | 1500 | Sub-budget for pinned, always-present memories |
|
|
582
|
+
| `skills_index_budget_tokens` | 800 | Sub-budget for the advertised skills index (L0) |
|
|
583
|
+
| `recall_budget_tokens` | 700 | Sub-budget for context-relevant recalled memories |
|
|
584
|
+
|
|
585
|
+
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.
|
|
586
|
+
|
|
518
587
|
## Benchmark
|
|
519
588
|
|
|
520
589
|
Empirical benchmarks show that agents with Brain Memory produce **more consistent** and **more successful** outputs across sessions.
|
package/assets/icon.png
CHANGED
|
Binary file
|
package/assets/icon.svg
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024">
|
|
2
|
+
<rect x="0" y="0" width="1024" height="1024" rx="224" ry="224" fill="#F0EFE8"/>
|
|
3
|
+
<g stroke="#1A1A1A" stroke-width="20" stroke-linecap="round">
|
|
4
|
+
<line x1="512" y1="512" x2="512" y2="232"/>
|
|
5
|
+
<line x1="512" y1="512" x2="754.49" y2="372"/>
|
|
6
|
+
<line x1="512" y1="512" x2="754.49" y2="652"/>
|
|
7
|
+
<line x1="512" y1="512" x2="512" y2="792"/>
|
|
8
|
+
<line x1="512" y1="512" x2="269.51" y2="652"/>
|
|
9
|
+
<line x1="512" y1="512" x2="269.51" y2="372"/>
|
|
10
|
+
</g>
|
|
11
|
+
<g fill="#1A1A1A">
|
|
12
|
+
<circle cx="512" cy="232" r="44"/>
|
|
13
|
+
<circle cx="754.49" cy="372" r="44"/>
|
|
14
|
+
<circle cx="754.49" cy="652" r="44"/>
|
|
15
|
+
<circle cx="512" cy="792" r="44"/>
|
|
16
|
+
<circle cx="269.51" cy="652" r="44"/>
|
|
17
|
+
<circle cx="269.51" cy="372" r="44"/>
|
|
18
|
+
</g>
|
|
19
|
+
<circle cx="512" cy="512" r="98" fill="#1A1A1A"/>
|
|
20
|
+
<circle cx="512" cy="512" r="58" fill="#E7B300"/>
|
|
21
|
+
</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();
|
package/bin/cloud-sync.js
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* brain
|
|
4
|
+
* brain cloud — CLI for Brain Cloud sync
|
|
5
5
|
*
|
|
6
6
|
* Usage:
|
|
7
|
-
* brain
|
|
8
|
-
* brain
|
|
9
|
-
* brain
|
|
10
|
-
* brain
|
|
11
|
-
* brain
|
|
7
|
+
* brain cloud login [--api-url URL] Authenticate via device code flow
|
|
8
|
+
* brain cloud logout Clear stored credentials
|
|
9
|
+
* brain cloud push Upload ~/.brain/ to the cloud
|
|
10
|
+
* brain cloud pull Download from the cloud to ~/.brain/
|
|
11
|
+
* brain cloud status Show connection and sync status
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
14
|
const path = require('path');
|
|
@@ -23,7 +23,7 @@ async function main() {
|
|
|
23
23
|
|
|
24
24
|
if (!command || command === '--help' || command === '-h') {
|
|
25
25
|
console.log(`
|
|
26
|
-
brain
|
|
26
|
+
brain cloud — Brain Cloud sync CLI
|
|
27
27
|
|
|
28
28
|
Commands:
|
|
29
29
|
login [--api-url URL] Authenticate via device code flow
|
|
@@ -118,7 +118,7 @@ async function cmdStatus() {
|
|
|
118
118
|
|
|
119
119
|
if (!s.connected) {
|
|
120
120
|
console.log('☁️ Not connected to Brain Cloud');
|
|
121
|
-
console.log(' Run: brain
|
|
121
|
+
console.log(' Run: brain cloud login');
|
|
122
122
|
return;
|
|
123
123
|
}
|
|
124
124
|
|
package/bin/memorize.js
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* brain
|
|
4
|
+
* brain memorize — Store memories from AI agent input
|
|
5
5
|
*
|
|
6
6
|
* Accepts a JSON payload via stdin with memory definitions.
|
|
7
7
|
* Handles all plumbing: ID generation, directory creation, file writing,
|
|
8
8
|
* index updates, association edges, search index, and optional sync.
|
|
9
9
|
*
|
|
10
10
|
* Usage:
|
|
11
|
-
* brain
|
|
11
|
+
* brain memorize [--sync] <<'EOF'
|
|
12
12
|
* { "memories": [{ "title": "...", "type": "learning", ... }] }
|
|
13
13
|
* EOF
|
|
14
14
|
*
|
|
@@ -29,6 +29,8 @@ const {
|
|
|
29
29
|
readAssociations,
|
|
30
30
|
writeAssociations,
|
|
31
31
|
reinforceEdge,
|
|
32
|
+
readPinned,
|
|
33
|
+
writePinned,
|
|
32
34
|
atomicWriteSync,
|
|
33
35
|
validateBrainPath,
|
|
34
36
|
} = require('../src/index-manager');
|
|
@@ -82,7 +84,7 @@ function buildMemoryFileContent(mem, id, now) {
|
|
|
82
84
|
mem.type, mem.cognitive_type, mem.strength_adjustment
|
|
83
85
|
);
|
|
84
86
|
|
|
85
|
-
const
|
|
87
|
+
const fmLines = [
|
|
86
88
|
'---',
|
|
87
89
|
`id: ${id}`,
|
|
88
90
|
`type: ${mem.type}`,
|
|
@@ -95,6 +97,16 @@ function buildMemoryFileContent(mem, id, now) {
|
|
|
95
97
|
`decay_rate: ${decay_rate}`,
|
|
96
98
|
`salience: ${mem.salience ?? 0.5}`,
|
|
97
99
|
`confidence: ${mem.confidence ?? 0.7}`,
|
|
100
|
+
];
|
|
101
|
+
// CoALA Phase 1: pinned (always-loaded) and stable (decay-exempt) are emitted
|
|
102
|
+
// only when set, so ordinary memories keep their existing frontmatter shape.
|
|
103
|
+
if (mem.pinned) {
|
|
104
|
+
fmLines.push('pinned: true');
|
|
105
|
+
fmLines.push(`pin_scope: "${mem.pin_scope || 'global'}"`);
|
|
106
|
+
fmLines.push(`pin_priority: ${mem.pin_priority || 0}`);
|
|
107
|
+
}
|
|
108
|
+
if (mem.stable) fmLines.push('stable: true');
|
|
109
|
+
fmLines.push(
|
|
98
110
|
`tags: [${(mem.tags || []).map(t => `"${t}"`).join(', ')}]`,
|
|
99
111
|
`related: [${(mem.related || []).map(r => `"${r}"`).join(', ')}]`,
|
|
100
112
|
`source: "${mem.source || ''}"`,
|
|
@@ -104,13 +116,14 @@ function buildMemoryFileContent(mem, id, now) {
|
|
|
104
116
|
` task_type: "${(mem.encoding_context && mem.encoding_context.task_type) || ''}"`,
|
|
105
117
|
'---',
|
|
106
118
|
'',
|
|
107
|
-
|
|
119
|
+
);
|
|
120
|
+
const frontmatter = fmLines.join('\n');
|
|
108
121
|
|
|
109
122
|
return { fileContent: frontmatter + mem.content + '\n', strength, decay_rate };
|
|
110
123
|
}
|
|
111
124
|
|
|
112
125
|
function buildIndexEntry(mem, id, strength, decayRate, now) {
|
|
113
|
-
|
|
126
|
+
const entry = {
|
|
114
127
|
title: mem.title,
|
|
115
128
|
path: mem.path,
|
|
116
129
|
type: mem.type,
|
|
@@ -125,7 +138,17 @@ function buildIndexEntry(mem, id, strength, decayRate, now) {
|
|
|
125
138
|
tags: mem.tags || [],
|
|
126
139
|
related: mem.related || [],
|
|
127
140
|
encoding_context: mem.encoding_context || {},
|
|
141
|
+
// CoALA Phase 0: cheap chars/4 token estimate for working-memory budgeting.
|
|
142
|
+
token_estimate: Math.ceil((mem.content || '').length / 4),
|
|
128
143
|
};
|
|
144
|
+
// CoALA Phase 1: only set when present — keeps existing index entries lean.
|
|
145
|
+
if (mem.pinned) {
|
|
146
|
+
entry.pinned = true;
|
|
147
|
+
entry.pin_scope = mem.pin_scope || 'global';
|
|
148
|
+
entry.pin_priority = mem.pin_priority || 0;
|
|
149
|
+
}
|
|
150
|
+
if (mem.stable) entry.stable = true;
|
|
151
|
+
return entry;
|
|
129
152
|
}
|
|
130
153
|
|
|
131
154
|
function updateMetaFiles(brainDir, memPath) {
|
|
@@ -184,7 +207,7 @@ function trySync() {
|
|
|
184
207
|
const cloudConfig = path.join(brainDir, '.cloud', 'config.json');
|
|
185
208
|
if (fs.existsSync(cloudConfig)) {
|
|
186
209
|
try {
|
|
187
|
-
execSync('brain
|
|
210
|
+
execSync('brain cloud push', { stdio: 'pipe', timeout: 30000 });
|
|
188
211
|
return { method: 'cloud', success: true };
|
|
189
212
|
} catch (err) {
|
|
190
213
|
return { method: 'cloud', success: false, error: err.message };
|
|
@@ -242,7 +265,7 @@ async function main() {
|
|
|
242
265
|
|
|
243
266
|
// Validate brain exists
|
|
244
267
|
if (!fs.existsSync(path.join(brainDir, 'index.json'))) {
|
|
245
|
-
console.error(JSON.stringify({ error: `Brain not initialized. Run brain
|
|
268
|
+
console.error(JSON.stringify({ error: `Brain not initialized. Run brain install first.` }));
|
|
246
269
|
process.exit(1);
|
|
247
270
|
}
|
|
248
271
|
|
|
@@ -278,6 +301,7 @@ async function main() {
|
|
|
278
301
|
const now = new Date().toISOString();
|
|
279
302
|
const results = [];
|
|
280
303
|
const newIds = [];
|
|
304
|
+
const pinnedToAdd = [];
|
|
281
305
|
|
|
282
306
|
for (const mem of input.memories) {
|
|
283
307
|
// Validate required fields
|
|
@@ -312,6 +336,16 @@ async function main() {
|
|
|
312
336
|
const indexEntry = buildIndexEntry(mem, id, strength, decay_rate, now);
|
|
313
337
|
addMemory(index, id, indexEntry);
|
|
314
338
|
|
|
339
|
+
// CoALA Phase 1: register a born-pinned memory in the pinned manifest
|
|
340
|
+
if (mem.pinned) {
|
|
341
|
+
pinnedToAdd.push({
|
|
342
|
+
id,
|
|
343
|
+
scope: mem.pin_scope || 'global',
|
|
344
|
+
priority: mem.pin_priority || 0,
|
|
345
|
+
token_estimate: indexEntry.token_estimate,
|
|
346
|
+
});
|
|
347
|
+
}
|
|
348
|
+
|
|
315
349
|
// Update associations — explicit related links
|
|
316
350
|
for (const relatedId of (mem.related || [])) {
|
|
317
351
|
if (index.memories[relatedId]) {
|
|
@@ -325,6 +359,15 @@ async function main() {
|
|
|
325
359
|
reinforceEdge(associations, id, overlapId, 'tag_overlap', 0.10);
|
|
326
360
|
}
|
|
327
361
|
|
|
362
|
+
// Tier B §10.2: surface potential contradictions with pinned/stable memories
|
|
363
|
+
// (high tag overlap) so the agent can adjudicate — never auto-resolved here.
|
|
364
|
+
const potentialConflicts = tagOverlaps
|
|
365
|
+
.filter((oid) => {
|
|
366
|
+
const e = index.memories[oid];
|
|
367
|
+
return e && (e.pinned || e.stable);
|
|
368
|
+
})
|
|
369
|
+
.map((oid) => ({ id: oid, title: index.memories[oid].title }));
|
|
370
|
+
|
|
328
371
|
// Update search index
|
|
329
372
|
addDocument(searchIndex, id, {
|
|
330
373
|
title: mem.title,
|
|
@@ -349,6 +392,7 @@ async function main() {
|
|
|
349
392
|
confidence: mem.confidence ?? 0.7,
|
|
350
393
|
tags: mem.tags || [],
|
|
351
394
|
edges_created: edgesCreated,
|
|
395
|
+
...(potentialConflicts.length ? { potential_conflicts: potentialConflicts } : {}),
|
|
352
396
|
});
|
|
353
397
|
}
|
|
354
398
|
|
|
@@ -357,6 +401,16 @@ async function main() {
|
|
|
357
401
|
writeAssociations(associations);
|
|
358
402
|
writeSearchIndex(brainDir, searchIndex);
|
|
359
403
|
|
|
404
|
+
// CoALA Phase 1: persist any born-pinned memories to the pinned manifest
|
|
405
|
+
if (pinnedToAdd.length > 0) {
|
|
406
|
+
const pinned = readPinned();
|
|
407
|
+
for (const p of pinnedToAdd) {
|
|
408
|
+
pinned.pins = pinned.pins.filter((x) => x.id !== p.id);
|
|
409
|
+
pinned.pins.push(p);
|
|
410
|
+
}
|
|
411
|
+
writePinned(pinned);
|
|
412
|
+
}
|
|
413
|
+
|
|
360
414
|
// Build output
|
|
361
415
|
const output = {
|
|
362
416
|
stored: results,
|
package/bin/pin.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* brain pin — pin a memory into the always-present semantic tier (CoALA Phase 1).
|
|
5
|
+
*
|
|
6
|
+
* Usage:
|
|
7
|
+
* brain pin <id> [--scope global|project:<name>] [--priority N]
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
const { pinMemory } = require('../src/pinning');
|
|
11
|
+
|
|
12
|
+
function parseArgs(argv) {
|
|
13
|
+
const args = { id: null, scope: 'global', priority: 0 };
|
|
14
|
+
for (let i = 0; i < argv.length; i++) {
|
|
15
|
+
switch (argv[i]) {
|
|
16
|
+
case '--scope': args.scope = argv[++i]; break;
|
|
17
|
+
case '--priority': args.priority = parseInt(argv[++i], 10) || 0; break;
|
|
18
|
+
default:
|
|
19
|
+
if (!argv[i].startsWith('--') && !args.id) args.id = argv[i];
|
|
20
|
+
break;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
return args;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function main(argv) {
|
|
27
|
+
const args = parseArgs(argv || process.argv.slice(2));
|
|
28
|
+
if (!args.id) {
|
|
29
|
+
console.error(JSON.stringify({ error: 'Usage: brain pin <id> [--scope global|project:<name>] [--priority N]' }));
|
|
30
|
+
process.exit(1);
|
|
31
|
+
}
|
|
32
|
+
const result = pinMemory(undefined, args.id, { scope: args.scope, priority: args.priority });
|
|
33
|
+
if (result.error) {
|
|
34
|
+
console.error(JSON.stringify(result));
|
|
35
|
+
process.exit(1);
|
|
36
|
+
}
|
|
37
|
+
console.log(JSON.stringify(result, null, 2));
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
if (require.main === module) {
|
|
41
|
+
main(process.argv.slice(2));
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
module.exports = { main, parseArgs };
|
package/bin/recall.js
CHANGED
|
@@ -7,10 +7,10 @@
|
|
|
7
7
|
* The agent calls this instead of manually computing the v4 formula.
|
|
8
8
|
*
|
|
9
9
|
* Usage:
|
|
10
|
-
* brain
|
|
11
|
-
* brain
|
|
12
|
-
* brain
|
|
13
|
-
* brain
|
|
10
|
+
* brain recall "async race conditions"
|
|
11
|
+
* brain recall "database pooling" --project my-app --task implementing --top 5
|
|
12
|
+
* brain recall --context # Session-start mode: auto-detect context
|
|
13
|
+
* brain recall --reindex # Rebuild search index from all memories
|
|
14
14
|
*
|
|
15
15
|
* Output: JSON array of scored results, sorted by score descending.
|
|
16
16
|
*/
|
|
@@ -54,7 +54,7 @@ function main() {
|
|
|
54
54
|
|
|
55
55
|
// Need a query for search
|
|
56
56
|
if (!args.query && !args.context) {
|
|
57
|
-
console.error(JSON.stringify({ error: 'Usage: brain
|
|
57
|
+
console.error(JSON.stringify({ error: 'Usage: brain recall "query" or brain recall --context' }));
|
|
58
58
|
process.exit(1);
|
|
59
59
|
}
|
|
60
60
|
|
package/bin/reinforce.js
CHANGED
|
@@ -8,8 +8,8 @@
|
|
|
8
8
|
* results instead of manually updating frontmatter.
|
|
9
9
|
*
|
|
10
10
|
* Usage:
|
|
11
|
-
* brain
|
|
12
|
-
* brain
|
|
11
|
+
* brain reinforce mem_123 mem_456 mem_789
|
|
12
|
+
* brain reinforce mem_123 --project my-app
|
|
13
13
|
*
|
|
14
14
|
* Effects:
|
|
15
15
|
* - Spaced reinforcement boost to each memory's strength
|
|
@@ -41,7 +41,7 @@ function main() {
|
|
|
41
41
|
const args = parseArgs(process.argv.slice(2));
|
|
42
42
|
|
|
43
43
|
if (args.memoryIds.length === 0) {
|
|
44
|
-
console.error(JSON.stringify({ error: 'Usage: brain
|
|
44
|
+
console.error(JSON.stringify({ error: 'Usage: brain reinforce <mem_id1> [mem_id2] ...' }));
|
|
45
45
|
process.exit(1);
|
|
46
46
|
}
|
|
47
47
|
|