semcache

Documentation

Overview

Package semcache is a deterministic, local semantic cache: it serves a previously stored result for a *similar* (not just identical) input, using Jaccard similarity over word-shingle signatures. Unlike the exact content-hash cache in internal/cache, this catches reworded or near-duplicate prompts and logs without any network or embedding model — everything is computed locally and is fully reproducible.

Index

• Constants
• func Clear(ns string) error
• func Entries(ns string) ([]string, error)
• func Lookup(ns, input string, v any, thr float64) (matched string, sim float64, hit bool, err error)
• func Similarity(a, b string) float64
• func Stats() (map[string]int, error)
• func Store(ns, input string, v any) error

Constants

const DefaultThreshold = 0.60

DefaultThreshold is the minimum Jaccard similarity for a hit on inputs with enough shingles to compare. 0.60 requires ~60% shingle overlap, which clear near-duplicates reach while unrelated text (even when it shares a common attached log) stays far below. This is deliberately conservative to avoid serving one prompt's cached result for another.

const MaxEntries = 200

MaxEntries bounds the in-memory and on-disk index per namespace.

const MaxInputLen = 2048

MaxInputLen caps the stored raw input per entry. Matching uses the bounded shingle signature; only a truncated preview of the input is kept on disk/in memory for the "matched" report and Entries() so long prompts and attached logs cannot balloon the index into many MB.

const MaxShingles = 2000

MaxShingles caps the signature size so a multi-megabyte log costs the same to compare as a prompt. Shingles are dropped deterministically (by hash), so the signature is stable across runs.

const ShortThreshold = 0.7

ShortThreshold applies to very short inputs (< 6 shingles) where Jaccard is noisy; require a closer match to avoid false positives.

Functions

func Clear

func Clear(ns string) error

Clear wipes the index (and payloads) for a namespace, or all namespaces when ns is empty. In-memory state is only updated after the on-disk removal succeeds, so a failure cannot leave memory and disk out of sync.

func Entries

func Entries(ns string) ([]string, error)

Entries reports the current index size and the stored inputs (most recent first) for a namespace.

func Lookup

func Lookup(ns, input string, v any, thr float64) (matched string, sim float64, hit bool, err error)

Lookup searches namespace ns for a stored entry whose input is similar enough to input. On a hit it loads the payload into v and returns the matched input, the similarity, and true. Thresholds: ShortThreshold for short inputs, else DefaultThreshold (overridable via thr when > 0).

func Similarity

func Similarity(a, b string) float64

Similarity returns the Jaccard similarity of a and b over their shingle sets: intersection / union. Returns 1 for identical, 0 for disjoint.

func Stats

func Stats() (map[string]int, error)

Stats returns the number of entries per namespace that have an on-disk index.

func Store

func Store(ns, input string, v any) error

Store records input -> v under namespace for future fuzzy hits. Entries are appended and the index is capped at MaxEntries (oldest dropped first).