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
- type ValidityWindow
- func (w *ValidityWindow) Age() time.Duration
- func (w *ValidityWindow) DecayedConfidence() float64
- func (w *ValidityWindow) DecayedConfidenceAt(t time.Time) float64
- func (w *ValidityWindow) Duration() time.Duration
- func (w *ValidityWindow) Invalidate()
- func (w *ValidityWindow) InvalidateAt(t time.Time)
- func (w *ValidityWindow) IsValid() bool
- func (w *ValidityWindow) IsValidAt(t time.Time) bool
- func (w *ValidityWindow) SetHalfLife(d time.Duration)
Constants ¶
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.