zenbrain

<p align="center">
  <h1 align="center">ZenBrain</h1>
  <p align="center"><strong>The neuroscience-inspired memory system for AI agents.</strong></p>
  <p align="center">7 memory layers. Real neuroscience — FSRS, Hebbian, sleep consolidation, emotional tagging, plus 10 advanced research modules (vmPFC-FSRS, two-factor Hebbian, simulation-selection sleep, Fiedler-value KG health, IB budget, Hopfield STM, ...).<br/>Pure TypeScript. Zero dependencies. 694 tests. Extracted from a production AI platform.</p>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@zensation/algorithms"><img src="https://img.shields.io/npm/v/@zensation/algorithms?color=blue&label=npm" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@zensation/algorithms"><img src="https://img.shields.io/npm/dm/@zensation/algorithms?color=blue" alt="npm downloads"></a>
  <a href="https://github.com/zensation-ai/zenbrain/actions/workflows/ci.yml"><img src="https://github.com/zensation-ai/zenbrain/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/zensation-ai/zenbrain/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.7+-blue.svg" alt="TypeScript"></a>
  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="Zero Dependencies">
</p>

<p align="center">
  <sub><strong>Status:</strong> pre-1.0, semver — the public API can still change before <code>1.0</code>.<br/>
  694 tests green on Node 22, 24 and 26 in CI · every release published to npm with build provenance ·
  every change recorded in the <a href="./CHANGELOG.md">CHANGELOG</a> · issues and pull requests get a first response typically within 72 hours.</sub>
</p>

---

<p align="center">
  <img src="docs/demo.gif" alt="ZenBrain Playground Demo" width="700"/>
</p>

<p align="center">
  <strong><a href="https://zensation.ai/en/playground?utm_source=github&utm_medium=readme&utm_campaign=evergreen">▶ Try the live playground in your browser</a></strong> — runs this published code, no install required.
</p>

<details>
<summary><strong>📄 Paper & Citation</strong> — ZenBrain: A Neuroscience-Inspired 7-Layer Memory Architecture for Autonomous AI Systems</summary>

<br/>

- **arXiv preprint** (cs.AI): [arxiv.org/abs/2604.23878](https://arxiv.org/abs/2604.23878)
- **Open-access archive** (Zenodo / CERN): [doi.org/10.5281/zenodo.19353663](https://doi.org/10.5281/zenodo.19353663)
- **ORCID**: [0009-0001-1793-012X](https://orcid.org/0009-0001-1793-012X)
- **License**: CC BY 4.0 (paper) · Apache-2.0 (code)

```bibtex
@misc{bering2026zenbrain,
  title         = {ZenBrain: A Neuroscience-Inspired 7-Layer Memory Architecture for Autonomous AI Systems},
  author        = {Bering, Alexander},
  year          = {2026},
  eprint        = {2604.23878},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  doi           = {10.5281/zenodo.19353663},
  url           = {https://arxiv.org/abs/2604.23878}
}
```

Feedback, replications, and counter-results are explicitly welcome — please open an issue or reach out via [research@zensation.ai](mailto:research@zensation.ai).

</details>

> **Your AI forgets everything after every conversation.** ZenBrain fixes that — with the same mechanisms your brain uses: spaced repetition, emotional consolidation, Hebbian strengthening, and exponential forgetting curves. Not a vector database with a wrapper. Actual neuroscience.

> **Architecture vs. this package.** ZenBrain's architecture is **15 neuroscience-inspired mechanisms — 9 foundational algorithms + 6 Predictive Memory Architecture (PMA) components** ([paper](https://arxiv.org/abs/2604.23878)). The 6 PMA components are proprietary and run in the production system. **This open-source package ships the algorithm library: 10 core algorithms + 10 advanced research modules (20 modules), zero-dependency.**

---

## Benchmark: LongMemEval-500

On LongMemEval-500, **three of nine head-to-head answer-quality comparisons hold** against
Letta, Mem0 and A-Mem — all three against A-Mem, the remaining six are ties, none lost. Three
competitors x three LLM judges, Bonferroni-corrected (alpha = 0.05/18) and version-matched. It
reaches **91.3% of a full-context oracle's binary-judge accuracy at 1/109.6 of the per-query
token cost** (47.7% vs. 52.2%).

Works out of the box without an embedding provider — lexical ranking, zero
dependencies. With `nomic-embed-text` as the embedding provider you get the
configuration those figures were measured in.

The paper prints where ZenBrain loses as well: on LoCoMo, substring-based aggregate F1 favours
lexical retrieval (BM25) by metric design, and we do not contest that. The advantage is most
pronounced on judge-graded answer quality and cross-session reasoning.

**The mechanism comparison further down re-runs from this repository in under a minute** —
`bash scripts/compare-mechanisms.sh`, no API keys and nothing to install. It prints a positive
and a negative control before the result, so the instrument can be checked before its output
is trusted. The method, the effect sizes and the ablations behind the numbers above are in the
paper; this repository ships no runner for them. The archived packages below run the significance
tests and effect sizes in full, and the mechanism ablation behind paper Tables 7–9.

- Method, effect sizes and ablations: [arXiv:2604.23878](https://arxiv.org/abs/2604.23878)
- Open-access archive: [10.5281/zenodo.19353663](https://doi.org/10.5281/zenodo.19353663)

---

## Reproduction packages

The raw material behind the numbers above is deposited on Zenodo, open access and citable. Both
links are concept DOIs and resolve to the latest version, the same convention this README uses for
the paper archive; each description was measured against the version named after it.

- **Mechanism ablation, paper Tables 7–9** — [10.5281/zenodo.22162063](https://doi.org/10.5281/zenodo.22162063)
  (described here: v1.0.0). Four experiment suites (95 tests), the reference JSON the paper's
  tables were generated from, and `verify-against-reference.mjs`, which diffs a fresh run against
  that reference and exits non-zero on drift. `npm install && npm run experiments`; the run itself
  needs no API keys and no network, and finishes in under a minute on a laptop. Two of the paper's
  other ablation tables need data this package does not carry: Table 11 the LoCoMo corpus, Table 13
  a different pipeline. The package says so itself.
- **Measurement package, LongMemEval-500 and the real-pipeline flag ablation** —
  [10.5281/zenodo.22161977](https://doi.org/10.5281/zenodo.22161977) (described here: v1).
  Per-(system, judge, seed) judged outputs, the flag manifests as recorded at run time, a
  `SHA256SUMS.txt` covering every file in the package, and the analysis scripts. Three of those
  scripts are stdlib-only and self-checking — the oracle comparison behind the 91.3% figure, the
  judge-agreement figures, and the real-pipeline flag-ablation table: each prints every re-derived
  value next to the reference it has to match, and exits non-zero on mismatch. The significance
  tests behind the nine head-to-head comparisons against Letta, Mem0 and A-Mem sit in a separate
  script that needs numpy and scipy; it recomputes all eighteen pairwise tests and rewrites the
  deposited significance JSON byte-identically, so what catches a mismatch there is the checksum,
  not an exit code.

Both packages name what they do not cover. Replications and counter-results are welcome:
[research@zensation.ai](mailto:research@zensation.ai).

---

## How ZenBrain differs from Mem0, Letta and Zep

ZenBrain implements fifteen mechanisms taken from human memory research. No system among those
surveyed in the paper integrates more than two of them. The table below records which of the
mechanisms appear in the public source of three widely used memory systems, at pinned versions,
on a fixed date.

| Mechanism | ZenBrain | Mem0 | Letta | Zep |
|---|:--:|:--:|:--:|:--:|
| FSRS spaced repetition | yes | — | — | — |
| Hebbian learning | yes | — | — | — |
| Ebbinghaus forgetting curves | yes | — | — | — |
| Sleep consolidation | yes | — | — | — |
| Emotional tagging | yes | — | — | — |
| Zero runtime dependencies | yes | — | — | — |

<sub><strong>How this was measured, 27 August 2026.</strong> Full-text search over the
checked-out public source of <a href="https://github.com/mem0ai/mem0">mem0ai/mem0</a>
(npm <code>mem0ai</code> 3.1.7, PyPI <code>mem0ai</code> 2.0.19),
<a href="https://github.com/letta-ai/letta-code">letta-ai/letta-code</a>
(npm <code>@letta-ai/letta-code</code> 0.31.2) and
<a href="https://github.com/getzep/zep">getzep/zep</a>, lockfiles excluded. A dash means
<strong>the term does not occur in that snapshot</strong> — not that the system cannot do
something comparable under another name. Dependency counts are declared direct dependencies:
<code>@zensation/core</code> resolves to two packages, both our own; <code>mem0ai</code>
declares four, <code>@letta-ai/letta-code</code> eighteen. Re-run the whole check yourself with
<a href="./scripts/compare-mechanisms.sh"><code>scripts/compare-mechanisms.sh</code></a>; it
prints its own positive and negative controls so you can see the instrument works before you
trust the result.</sub>

Human memory does not work like a key-value store. The brain keeps specialised systems for
different kinds of memory, forgets actively, modulates by emotion and retrieves by context.
ZenBrain brings those mechanisms to AI agents.

### Advanced algorithms (since v0.3.0, May 2026)

On top of the 10 core algorithms above, `@zensation/algorithms` ships 10 advanced algorithms grounded in recent neuroscience and ML research. Each is exposed as its own sub-path (`@zensation/algorithms/<name>`) and remains zero-dependency:

- **`fsrs-vmPFC`** — Prediction-Error coupled FSRS
- **`hebbi