brain-memory 0.1.0-beta.15 → 0.1.0-beta.17

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
@@ -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
@@ -78,6 +80,8 @@ brain update
78
80
 
79
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
 
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
+
81
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
@@ -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 automatically:
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. Reads the brain index and loads the top 3-5 memories relevant to the current project
141
- 2. Checks the review queue for memories due for spaced repetition
142
- 3. Outputs a brief status line:
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,35 +562,46 @@ 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
 
518
- ## Benchmark
565
+ ### Working-Memory Budget
519
566
 
520
- Empirical benchmarks show that agents with Brain Memory produce **more consistent** and **more successful** outputs across sessions.
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:
521
568
 
522
- | Scenario | What it tests | Consistency Improvement | Success Improvement |
523
- |----------|---------------|:---:|:---:|
524
- | Multi-Session Continuity | Decisions carry from Session 1 → Session 2 | **+26.2%** | 0% |
525
- | Cross-Agent Consistency | All agents follow memorized style guide | 0% | 0% |
526
- | Accumulated Knowledge | 5 sessions of learning → better Session 6 | **+7.3%** | 0% |
527
- | Error Pattern Learning | Past debugging → faster fix | **+4.8%** | 0% |
528
- | Preference Retention | Preferences applied without re-stating | **+34.7%** | **+33.3%** |
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
+ ```
529
577
 
530
- **Per-agent consistency gains (Scenario 1 — Continuity):**
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 |
531
584
 
532
- | Agent | With Brain | Without Brain | Improvement |
533
- |-------|:---:|:---:|:---:|
534
- | Claude Code | 0.944 | 0.645 | +46.4% |
535
- | Gemini CLI | 0.822 | 0.555 | +48.1% |
536
- | Codex CLI | 0.767 | 0.545 | +40.7% |
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
+
587
+ ## Benchmark
537
588
 
538
- **Preference retention (Scenario 5) — the strongest result:**
589
+ 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.
539
590
 
540
- | Agent | With Brain | Without Brain | Notes |
541
- |-------|:---:|:---:|:---|
542
- | Claude Code | 0.866 / PASS | 0.359 / **FAIL** | Brain prevented failure |
543
- | Gemini CLI | 0.800 / PASS | 0.534 / PASS | +49.8% consistency |
544
- | Codex CLI | 0.934 / PASS | 0.666 / PASS | +40.2% consistency |
591
+ **Six scenarios**, each describable in one sentence:
545
592
 
546
- > 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.
593
+ | Id | Pitch | Tests |
594
+ |---|---|---|
595
+ | **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) |
596
+ | **B** *Three Sessions, One Decision* | "Postgres Monday, gRPC rewrite Wednesday, new resource Friday — still Postgres?" | Multi-session continuity + Pinned Tier ablation |
597
+ | **C** *The Contradiction Test* | "Tabs, then spaces, then tabs again — which version wins?" | Decay-weighted recency + contradiction handling |
598
+ | **D** *Skill Progressive Disclosure* | "Five skills indexed, one needed — does brain load just the one?" | CoALA Phase-2 L0/L1/L2 token efficiency |
599
+ | **E** *Continual Coding* | "Five bugs in order — does bug 5 finish faster than bug 1?" | Forward transfer; agent writes memories between tasks |
600
+ | **F** *Abstention* | "No deployment target in memory — does the agent ask or invent?" | Confabulation resistance |
601
+
602
+ **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.
603
+
604
+ > 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.
547
605
 
548
606
  Run the benchmarks yourself:
549
607
 
@@ -554,24 +612,52 @@ npm test # Unit tests
554
612
  node harness/runner.js # Full benchmark (cloud APIs)
555
613
  ```
556
614
 
557
- Full methodology, per-scenario breakdowns, and raw data: [`benchmark/`](benchmark/) | [Detailed Report](benchmark/results/REPORT.md)
615
+ Live methodology and per-scenario detail: [brainmemory.work/docs/benchmarks](https://brainmemory.work/docs/benchmarks) · Source: [`benchmark/`](benchmark/)
558
616
 
559
617
  ## Contributing
560
618
 
561
619
  Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
562
620
 
563
- ## Inspired By
564
-
565
- - [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents
566
- - [Memory in the Age of AI Agents](https://arxiv.org/abs/2512.13564) — Comprehensive survey on agent memory architectures
567
- - [Mem0](https://arxiv.org/pdf/2504.19413) — Human-like memory reinforcement and decay
568
- - [MemOS](https://arxiv.org/pdf/2507.03724) — Memory lifecycle state management
569
- - [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve) — Exponential memory decay
570
- - [Spreading activation](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory
571
- - [Hebbian theory](https://en.wikipedia.org/wiki/Hebbian_theory) — "Neurons that fire together wire together"
572
- - [Synaptic homeostasis hypothesis](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function
573
- - [SM-2 algorithm](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — Spaced repetition scheduling
574
- - [Memory reconsolidation](https://en.wikipedia.org/wiki/Memory_consolidation#Reconsolidation) — How recalling memories makes them temporarily malleable
621
+ ## References
622
+
623
+ Brain Memory's architecture and benchmark methodology are grounded in the following work.
624
+
625
+ ### Foundations — the agent-memory model Brain implements
626
+
627
+ - [**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.
628
+ - [**MemGPT — LLMs as Operating Systems**](https://arxiv.org/abs/2310.08560) (arxiv 2310.08560) — Packer et al. Paging-style memory management.
629
+ - [**Generative Agents — Interactive Simulacra of Human Behavior**](https://arxiv.org/abs/2304.03442) (arxiv 2304.03442) — Park et al. Recency · importance · relevance retrieval blend.
630
+ - [**Memory in the Age of AI Agents**](https://arxiv.org/abs/2512.13564) (arxiv 2512.13564) — Comprehensive survey on agent memory architectures.
631
+ - [**Mem0**](https://arxiv.org/abs/2504.19413) (arxiv 2504.19413) — Human-like memory reinforcement and decay.
632
+ - [**MemOS**](https://arxiv.org/abs/2507.03724) (arxiv 2507.03724) — Memory lifecycle state management.
633
+
634
+ ### Memory benchmarks (the suite this work follows)
635
+
636
+ - [**LongMemEval**](https://arxiv.org/abs/2410.10813) (arxiv 2410.10813) — distractor haystacks (S / M / Oracle), abstention category, GPT-4o judge with 97% human agreement.
637
+ - [**MemoryAgentBench**](https://arxiv.org/abs/2507.05257) (arxiv 2507.05257) — four-competency framework; FactConsolidation inspired Scenario C.
638
+ - [**SWE-Bench-CL**](https://arxiv.org/abs/2507.00014) (arxiv 2507.00014) — repo-scoped chronological evaluation; template for Scenario E.
639
+ - [**LoCoMo**](https://arxiv.org/abs/2402.17753) (arxiv 2402.17753) — long-conversation memory benchmark.
640
+ - [**MIRIX**](https://arxiv.org/abs/2507.07957) (arxiv 2507.07957) — realistic synthetic-but-grounded memory benchmarks.
641
+
642
+ ### Methodology — judging and benchmark hygiene
643
+
644
+ - [**Preference Leakage in LLM-as-judge**](https://arxiv.org/abs/2502.01534) (arxiv 2502.01534) — drives cross-family judging.
645
+ - [**When Judgment Becomes Noise — position bias**](https://arxiv.org/abs/2509.20293) (arxiv 2509.20293) — drives position-swap mitigation.
646
+ - [**Silent Judge — shortcut bias**](https://arxiv.org/abs/2509.26072) (arxiv 2509.26072) — drives rubric-based judging.
647
+ - [**LastingBench**](https://arxiv.org/abs/2506.21614) (arxiv 2506.21614) — benchmark-leakage defense.
648
+
649
+ ### Neuroscience
650
+
651
+ - [**Ebbinghaus forgetting curve**](https://en.wikipedia.org/wiki/Forgetting_curve) — exponential memory decay.
652
+ - [**Spreading activation**](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory.
653
+ - [**Hebbian theory**](https://en.wikipedia.org/wiki/Hebbian_theory) — "neurons that fire together wire together."
654
+ - [**Synaptic homeostasis hypothesis**](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function.
655
+ - [**SM-2 algorithm**](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — spaced repetition scheduling.
656
+ - [**Memory reconsolidation**](https://en.wikipedia.org/wiki/Memory_consolidation#Reconsolidation) — recalling memories makes them temporarily malleable.
657
+
658
+ ### Related projects
659
+
660
+ - [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents.
575
661
 
576
662
  ## License
577
663
 
package/assets/icon.png CHANGED
Binary file
package/assets/icon.svg CHANGED
@@ -1,21 +1,27 @@
1
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"/>
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"/>
10
17
  </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"/>
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"/>
21
27
  </svg>
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Merge related weak memories into stronger combined memories
3
+ argument-hint: "[scope]"
4
+ ---
5
+
1
6
  # /brain:consolidate — Merge Related Memories
2
7
 
3
8
  You are consolidating memories in the Brain Memory system. Consolidation combines multiple related or weakening memories into a single stronger, more coherent memory — mimicking how human brains merge similar experiences into generalized knowledge.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Browse the brain memory hierarchy
3
+ argument-hint: "[category]"
4
+ ---
5
+
1
6
  # /brain:explore — Browse the Brain Structure
2
7
 
3
8
  You are exploring the Brain Memory system's hierarchical structure. This gives the user a visual overview of their memory landscape.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Decay or archive memories
3
+ argument-hint: "[target]"
4
+ ---
5
+
1
6
  # /brain:forget — Decay or Remove Memories
2
7
 
3
8
  You are managing memory decay in the Brain Memory system. This command accelerates forgetting for specific memories or prunes memories that have naturally decayed below usefulness.
@@ -1,3 +1,7 @@
1
+ ---
2
+ description: Initialize the brain memory structure
3
+ ---
4
+
1
5
  # /brain:init — Initialize Brain Memory Structure
2
6
 
3
7
  You are initializing the Brain Memory system. This creates a `~/.brain/` directory that serves as a hierarchical, file-system-based memory store inspired by human cognition.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Store memories from the current conversation context
3
+ argument-hint: "[topic]"
4
+ ---
5
+
1
6
  # /brain:memorize — Store a New Memory
2
7
 
3
8
  You are storing memories in the Brain Memory system. Your job is to decide **what** to remember and **how to classify** it. The `brain memorize` CLI handles all file operations.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Pin a memory to the always-present tier
3
+ argument-hint: "[id|query]"
4
+ ---
5
+
1
6
  # /brain:pin — Pin a Memory (Always-Present Tier)
2
7
 
3
8
  You are pinning a memory into the **always-present semantic tier**. Pinned memories are injected at every session start regardless of recall score, and are decay-exempt — they never fade.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Recall relevant memories with spreading activation and context matching
3
+ argument-hint: "[query]"
4
+ ---
5
+
1
6
  # /brain:remember — Recall Relevant Memories
2
7
 
3
8
  You are recalling memories from the Brain Memory system. This command uses the **deterministic recall engine** (`brain recall`) to score and rank memories, then presents the results.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Spaced-repetition review session for memories due for reinforcement
3
+ argument-hint: "[scope]"
4
+ ---
5
+
1
6
  # /brain:review — Spaced Repetition Review
2
7
 
3
8
  You are conducting a spaced repetition review session. This command surfaces memories that are due for review based on optimal spacing intervals, measures recall quality, and schedules the next review. Regular review sessions dramatically improve long-term retention.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Manage procedural skills (list, show, add, use, remove, export)
3
+ argument-hint: "[subcommand]"
4
+ ---
5
+
1
6
  # /brain:skill — Manage Procedural Skills
2
7
 
3
8
  You are managing **procedural memory** — reusable "how to do things" stored as `~/.brain/_skills/<name>/SKILL.md`. Skills use **progressive disclosure** so they never bloat the context window:
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Full maintenance cycle: replay, homeostasis, consolidation, pruning, dreaming
3
+ argument-hint: "[scope]"
4
+ ---
5
+
1
6
  # /brain:sleep — Overnight Memory Reorganization
2
7
 
3
8
  You are performing a **sleep cycle** on the Brain Memory system. Just like the human brain during sleep — where the hippocampus replays recent experiences and the neocortex reorganizes them into long-term structured knowledge — this command restructures, consolidates, prunes, and deepens the `~/.brain/` hierarchy.
@@ -1,3 +1,7 @@
1
+ ---
2
+ description: Dashboard with brain health overview
3
+ ---
4
+
1
5
  # /brain:status — Brain Overview Dashboard
2
6
 
3
7
  You are displaying a comprehensive overview of the Brain Memory system's current state.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Deep forensic erasure — trace and remove all references to a memory
3
+ argument-hint: "[target]"
4
+ ---
5
+
1
6
  # /brain:sunshine — Deep Forensic Memory Erasure
2
7
 
3
8
  You are performing **deep forensic erasure** on a memory in the Brain Memory system. Like the procedure in *Eternal Sunshine of the Spotless Mind*, this command doesn't just delete a memory — it traces every ripple that memory left across the entire `~/.brain/` tree and surgically removes or repairs each one. When complete, it's as if the memory never existed.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Sync memories via Git remote, Brain Cloud, or export/import
3
+ argument-hint: "[subcommand]"
4
+ ---
5
+
1
6
  # /brain:sync — Portable Sync
2
7
 
3
8
  You are managing synchronization for the Brain Memory system. This enables manual push/pull of `~/.brain/` memories via any Git remote, plus encrypted single-file export/import for portable transfers.
@@ -1,3 +1,8 @@
1
+ ---
2
+ description: Remove a memory from the always-present tier
3
+ argument-hint: "[id|query]"
4
+ ---
5
+
1
6
  # /brain:unpin — Remove a Memory from the Always-Present Tier
2
7
 
3
8
  You are unpinning a memory. It will no longer load automatically at session start and returns to normal recall + decay (an independent `stable` flag, if set, is left untouched).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.15",
3
+ "version": "0.1.0-beta.17",
4
4
  "description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
5
5
  "keywords": [
6
6
  "claude-code",