Struct SearchEngine 

pub struct SearchEngine { /* private fields */ }

The full-text search engine backed by Tantivy.

Implementations

impl SearchEngine

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Create or open a search engine index at the given path.

pub fn open_readonly(path: impl AsRef<Path>) -> Result<Self>

Open the index in read-only mode: no writer is created, so no exclusive tantivy lock is taken. Multiple processes (e.g. Antigravity’s proxy and an opencode MCP client) can share the store for searches; writes through this engine fail with a clear error.

pub const fn schema_migrated(&self) -> bool

True when the on-disk index had an incompatible schema and was replaced with a fresh empty index at open time. The old index was preserved as a .schema-mismatch.<timestamp> sibling directory. Callers that own the canonical LMDB store should rebuild via reindex::rebuild_index when this returns true.

pub const fn health(&self) -> &IndexHealth

Returns a snapshot of index health (success/failure counts, degraded flag, last error).

pub fn count_docs_in_galaxy(&self, galaxy: &str) -> Result<usize>

Count the number of indexed documents for a specific galaxy.

Used by consistency checks to compare Tantivy doc counts against LMDB memory counts. Returns 0 if the index is empty or the galaxy has no documents.

pub fn indexed_ids_in_galaxy(&self, galaxy: &str) -> Result<HashSet<String>>

Enumerate the memory IDs currently indexed for one galaxy.

Used by the incremental drift heal to diff the index against LMDB without rebuilding whole galaxies. Bounded by the galaxy’s own document count (a term query on the non-tokenized galaxy field, so the cost is one term seek + one stored-field fetch per hit).

pub fn is_readonly(&self) -> bool

True when the engine was opened read-only (no tantivy writer).

pub fn writer(&self) -> Result<MutexGuard<'_, Option<IndexWriter>>>

Lock the shared writer for adding/removing documents.

The writer is created at open() time and shared across all callers via a Mutex, preventing lock contention with Tantivy’s single-writer model. In read-only mode this errors.

pub fn add_document( &self, writer: &mut Option<IndexWriter>, memory_id: &str, galaxy: &str, content: &str, tags: &[String], timestamp: i64, ) -> Result<()>

Index a memory document.

Content that is not clean text (binary garbage, low printable-char ratio, null bytes) is skipped at index time — no document is added and Ok(()) is returned so callers can proceed. See sanitize_content_for_index.

pub fn index_memory( &self, writer: &mut Option<IndexWriter>, mem: &Memory, ) -> Result<()>

Index a complete Memory entry.

pub fn delete_document( &self, writer: &mut Option<IndexWriter>, memory_id: &str, ) -> Result<()>

Delete documents by memory ID.

pub fn delete_by_galaxy( &self, writer: &mut Option<IndexWriter>, galaxy: &str, ) -> Result<()>

Delete every document belonging to a galaxy.

Used by filtered reindexing so --galaxy codex removes only codex documents instead of wiping the entire index.

pub fn commit(&self, writer: &mut Option<IndexWriter>) -> Result<()>

Commit pending index changes and reload the reader.

pub fn search(&self, query: &str, limit: usize) -> Result<Vec<SearchResult>>

Search for memories matching the query text. Returns results sorted by BM25 score (descending).

The query is stripped of stopwords and sanitized to prevent Tantivy query syntax injection.

pub fn search_in_galaxy( &self, query: &str, galaxy: Option<Galaxy>, limit: usize, ) -> Result<Vec<SearchResult>>

Search for memories matching the query, optionally filtered by galaxy.

The query is stripped of stopwords and sanitized to escape Tantivy special characters (+, -, *, “”, field syntax, boolean operators) that could be used for query injection.

pub fn search_opt( &self, query: &str, opts: &SearchOptions, ) -> Result<Vec<SearchResult>>

Search with full recall-quality options (stopword stripping, score thresholds, token-coverage filtering, galaxy filter).

Pipeline:

1. strip_stopwords — common English stopwords are removed.
2. sanitize_tantivy_query — reserved query syntax is neutralized; plain terms (incl. hyphenated compounds) pass through so the tokenizer can split them into phrase matches.
3. OR query across content + tags (broader recall than conjunction, filtered by token-coverage in step 5).
4. Hits below min_score (absolute) or relative_floor * top_score are dropped.
5. Token-coverage floor: for queries with ≥ 3 terms, at least 2 must appear in the content (stemming-aware). Documents that pass the floor receive a coverage-ratio score boost.
6. Output content is scrubbed of control characters.

pub fn search_ids(&self, query: &str, limit: usize) -> Result<Vec<MemoryId>>

Search and return memory IDs only (for integration with MemoryStore).