store

Documentation

Overview

Package store wraps the sqlite + sqlite-vec database: a files table keyed by (path, model, version), a chunks table, and one vec0 table per (modelName, version). There are no tracked-source/exclusion tables.

Index

• Constants
• func ChunkKey(headingContext, text string) string
• type ChunkRow
• type FileMeta
• type SearchResult
• type Stats
• type Store
  • func Open(dbPath string) (*Store, error)
  • func (s *Store) ChunkEmbeddings(path, modelName string) (map[string]embed.Embedding, error)
  • func (s *Store) CleanupOrphans(activeModels []string) error
  • func (s *Store) Close() error
  • func (s *Store) DeleteFile(path, modelName string) error
  • func (s *Store) EnsureVecTable(modelName string, dims int) error
  • func (s *Store) IndexedFiles(modelName string) (map[string]FileMeta, error)
  • func (s *Store) PutFile(path, modelName, blobSha string, rows []ChunkRow, embeddings []embed.Embedding) error
  • func (s *Store) Search(modelName string, query embed.Embedding, topK int) ([]SearchResult, error)
  • func (s *Store) Stats(modelName string) (Stats, error)
  • func (s *Store) Vacuum() error

Constants

const MajorVersion = 11

MajorVersion is the embedding compatibility identity ("major version"). Together with the embedding model_name (which already encodes model@dims), it forms the major identity that keys each vec table and the files row, and determines when a stored vector is still usable. Bump it whenever anything that changes the meaning of an embedding changes: the chunking algorithm, breadcrumb/heading-context handling, tree-sitter grammars, or the tags.scm / pkb chunking logic. Bumping it isolates old vectors into separate vec tables and forces a full recompute.

Functions

func ChunkKey

func ChunkKey(headingContext, text string) string

ChunkKey is the reuse key for a chunk: the deterministic inputs to its embedding (heading breadcrumb + raw text). A chunk re-embeds when its text or any parent heading/breadcrumb changes, but is reused otherwise.

Types

type ChunkRow

type ChunkRow struct {
	Text           string
	Contextualized string
	HeadingContext string
	StartLine      int
	StartCol       int
	EndLine        int
	EndCol         int
}

ChunkRow is a single chunk's cache row: the text actually embedded, its display/situating context, and its line/col extent (derived from the stored byte offsets at reconstruction time).

type FileMeta

type FileMeta struct {
	Sha string
}

FileMeta records the reuse-relevant metadata stored for an indexed file: the blob sha.

type SearchResult

type SearchResult struct {
	Path           string
	Text           string
	HeadingContext string
	StartLine      int
	EndLine        int
	Score          float64
}

SearchResult is one hit from a vector search.

type Stats

type Stats struct {
	Files  int
	Chunks int
}

Stats holds index counts for a model.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store owns the database connection.

func Open

func Open(dbPath string) (*Store, error)

Open opens (creating if needed) the database at dbPath and ensures the base schema exists.

func (*Store) ChunkEmbeddings

func (s *Store) ChunkEmbeddings(path, modelName string) (map[string]embed.Embedding, error)

ChunkEmbeddings returns a map of ChunkKey -> embedding for a path/model, so an incremental reindex can reuse vectors for unchanged chunks instead of re-embedding them. Duplicate keys collapse harmlessly (identical deterministic input yields an identical embedding).

func (*Store) CleanupOrphans

func (s *Store) CleanupOrphans(activeModels []string) error

CleanupOrphans drops vec tables and removes files/chunks rows for any model that is not in activeModels (at the current MajorVersion). This is how a model-name change reclaims storage instead of silently mixing vectors.

func (*Store) Close

func (s *Store) Close() error

Close closes the underlying database.

func (*Store) DeleteFile

func (s *Store) DeleteFile(path, modelName string) error

DeleteFile removes a file's row, its chunks, and its vec entries.

func (*Store) EnsureVecTable

func (s *Store) EnsureVecTable(modelName string, dims int) error

EnsureVecTable creates the vec0 table for a model if it does not exist.

func (*Store) IndexedFiles

func (s *Store) IndexedFiles(modelName string) (map[string]FileMeta, error)

IndexedFiles returns a map of relative path -> FileMeta for files already indexed by the given model.

func (*Store) PutFile

func (s *Store) PutFile(path, modelName, blobSha string, rows []ChunkRow, embeddings []embed.Embedding) error

PutFile (re)indexes a single file in one transaction: it deletes any existing rows for the path, inserts the file row recording the new blob sha, then inserts every chunk (with its vector). Because the whole write is a single transaction, a crash leaves the previously committed state intact, so the file is simply reindexed on the next run; expensive embedding work has already been done in memory by the caller before this is invoked.

func (*Store) Search

func (s *Store) Search(modelName string, query embed.Embedding, topK int) ([]SearchResult, error)

Search queries a model's vec table for the topK nearest chunks to the query embedding.

func (*Store) Stats

func (s *Store) Stats(modelName string) (Stats, error)

Stats returns file and chunk counts for a model.

func (*Store) Vacuum

func (s *Store) Vacuum() error

Vacuum reclaims free pages left behind by reindex churn, shrinking the db file to its live size.