Skip to content

Misleading comments: toFrecencyInput claims tracking fields aren't stored in TOMLs #376

@toejough

Description

@toejough

Problem

Two comments in the codebase falsely claim that tracking fields are not stored in TOML files:

1. internal/surface/surface.go (lines 1467-1470)

// toFrecencyInput converts a stored memory to a frecency input.
// Tracking fields (SurfacedCount, LastSurfaced, SurfacingContexts) are no longer
// stored inline in TOMLs — they default to zero, falling back to recency-only ranking.
// Future: populate from instruction registry for full frecency scoring.

2. internal/track/track.go (lines 19-22)

// ComputeUpdate calculates new tracking values after a surfacing event.
// Takes explicit current values rather than reading from memory.Stored,
// since tracking fields are no longer stored inline in TOMLs (UC-23).

What's actually true

Tracking fields ARE stored in TOMLs. Evidence:

  • internal/memory/record.go defines SurfacedCount int \toml:"surfaced_count"`andLastSurfacedAt string `toml:"last_surfaced_at"``
  • Real TOML files contain surfaced_count = 379, last_surfaced_at = "2026-03-24T21:52:47Z", etc.
  • memory.Stored struct has SurfacedCount int (memory.go:92)

Impact

The misleading comment in toFrecencyInput caused the function to not wire SurfacedCount or LastSurfaced into frecency.Input. As a result, frecency activation is always zero in prompt/tool modes:

  • freq = ln(1 + 0) = 0 → entire product is zero
  • CombinedScore = BM25 × (1 + 0) = BM25 → frecency re-ranking is a no-op

The frecency formula exists, the data exists, but they aren't connected — because a stale comment convinced someone (or an LLM) that the data wasn't available.

Fix

  1. Delete the misleading comments
  2. Wire SurfacedCount and LastSurfacedAt from memory.Stored into toFrecencyInput
  3. (Part of Rebalance frecency formula: recency factor dominates all other signals #374's scope)

🤖 Generated with Claude Code

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions