Mnemex
index.html•91.3 kB
<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Memory persistence for AI assistants with temporal decay">
<meta name="author" content="prefrontal-systems">
<link rel="canonical" href="https://cortexgraph.dev/scoring_algorithm/">
<link rel="prev" href="../graph_features/">
<link rel="next" href="../deployment/">
<link rel="icon" href="../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.0">
<title>Scoring Algorithm - CortexGraph Documentation</title>
<link rel="stylesheet" href="../assets/stylesheets/main.618322db.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.ab4e12ef.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#temporal-decay-scoring-algorithm" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="CortexGraph Documentation" class="md-header__button md-logo" aria-label="CortexGraph Documentation" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
CortexGraph Documentation
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Scoring Algorithm
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_0">
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
</label>
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/prefrontal-systems/cortexgraph" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
</div>
<div class="md-source__repository">
prefrontal-systems/cortexgraph
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href=".." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../installation/" class="md-tabs__link">
Getting Started
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../architecture/" class="md-tabs__link">
Documentation
</a>
</li>
<li class="md-tabs__item">
<a href="../deployment/" class="md-tabs__link">
Deployment
</a>
</li>
<li class="md-tabs__item">
<a href="../CONTRIBUTING/" class="md-tabs__link">
Development
</a>
</li>
<li class="md-tabs__item">
<a href="../features/auto-recall-conversation/" class="md-tabs__link">
Features
</a>
</li>
<li class="md-tabs__item">
<a href="../LICENSE/" class="md-tabs__link">
About
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="CortexGraph Documentation" class="md-nav__button md-logo" aria-label="CortexGraph Documentation" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
CortexGraph Documentation
</label>
<div class="md-nav__source">
<a href="https://github.com/prefrontal-systems/cortexgraph" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
</div>
<div class="md-source__repository">
prefrontal-systems/cortexgraph
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2" >
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
<span class="md-ellipsis">
Getting Started
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Getting Started
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../installation/" class="md-nav__link">
<span class="md-ellipsis">
Installation
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../quickstart/" class="md-nav__link">
<span class="md-ellipsis">
Quick Start
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../configuration/" class="md-nav__link">
<span class="md-ellipsis">
Configuration
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
<span class="md-ellipsis">
Documentation
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Documentation
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../architecture/" class="md-nav__link">
<span class="md-ellipsis">
Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/" class="md-nav__link">
<span class="md-ellipsis">
API Reference
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../graph_features/" class="md-nav__link">
<span class="md-ellipsis">
Knowledge Graph
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Scoring Algorithm
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Scoring Algorithm
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#overview" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#model-selection" class="md-nav__link">
<span class="md-ellipsis">
Model Selection
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#core-formula" class="md-nav__link">
<span class="md-ellipsis">
Core Formula
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#parameter-reference-at-a-glance" class="md-nav__link">
<span class="md-ellipsis">
Parameter Reference (at a glance)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#components-explained" class="md-nav__link">
<span class="md-ellipsis">
Components Explained
</span>
</a>
<nav class="md-nav" aria-label="Components Explained">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#1-use-count-component-n_textusebeta" class="md-nav__link">
<span class="md-ellipsis">
1. Use Count Component: $(n_{\text{use}})^\beta$
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#2-decay-component-e-lambda-cdot-delta-t" class="md-nav__link">
<span class="md-ellipsis">
2. Decay Component: $e^{-\lambda \cdot \Delta t}$
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#3-strength-multiplier" class="md-nav__link">
<span class="md-ellipsis">
3. Strength Multiplier
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#decision-thresholds" class="md-nav__link">
<span class="md-ellipsis">
Decision Thresholds
</span>
</a>
<nav class="md-nav" aria-label="Decision Thresholds">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#forget-threshold-tau_textforget-005" class="md-nav__link">
<span class="md-ellipsis">
Forget Threshold: $\tau_{\text{forget}} = 0.05$
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#threshold-summary" class="md-nav__link">
<span class="md-ellipsis">
Threshold Summary
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#promote-threshold-tau_textpromote-065" class="md-nav__link">
<span class="md-ellipsis">
Promote Threshold: $\tau_{\text{promote}} = 0.65$
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#complete-decision-logic" class="md-nav__link">
<span class="md-ellipsis">
Complete Decision Logic
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#parameter-interactions" class="md-nav__link">
<span class="md-ellipsis">
Parameter Interactions
</span>
</a>
<nav class="md-nav" aria-label="Parameter Interactions">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#high-beta-short-half-life" class="md-nav__link">
<span class="md-ellipsis">
High $\beta$ + Short Half-Life
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#low-beta-long-half-life" class="md-nav__link">
<span class="md-ellipsis">
Low $\beta$ + Long Half-Life
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#high-strength-normal-decay" class="md-nav__link">
<span class="md-ellipsis">
High Strength + Normal Decay
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#worked-examples" class="md-nav__link">
<span class="md-ellipsis">
Worked Examples
</span>
</a>
<nav class="md-nav" aria-label="Worked Examples">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#example-a-low-use-recent-normal-strength" class="md-nav__link">
<span class="md-ellipsis">
Example A: Low-use, recent, normal strength
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#example-b-frequent-use-mildly-stale-normal-strength" class="md-nav__link">
<span class="md-ellipsis">
Example B: Frequent-use, mildly stale, normal strength
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#example-c-high-strength-older-modest-use" class="md-nav__link">
<span class="md-ellipsis">
Example C: High strength, older, modest use
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#example-d-rarely-used-very-old" class="md-nav__link">
<span class="md-ellipsis">
Example D: Rarely used, very old
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#visualizations" class="md-nav__link">
<span class="md-ellipsis">
Visualizations
</span>
</a>
<nav class="md-nav" aria-label="Visualizations">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#decay-curves-n_textuse1-s10" class="md-nav__link">
<span class="md-ellipsis">
Decay Curves ($n_{\text{use}}=1$, $s=1.0$)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#use-count-impact-delta-t1-day-s10-beta06" class="md-nav__link">
<span class="md-ellipsis">
Use Count Impact ($\Delta t=1$ day, $s=1.0$, $\beta=0.6$)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#strength-modulation-n_textuse1-delta-t1-day" class="md-nav__link">
<span class="md-ellipsis">
Strength Modulation ($n_{\text{use}}=1$, $\Delta t=1$ day)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#tuning-for-different-use-cases" class="md-nav__link">
<span class="md-ellipsis">
Tuning for Different Use Cases
</span>
</a>
<nav class="md-nav" aria-label="Tuning for Different Use Cases">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#personal-assistant-balanced" class="md-nav__link">
<span class="md-ellipsis">
Personal Assistant (Balanced)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#development-environment-aggressive" class="md-nav__link">
<span class="md-ellipsis">
Development Environment (Aggressive)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#research-archival-conservative" class="md-nav__link">
<span class="md-ellipsis">
Research / Archival (Conservative)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#meeting-notes-high-velocity" class="md-nav__link">
<span class="md-ellipsis">
Meeting Notes (High Velocity)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#implementation-notes" class="md-nav__link">
<span class="md-ellipsis">
Implementation Notes
</span>
</a>
<nav class="md-nav" aria-label="Implementation Notes">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#precision" class="md-nav__link">
<span class="md-ellipsis">
Precision
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#caching" class="md-nav__link">
<span class="md-ellipsis">
Caching
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#batch-operations" class="md-nav__link">
<span class="md-ellipsis">
Batch Operations
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#comparison-to-other-approaches" class="md-nav__link">
<span class="md-ellipsis">
Comparison to Other Approaches
</span>
</a>
<nav class="md-nav" aria-label="Comparison to Other Approaches">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#vs-fixed-ttl-eg-redis" class="md-nav__link">
<span class="md-ellipsis">
vs. Fixed TTL (e.g., Redis)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#vs-lru-least-recently-used" class="md-nav__link">
<span class="md-ellipsis">
vs. LRU (Least Recently Used)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#vs-linear-decay" class="md-nav__link">
<span class="md-ellipsis">
vs. Linear Decay
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#future-enhancements" class="md-nav__link">
<span class="md-ellipsis">
Future Enhancements
</span>
</a>
<nav class="md-nav" aria-label="Future Enhancements">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#adaptive-decay" class="md-nav__link">
<span class="md-ellipsis">
Adaptive Decay
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#spaced-repetition" class="md-nav__link">
<span class="md-ellipsis">
Spaced Repetition
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#context-aware-strength" class="md-nav__link">
<span class="md-ellipsis">
Context-Aware Strength
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_4" >
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
<span class="md-ellipsis">
Deployment
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
Deployment
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../deployment/" class="md-nav__link">
<span class="md-ellipsis">
Deployment Guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../security/" class="md-nav__link">
<span class="md-ellipsis">
Security
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Development
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Development
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../CONTRIBUTING/" class="md-nav__link">
<span class="md-ellipsis">
Contributing
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ROADMAP/" class="md-nav__link">
<span class="md-ellipsis">
Roadmap
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../future_roadmap/" class="md-nav__link">
<span class="md-ellipsis">
Future Plans
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6" >
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
<span class="md-ellipsis">
Features
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
Features
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../features/auto-recall-conversation/" class="md-nav__link">
<span class="md-ellipsis">
Auto-Recall
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_7" >
<label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0">
<span class="md-ellipsis">
About
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_7">
<span class="md-nav__icon md-icon"></span>
About
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../LICENSE/" class="md-nav__link">
<span class="md-ellipsis">
License
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../CHANGELOG/" class="md-nav__link">
<span class="md-ellipsis">
Changelog
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#overview" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#model-selection" class="md-nav__link">
<span class="md-ellipsis">
Model Selection
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#core-formula" class="md-nav__link">
<span class="md-ellipsis">
Core Formula
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#parameter-reference-at-a-glance" class="md-nav__link">
<span class="md-ellipsis">
Parameter Reference (at a glance)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#components-explained" class="md-nav__link">
<span class="md-ellipsis">
Components Explained
</span>
</a>
<nav class="md-nav" aria-label="Components Explained">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#1-use-count-component-n_textusebeta" class="md-nav__link">
<span class="md-ellipsis">
1. Use Count Component: $(n_{\text{use}})^\beta$
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#2-decay-component-e-lambda-cdot-delta-t" class="md-nav__link">
<span class="md-ellipsis">
2. Decay Component: $e^{-\lambda \cdot \Delta t}$
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#3-strength-multiplier" class="md-nav__link">
<span class="md-ellipsis">
3. Strength Multiplier
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#decision-thresholds" class="md-nav__link">
<span class="md-ellipsis">
Decision Thresholds
</span>
</a>
<nav class="md-nav" aria-label="Decision Thresholds">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#forget-threshold-tau_textforget-005" class="md-nav__link">
<span class="md-ellipsis">
Forget Threshold: $\tau_{\text{forget}} = 0.05$
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#threshold-summary" class="md-nav__link">
<span class="md-ellipsis">
Threshold Summary
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#promote-threshold-tau_textpromote-065" class="md-nav__link">
<span class="md-ellipsis">
Promote Threshold: $\tau_{\text{promote}} = 0.65$
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#complete-decision-logic" class="md-nav__link">
<span class="md-ellipsis">
Complete Decision Logic
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#parameter-interactions" class="md-nav__link">
<span class="md-ellipsis">
Parameter Interactions
</span>
</a>
<nav class="md-nav" aria-label="Parameter Interactions">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#high-beta-short-half-life" class="md-nav__link">
<span class="md-ellipsis">
High $\beta$ + Short Half-Life
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#low-beta-long-half-life" class="md-nav__link">
<span class="md-ellipsis">
Low $\beta$ + Long Half-Life
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#high-strength-normal-decay" class="md-nav__link">
<span class="md-ellipsis">
High Strength + Normal Decay
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#worked-examples" class="md-nav__link">
<span class="md-ellipsis">
Worked Examples
</span>
</a>
<nav class="md-nav" aria-label="Worked Examples">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#example-a-low-use-recent-normal-strength" class="md-nav__link">
<span class="md-ellipsis">
Example A: Low-use, recent, normal strength
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#example-b-frequent-use-mildly-stale-normal-strength" class="md-nav__link">
<span class="md-ellipsis">
Example B: Frequent-use, mildly stale, normal strength
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#example-c-high-strength-older-modest-use" class="md-nav__link">
<span class="md-ellipsis">
Example C: High strength, older, modest use
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#example-d-rarely-used-very-old" class="md-nav__link">
<span class="md-ellipsis">
Example D: Rarely used, very old
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#visualizations" class="md-nav__link">
<span class="md-ellipsis">
Visualizations
</span>
</a>
<nav class="md-nav" aria-label="Visualizations">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#decay-curves-n_textuse1-s10" class="md-nav__link">
<span class="md-ellipsis">
Decay Curves ($n_{\text{use}}=1$, $s=1.0$)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#use-count-impact-delta-t1-day-s10-beta06" class="md-nav__link">
<span class="md-ellipsis">
Use Count Impact ($\Delta t=1$ day, $s=1.0$, $\beta=0.6$)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#strength-modulation-n_textuse1-delta-t1-day" class="md-nav__link">
<span class="md-ellipsis">
Strength Modulation ($n_{\text{use}}=1$, $\Delta t=1$ day)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#tuning-for-different-use-cases" class="md-nav__link">
<span class="md-ellipsis">
Tuning for Different Use Cases
</span>
</a>
<nav class="md-nav" aria-label="Tuning for Different Use Cases">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#personal-assistant-balanced" class="md-nav__link">
<span class="md-ellipsis">
Personal Assistant (Balanced)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#development-environment-aggressive" class="md-nav__link">
<span class="md-ellipsis">
Development Environment (Aggressive)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#research-archival-conservative" class="md-nav__link">
<span class="md-ellipsis">
Research / Archival (Conservative)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#meeting-notes-high-velocity" class="md-nav__link">
<span class="md-ellipsis">
Meeting Notes (High Velocity)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#implementation-notes" class="md-nav__link">
<span class="md-ellipsis">
Implementation Notes
</span>
</a>
<nav class="md-nav" aria-label="Implementation Notes">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#precision" class="md-nav__link">
<span class="md-ellipsis">
Precision
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#caching" class="md-nav__link">
<span class="md-ellipsis">
Caching
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#batch-operations" class="md-nav__link">
<span class="md-ellipsis">
Batch Operations
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#comparison-to-other-approaches" class="md-nav__link">
<span class="md-ellipsis">
Comparison to Other Approaches
</span>
</a>
<nav class="md-nav" aria-label="Comparison to Other Approaches">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#vs-fixed-ttl-eg-redis" class="md-nav__link">
<span class="md-ellipsis">
vs. Fixed TTL (e.g., Redis)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#vs-lru-least-recently-used" class="md-nav__link">
<span class="md-ellipsis">
vs. LRU (Least Recently Used)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#vs-linear-decay" class="md-nav__link">
<span class="md-ellipsis">
vs. Linear Decay
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#future-enhancements" class="md-nav__link">
<span class="md-ellipsis">
Future Enhancements
</span>
</a>
<nav class="md-nav" aria-label="Future Enhancements">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#adaptive-decay" class="md-nav__link">
<span class="md-ellipsis">
Adaptive Decay
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#spaced-repetition" class="md-nav__link">
<span class="md-ellipsis">
Spaced Repetition
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#context-aware-strength" class="md-nav__link">
<span class="md-ellipsis">
Context-Aware Strength
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<a href="https://github.com/prefrontal-systems/cortexgraph/edit/main/docs/scoring_algorithm.md" title="Edit this page" class="md-content__button md-icon" rel="edit">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg>
</a>
<h1 id="temporal-decay-scoring-algorithm">Temporal Decay Scoring Algorithm<a class="headerlink" href="#temporal-decay-scoring-algorithm" title="Permanent link">¶</a></h1>
<p><strong>Version:</strong> 0.2.0
<strong>Last Updated:</strong> 2025-01-07</p>
<h2 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">¶</a></h2>
<p>CortexGraph uses a novel temporal decay algorithm that mimics human memory dynamics. Memories naturally fade over time unless reinforced through use. This document explains the mathematical model, parameter tuning, and design rationale.</p>
<h2 id="model-selection">Model Selection<a class="headerlink" href="#model-selection" title="Permanent link">¶</a></h2>
<p>CortexGraph supports three decay models. Choose per use case via <code>CORTEXGRAPH_DECAY_MODEL</code>:</p>
<ol>
<li>Power‑Law (default):
$$ f(\Delta t) = \left(1 + \frac{\Delta t}{t_0}\right)^{-\alpha} $$</li>
<li>Heavier tail; retains older-but-important memories better.</li>
<li>
<p>Parameters: $\alpha$ (shape), $t_0$ (characteristic time). We derive $t_0$ from a chosen half‑life $H$ via $t_0 = H / (2^{1/\alpha} - 1)$.</p>
</li>
<li>
<p>Exponential:
$$ f(\Delta t) = e^{-\lambda\,\Delta t} $$</p>
</li>
<li>Lighter tail; simpler and forgets sooner.</li>
<li>
<p>Parameter: $\lambda$ (from half‑life).</p>
</li>
<li>
<p>Two‑Component Exponential:
$$ f(\Delta t) = w\,e^{-\lambda_f\,\Delta t} + (1-w)\,e^{-\lambda_s\,\Delta t} $$</p>
</li>
<li>Forgets very recent items faster (fast component) but keeps a heavier tail (slow component).</li>
<li>Parameters: $\lambda_f, \lambda_s, w$.</li>
</ol>
<p>Combined score (all models):
$$
\text{score} = (n_{\text{use}})^\beta \cdot f(\Delta t) \cdot s
$$</p>
<h2 id="core-formula">Core Formula<a class="headerlink" href="#core-formula" title="Permanent link">¶</a></h2>
<p>$$
\text{score} = (n_{\text{use}})^\beta \cdot e^{-\lambda \cdot \Delta t} \cdot s
$$</p>
<p>Where:
- $n_{\text{use}}$: Number of times the memory has been accessed (touches)
- $\beta$ (beta): Use count weight exponent (default: 0.6)
- $\lambda$ (lambda): Decay constant (default: $2.673 \times 10^{-6}$ for 3-day half-life)
- $\Delta t$: Time delta in seconds since last access ($t_{\text{now}} - t_{\text{last used}}$)
- $s$: Base multiplier (range: 0.0-2.0, default: 1.0)</p>
<h2 id="parameter-reference-at-a-glance">Parameter Reference (at a glance)<a class="headerlink" href="#parameter-reference-at-a-glance" title="Permanent link">¶</a></h2>
<ul>
<li>$\beta$ (beta): Sub-linear exponent for use count.</li>
<li>Default: 0.6; Range: 0.0–1.0</li>
<li>Higher → frequent memories gain more; Lower → emphasize recency</li>
<li>$\lambda$ (lambda): Exponential decay constant.</li>
<li>Computed from half-life: $\lambda = \ln(2) / t_{1/2}$</li>
<li>Example values: 1-day = $8.02\times 10^{-6}$, 3-day = $2.67\times 10^{-6}$, 7-day = $1.15\times 10^{-6}$</li>
<li>$\Delta t$: Seconds since last use.</li>
<li>Larger $\Delta t$ → lower score via $e^{-\lambda\Delta t}$</li>
<li>$s$ (strength): Importance multiplier.</li>
<li>Default: 1.0; Range: 0.0–2.0; Can be nudged by touch with boost</li>
<li>$\tau_{\text{forget}}$: Forget threshold.</li>
<li>Default: 0.05; If score < $\tau_{\text{forget}}$ → forget</li>
<li>$\tau_{\text{promote}}$: Promote threshold.</li>
<li>Default: 0.65; If score ≥ $\tau_{\text{promote}}$ → promote</li>
<li>Usage promotion rule: $n_{\text{use}} \ge 5$ within 14 days (configurable)</li>
<li>Captures frequently referenced info even if not extremely recent</li>
</ul>
<h2 id="components-explained">Components Explained<a class="headerlink" href="#components-explained" title="Permanent link">¶</a></h2>
<h3 id="1-use-count-component-n_textusebeta">1. Use Count Component: $(n_{\text{use}})^\beta$<a class="headerlink" href="#1-use-count-component-n_textusebeta" title="Permanent link">¶</a></h3>
<p><strong>Purpose:</strong> Reward frequently accessed memories.</p>
<p><strong>Why Exponent?</strong>
- Linear growth ($\beta=1.0$) over-rewards high use counts
- Sub-linear ($\beta<1.0$) provides diminishing returns
- Default $\beta=0.6$ balances reward vs. diminishing returns</p>
<p><strong>Examples:</strong></p>
<table>
<thead>
<tr>
<th>Use Count</th>
<th>$n^{0.6}$</th>
<th>Boost Factor</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>1.00</td>
<td>1.0x</td>
</tr>
<tr>
<td>5</td>
<td>2.63</td>
<td>2.6x</td>
</tr>
<tr>
<td>10</td>
<td>3.98</td>
<td>4.0x</td>
</tr>
<tr>
<td>50</td>
<td>11.45</td>
<td>11.4x</td>
</tr>
</tbody>
</table>
<p><strong>Tuning Guidelines:</strong>
- <strong>Higher $\beta$</strong> (0.8-1.0): Strongly favor frequently used memories
- <strong>Lower $\beta$</strong> (0.3-0.5): Reduce impact of use count, emphasize recency
- <strong>$\beta=0.0$</strong>: Disable use count entirely (pure temporal decay)</p>
<h3 id="2-decay-component-e-lambda-cdot-delta-t">2. Decay Component: $e^{-\lambda \cdot \Delta t}$<a class="headerlink" href="#2-decay-component-e-lambda-cdot-delta-t" title="Permanent link">¶</a></h3>
<p><strong>Purpose:</strong> Exponential decay over time (<a href="https://en.wikipedia.org/wiki/Forgetting_curve">Ebbinghaus forgetting curve</a>).</p>
<p><strong>Why Exponential?</strong>
- Models human memory better than linear decay
- Creates natural "forgetting" behavior
- Continuous and smooth (no sudden drops)</p>
<p><strong>Half-Life Calculation:</strong></p>
<p>$$
\lambda = \frac{\ln(2)}{t_{1/2}}
$$</p>
<p>Where $t_{1/2}$ is the half-life in seconds.</p>
<p>For a 3-day half-life:</p>
<p>$$
\lambda = \frac{\ln(2)}{3 \times 86400} = 2.673 \times 10^{-6}
$$</p>
<p><strong>Decay Curves:</strong></p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>Time Since Last Use | Score Multiplier (λ=3-day half-life)
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>--------------------|-------------------------------------
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>0 hours | 1.000 (100%)
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>12 hours | 0.917 (92%)
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>1 day | 0.841 (84%)
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>3 days | 0.500 (50%) ← Half-life
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>7 days | 0.210 (21%)
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>14 days | 0.044 (4%)
<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>30 days | 0.001 (0.1%)
</code></pre></div>
<p><strong>Tuning Guidelines:</strong>
- <strong>1-day half-life</strong> ($\lambda=8.02 \times 10^{-6}$): Aggressive decay, forget quickly
- <strong>3-day half-life</strong> ($\lambda=2.67 \times 10^{-6}$): Default, balanced retention
- <strong>7-day half-life</strong> ($\lambda=1.15 \times 10^{-6}$): Gentle decay, longer retention
- <strong>14-day half-life</strong> ($\lambda=5.73 \times 10^{-7}$): Very gentle, archives slowly</p>
<h3 id="3-strength-multiplier">3. Strength Multiplier<a class="headerlink" href="#3-strength-multiplier" title="Permanent link">¶</a></h3>
<p><strong>Purpose:</strong> Boost or dampen specific memories based on importance.</p>
<p><strong>Range:</strong> 0.0 to 2.0
- <strong>0.0-0.5</strong>: Low priority, ephemeral
- <strong>1.0</strong>: Normal (default)
- <strong>1.5-2.0</strong>: High priority, critical</p>
<p><strong>Use Cases:</strong>
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="c1"># Security credentials - critical</span>
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="n">strength</span> <span class="o">=</span> <span class="mf">2.0</span>
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="c1"># User preferences - important</span>
<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a><span class="n">strength</span> <span class="o">=</span> <span class="mf">1.5</span>
<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>
<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="c1"># Normal conversation context</span>
<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a><span class="n">strength</span> <span class="o">=</span> <span class="mf">1.0</span>
<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a>
<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="c1"># Tentative ideas, exploratory thoughts</span>
<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a><span class="n">strength</span> <span class="o">=</span> <span class="mf">0.5</span>
</code></pre></div></p>
<p><strong>Strength Over Time:</strong>
- Can be increased via <code>touch_memory(boost_strength=True)</code>
- Caps at 2.0 to prevent runaway growth
- Only way to "permanently" resist decay (besides re-touching)</p>
<h2 id="decision-thresholds">Decision Thresholds<a class="headerlink" href="#decision-thresholds" title="Permanent link">¶</a></h2>
<h3 id="forget-threshold-tau_textforget-005">Forget Threshold: $\tau_{\text{forget}} = 0.05$<a class="headerlink" href="#forget-threshold-tau_textforget-005" title="Permanent link">¶</a></h3>
<p><strong>Purpose:</strong> Delete memories with very low scores.</p>
<p><strong>Rationale:</strong>
- Below 5% of original score → likely irrelevant
- Prevents database bloat</p>
<h3 id="threshold-summary">Threshold Summary<a class="headerlink" href="#threshold-summary" title="Permanent link">¶</a></h3>
<ul>
<li>Forget if $\text{score} < \tau_{\text{forget}}$ (default 0.05)</li>
<li>Promote if $\text{score} \ge \tau_{\text{promote}}$ (default 0.65)</li>
<li>Or promote if $n_{\text{use}}\ge 5$ within 14 days (usage-based)</li>
<li>User can override by touching memory</li>
</ul>
<p><strong>Example:</strong></p>
<p>For a memory with $n_{\text{use}}=1$, $s=1.0$, $\beta=0.6$, $\lambda=2.673 \times 10^{-6}$ (3-day half-life), and $\Delta t = 30$ days:</p>
<p>$$
\begin{align<em>}
\text{score} &= (1)^{0.6} \cdot e^{-2.673 \times 10^{-6} \cdot 2{,}592{,}000} \cdot 1.0 \
&= 1.0 \cdot e^{-6.93} \cdot 1.0 \
&= 0.001
\end{align</em>}
$$</p>
<p>Since $0.001 < 0.05$ → <strong>FORGET</strong></p>
<h3 id="promote-threshold-tau_textpromote-065">Promote Threshold: $\tau_{\text{promote}} = 0.65$<a class="headerlink" href="#promote-threshold-tau_textpromote-065" title="Permanent link">¶</a></h3>
<p><strong>Purpose:</strong> Move high-value memories to long-term storage (LTM).</p>
<p><strong>Dual Criteria (OR logic):</strong>
1. <strong>Score-based:</strong> $\text{score} \geq 0.65$
2. <strong>Usage-based:</strong> $n_{\text{use}} \geq 5$ within 14 days</p>
<p><strong>Rationale:</strong>
- Score-based: Catches quickly-important info (e.g., high strength + recent)
- Usage-based: Catches frequently referenced info (even if not recent)</p>
<p><strong>Example Scenario 1:</strong> High score (strong memory, recently used)</p>
<p>$$
\begin{align<em>}
n_{\text{use}} &= 3 \
\Delta t &= 1 \text{ hour} = 3600 \text{ seconds} \
s &= 2.0 \
\
\text{score} &= (3)^{0.6} \cdot e^{-2.673 \times 10^{-6} \cdot 3600} \cdot 2.0 \
&= 1.93 \cdot 0.99 \cdot 2.0 \
&= 3.82
\end{align</em>}
$$</p>
<p>Since $3.82 > 0.65$ → <strong>PROMOTE</strong></p>
<p><strong>Example Scenario 2:</strong> High use count (frequently accessed)</p>
<ul>
<li>$n_{\text{use}} = 5$</li>
<li>$\Delta t = 7$ days</li>
<li>Memory created 10 days ago</li>
</ul>
<p>Within 14-day window <strong>AND</strong> $n_{\text{use}} \geq 5$ → <strong>PROMOTE</strong></p>
<h2 id="complete-decision-logic">Complete Decision Logic<a class="headerlink" href="#complete-decision-logic" title="Permanent link">¶</a></h2>
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">enum</span><span class="w"> </span><span class="kn">import</span> <span class="n">Enum</span>
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="k">class</span><span class="w"> </span><span class="nc">MemoryAction</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a> <span class="n">KEEP</span> <span class="o">=</span> <span class="s2">"keep"</span> <span class="c1"># Normal retention</span>
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="n">FORGET</span> <span class="o">=</span> <span class="s2">"forget"</span> <span class="c1"># Delete from STM</span>
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="n">PROMOTE</span> <span class="o">=</span> <span class="s2">"promote"</span> <span class="c1"># Move to LTM</span>
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a>
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="k">def</span><span class="w"> </span><span class="nf">decide_action</span><span class="p">(</span><span class="n">memory</span><span class="p">,</span> <span class="n">now</span><span class="p">):</span>
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="w"> </span><span class="sd">"""Determine action for a memory."""</span>
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a> <span class="c1"># Calculate current score</span>
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a> <span class="n">time_delta</span> <span class="o">=</span> <span class="n">now</span> <span class="o">-</span> <span class="n">memory</span><span class="o">.</span><span class="n">last_used</span>
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a> <span class="n">score</span> <span class="o">=</span> <span class="p">(</span>
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a> <span class="n">math</span><span class="o">.</span><span class="n">pow</span><span class="p">(</span><span class="n">memory</span><span class="o">.</span><span class="n">use_count</span><span class="p">,</span> <span class="n">β</span><span class="p">)</span> <span class="o">*</span>
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a> <span class="n">math</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="o">-</span><span class="n">λ</span> <span class="o">*</span> <span class="n">time_delta</span><span class="p">)</span> <span class="o">*</span>
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a> <span class="n">memory</span><span class="o">.</span><span class="n">strength</span>
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a> <span class="p">)</span>
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a>
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a> <span class="c1"># Check promotion criteria</span>
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a> <span class="k">if</span> <span class="n">score</span> <span class="o">>=</span> <span class="n">τ_promote</span><span class="p">:</span>
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a> <span class="k">return</span> <span class="n">MemoryAction</span><span class="o">.</span><span class="n">PROMOTE</span><span class="p">,</span> <span class="s2">"High score"</span>
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a>
<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a> <span class="n">age_days</span> <span class="o">=</span> <span class="p">(</span><span class="n">now</span> <span class="o">-</span> <span class="n">memory</span><span class="o">.</span><span class="n">created_at</span><span class="p">)</span> <span class="o">/</span> <span class="mi">86400</span>
<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a> <span class="k">if</span> <span class="n">memory</span><span class="o">.</span><span class="n">use_count</span> <span class="o">>=</span> <span class="mi">5</span> <span class="ow">and</span> <span class="n">age_days</span> <span class="o"><=</span> <span class="mi">14</span><span class="p">:</span>
<a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a> <span class="k">return</span> <span class="n">MemoryAction</span><span class="o">.</span><span class="n">PROMOTE</span><span class="p">,</span> <span class="s2">"Frequently used"</span>
<a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a>
<a id="__codelineno-2-26" name="__codelineno-2-26" href="#__codelineno-2-26"></a> <span class="c1"># Check forget criteria</span>
<a id="__codelineno-2-27" name="__codelineno-2-27" href="#__codelineno-2-27"></a> <span class="k">if</span> <span class="n">score</span> <span class="o"><</span> <span class="n">τ_forget</span><span class="p">:</span>
<a id="__codelineno-2-28" name="__codelineno-2-28" href="#__codelineno-2-28"></a> <span class="k">return</span> <span class="n">MemoryAction</span><span class="o">.</span><span class="n">FORGET</span><span class="p">,</span> <span class="s2">"Low score"</span>
<a id="__codelineno-2-29" name="__codelineno-2-29" href="#__codelineno-2-29"></a>
<a id="__codelineno-2-30" name="__codelineno-2-30" href="#__codelineno-2-30"></a> <span class="c1"># Default: keep in STM</span>
<a id="__codelineno-2-31" name="__codelineno-2-31" href="#__codelineno-2-31"></a> <span class="k">return</span> <span class="n">MemoryAction</span><span class="o">.</span><span class="n">KEEP</span><span class="p">,</span> <span class="sa">f</span><span class="s2">"Score: </span><span class="si">{</span><span class="n">score</span><span class="si">:</span><span class="s2">.3f</span><span class="si">}</span><span class="s2">"</span>
</code></pre></div>
<h2 id="parameter-interactions">Parameter Interactions<a class="headerlink" href="#parameter-interactions" title="Permanent link">¶</a></h2>
<h3 id="high-beta-short-half-life">High $\beta$ + Short Half-Life<a class="headerlink" href="#high-beta-short-half-life" title="Permanent link">¶</a></h3>
<p>$$
\beta = 0.8, \quad \lambda = 8.02 \times 10^{-6} \text{ (1-day half-life)}
$$</p>
<p><strong>Effect:</strong> Strongly favor frequently used, recent memories. Aggressive forgetting.
<strong>Use Case:</strong> High-velocity environments, rapid context switching.</p>
<h3 id="low-beta-long-half-life">Low $\beta$ + Long Half-Life<a class="headerlink" href="#low-beta-long-half-life" title="Permanent link">¶</a></h3>
<p>$$
\beta = 0.3, \quad \lambda = 5.73 \times 10^{-7} \text{ (14-day half-life)}
$$</p>
<p><strong>Effect:</strong> Gentle decay, less emphasis on use count. Longer retention.
<strong>Use Case:</strong> Slow-paced projects, archival needs.</p>
<h3 id="high-strength-normal-decay">High Strength + Normal Decay<a class="headerlink" href="#high-strength-normal-decay" title="Permanent link">¶</a></h3>
<p>$$
s = 2.0, \quad \beta = 0.6, \quad \lambda = 2.67 \times 10^{-6} \text{ (3-day half-life)}
$$</p>
<p><strong>Effect:</strong> Important memories resist decay longer.
<strong>Use Case:</strong> Critical information (credentials, decisions) in normal workflow.</p>
<h2 id="worked-examples">Worked Examples<a class="headerlink" href="#worked-examples" title="Permanent link">¶</a></h2>
<h3 id="example-a-low-use-recent-normal-strength">Example A: Low-use, recent, normal strength<a class="headerlink" href="#example-a-low-use-recent-normal-strength" title="Permanent link">¶</a></h3>
<p>Given: $n_{\text{use}}=1$, $\beta=0.6$, $\lambda=2.673\times10^{-6}$ (3-day), $\Delta t=6$ hours, $s=1.0$.</p>
<p>1) Use factor: $(1)^{0.6}=1.00$<br />
2) Decay: $e^{-2.673\times10^{-6}\cdot 21600} = e^{-0.0578}=0.9439$<br />
3) Strength: $1.0$<br />
Score: $1.00\times 0.9439\times 1.0=0.944$ → Keep (between thresholds)</p>
<h3 id="example-b-frequent-use-mildly-stale-normal-strength">Example B: Frequent-use, mildly stale, normal strength<a class="headerlink" href="#example-b-frequent-use-mildly-stale-normal-strength" title="Permanent link">¶</a></h3>
<p>Given: $n_{\text{use}}=6$, $\beta=0.6$, $\lambda=2.673\times10^{-6}$ (3-day), $\Delta t=2$ days, $s=1.0$.</p>
<p>1) Use factor: $(6)^{0.6}\approx 2.93$<br />
2) Decay: $e^{-2.673\times10^{-6}\cdot 172800} = e^{-0.462} = 0.629$<br />
3) Strength: $1.0$<br />
Score: $2.93\times 0.629 \approx 1.84$ → $\ge 0.65$ ⇒ Promote (score-based)</p>
<h3 id="example-c-high-strength-older-modest-use">Example C: High strength, older, modest use<a class="headerlink" href="#example-c-high-strength-older-modest-use" title="Permanent link">¶</a></h3>
<p>Given: $n_{\text{use}}=3$, $\beta=0.6$, $\lambda=2.673\times10^{-6}$ (3-day), $\Delta t=5$ days, $s=1.5$.</p>
<p>1) Use factor: $(3)^{0.6}\approx 1.93$<br />
2) Decay: $e^{-2.673\times10^{-6}\cdot 432000} = e^{-1.156} = 0.315$<br />
3) Strength: $1.5$<br />
Score: $1.93\times 0.315 \times 1.5 \approx 0.91$ → $\ge 0.65$ ⇒ Promote (score-based)</p>
<h3 id="example-d-rarely-used-very-old">Example D: Rarely used, very old<a class="headerlink" href="#example-d-rarely-used-very-old" title="Permanent link">¶</a></h3>
<p>Given: $n_{\text{use}}=1$, $\beta=0.6$, $\lambda=2.673\times10^{-6}$ (3-day), $\Delta t=21$ days, $s=1.0$.</p>
<p>1) Use factor: $1.00$<br />
2) Decay: $e^{-2.673\times10^{-6}\cdot 1,814,400} = e^{-4.85} = 0.0078$<br />
3) Strength: $1.0$<br />
Score: $\approx 0.0078$ → $< 0.05$ ⇒ Forget</p>
<h2 id="visualizations">Visualizations<a class="headerlink" href="#visualizations" title="Permanent link">¶</a></h2>
<h3 id="decay-curves-n_textuse1-s10">Decay Curves ($n_{\text{use}}=1$, $s=1.0$)<a class="headerlink" href="#decay-curves-n_textuse1-s10" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>Score
<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>1.0 |●
<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a> | ●
<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>0.8 | ●
<a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a> | ●
<a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a>0.6 | ●
<a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a> | ●●
<a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a>0.4 | ●●
<a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a> | ●●●
<a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a>0.2 | ●●●●
<a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a> | ●●●●●●●
<a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a>0.0 |_________________________________●●●●●●●●●●●●●●
<a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 days
<a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a>
<a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a>Legend:
<a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a>● = score at each day
<a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a>Horizontal line at 0.65 = promotion threshold
<a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a>Horizontal line at 0.05 = forget threshold
</code></pre></div>
<h3 id="use-count-impact-delta-t1-day-s10-beta06">Use Count Impact ($\Delta t=1$ day, $s=1.0$, $\beta=0.6$)<a class="headerlink" href="#use-count-impact-delta-t1-day-s10-beta06" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>Score
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>4.0 | ●
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a> | ●
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>3.0 | ●
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a> | ●
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a>2.0 | ●
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a> | ●
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a>1.0 |● ● ● ● ●
<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a> |_______________________________________________
<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a> 0 5 10 15 20 use_count
</code></pre></div>
<h3 id="strength-modulation-n_textuse1-delta-t1-day">Strength Modulation ($n_{\text{use}}=1$, $\Delta t=1$ day)<a class="headerlink" href="#strength-modulation-n_textuse1-delta-t1-day" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>Score
<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a>2.0 | ● (s=2.0)
<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a> | ● (s=1.5)
<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a>1.0 |● (s=1.0)
<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a> | ● (s=0.5)
<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a>0.0 |_________________________________
</code></pre></div>
<h2 id="tuning-for-different-use-cases">Tuning for Different Use Cases<a class="headerlink" href="#tuning-for-different-use-cases" title="Permanent link">¶</a></h2>
<h3 id="personal-assistant-balanced">Personal Assistant (Balanced)<a class="headerlink" href="#personal-assistant-balanced" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>CORTEXGRAPH_DECAY_LAMBDA=2.673e-6 # 3-day half-life
<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>CORTEXGRAPH_DECAY_BETA=0.6
<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>CORTEXGRAPH_FORGET_THRESHOLD=0.05
<a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a>CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
</code></pre></div>
<h3 id="development-environment-aggressive">Development Environment (Aggressive)<a class="headerlink" href="#development-environment-aggressive" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>CORTEXGRAPH_DECAY_LAMBDA=8.02e-6 # 1-day half-life
<a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>CORTEXGRAPH_DECAY_BETA=0.8
<a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>CORTEXGRAPH_FORGET_THRESHOLD=0.10
<a id="__codelineno-7-4" name="__codelineno-7-4" href="#__codelineno-7-4"></a>CORTEXGRAPH_PROMOTE_THRESHOLD=0.70
</code></pre></div>
<h3 id="research-archival-conservative">Research / Archival (Conservative)<a class="headerlink" href="#research-archival-conservative" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>CORTEXGRAPH_DECAY_LAMBDA=5.73e-7 # 14-day half-life
<a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>CORTEXGRAPH_DECAY_BETA=0.4
<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a>CORTEXGRAPH_FORGET_THRESHOLD=0.03
<a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a>CORTEXGRAPH_PROMOTE_THRESHOLD=0.50
</code></pre></div>
<h3 id="meeting-notes-high-velocity">Meeting Notes (High Velocity)<a class="headerlink" href="#meeting-notes-high-velocity" title="Permanent link">¶</a></h3>
<div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>CORTEXGRAPH_DECAY_LAMBDA=1.60e-5 # 12-hour half-life
<a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a>CORTEXGRAPH_DECAY_BETA=0.9
<a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a>CORTEXGRAPH_FORGET_THRESHOLD=0.15
<a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a>CORTEXGRAPH_PROMOTE_THRESHOLD=0.75
</code></pre></div>
<h2 id="implementation-notes">Implementation Notes<a class="headerlink" href="#implementation-notes" title="Permanent link">¶</a></h2>
<h3 id="precision">Precision<a class="headerlink" href="#precision" title="Permanent link">¶</a></h3>
<p>Use floating-point for all calculations:
<div class="highlight"><pre><span></span><code><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="c1"># Good</span>
<a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="n">time_delta</span> <span class="o">=</span> <span class="nb">float</span><span class="p">(</span><span class="n">now</span> <span class="o">-</span> <span class="n">last_used</span><span class="p">)</span>
<a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="n">score</span> <span class="o">=</span> <span class="n">math</span><span class="o">.</span><span class="n">pow</span><span class="p">(</span><span class="n">use_count</span><span class="p">,</span> <span class="n">beta</span><span class="p">)</span> <span class="o">*</span> <span class="n">math</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="o">-</span><span class="n">lambda_</span> <span class="o">*</span> <span class="n">time_delta</span><span class="p">)</span> <span class="o">*</span> <span class="n">strength</span>
<a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a>
<a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="c1"># Bad (integer overflow risk)</span>
<a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="n">time_delta</span> <span class="o">=</span> <span class="n">now</span> <span class="o">-</span> <span class="n">last_used</span> <span class="c1"># int</span>
<a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="n">score</span> <span class="o">=</span> <span class="n">use_count</span> <span class="o">**</span> <span class="n">beta</span> <span class="o">*</span> <span class="n">math</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="o">-</span><span class="n">lambda_</span> <span class="o">*</span> <span class="n">time_delta</span><span class="p">)</span> <span class="o">*</span> <span class="n">strength</span>
</code></pre></div></p>
<h3 id="caching">Caching<a class="headerlink" href="#caching" title="Permanent link">¶</a></h3>
<p>Scores change over time. Either:
1. Calculate on-demand (accurate but slower)
2. Cache with TTL (faster but approximate)</p>
<p>STM uses on-demand calculation for accuracy.</p>
<h3 id="batch-operations">Batch Operations<a class="headerlink" href="#batch-operations" title="Permanent link">¶</a></h3>
<p>For garbage collection, calculate scores in batch:
<div class="highlight"><pre><span></span><code><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="n">now</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">())</span>
<a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="n">memories_to_delete</span> <span class="o">=</span> <span class="p">[]</span>
<a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a>
<a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="k">for</span> <span class="n">memory</span> <span class="ow">in</span> <span class="n">all_memories</span><span class="p">:</span>
<a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a> <span class="n">score</span> <span class="o">=</span> <span class="n">calculate_score</span><span class="p">(</span><span class="n">memory</span><span class="p">,</span> <span class="n">now</span><span class="p">)</span>
<a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a> <span class="k">if</span> <span class="n">score</span> <span class="o"><</span> <span class="n">forget_threshold</span><span class="p">:</span>
<a id="__codelineno-11-7" name="__codelineno-11-7" href="#__codelineno-11-7"></a> <span class="n">memories_to_delete</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">memory</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
<a id="__codelineno-11-8" name="__codelineno-11-8" href="#__codelineno-11-8"></a>
<a id="__codelineno-11-9" name="__codelineno-11-9" href="#__codelineno-11-9"></a><span class="c1"># Delete in batch</span>
<a id="__codelineno-11-10" name="__codelineno-11-10" href="#__codelineno-11-10"></a><span class="n">delete_memories</span><span class="p">(</span><span class="n">memories_to_delete</span><span class="p">)</span>
</code></pre></div></p>
<h2 id="comparison-to-other-approaches">Comparison to Other Approaches<a class="headerlink" href="#comparison-to-other-approaches" title="Permanent link">¶</a></h2>
<h3 id="vs-fixed-ttl-eg-redis">vs. Fixed TTL (e.g., Redis)<a class="headerlink" href="#vs-fixed-ttl-eg-redis" title="Permanent link">¶</a></h3>
<p><strong>Redis-style:</strong>
$$
\text{if } (t_{\text{now}} - t_{\text{created}}) > \text{TTL} \implies \text{delete}
$$</p>
<p><strong>STM-style:</strong>
$$
\text{if } \text{score}(t) < \tau_{\text{forget}} \implies \text{delete}
$$</p>
<p><strong>Advantage:</strong> STM rewards frequent use. Redis deletes unconditionally.</p>
<h3 id="vs-lru-least-recently-used">vs. LRU (Least Recently Used)<a class="headerlink" href="#vs-lru-least-recently-used" title="Permanent link">¶</a></h3>
<p><strong>LRU:</strong>
$$
\text{if cache full} \implies \text{evict(least recently used)}
$$</p>
<p><strong>STM:</strong>
$$
\text{if } \text{score}(t) < \tau_{\text{forget}} \implies \text{forget}
$$</p>
<p><strong>Advantage:</strong> STM uses exponential decay + use count. LRU only tracks recency.</p>
<h3 id="vs-linear-decay">vs. Linear Decay<a class="headerlink" href="#vs-linear-decay" title="Permanent link">¶</a></h3>
<p><strong>Linear decay:</strong>
$$
\text{score} = \max\left(0, 1.0 - \frac{t_{\text{age}}}{t_{\text{max}}}\right)
$$</p>
<p><strong>STM exponential decay:</strong>
$$
\text{score} = e^{-\lambda \cdot \Delta t}
$$</p>
<p><strong>Advantage:</strong> Exponential matches Ebbinghaus curve (human forgetting).</p>
<h2 id="future-enhancements">Future Enhancements<a class="headerlink" href="#future-enhancements" title="Permanent link">¶</a></h2>
<h3 id="adaptive-decay">Adaptive Decay<a class="headerlink" href="#adaptive-decay" title="Permanent link">¶</a></h3>
<p>Adjust $\lambda$ based on memory category:</p>
<p>$$
\lambda_{\text{effective}} = \begin{cases}
0.5 \cdot \lambda_{\text{base}} & \text{if category = "credentials"} \
2.0 \cdot \lambda_{\text{base}} & \text{if category = "ephemeral"} \
\lambda_{\text{base}} & \text{otherwise}
\end{cases}
$$</p>
<h3 id="spaced-repetition">Spaced Repetition<a class="headerlink" href="#spaced-repetition" title="Permanent link">¶</a></h3>
<p>For stable memories with high use counts:</p>
<p>$$
t_{\text{next review}} = t_{\text{now}} + \Delta t_{\text{interval}}
$$</p>
<p>Where $\Delta t_{\text{interval}}$ increases with each successful review.</p>
<h3 id="context-aware-strength">Context-Aware Strength<a class="headerlink" href="#context-aware-strength" title="Permanent link">¶</a></h3>
<p>Boost strength based on conversation context:</p>
<p>$$
s = \begin{cases}
2.0 & \text{if is security critical(content)} \
1.5 & \text{if is decision(content)} \
1.3 & \text{if is preference(content)} \
1.0 & \text{otherwise}
\end{cases}
$$</p>
<hr />
<p><strong>Note:</strong> The combination of exponential decay, sub-linear use count, and strength modulation creates memory dynamics that closely mimic human cognition. These parameters can be tuned for different use cases and workflows.</p>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
<div class="md-social">
<a href="https://github.com/prefrontal-systems/cortexgraph" target="_blank" rel="noopener" title="github.com" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
</a>
<a href="https://github.com/prefrontal-systems/cortexgraph/discussions" target="_blank" rel="noopener" title="github.com" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M384 144c0 97.2-86 176-192 176-26.7 0-52.1-5-75.2-14l-81.6 43.2c-9.3 4.9-20.7 3.2-28.2-4.2s-9.2-18.9-4.2-28.2l35.6-67.2C14.3 220.2 0 183.6 0 144 0 46.8 86-32 192-32s192 78.8 192 176m0 368c-94.1 0-172.4-62.1-188.8-144 120-1.5 224.3-86.9 235.8-202.7 83.3 19.2 145 88.3 145 170.7 0 39.6-14.3 76.2-38.4 105.6l35.6 67.2c4.9 9.3 3.2 20.7-4.2 28.2s-18.9 9.2-28.2 4.2L459.2 498c-23.1 9-48.5 14-75.2 14"/></svg>
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.instant", "navigation.tracking", "navigation.tabs", "navigation.sections", "navigation.expand", "navigation.top", "search.suggest", "search.highlight", "content.code.copy", "content.code.annotate", "content.action.edit"], "search": "../assets/javascripts/workers/search.7a47a382.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../assets/javascripts/bundle.e71a0d61.min.js"></script>
</body>
</html>
Latest Blog Posts
- MCP Moves to the Linux Foundation: Neutral Stewardship for Agentic InfrastructureBy Om-Shree-0709 on .mcpanthropicLinux Foundation
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/prefrontalsys/mnemex'
If you have feedback or need assistance with the MCP directory API, please join our Discord server