temporal

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 3, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package temporal provides bi-temporal validity windows for memory nodes. Each node tracks two time axes: when the fact was true in the real world (valid_from/invalid_at), and when yaad recorded it (transaction time via git commit). Confidence decays over time using an Ebbinghaus-inspired exponential curve, allowing stale facts to be deprioritised during retrieval.

Index

Constants

View Source
const DefaultHalfLife = 14 * 24 * time.Hour

DefaultHalfLife is the default duration after which confidence drops to 50%. 14 days mirrors the Ebbinghaus forgetting curve's first steep drop-off.

Variables

This section is empty.

Functions

This section is empty.

Types

type ValidityWindow added in v0.3.0

type ValidityWindow struct {
	// ValidFrom is the moment the fact became true (real-world axis).
	ValidFrom time.Time `json:"valid_from"`

	// InvalidAt is the moment the fact stopped being true.
	// Zero value means the fact is still considered valid.
	InvalidAt time.Time `json:"invalid_at,omitempty"`

	// GitCommit is the commit hash that recorded this fact (transaction axis).
	GitCommit string `json:"git_commit,omitempty"`

	// Confidence is the initial confidence score in [0,1].
	// It decays over time via DecayedConfidence.
	Confidence float64 `json:"confidence"`

	// HalfLife controls how fast confidence decays.
	// Zero value falls back to DefaultHalfLife.
	HalfLife time.Duration `json:"half_life,omitempty"`
	// contains filtered or unexported fields
}

ValidityWindow represents a bi-temporal validity record for a memory node. ValidFrom/InvalidAt track real-world truth; GitCommit tracks transaction time.

func NewWindow added in v0.3.0

func NewWindow(confidence float64, gitCommit string) *ValidityWindow

NewWindow creates a validity window that starts now with the given confidence.

func NewWindowAt added in v0.3.0

func NewWindowAt(validFrom time.Time, confidence float64, gitCommit string) *ValidityWindow

NewWindowAt creates a validity window starting at a specific time.

func (*ValidityWindow) Age added in v0.3.0

func (w *ValidityWindow) Age() time.Duration

Age returns how long the fact has been recorded (since ValidFrom).

func (*ValidityWindow) DecayedConfidence added in v0.3.0

func (w *ValidityWindow) DecayedConfidence() float64

DecayedConfidence returns the current confidence after applying Ebbinghaus-inspired exponential decay: C(t) = C0 * 2^(-age/half_life). This matches the forgetting curve where retention halves every half-life.

func (*ValidityWindow) DecayedConfidenceAt added in v0.3.0

func (w *ValidityWindow) DecayedConfidenceAt(t time.Time) float64

DecayedConfidenceAt returns what the confidence would be at time t.

func (*ValidityWindow) Duration added in v0.3.0

func (w *ValidityWindow) Duration() time.Duration

Duration returns how long the fact was (or has been) valid. For still-valid facts, this returns the time since ValidFrom. For invalidated facts, this returns InvalidAt - ValidFrom.

func (*ValidityWindow) Invalidate added in v0.3.0

func (w *ValidityWindow) Invalidate()

Invalidate marks the fact as no longer true, effective now.

func (*ValidityWindow) InvalidateAt added in v0.3.0

func (w *ValidityWindow) InvalidateAt(t time.Time)

InvalidateAt marks the fact as no longer true, effective at t.

func (*ValidityWindow) IsValid added in v0.3.0

func (w *ValidityWindow) IsValid() bool

IsValid reports whether the fact is currently considered true. A window is valid when InvalidAt is zero (not yet invalidated).

func (*ValidityWindow) IsValidAt added in v0.3.0

func (w *ValidityWindow) IsValidAt(t time.Time) bool

IsValidAt reports whether the fact was valid at a specific point in time.

func (*ValidityWindow) SetHalfLife added in v0.3.0

func (w *ValidityWindow) SetHalfLife(d time.Duration)

SetHalfLife overrides the decay half-life for this window.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL