Documentation
¶
Overview ¶
Package insight surfaces observations the vault already contains but nobody has stated out loud: a blocker that has survived several checkpoints without being resolved, a memory nobody has drawn on in months. Nothing here is invented — every generator reads checkpoints, memories or notes already in the vault and reports what pattern it found in them.
This ships one tier: mechanical, vault-only generators that need no model and no network. Filter enforces the same rule internal/ingest's distiller pipeline applies to a claim: an insight that cannot name the checkpoint or memory it came from is dropped before it is shown, not shown with a caveat (see internal/ingest/distil.go's doc comment on Filter). A stronger generator is not a more trusted one, and an insight is a claim like any other — the citation rule is the same rule for the same reason.
Index ¶
Constants ¶
const Degraded = "" /* 157-byte string literal not displayed */
Degraded explains, in one sentence, why Generate never does more than the mechanical tier: there is currently no model-augmented generator at all. It exists so a caller can announce the degradation (invariant 3) instead of a short list quietly reading as "there was nothing to find".
const DormantAfter = 60 * 24 * time.Hour
DormantAfter is how long a memory can go unused before it is worth a second look. Long enough that an ordinary lull between sessions on a project doesn't trip it, short enough that it still catches something a user genuinely forgot they knew.
Variables ¶
This section is empty.
Functions ¶
func Dormant ¶ added in v0.5.8
Dormant is the one rule for a memory taking space: not drawn on for DormantAfter and not pinned out of use. `logos stats` and the usage dashboard both ask it, so they never disagree about the same vault.
func Filter ¶
Filter applies the citation rule: no source, no insight. It is the same shape as internal/ingest.Filter for the same reason — a claim nobody can trace back to something in the vault is a fabrication with good manners, whether it came from a distiller reading a transcript or a generator reading a checkpoint.
func Generate ¶
Generate produces every insight the mechanical generators can find. project scopes to one project's checkpoints and memories; "" scans every project session.Projects lists and every memory regardless of project.
Callers must have already run memory.Init and session.Init against db — the same expectation every other package taking a *sql.DB in this codebase makes, so this package does not duplicate schema setup that belongs to the packages that own those tables.
func LastTouched ¶ added in v0.5.8
dormantMemories finds a memory nobody has drawn on in DormantAfter, so it can be re-confirmed, re-pinned, or forgotten rather than silently going stale. A memory already excluded from recall (PinNever) is not this generator's business — its owner already decided to stop hearing about it. LastTouched is when a memory was last drawn on, or written if never.
Types ¶
type Drop ¶
Drop is an insight the filter refused, and why. Dropped insights are returned, never discarded quietly (invariant 4) — a generator that found ten candidates and shipped six must not read as one that only ever found six.
type Insight ¶
type Insight struct {
Kind string // "recurring-blocker", "dormant-memory"
Text string // what to tell the user, in plain language
Sources []string // note path, "memory#<id>", or a checkpoint's vault slug
}
Insight is one observation, always traceable to what produced it.
type Scan ¶
Scan is what Generate looked at. It exists because "0 insights found" on its own is indistinguishable from a command that declined to run, and an empty state a user cannot tell apart from a broken one is the empty state they close the tool over. Reporting the size of the haystack turns it into "looked at this much, found nothing" (invariant 3).
Source Files