recall

Documentation

Overview

Package recall answers natural-language questions about a repository's prose memory — "where did we decide X?", "what's our policy on Y?" — by ranking the corpus of source docs, adjudicated claims, and human decisions against the question with BM25 plus memcode-aware boosts (claim status, recency, scope, source kind, exact phrase). It is deliberately NOT embeddings: lexical search over prose is cheap, offline, deterministic, and "good enough" until a measured recall eval proves otherwise. Code questions ("where is this handler/symbol/test?") are answered by exact tools instead — `memcode explore` and the agent's rg/read/git tools — not here.

The ranking respects memcode doctrine: current beats stale, scope matters, recent reality matters, evidence is not truth — but a query that explicitly asks about history/conflicts surfaces stale and conflicted material instead of burying it.

Index

• type Category
• type Chunk
  • func Corpus(ctx context.Context, st store.Store, root string) ([]Chunk, error)
• type Hit
  • func Recall(ctx context.Context, st store.Store, root, query, scopePath string, k int) ([]Hit, error)

Types

type Category

type Category string

Category groups a chunk by its source kind, which drives weighting.

const (
	CatDoc   Category = "doc"   // a source document (CLAUDE.md, README, AGENTS.md, docs)
	CatClaim Category = "claim" // an adjudicated claim
	CatEvent Category = "event" // a human decision/assertion/note
	CatRule  Category = "rule"  // a promoted standing rule (confirmed preference / distilled lesson)
)

type Chunk

type Chunk struct {
	ID     string
	Text   string
	Source string // human-readable provenance

	Cat    Category
	Kind   string    // doc: claude/readme/docs/…; claim: claim type; event: decision/…
	Status string    // claim status (current|candidate|stale|conflicted)
	Stale  bool      // source doc is stale relative to the code it governs
	Scope  string    // dir it governs ("." = repo, "" = none)
	When   time.Time // recency signal (doc git date / event timestamp)
}

Chunk is one unit of prose with its provenance and ranking signals.

func Corpus

func Corpus(ctx context.Context, st store.Store, root string) ([]Chunk, error)

Corpus assembles the prose corpus from source docs, adjudicated claims, and decision-bearing events, each tagged with its ranking signals.

type Hit

type Hit struct {
	Chunk Chunk
	Score float64
}

Hit is a ranked chunk.

func Recall

func Recall(ctx context.Context, st store.Store, root, query, scopePath string, k int) ([]Hit, error)

Recall ranks the prose corpus against query and returns the top k hits with a positive score. scopePath (may be "") boosts chunks governing that path.