@zensation/algorithms
Advanced tools
Agent memory for LLM agents: FSRS spaced repetition, Hebbian learning, Ebbinghaus forgetting curves, emotional tagging, sleep consolidation and 15 more. ZenBrain's algorithm core — 20 modules, zero-dependency TypeScript library.
Neuroscience-inspired memory algorithms for AI agents. Pure TypeScript. Zero dependencies.
20 algorithm modules (10 core + 10 advanced), extracted from a production AI platform and published as standalone, dependency-free modules. Pure TypeScript, zero runtime dependencies, tree-shakeable subpath exports, 429 tests.
ZenBrain's full architecture is 15 neuroscience-inspired mechanisms (9 foundational + 6 PMA) (paper). The 6 PMA components are proprietary; this open-source package ships the algorithm library described below.
| Algorithm | Inspired By | What It Does |
|---|---|---|
| FSRS | Free Spaced Repetition Scheduler | Optimal review scheduling — your AI never forgets what matters |
| Ebbinghaus | Ebbinghaus (1885) | Exponential forgetting curves with personalized decay profiles |
| Emotional | Amygdala modulation (Cahill & McGaugh, 1998) | Arousal/valence/significance tagging — emotional memories decay 3× slower |
| Hebbian | Hebb's Rule (1949) | Co-activation strengthening with homeostatic normalization |
| Bayesian | Bayesian belief propagation | Confidence propagation through knowledge graphs |
| Context Retrieval | Encoding Specificity (Tulving, 1973) | Context-dependent retrieval boost when contexts match |
| Similarity | NLP heuristics | Negation detection (EN/DE), Jaccard similarity, text analysis |
| Sleep Consolidation | Stickgold & Walker (2013) | Replay simulation — strengthens emotional/recent memories, prunes weak edges |
| Intervals | Statistics | 95 % confidence intervals on retrievability and propagation |
| Visualization | — | Export retention curves and FSRS schedules for charting |
(plus shared types) | — | Logger interface, common typedefs |
Each is a separate sub-path import. Grounded in recent neuroscience and ML literature:
| Algorithm | Sub-path | Inspired by |
|---|---|---|
| Prediction-Error coupled FSRS | ./fsrs-vmPFC | Zou et al. 2025, vmPFC re-encoding |
| Two-Factor Synaptic Hebbian | ./hebbian-two-factor | Zenke et al. 2025, two-factor consolidation |
| Simulation-Selection Sleep Loop | ./sleep-simulation-selection | Frontiers Comp. Neurosci. 2025, RL replay |
| Spectral KG Health (Fiedler value) | ./spectral-health | Algebraic graph theory |
| Information-Bottleneck Budget | ./ib-budget | MemFly 2026, IB-based retention |
| Dopamine-Modulated Routing | ./dopamine-routing | Reward-modulated retrieval routing |
| Hopfield Short-Term Memory | ./hopfield-stm | Modern Hopfield networks |
| Personalized PageRank | ./personalized-pagerank | Graph propagation |
| Surprise-Gradient (Variational FE) Memory | ./surprise-gradient-memory | Free-energy principle |
| Temporal Multi-Route Retrieval | ./temporal-multi-route | Decomposed temporal queries |
npm install @zensation/algorithms
import {
// FSRS Spaced Repetition
initFromDecayClass,
getRetrievability,
updateAfterRecall,
scheduleNextReview,
// Emotional Memory
tagEmotion,
computeEmotionalWeight,
// Hebbian Learning
computeHebbianStrengthening,
computeHebbianDecay,
// Bayesian Confidence
propagateForRelation,
} from '@zensation/algorithms';
// 1. Create a memory with FSRS scheduling
const memory = initFromDecayClass('normal_decay');
console.log(memory);
// { difficulty: 5, stability: 7, nextReview: Date }
// 2. A week later, check recall probability (Ebbinghaus decay)
const aWeekLater = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
const retention = getRetrievability(memory, aWeekLater);
console.log(`Recall probability: ${(retention * 100).toFixed(1)}%`);
// ~36.8% — retrievability has decayed over the week
// 3. User recalled it anyway with grade 4 (good)
const updated = updateAfterRecall(memory, 4, retention, aWeekLater);
console.log(`Stability: ${memory.stability} -> ${updated.stability.toFixed(2)}`);
// 7 -> 8.19 — recalling at low retrievability gives a bigger boost (desirable difficulty)
// 4. Tag emotional significance
const emotion = tagEmotion('I am absolutely thrilled — I got the promotion!');
console.log(emotion);
// { sentiment: 0.55, arousal: 0.35, valence: 0.78, significance: 0.85 }
const weight = computeEmotionalWeight(emotion);
console.log(`Decay multiplier: ${weight.decayMultiplier}x`);
// 2.7x — this memory will decay nearly 3x slower
// 5. Strengthen knowledge graph edges via Hebbian learning
const newWeight = computeHebbianStrengthening(1.0);
// 1.09 — asymptotic growth toward MAX_WEIGHT (10.0)
// 6. Propagate confidence through relations
const newConfidence = propagateForRelation(
0.5, // base confidence
0.8, // source confidence
1.0, // edge weight
'supports'
);
// 0.9 — supporting evidence increases confidence
Import only what you need:
// Just FSRS
import { updateAfterRecall, getRetrievability } from '@zensation/algorithms/fsrs';
// Just emotional tagging
import { tagEmotion } from '@zensation/algorithms/emotional';
// Just Hebbian dynamics
import { computeHebbianStrengthening } from '@zensation/algorithms/hebbian';
SM-2 (SuperMemo 2, 1990) uses fixed multipliers. FSRS uses the desirable difficulty principle: reviewing when retention is low gives a bigger stability boost. The result? 30% fewer reviews for the same retention.
Human brains consolidate emotional memories more strongly (flashbulb memory effect). This module gives your AI the same capability: memories tagged with high arousal + significance get up to 3x longer decay half-life.
Knowledge graph edges that are frequently co-activated grow stronger. Edges that are never used decay and get pruned. The result is a self-organizing knowledge structure that reflects actual usage patterns.
Tulving showed that memory recall improves when the retrieval context matches the encoding context. This module captures temporal + task context at encoding time and provides up to a 30% retrieval boost when contexts match.
@zensation/algorithms/fsrs)| Function | Description |
|---|---|
initFromDecayClass(class, emotionalWeight?) | Create initial state from decay class |
initFromSM2(stability) | Convert SM-2 stability to FSRS state |
getRetrievability(state, now?) | Calculate current recall probability |
scheduleNextReview(state, targetRetention?, now?) | Schedule next optimal review |
updateAfterRecall(state, grade, retrievability, now?) | Update after successful recall (grade 1-5) |
updateAfterForgot(state, retrievability, now?) | Update after failed recall |
updateStabilityCompat(stability, success, multiplier?) | Drop-in SM-2 replacement |
getRetentionProbabilityCompat(lastAccess, stability, multiplier?) | Drop-in Ebbinghaus replacement |
@zensation/algorithms/ebbinghaus)| Function | Description |
|---|---|
calculateRetention(lastAccess, stability, emotionalMultiplier?) | Full retention analysis |
updateStability(stability, success) | SM-2 stability update |
getRepetitionCandidates(facts, threshold?) | Find facts due for review |
calculateOptimalInterval(stability, targetRetention?) | Optimal review interval |
batchCalculateRetention(facts) | Efficient batch retention |
learnDecayProfile(history) | Personalized decay curves |
calculatePersonalizedRetention(lastAccess, stability, profile) | User-specific retention |
@zensation/algorithms/emotional)| Function | Description |
|---|---|
tagEmotion(text, contextDomain?) | Multi-dimensional emotion analysis |
computeEmotionalWeight(tag) | Consolidation weight + decay multiplier |
isEmotionallySignificant(text, threshold?) | Quick significance check |
computeContextualValence(text, domain) | Domain-adjusted valence |
@zensation/algorithms/hebbian)| Function | Description |
|---|---|
computeHebbianStrengthening(weight) | Asymptotic edge strengthening |
computeHebbianDecay(weight) | Exponential decay with pruning |
computeHomeostaticNormalization(weights, targetSum) | Normalize weight distribution |
generatePairs(items) | Generate C(n,2) co-activation pairs |
@zensation/algorithms/bayesian)| Function | Description |
|---|---|
propagateForRelation(base, source, weight, type) | Single-edge confidence propagation |
applyDamping(newValue, previousValue) | Blend with previous for stability |
isSignificantChange(newValue, previousValue) | Check if update is worth persisting |
@zensation/algorithms/context-retrieval)| Function | Description |
|---|---|
captureEncodingContext(taskType?) | Snapshot current context |
calculateContextSimilarity(encoding, current?) | Context match score + boost |
serializeContext(ctx) / deserializeContext(data) | Storage helpers |
@zensation/algorithms/similarity)| Function | Description |
|---|---|
detectNegation(text) | Detect negation with target extraction (EN/DE) |
computeStringSimilarity(a, b) | Jaccard word overlap similarity |
stripNegation(text) | Remove negation words |
safeJsonParse(json, fallback) | Safe JSON parsing with fallback |
All functions accept an optional Logger parameter. Pass console, your favorite logger, or nothing (silent by default):
import { updateAfterRecall } from '@zensation/algorithms';
// Silent (default)
updateAfterRecall(state, 4, 0.9);
// With logging
updateAfterRecall(state, 4, 0.9, new Date(), console);
These algorithms are documented in an open-access technical disclosure: ZenBrain: A Neuroscience-Inspired 7-Layer Memory Architecture (Zenodo). See also: HuggingFace Model Card.
This package is part of the ZenBrain monorepo — the neuroscience-inspired memory system for AI agents.
| Package | Description |
|---|---|
| @zensation/algorithms | Pure algorithms (this package) |
@zensation/core | Memory layers + coordinator |
@zensation/adapter-postgres | PostgreSQL + pgvector storage |
@zensation/adapter-sqlite | SQLite storage (better-sqlite3) |
@zensation/mcp | MCP server: store, recall, consolidate, health |
@zensation/ai-sdk | Vercel AI SDK memory middleware |
Apache 2.0 — see LICENSE.
ZenBrain is a seven-layer, neuroscience-derived memory architecture for LLM agents, built as zero-dependency TypeScript and published under Apache-2.0. The benchmark results, and the configuration they were measured in, are reported in the paper; the reproduction packages are on Zenodo.
Works out of the box without an embedding provider — lexical ranking, zero
dependencies. The paper's measurements used nomic-embed-text as the embedding provider.
@zensation/algorithms · @zensation/core · @zensation/adapter-postgres · @zensation/adapter-sqlite · @zensation/mcp · @zensation/ai-sdkLicense: Apache-2.0
FAQs
Agent memory for LLM agents: FSRS spaced repetition, Hebbian learning, Ebbinghaus forgetting curves, emotional tagging, sleep consolidation and 15 more. ZenBrain's algorithm core — 20 modules, zero-dependency TypeScript library.
The npm package @zensation/algorithms receives a total of 128 weekly downloads. As such, @zensation/algorithms popularity was classified as not popular.
We found that @zensation/algorithms demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
arXiv now limits authors to two submissions a month as AI slop overwhelms moderators, delays good papers, and sparks debate over applying the limit to everyone.
Research
/Security News
A new GhostAction wave hits hundreds of GitHub repos, expanding CI/CD secret theft to cloud and AI credentials in source code and git history.
Research
/Security News
Tensorlake npm SDK version 0.5.144 was compromised in a ChainDrop / Shai-Hulud attack, delivering credential-stealing malware.