brain-memory 0.1.0-beta.16 → 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
@@ -586,33 +586,22 @@ Token counts use a dependency-free heuristic stored on each memory at write time
586
586
 
587
587
  ## Benchmark
588
588
 
589
- Empirical benchmarks show that agents with Brain Memory produce **more consistent** and **more successful** outputs across sessions.
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.
590
590
 
591
- | Scenario | What it tests | Consistency Improvement | Success Improvement |
592
- |----------|---------------|:---:|:---:|
593
- | Multi-Session Continuity | Decisions carry from Session 1 → Session 2 | **+26.2%** | 0% |
594
- | Cross-Agent Consistency | All agents follow memorized style guide | 0% | 0% |
595
- | Accumulated Knowledge | 5 sessions of learning → better Session 6 | **+7.3%** | 0% |
596
- | Error Pattern Learning | Past debugging → faster fix | **+4.8%** | 0% |
597
- | Preference Retention | Preferences applied without re-stating | **+34.7%** | **+33.3%** |
591
+ **Six scenarios**, each describable in one sentence:
598
592
 
599
- **Per-agent consistency gains (Scenario 1 — Continuity):**
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 |
600
601
 
601
- | Agent | With Brain | Without Brain | Improvement |
602
- |-------|:---:|:---:|:---:|
603
- | Claude Code | 0.944 | 0.645 | +46.4% |
604
- | Gemini CLI | 0.822 | 0.555 | +48.1% |
605
- | Codex CLI | 0.767 | 0.545 | +40.7% |
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.
606
603
 
607
- **Preference retention (Scenario 5) — the strongest result:**
608
-
609
- | Agent | With Brain | Without Brain | Notes |
610
- |-------|:---:|:---:|:---|
611
- | Claude Code | 0.866 / PASS | 0.359 / **FAIL** | Brain prevented failure |
612
- | Gemini CLI | 0.800 / PASS | 0.534 / PASS | +49.8% consistency |
613
- | Codex CLI | 0.934 / PASS | 0.666 / PASS | +40.2% consistency |
614
-
615
- > 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.
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.
616
605
 
617
606
  Run the benchmarks yourself:
618
607
 
@@ -623,24 +612,52 @@ npm test # Unit tests
623
612
  node harness/runner.js # Full benchmark (cloud APIs)
624
613
  ```
625
614
 
626
- 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/)
627
616
 
628
617
  ## Contributing
629
618
 
630
619
  Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
631
620
 
632
- ## Inspired By
633
-
634
- - [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents
635
- - [Memory in the Age of AI Agents](https://arxiv.org/abs/2512.13564) — Comprehensive survey on agent memory architectures
636
- - [Mem0](https://arxiv.org/pdf/2504.19413) — Human-like memory reinforcement and decay
637
- - [MemOS](https://arxiv.org/pdf/2507.03724) — Memory lifecycle state management
638
- - [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve) — Exponential memory decay
639
- - [Spreading activation](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory
640
- - [Hebbian theory](https://en.wikipedia.org/wiki/Hebbian_theory) — "Neurons that fire together wire together"
641
- - [Synaptic homeostasis hypothesis](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function
642
- - [SM-2 algorithm](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — Spaced repetition scheduling
643
- - [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.
644
661
 
645
662
  ## License
646
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.16",
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",