Full-Text Search (FTS5)

Engrams CLI uses SQLite's built-in FTS5 virtual tables to index architectural decisions and custom data. This enables your AI coding assistant to query and retrieve project memory instantly without external API calls or vector embedding overhead.

Why FTS5 over Vector Search?

While semantic vector search sounds high-tech, it introduces significant downsides for local development:

  • High Resource Usage: Local vector search requires loading large machine learning models (like sentence-transformers) into memory, eating CPU/GPU.
  • External Costs & Network Dependency: Cloud embedding APIs (like OpenAI's) cost money per request, require active internet, and leak your codebase decisions to third parties.
  • Fragile Dependency Chains: C++ vector databases and Python bindings are notorious for breaking on OS updates or arch changes (e.g., Apple Silicon).

SQLite FTS5 is built directly into the SQLite binary. It requires zero configuration, has zero memory footprint when idle, and searches your database in under 5 milliseconds.

How to Search

You can search the database globally across multiple types using the unified query command, or run FTS search under individual entities:

1. Unified Cross-Type Query

Search across decisions, patterns, and custom data in one command, sorted by FTS BM25 relevance: 

engrams query "PostgreSQL"

You can restrict the search to specific types, filter by tags, limit the results, or include superseded decisions: 

engrams query "PostgreSQL" --types decision,pattern --tags sql --limit 5 --all

2. Search decisions (ADRs)

engrams decision search "PostgreSQL"

3. Search custom data

engrams custom search "api_host"

Snippet Search

To minimize token usage when searching, you can request highlighted FTS snippets instead of the full database rows by passing the --snippets flag: 

engrams decision search "PostgreSQL" --snippets
engrams query "PostgreSQL" # unified query returns snippets by default

Under the Hood: SQLite Virtual Tables

Engrams automatically maintains the search index behind the scenes. When you initialize the database, the CLI creates FTS virtual tables: 

CREATE VIRTUAL TABLE decisions_fts USING fts5(
  summary, rationale, implementation_details, tags,
  content='decisions', content_rowid='id'
);

Automatic database triggers are configured for INSERT, UPDATE, and DELETE. Whenever you or your AI changes a decision or custom key-value pair, the FTS index updates instantly in the same transaction.

Practical Benefits for AI Assistants

Because FTS5 search is so fast and lightweight, your AI assistant can proactively run searches during a task. For example, before editing a database file, the agent's system prompt instructs it to run: 

engrams decision search "database"

The agent receives matching ADRs immediately, preventing it from suggesting out-of-spec packages or storage engines.