search

package
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package search builds a persistent, ranked index over Claude Code session transcripts: full-text (SQLite FTS5, BM25) plus optional embeddings for semantic ranking. Automated sessions (SDK/cron runs) are flagged so they can be filtered out of results.

Index

Constants

View Source
const (
	ModeHybrid   = "hybrid"   // keyword + semantic (falls back to keyword without an embedder)
	ModeKeyword  = "keyword"  // BM25 only
	ModeSemantic = "semantic" // embeddings only
)

Ranking modes for Service.Query.

View Source
const AnyTermCap = 20

AnyTermCap bounds the any-term fallback: once nothing covers enough of the query, a loose match is a guess, and a long list of guesses buries the point.

Variables

Modes lists the valid ranking modes.

Functions

func DefaultArchiveDir

func DefaultArchiveDir() string

DefaultArchiveDir holds transcripts kept past Claude Code's cleanup, in the ~/.claude/projects layout.

func DefaultPath

func DefaultPath() string

DefaultPath is ~/.aimux/search.db.

func HasPhrase

func HasPhrase(q string) bool

HasPhrase reports whether q asks for an exact phrase.

Types

type AmbiguousError

type AmbiguousError struct {
	Prefix     string
	Candidates []Result
}

AmbiguousError reports a session ID prefix that matches more than one session.

func (*AmbiguousError) Error

func (e *AmbiguousError) Error() string

type Chunk

type Chunk struct {
	Seq    int
	Prompt string // the human message that opened the exchange, one line
	Text   string // searchable: messages, tool calls, trimmed tool output (first MaxChunkChars)
	More   string // the rest of a long exchange (up to MaxTextChars), searched at a lower weight
	Prose  string // only what was said (human + assistant text), for embeddings
}

Chunk is one exchange: a human message plus the assistant text, tool calls and tool output that followed it.

type Detail

type Detail struct {
	SessionID     string
	Path          string
	CWD           string
	Title         string
	FirstPrompt   string
	Automated     bool
	ModTime       time.Time
	Exchanges     int
	RecentPrompts []string // oldest first
}

Detail is what a picker preview shows for one session.

type Doc

type Doc struct {
	SessionID   string
	Path        string
	CWD         string
	Title       string // custom title > latest ai-title > first prompt
	FirstPrompt string
	Automated   bool
	ModTime     time.Time
	Chunks      []Chunk
}

Doc is one session transcript reduced to searchable text.

func ExtractFile

func ExtractFile(path string, opts ExtractOpts) (Doc, error)

ExtractFile parses a session JSONL file. Malformed lines are skipped.

type Embedder

type Embedder interface {
	Model() string
	Embed(ctx context.Context, texts []string) ([][]float32, error)
}

Embedder turns text into vectors. Model identifies the vector space, so vectors from different models are never compared.

type Exchange

type Exchange struct {
	Seq    int
	Prompt string
	Prose  string
}

Exchange is one indexed exchange: the prompt that opened it and what was said (human and assistant text, no tool output).

type ExtractOpts

type ExtractOpts struct {
	AutomatedPrefixes  []string // first-prompt prefixes that mark a session as automated
	MaxChunkChars      int      // embedding budget; prose is kept within half of it
	MaxTextChars       int      // searchable text per exchange (full-text index)
	MaxToolOutputChars int
}

ExtractOpts controls what gets indexed and how much of it.

func DefaultExtractOpts

func DefaultExtractOpts() ExtractOpts

DefaultExtractOpts returns limits sized for embedding (~1k tokens per chunk).

type Index

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

Index is a persistent full-text index over session transcripts.

func Open

func Open(path string) (*Index, error)

Open opens (creating if needed) the index database at path.

func (*Index) CachedEmbedder

func (ix *Index) CachedEmbedder(e Embedder) Embedder

CachedEmbedder wraps e so single-text embeds (search queries) are stored in the index and reused: retyping or backspacing to an earlier query costs no API call. Batches pass straight through.

func (*Index) Close

func (ix *Index) Close() error

Close releases the database.

func (*Index) Detail

func (ix *Index) Detail(sessionID string, n int) (Detail, error)

Detail returns preview data for one session, with its last n prompts.

func (*Index) EmbedMissing

func (ix *Index) EmbedMissing(ctx context.Context, e Embedder, batchSize int) (int, error)

EmbedMissing embeds, for every non-automated session, each chunk's prose and one session summary that have no vector for e's model yet, batchSize texts per request. Each batch is committed on its own, so an interrupted run keeps its progress.

func (*Index) EmbedMissingFor

func (ix *Index) EmbedMissingFor(ctx context.Context, e Embedder, sessionIDs []string, batchSize int) (int, error)

EmbedMissingFor is EmbedMissing limited to the given sessions (typically UpdateStats.Changed), so a search only inspects what just changed instead of hashing every exchange in the index.

func (*Index) Exchanges

func (ix *Index) Exchanges(sessionID string) ([]Exchange, error)

Exchanges returns every indexed exchange of a session in order.

func (*Index) Hybrid

func (ix *Index) Hybrid(ctx context.Context, query string, opts SearchOpts, e Embedder) (rs []Result, used bool, err error)

Hybrid fuses keyword (BM25) and semantic rankings with reciprocal rank fusion. It degrades to keyword results, with used=false, when there is no embedder, the embedder fails, or no vectors are stored yet.

func (*Index) PendingEmbeddings

func (ix *Index) PendingEmbeddings(model string) (int, error)

PendingEmbeddings counts texts (chunks and session summaries) of non-automated sessions with no vector for model.

func (*Index) Recent

func (ix *Index) Recent(opts SearchOpts) ([]Result, error)

Recent lists sessions by last activity, newest first.

func (*Index) Resolve

func (ix *Index) Resolve(idOrPrefix string) (string, error)

Resolve maps a full session ID or a unique prefix of one to the full ID. Automated sessions resolve too: an explicit ID always wins over filters.

func (*Index) Search

func (ix *Index) Search(query string, opts SearchOpts) ([]Result, error)

Search returns sessions matching query, best first, ranked by the BM25 score of their best chunk. Text in double quotes must appear as an exact phrase (an unclosed quote is a phrase up to the end, its last word a prefix, so it works while typing). Free words: chunks covering fewer than minCoverage of them are dropped; if no session qualifies, up to AnyTermCap sessions matching any word are returned. Titles naming the query are lifted to the top (tierByTitle).

func (*Index) Semantic

func (ix *Index) Semantic(ctx context.Context, query string, opts SearchOpts, e Embedder) ([]Result, error)

Semantic ranks sessions by cosine similarity between the query and their best vector (a chunk or the session summary). It returns nothing (and no error) if no vectors are stored.

func (*Index) Update

func (ix *Index) Update(projectsDir string, opts ExtractOpts, archiveDirs ...string) (UpdateStats, error)

Update brings the index in line with the session files under projectsDir and any archiveDirs (layout: <dir>/<project>/<session-id>.jsonl). A session in projectsDir wins over an archived copy. Only new, changed or moved files are re-read. A session is removed only when its recorded file is gone and no scanned dir has it, so an Update that does not scan an archive never drops that archive's sessions.

type OpenAIEmbedder

type OpenAIEmbedder struct {
	APIKey     string
	BaseURL    string // default https://api.openai.com
	ModelName  string // default text-embedding-3-small
	Dimensions int    // 0 = model default; 512 keeps the index small
	HTTPClient *http.Client
}

OpenAIEmbedder calls the OpenAI embeddings API.

func NewOpenAIEmbedderFromEnv

func NewOpenAIEmbedderFromEnv() *OpenAIEmbedder

NewOpenAIEmbedderFromEnv returns an embedder using OPENAI_API_KEY, or nil when the variable is unset so callers can fall back to keyword search.

func (*OpenAIEmbedder) Embed

func (o *OpenAIEmbedder) Embed(ctx context.Context, texts []string) ([][]float32, error)

Embed returns one vector per input text, in input order.

func (*OpenAIEmbedder) Model

func (o *OpenAIEmbedder) Model() string

Model identifies the vector space (model and dimensions).

type QueryOpts

type QueryOpts struct {
	Mode             string // "" means hybrid
	Limit            int
	IncludeAutomated bool
	Dir              string   // only sessions under this working directory
	IDs              []string // only these sessions; nil = no restriction, empty = none
}

QueryOpts narrows a Service query.

type Result

type Result struct {
	SessionID string
	Path      string
	CWD       string
	Title     string
	Automated bool
	ModTime   time.Time
	Snippet   string
	Score     float64 // lower is better (BM25)
	// contains filtered or unexported fields
}

Result is one matching session, best-scoring chunk first.

type SearchOpts

type SearchOpts struct {
	Limit            int
	IncludeAutomated bool
	Dir              string   // only sessions whose cwd is Dir or below it
	IDs              []string // only these sessions; nil = no restriction, empty = none
}

SearchOpts narrows a search.

type Service

type Service struct {
	DBPath      string
	ProjectsDir string
	ArchiveDirs []string  // also indexed; sessions here outlive Claude Code's cleanup
	Embedder    Embedder  // nil: keyword only
	Notes       io.Writer // explanations of degraded modes; nil discards
	// contains filtered or unexported fields
}

Service is the one entry point every frontend (CLI, TUI, web) uses to search sessions: it refreshes the index, then ranks.

func DefaultService

func DefaultService(notes io.Writer) *Service

DefaultService searches ~/.aimux/search.db over ~/.claude/projects and ~/.aimux/archive, with OpenAI embeddings when OPENAI_API_KEY is set.

func (*Service) Query

func (s *Service) Query(ctx context.Context, query string, o QueryOpts) ([]Result, bool, error)

Query refreshes the index (only changed files are re-read) and returns sessions best first, and whether semantic ranking contributed.

func (*Service) Recent

func (s *Service) Recent(ctx context.Context, o SearchOpts) ([]Result, error)

Recent refreshes the index and lists sessions by last activity.

func (*Service) Refresh

func (s *Service) Refresh(ctx context.Context) error

Refresh brings the index up to date and embeds what changed, without querying. The picker runs it in the background so hybrid ranking sees new sessions too.

func (*Service) Session

func (s *Service) Session(ctx context.Context, idOrPrefix string) (Transcript, error)

Session refreshes the index, resolves an ID or unique prefix, and returns the whole session. Resolve errors come back unwrapped, so callers can errors.As them into *AmbiguousError.

type Transcript

type Transcript struct {
	Detail    Detail
	Exchanges []Exchange
}

Transcript is one session's preview data plus every exchange in order.

type UpdateStats

type UpdateStats struct {
	Indexed int      // sessions (re)read because they were new or changed
	Changed []string // ids of those sessions
	Removed int      // sessions dropped because their file is gone
	Total   int      // sessions in the index afterwards
}

UpdateStats reports what an Update changed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL