vec

Documentation

Index

• func Init()
• type Entry
• type Fallback
  • func NewFallback(db *sql.DB) (*Fallback, error)
  • func (f *Fallback) Available() bool
  • func (f *Fallback) Close() error
  • func (f *Fallback) Delete(ctx context.Context, agentID, id string) error
  • func (f *Fallback) Get(ctx context.Context, agentID, id string) (*Entry, error)
  • func (f *Fallback) Search(ctx context.Context, agentID string, q []float32, topK int) ([]Hit, error)
  • func (f *Fallback) SearchByKeywords(ctx context.Context, agentID, query string, topK int) ([]Hit, error)
  • func (f *Fallback) Upsert(ctx context.Context, e Entry) error
• type Hit
• type SQLiteVec
  • func NewSQLiteVec(db *sql.DB, dimensions int) (*SQLiteVec, error)
  • func (v *SQLiteVec) Available() bool
  • func (v *SQLiteVec) Close() error
  • func (v *SQLiteVec) Delete(ctx context.Context, agentID, id string) error
  • func (v *SQLiteVec) Get(ctx context.Context, agentID, id string) (*Entry, error)
  • func (v *SQLiteVec) Search(ctx context.Context, agentID string, q []float32, topK int) ([]Hit, error)
  • func (v *SQLiteVec) SearchByKeywords(ctx context.Context, agentID, query string, topK int) ([]Hit, error)
  • func (v *SQLiteVec) Upsert(ctx context.Context, e Entry) error
• type VectorIndex

Functions

func Init

func Init()

Init registers the sqlite-vec auto-extension. It must be called BEFORE any database/sql connection is opened (sqlite3_auto_extension only affects connections created afterwards). Idempotent; safe to call once at startup.

Types

type Entry

type Entry struct {
	ID       string // page or interest-point id
	AgentID  string // namespace
	Kind     string // "interest_point" | "wiki_page"
	Vector   []float32
	Metadata map[string]string // title, page_type, etc.
}

Entry is one vector record to index.

type Fallback

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

Fallback implements VectorIndex with keyword-only search (no sqlite-vec). It mirrors the vec metadata in a plain table and searches with LIKE. This is the degradation path when sqlite-vec is unavailable.

func NewFallback

func NewFallback(db *sql.DB) (*Fallback, error)

NewFallback creates the keyword fallback store.

func (*Fallback) Available

func (f *Fallback) Available() bool

Available always reports true: the fallback is usable, but only for keyword search, never real vector search.

func (*Fallback) Close

func (f *Fallback) Close() error

func (*Fallback) Delete

func (f *Fallback) Delete(ctx context.Context, agentID, id string) error

func (*Fallback) Get

func (f *Fallback) Get(ctx context.Context, agentID, id string) (*Entry, error)

Get implements VectorIndex. The keyword fallback does not store vectors, so it always returns nil, nil (no historical vector available to recall).

func (*Fallback) Search

func (f *Fallback) Search(ctx context.Context, agentID string, q []float32, topK int) ([]Hit, error)

func (*Fallback) SearchByKeywords

func (f *Fallback) SearchByKeywords(ctx context.Context, agentID, query string, topK int) ([]Hit, error)

func (*Fallback) Upsert

func (f *Fallback) Upsert(ctx context.Context, e Entry) error

Upsert stores the metadata (vector is ignored in fallback mode).

type Hit

type Hit struct {
	ID      string
	AgentID string
	Kind    string
	Score   float32 // cosine similarity / relevance, higher is better
	Meta    map[string]string
}

Hit is a search result.

type SQLiteVec

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

SQLiteVec implements VectorIndex over sqlite-vec vec0 virtual tables, sharing the caller's *sql.DB (database/sql abstraction).

One vec0 table per kind (interest_point / wiki_page), each with a fixed dimension set at construction. Tables are created lazily on first use.

func NewSQLiteVec

func NewSQLiteVec(db *sql.DB, dimensions int) (*SQLiteVec, error)

NewSQLiteVec opens the vec layer on the shared database connection. Call Init() before the store opens its connection for the extension to load.

func (*SQLiteVec) Available

func (v *SQLiteVec) Available() bool

Available reports whether sqlite-vec is operational.

func (*SQLiteVec) Close

func (v *SQLiteVec) Close() error

Close implements VectorIndex.

func (*SQLiteVec) Delete

func (v *SQLiteVec) Delete(ctx context.Context, agentID, id string) error

Delete implements VectorIndex.

func (*SQLiteVec) Get

func (v *SQLiteVec) Get(ctx context.Context, agentID, id string) (*Entry, error)

Get implements VectorIndex: returns the stored entry for one id, decoding the stored (L2-normalized) embedding blob back into a []float32. Returns nil, nil when the id does not exist in either kind table.

func (*SQLiteVec) Search

func (v *SQLiteVec) Search(ctx context.Context, agentID string, q []float32, topK int) ([]Hit, error)

Search implements VectorIndex (KNN via vec0 MATCH).

func (*SQLiteVec) SearchByKeywords

func (v *SQLiteVec) SearchByKeywords(ctx context.Context, agentID, query string, topK int) ([]Hit, error)

SearchByKeywords is a no-op pass-through for SQLiteVec; the FTS fallback implementation handles keyword-only search. Kept to satisfy VectorIndex.

func (*SQLiteVec) Upsert

func (v *SQLiteVec) Upsert(ctx context.Context, e Entry) error

Upsert implements VectorIndex.

type VectorIndex

type VectorIndex interface {
	// Upsert inserts or replaces an entry's vector.
	Upsert(ctx context.Context, e Entry) error
	// Search returns the top-K most similar entries for a query vector.
	Search(ctx context.Context, agentID string, q []float32, topK int) ([]Hit, error)
	// SearchByKeywords falls back to keyword matching (used when vectors
	// are unavailable or query has no meaningful embedding).
	SearchByKeywords(ctx context.Context, agentID, query string, topK int) ([]Hit, error)
	// Get returns the stored entry (including its raw embedding vector) for
	// one id, or nil when absent. Used to fetch historical vectors so the
	// caller can recompute exact pairwise similarity instead of relying on
	// Search's ranking scores.
	Get(ctx context.Context, agentID, id string) (*Entry, error)
	// Delete removes an entry by id.
	Delete(ctx context.Context, agentID, id string) error
	// Available reports whether the index is usable at all (vector search
	// may still be a keyword-only degradation for the Fallback).
	Available() bool
	Close() error
}

VectorIndex is the pluggable vector store interface. Implementations:

• SQLiteVec: sqlite-vec vec0 virtual table over the shared *sql.DB
• Fallback: keyword-only search (plain metadata table + LIKE) when sqlite-vec is unavailable