prefs

Documentation

Overview

Package prefs is the preference-learning reducer. It scans preference_signal events from the event log (the source of truth), clusters them by axis + lexical similarity, weighs each cluster with recency decay, tracks contradictions, and materializes the resulting candidates into the preference_candidates table atomically. Promotion to a standing plaintext rule (and demotion on contradiction) is a separate, silent step in StartChat (see promote.go) — this package is pure over the event log and makes no LLM calls.

Index

• func ConfirmPath(root, id string) string
• type Candidate
  • func PendingDemotions(cands []Candidate, _ store.Store) ([]Candidate, error)
  • func PendingPromotions(cands []Candidate) []Candidate
  • func Reduce(ctx context.Context, st store.Store) ([]Candidate, error)
• type SignalRef

Functions

func ConfirmPath

func ConfirmPath(root, id string) string

ConfirmPath resolves the plaintext file for a confirmed preference under .memcode/prefs/. The file is written as <id>-<slug>.md (see writeConfirmedPref), so this globs <id>-*.md rather than guessing the slug — the previous <id>.md form never matched, so demotion deleted a nonexistent path and the binding file survived. Falls back to the legacy <id>.md if no slugged file is found.

Types

type Candidate

type Candidate struct {
	ID            string
	Axis          string
	Text          string
	Scope         string
	Weight        float64
	SignalCount   int
	SessionCount  int
	FirstSeen     time.Time
	LastSeen      time.Time
	Status        string
	ConfirmedPath string // set when Status=="confirmed" — the exact plaintext file to revoke
	Evidence      []SignalRef

	// Contradictions is the count of same-axis signals with opposite polarity
	// that contradicted this candidate. Used by PendingDemotions to decide whether
	// a confirmed pref has been overturned.
	Contradictions int
}

Candidate is a clustered, weighted preference candidate — the reducer's output before promotion/demotion decides its fate. It maps 1:1 onto a store.PreferenceCandidate row.

func PendingDemotions

func PendingDemotions(cands []Candidate, _ store.Store) ([]Candidate, error)

PendingDemotions returns CONFIRMED candidates whose contradiction signal count (from the event log, via the reducer's Contradictions field) has crossed contradictionThreshold — the user has pushed back enough that the standing preference should be demoted. The caller passes the candidates from Reduce (which carries Contradictions); the store parameter is accepted for the v2 case where demotion needs to re-scan the event log for fresh contradictions since the last Reduce. For v1 the candidates already carry the count.

func PendingPromotions

func PendingPromotions(cands []Candidate) []Candidate

PendingPromotions returns candidates that have crossed the evidence bar and are ready to be promoted to standing plaintext rules: weight ≥ promotionThreshold, ≥ minSignals signals, ≥ minSessions sessions, and status is still "candidate" (not already confirmed or demoted). Sorted by weight descending so the strongest preferences promote first.

func Reduce

func Reduce(ctx context.Context, st store.Store) ([]Candidate, error)

Reduce scans preference_signal events, clusters them, weighs them with recency decay, tracks contradictions, and materializes the candidates into the preference_candidates table atomically (ClearPreferenceCandidates + a batch of AddPreferenceCandidate in a single RunInTx — same pattern as learn.Run). It returns the candidates so the caller (applyPreferencePromotions) can decide promotions and demotions.

type SignalRef

type SignalRef struct {
	SessionID string    `json:"session_id"`
	Text      string    `json:"text"`
	Strength  float64   `json:"strength"`
	TS        time.Time `json:"ts"`
	HeadSHA   string    `json:"head_sha,omitempty"` // repo HEAD when the directive was given — provenance
}

SignalRef is a pointer back to the event that contributed to a candidate — so the promotion notice and the introspect tool can show evidence (which sessions, what text). It's the "why did this become a rule" trail.