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
- Variables
- func DefaultArchiveDir() string
- func DefaultPath() string
- func HasPhrase(q string) bool
- type AmbiguousError
- type Chunk
- type Detail
- type Doc
- type Embedder
- type Exchange
- type ExtractOpts
- type Index
- func (ix *Index) CachedEmbedder(e Embedder) Embedder
- func (ix *Index) Close() error
- func (ix *Index) Detail(sessionID string, n int) (Detail, error)
- func (ix *Index) EmbedMissing(ctx context.Context, e Embedder, batchSize int) (int, error)
- func (ix *Index) EmbedMissingFor(ctx context.Context, e Embedder, sessionIDs []string, batchSize int) (int, error)
- func (ix *Index) Exchanges(sessionID string) ([]Exchange, error)
- func (ix *Index) Hybrid(ctx context.Context, query string, opts SearchOpts, e Embedder) (rs []Result, used bool, err error)
- func (ix *Index) PendingEmbeddings(model string) (int, error)
- func (ix *Index) Recent(opts SearchOpts) ([]Result, error)
- func (ix *Index) RecentWhere(opts SearchOpts, pageSize, maxPages int, keep func(Result) bool) (rows []Result, capped bool, err error)
- func (ix *Index) Resolve(idOrPrefix string) (string, error)
- func (ix *Index) Search(query string, opts SearchOpts) ([]Result, error)
- func (ix *Index) Semantic(ctx context.Context, query string, opts SearchOpts, e Embedder) ([]Result, error)
- func (ix *Index) Update(projectsDir string, opts ExtractOpts, archiveDirs ...string) (UpdateStats, error)
- type OpenAIEmbedder
- type QueryOpts
- type Result
- type SearchOpts
- type Service
- func (s *Service) Query(ctx context.Context, query string, o QueryOpts) ([]Result, bool, error)
- func (s *Service) Recent(ctx context.Context, o SearchOpts) ([]Result, error)
- func (s *Service) RecentWhere(ctx context.Context, o SearchOpts, pageSize, maxPages int, ...) ([]Result, bool, error)
- func (s *Service) Refresh(ctx context.Context) error
- func (s *Service) Session(ctx context.Context, idOrPrefix string) (Transcript, error)
- func (s *Service) Wait()
- type Transcript
- type UpdateStats
Constants ¶
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.
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 ¶
var ErrNewerIndex = errors.New("search index was written by a newer aimux; not refreshing it")
ErrNewerIndex is Update's answer for an index a newer aimux wrote: this build serves it as it is and leaves the refresh to that aimux.
var Modes = []string{ModeHybrid, ModeKeyword, ModeSemantic}
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.
Types ¶
type AmbiguousError ¶
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 // history.ShownTitle: owner's meta title, /rename, namer's meta title, ai-title, first message
FirstPrompt string
Automated bool
ModTime time.Time
MetaModTime int64 // .meta.json mtime (UnixNano) when Title was read; 0 without one
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 ¶
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 (*Index) CachedEmbedder ¶
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) EmbedMissing ¶
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) 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 ¶
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) RecentWhere ¶ added in v0.14.0
func (ix *Index) RecentWhere(opts SearchOpts, pageSize, maxPages int, keep func(Result) bool) (rows []Result, capped bool, err error)
RecentWhere is Recent with a filter that does not cost rows: it reads pages of pageSize rows, keeps the rows keep accepts, and stops at opts.Limit kept rows (<= 0: 200), at the end of the index, or after maxPages pages; capped reports that the page cap stopped it with rows left unread.
func (*Index) Resolve ¶
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) 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
NoRefresh bool // skip the file scan; the caller keeps the index fresh
}
QueryOpts narrows a Service query.
type Result ¶
type Result struct {
SessionID string
Path string
CWD string
Title string
// FirstPrompt is the session's first message; only Recent fills it.
FirstPrompt 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
// Since: only sessions modified after it (Recent and RecentWhere only).
Since time.Time
}
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
// EmbedInBackground queues changed sessions for embedding instead of
// waiting on the embedding API inside a query. For long-lived frontends
// (TUI, web, MCP); one-shot CLI runs exit before background work ends.
EmbedInBackground bool
// 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 ¶
DefaultService searches ~/.aimux/search.db over ~/.claude/projects and ~/.aimux/archive, with OpenAI embeddings when OPENAI_API_KEY is set.
func (*Service) Query ¶
Query refreshes the index (only changed files are re-read) and returns sessions best first, and whether semantic ranking contributed.
func (*Service) RecentWhere ¶ added in v0.14.0
func (s *Service) RecentWhere(ctx context.Context, o SearchOpts, pageSize, maxPages int, keep func(Result) bool) ([]Result, bool, error)
RecentWhere refreshes the index once, then lists sessions by last activity as Index.RecentWhere does: keep filters without costing rows.
func (*Service) Refresh ¶
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.
type Transcript ¶
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.