chronofy
v0.1.8
Published
JavaScript implementation of Chronofy's core temporal-validity APIs for time-aware AI systems.
Maintainers
Readme
Chronofy
Temporal validity framework for time-aware AI systems.
JavaScript implementation of Chronofy's core Temporal-Logical Decay Architecture (TLDA) APIs for temporal facts, scalar decay, filtering, verification, analysis, and scoring.
Also available as a Python package.
Package scope and versioning
The npm and Python packages use independent semantic versions because the
implementations ship on separate schedules. [email protected] implements the
JavaScript API documented below, based on the Python 0.1.6 core feature set.
Python-only temporal embedding, graph and rule retrieval, and Subjective Logic
modules are not included in the npm package. Matching npm and Python version
numbers therefore do not imply feature parity.
The Problem
RAG systems treat all retrieved facts as equally valid regardless of age. A clinical lab reading from yesterday and one from six months ago receive identical weight if semantically similar. This causes temporal hallucination — plausible but factually obsolete outputs.
Installation
npm install chronofyQuick Start
const {
TemporalFact,
ExponentialDecay,
EpistemicFilter,
STLVerifier,
ReasoningStep,
ReasoningTrace,
} = require('chronofy');
const now = new Date();
const daysAgo = (n) => new Date(now.getTime() - n * 86400000);
const hoursAgo = (n) => new Date(now.getTime() - n * 3600000);
// 1. Define timestamped facts
const facts = [
new TemporalFact({
content: 'Serum potassium: 4.1 mEq/L',
timestamp: hoursAgo(1),
factType: 'vital_sign',
sourceQuality: 0.95,
}),
new TemporalFact({
content: 'Serum potassium: 3.2 mEq/L',
timestamp: daysAgo(180),
factType: 'vital_sign',
sourceQuality: 0.95,
}),
new TemporalFact({
content: 'Blood type: O+',
timestamp: daysAgo(3650),
factType: 'demographic',
sourceQuality: 1.0,
}),
];
// 2. Configure decay — β = 2κ (Proposition 1)
const decay = new ExponentialDecay({
beta: {
vital_sign: 5.0, // volatile — decays in hours/days
lab_result: 2.0,
medication: 1.0,
chronic_condition: 0.01,
demographic: 0.0, // invariant — never decays
},
});
// 3. Filter to temporally valid facts only
const filter = new EpistemicFilter({ decayFn: decay, threshold: 0.1 });
const validFacts = filter.filter(facts, now);
for (const fact of validFacts) {
console.log(`[${decay.compute(fact, now).toFixed(4)}] ${fact.content}`);
}
// The 6-month reading is filtered out.
// 4. Verify reasoning chain with STL
const step = new ReasoningStep({ stepIndex: 0, content: 'assess risk', factsUsed: validFacts });
const trace = new ReasoningTrace({ steps: [step], queryTime: now });
const verifier = new STLVerifier({ decayFn: decay, threshold: 0.05 });
const result = verifier.verify(trace);
console.log(`STL satisfied: ${result.satisfied}`);
console.log(`Robustness: ${result.robustness.toFixed(4)}`);
console.log(`Confidence bound: ${result.outputConfidenceBound.toFixed(4)}`);[0.7713] Serum potassium: 4.1 mEq/L
[1.0000] Blood type: O+
STL satisfied: true
Robustness: 0.7213
Confidence bound: 0.7713Core Concepts
TemporalFact
Every piece of evidence is a tuple (content, timestamp, sourceQuality, factType):
const fact = new TemporalFact({
content: 'Patient serum potassium: 4.1 mEq/L',
timestamp: new Date('2024-06-01T08:30:00Z'), // observation time
factType: 'lab_result',
sourceQuality: 0.95, // reliability weight q ∈ (0, 1]
source: 'EPIC/LAB',
metadata: { units: 'mEq/L' },
});
const ageDays = fact.ageAt(new Date()); // age in days at any reference timeageAt() and the built-in decay functions compute age from timestamp. The optional
publicationTimestamp is reporting/publication provenance only; it does not change age or
validity.
Decay Functions
All decay functions return a validity score V(e, T_q) ∈ [0, 1].
const { ExponentialDecay, HalfLifeDecay, LinearDecay, PowerLawDecay, WeibullDecay } = require('chronofy');
// ExponentialDecay — Bayesian-optimal under Ornstein-Uhlenbeck dynamics
// β = 2κ where κ is the latent process mean-reversion rate (Proposition 1)
const decay = new ExponentialDecay({ beta: { vital_sign: 5.0, demographic: 0.0 } });
// Construct directly from mean-reversion rates
const decay2 = ExponentialDecay.fromMeanReversionRate({ vital_sign: 2.5, lab_result: 1.0 });
// Half-life parameterised (same as exponential, different interface)
const decay3 = new HalfLifeDecay({ halfLife: { vital_sign: 3.0, lab_result: 14.0 } });
// Linear — hard expiry at 1/rate days
const decay4 = new LinearDecay({ rate: { regulatory: 0.1 } });
// Power-law — heavy-tailed; matches citation/web patterns
const decay5 = new PowerLawDecay({ exponent: { news: 1.5 } });
// Weibull — shape > 1: accelerating decay; shape < 1: decelerating
const decay6 = new WeibullDecay({ scale: { lab_result: 7.0 }, shape: { lab_result: 1.5 } });
// Compute a single score
const score = decay.compute(fact, new Date());
// Compute batch
const scores = decay.computeBatch(facts, new Date());Temporal Invariance Guarantee: When β = 0, the temporal multiplier remains 1.0, so validity stays at the fact's sourceQuality regardless of age.
EpistemicFilter
Structurally excludes stale evidence from the LLM context window:
const { EpistemicFilter } = require('chronofy');
const filter = new EpistemicFilter({ decayFn: decay, threshold: 0.1 });
const fresh = filter.filter(facts, now);
const [fresh2, stale] = filter.partition(facts, now);
const needsRefresh = filter.needsReacquisition(facts, now);STLVerifier
Applies Signal Temporal Logic robustness to knowledge validity — not to LLM output confidence. Catches cases where the LLM is confidently wrong due to stale retrieval.
STL formula: φ_valid = G[0,n]( v(sᵢ) ≥ γ )
Robustness: ρ = minᵢ ( v(sᵢ) − γ ) — positive means satisfied.
Theorem 1 (Weakest-Link Bound): C_out ≤ minᵢ V(eᵢ, T_q)
const { STLVerifier, ReasoningStep, ReasoningTrace } = require('chronofy');
const verifier = new STLVerifier({ decayFn: decay, threshold: 0.3 });
const result = verifier.verify(trace);
result.satisfied // boolean
result.robustness // scalar ρ
result.stepValidity // per-step signals
result.outputConfidenceBound // Theorem 1 bound
result.weakestFact // the single least-fresh factCorpusStats
Temporal health statistics for a fact corpus:
const { CorpusStats } = require('chronofy');
const stats = new CorpusStats({ facts, queryTime: new Date(), decayFn: decay });
stats.factCount // number of facts
stats.effectiveDensity // mean validity (0–1 health score)
stats.temporalSpanDays // range from oldest to newest fact
stats.ageStats // { min, max, mean, median, std, p25, p75 }
stats.validityStats // same for validity scores
stats.stalenessRate(0.1) // fraction of facts below 10% validity
stats.coverageGaps(7) // gaps with no facts for ≥ 7 days
stats.summary() // all of the above as a plain objectBetaEstimator
Fit β empirically from labelled observations (ageInDays, stillValid):
const { BetaEstimator, MLEBernoulli, MomentMatching, EnsembleMethod } = require('chronofy');
// Default: MLE under P(valid | age, β) = exp(-β · age)
const estimator = new BetaEstimator();
const result = estimator.fit({
ages: [1, 5, 10, 30, 60],
valid: [true, true, true, false, false],
factType: 'lab_result',
});
console.log(`β̂ = ${result.beta.toFixed(4)}, half-life = ${result.halfLife.toFixed(1)} days`);
// Fit per fact type from a labelled corpus
const results = estimator.fitCorpus({ facts, labels, queryTime: new Date() });
// Convert directly to ExponentialDecay
const fittedDecay = estimator.toDecay(results);
// Swap the estimation backend
const mmEst = new BetaEstimator({ method: new MomentMatching() });
const ensembleEst = new BetaEstimator({
method: new EnsembleMethod({
methods: [new MLEBernoulli(), new MomentMatching()],
weights: [0.7, 0.3],
}),
});TemporalScorer
Combines semantic similarity with temporal validity for retrieval ranking:
const {
TemporalScorer, MultiplicativeScoring, HarmonicScoring,
WeightedBlendScoring, PowerScoring,
} = require('chronofy');
const scorer = new TemporalScorer({
decayFn: decay,
strategy: new HarmonicScoring(), // or Multiplicative, WeightedBlend, Power
});
// Score a single fact
const sf = scorer.scoreFact(fact, 0.85, new Date());
sf.similarity // 0.85
sf.validity // from decay function
sf.combinedScore // from strategy
// Score and rank a batch
const ranked = scorer.rank(facts, similarities, new Date(), /* topK= */ 5);| Strategy | Formula | Best for |
|---|---|---|
| MultiplicativeScoring | sim × val | Default; aggressively penalises either weakness |
| HarmonicScoring | 2·sim·val / (sim+val) | Balanced; satisfies min ≤ H ≤ max |
| WeightedBlendScoring(α) | α·sim + (1-α)·val | Explicit trade-off control |
| PowerScoring(α) | sim^α · val^(1-α) | Geometric blend; α=0.5 is geometric mean |
DecayComparison
Evaluate multiple decay backends on labelled data to select the best fit:
const { DecayComparison, ExponentialDecay, LinearDecay } = require('chronofy');
const dc = new DecayComparison({
decayFns: {
exponential: new ExponentialDecay({ beta: { lab: 2.0 } }),
linear: new LinearDecay({ rate: { lab: 0.1 } }),
},
facts,
labels, // parallel boolean array
queryTime: new Date(),
});
const results = dc.compare(); // sorted by AUROC descending
for (const r of results) {
console.log(`${r.name}: AUC=${r.auc_roc.toFixed(3)} Brier=${r.brier_score.toFixed(3)}`);
}
const best = dc.best('auc_roc'); // or 'brier_score', 'log_loss'
const summary = dc.summary();Custom Extensions
Custom Decay Function
const { DecayFunction, validateDecayFunction } = require('chronofy');
class SeasonalDecay extends DecayFunction {
constructor({ baseRate = 0.01, periodDays = 365 } = {}) {
super();
this.baseRate = baseRate;
this.periodDays = periodDays;
}
compute(fact, queryTime) {
const age = fact.ageAt(queryTime);
const monotone = Math.exp(-this.baseRate * age);
const seasonal = 0.5 * (1 + Math.cos(2 * Math.PI * age / this.periodDays));
return fact.sourceQuality * monotone * seasonal;
}
computeBatch(facts, queryTime) {
return facts.map(f => this.compute(f, queryTime));
}
}
// Validate before use — catches bugs immediately
const decay = validateDecayFunction(new SeasonalDecay());Custom Estimation Method
const { EstimationMethod, BetaEstimator, validateEstimationMethod } = require('chronofy');
class MedianHalfLifeEstimator extends EstimationMethod {
fit(ages, valid) {
const invalidAges = ages.filter((_, i) => !valid[i]).sort((a, b) => a - b);
if (!invalidAges.length) return 0;
const median = invalidAges[Math.floor(invalidAges.length / 2)];
return median > 0 ? Math.LN2 / median : 50;
}
}
const method = validateEstimationMethod(new MedianHalfLifeEstimator());
const estimator = new BetaEstimator({ method });Custom Scoring Strategy
const { ScoringStrategy, TemporalScorer, validateScoringStrategy } = require('chronofy');
class MinScoring extends ScoringStrategy {
score(similarity, validity) {
return Math.min(similarity, validity); // conservative lower bound
}
}
const strategy = validateScoringStrategy(new MinScoring());
const scorer = new TemporalScorer({ decayFn: decay, strategy });Decision-Theoretic Grounding
The decay coefficient β is not an arbitrary hyperparameter. Under Gaussian latent dynamics (Ornstein-Uhlenbeck process), the information-theoretically optimal decay rate is β = 2κ, where κ is the mean-reversion rate of the underlying process.
// If you know the domain dynamics, construct from κ directly
const decay = ExponentialDecay.fromMeanReversionRate({
vital_sign: 2.5, // β = 5.0
lab_result: 1.0, // β = 2.0
demographic: 0.0, // β = 0.0 (invariant)
});API Reference
| Class | Description |
|---|---|
| TemporalFact | Evidence tuple with .ageAt(queryTime) |
| ReasoningStep | One CoT step with associated facts |
| ReasoningTrace | Full reasoning chain over a query time |
| ExponentialDecay | β-parameterised; OU-optimal |
| HalfLifeDecay | Half-life parameterised |
| LinearDecay | Hard expiry at 1/rate |
| PowerLawDecay | Heavy-tailed decay |
| WeibullDecay | Generalised exponential |
| DecayFunction | Base class for custom backends |
| EpistemicFilter | τ-threshold gate; filter, partition, needsReacquisition |
| STLVerifier | STL robustness over knowledge validity |
| STLResult | Frozen: robustness, stepValidity, weakestFact, confidenceBound |
| CorpusStats | Temporal health: age/validity stats, staleness, gaps |
| BetaEstimator | Fit β from data; fit, fitCorpus, toDecay |
| MLEBernoulli | MLE under Bernoulli decay model |
| MomentMatching | Closed-form method-of-moments estimator |
| EnsembleMethod | Weighted combination of estimators |
| TemporalScorer | Rank facts by sim + validity; scoreFact, scoreFacts, rank |
| MultiplicativeScoring | sim × val |
| HarmonicScoring | 2·sim·val / (sim+val) |
| WeightedBlendScoring | α·sim + (1-α)·val |
| PowerScoring | sim^α · val^(1-α) |
| ScoringStrategy | Base class for custom strategies |
| DecayComparison | Compare decay backends: AUROC, Brier, log loss, Spearman ρ |
| validateDecayFunction | Smoke-test custom decay; returns fn on success |
| validateEstimationMethod | Smoke-test custom estimator |
| validateScoringStrategy | Smoke-test custom scoring strategy |
| PluginValidationError | Thrown by validators with descriptive message |
Citation
@misc{syed2026chronofytemporallogicaldecayarchitecture,
title = {Chronofy: A Temporal-Logical Decay Architecture for Information
Validity in Time-Aware Retrieval-Augmented Generation},
author = {Muntaser Syed and Marius Silaghi and Sheikh Abujar and
Sharun Akter},
year = {2026},
eprint = {2607.20560},
archivePrefix = {arXiv},
primaryClass = {cs.LG},
url = {https://arxiv.org/abs/2607.20560},
}License
MIT
