Unified Search (Query)

Find information across your entire project knowledge base instantly. The query command executes a unified search across decisions, system patterns, and custom key-value pairs using SQLite FTS5.

How to Query

Run the command with your search term to query all tracked knowledge types simultaneously:

engrams query "PostgreSQL"

Refining Queries with Options

You can customize your search with flags to restrict types, filter by tags, set limits, or include history:

Filter by Type (--types): Search only specific tables (comma-separated list of decision, pattern, custom).
```
engrams query "auth" --types decision,pattern
```
Filter by Tags (--tags): Restrict search to items containing specific tags (comma-separated).
```
engrams query "redis" --tags database,cache
```
Time Cutoff (--since): Only return items created or modified after a given timestamp.
```
engrams query "JWT" --since "2026-07-01T00:00:00Z"
```
Result Limits (--limit): Limit the number of results returned (defaults to 10).
```
engrams query "sqlite" --limit 5
```
Include Superseded (--all): By default, decisions marked as superseded are ignored. Pass --all to include them in the query results.
```
engrams query "database" --all
```

FTS5 Highlighted Snippets

The query command automatically returns FTS5 snippet highlights around matching terms. Snippets are truncated and format matching terms inside >> and << markers to make them easy for developers and AI agents to scan.

Example Output

Search results are ranked by relevance and returned in a unified JSON array:

[
  {
    "type": "decision",
    "id": 4,
    "title": "Use PostgreSQL for primary database",
    "snippet": "...decision to use >>PostgreSQL<< for caching and...",
    "timestamp": "2026-07-12T10:15:30Z",
    "rank": -0.892
  },
  {
    "type": "system_pattern",
    "id": 1,
    "title": "Connection Pooling",
    "snippet": "...pools database connections for >>PostgreSQL<< clients...",
    "timestamp": "2026-07-12T09:30:00Z",
    "rank": -0.415
  }
]