Configuration
sqry uses a configuration file for project-level settings and environment variables for runtime performance tuning. Both are optional — sensible defaults apply out of the box.
Config File
sqry stores project configuration at .sqry/graph/config/config.json, relative to your project root. Create it with sqry config init. The sqry config commands below require it, and sqry index . on its own does not create it.
To view the effective configuration at any time:
cat .sqry/graph/config/config.json
# Or:
sqry config show
The generated file includes top-level schema metadata, an integrity hash, and the config object that contains user settings. This abbreviated example shows the sections most commonly edited by hand:
{
"schema_version": 1,
"metadata": {
"created_at": "2026-05-21T00:00:00Z",
"updated_at": "2026-05-21T00:00:00Z",
"written_by": {
"sqry_version": "X.Y.Z"
}
},
"integrity": {
"normalized_hash_alg": "blake3",
"normalized_hash_of": "config",
"normalized_hash": "...",
"last_verified_at": "2026-05-21T00:00:00Z"
},
"config": {
"indexing": {
// Maximum file size to index. Files larger than this are skipped.
// Default: 10485760 (10 MB)
"max_file_size": 10485760,
// Maximum directory traversal depth.
// Default: 100
"max_depth": 100,
// Extract scope information (parent/child symbol relationships).
// Default: true
"enable_scope_extraction": true,
// Extract relation information (callers, callees, imports, exports).
// Default: true
"enable_relation_extraction": true,
// Additional directories to exclude during repository detection.
// Extends the built-in ignored list.
// Default: []
"additional_ignored_dirs": []
},
"ignore": {
// Glob patterns (gitignore syntax) for files and directories to exclude.
// These defaults are applied automatically; add your own patterns as needed.
"patterns": [
"node_modules/**",
"target/**",
"dist/**",
"*.min.js",
"vendor/**",
".git/**",
"__pycache__/**",
".pytest_cache/**",
".mypy_cache/**",
".tox/**",
".venv/**",
"venv/**",
".gradle/**",
".idea/**",
".vs/**",
".vscode/**"
]
},
"include": {
// Glob patterns that override ignore patterns.
// Useful for including specific subdirectories inside ignored paths.
// Example: ["vendor/internal/**"]
// Default: []
"patterns": []
},
"languages": {
// Map custom file extensions to language IDs.
// Example: { "jsx": "javascript", "tsx": "typescript" }
"extensions": {},
// Map specific filenames to language IDs.
// Example: { "Jenkinsfile": "groovy" }
"files": {}
},
"cache": {
// Cache directory relative to project root.
// Default: ".sqry-cache"
"directory": ".sqry-cache",
// Enable persistent on-disk cache.
// Default: true
"persistent": true
},
"limits": {
"max_results": 5000,
"max_depth": 6,
"max_bytes_per_file": 10485760,
"analysis_label_budget_per_kind": 15000000,
"analysis_density_gate_threshold": 64,
"analysis_budget_exceeded_policy": "degrade"
},
"parallelism": {
"max_threads": 0,
"lexer_pool_max": 4,
"compaction_chunk_size": 10000
},
"timeouts": {
"parse_timeout_us": 2000000,
"session_timeout_ms": 120000,
"watch_debounce_ms": 50
}
}
}
After editing the config, rebuild the index to apply the changes:
sqry index --force .
Migrating from legacy config: If you have a .sqry-config.toml from an older version, sqry migrates it automatically the next time you run any command. The legacy file can be removed once you have verified the new config is correct.
Environment Variables
Environment variables override config file settings and are useful for CI/CD pipelines, containers, and per-session tuning. They do not persist between sessions.
Cache variables
| Variable | Default | Description |
|---|---|---|
SQRY_CACHE_ROOT | .sqry-cache | Cache directory location. Set to an absolute path to use a shared or SSD-backed location. |
SQRY_CACHE_MAX_BYTES | 52428800 (50 MB) | Maximum cache size in bytes. When exceeded, older entries are evicted. |
SQRY_CACHE_DISABLE_PERSIST | 0 | Set to 1 to disable disk persistence (memory-only). Useful in containers or ephemeral CI runners. |
SQRY_CACHE_POLICY | lru | Eviction policy: lru (least-recently-used), tiny_lfu (admission-filtered hot set), or hybrid (LRU window + TinyLFU body). |
SQRY_CACHE_DEBUG | (unset) | Set to 1 to emit CacheStats{...} lines to stderr after every query. Useful for benchmarking and CI validation. |
Lexer pool variables
The query lexer uses thread-local buffer pooling to reduce memory allocations. The defaults are appropriate for most workloads.
| Variable | Default | Description |
|---|---|---|
SQRY_LEXER_POOL_MAX | 4 | Maximum pool size per thread. Set to 0 to disable pooling entirely (useful for micro-benchmarking). Increase for high-concurrency server workloads. |
SQRY_LEXER_POOL_MAX_CAP | 256 | Buffer capacity limit in tokens. Buffers larger than this are not returned to the pool. |
SQRY_LEXER_POOL_SHRINK_RATIO | 8 | When a buffer exceeds the capacity limit, it is shrunk by this ratio before being discarded. |
JSON Plugin
The JSON language plugin (sqry-lang-json) has safety limits for traversal depth and node count.
| Variable | Default | Range | Description |
|---|---|---|---|
SQRY_JSON_MAX_DEPTH | 64 | 8–256 | Maximum nesting depth for JSON traversal |
SQRY_JSON_MAX_NODES | 500000 | 1,000–5,000,000 | Maximum nodes extracted per JSON file |
Gitignore
The .sqry-cache/ directory holds binary AST cache files that should not be committed. The .sqry/ directory contains the graph index snapshot and config; whether to commit it depends on your workflow.
Recommended .gitignore additions:
# Always ignore the cache (large binary files)
.sqry-cache/
# Ignore the full sqry state directory (recommended for most projects)
.sqry/
If you want to commit the configuration file but not the index itself, you can be more selective:
.sqry-cache/
.sqry/graph/snapshot.sqry
The .sqryignore file (same gitignore syntax, placed at the project root) provides a sqry-specific ignore list that does not affect git. This is useful for excluding generated files or test fixtures from indexing without modifying .gitignore.
Config Commands
sqry provides subcommands for managing configuration without editing JSON by hand:
# Initialize config with defaults
sqry config init
# Show the full effective configuration
sqry config show
# Get a single setting
sqry config get limits.max_results
# Set a value
sqry config set limits.max_results 10000 --yes
# Validate config file integrity
sqry config validate
Query Aliases
Save a frequently used query or search as a named alias with --save-as, then run it with the bare top-level @name form:
# Create a runnable alias from a query or search (add --global to save it for all projects)
sqry query "kind:function AND async:true AND lang:rust" --save-as async-fns
sqry search "TODO" --save-as todos --global
# Run it with the top-level @name form
sqry @async-fns
sqry @todos
Manage aliases with the dedicated alias command:
# List aliases (local and global)
sqry alias list
sqry alias list --global
# Show, rename, or delete an alias
sqry alias show async-fns
sqry alias rename async-fns af
sqry alias delete async-fns
# Export/import aliases
sqry alias export aliases.json
sqry alias import aliases.json
Notes:
- Run aliases with the bare
sqry @nameform.sqry query @nameis not supported (the query parser rejects the leading@). - Create runnable aliases with
--save-as;sqry aliashas nosetsubcommand. - Local aliases are stored alongside the project index;
--globalaliases live in your user config directory and work across projects. sqry config aliasis a separate config-file mechanism and does not create runnable@namealiases.
MCP Server Variables
When running sqry as an MCP server, these variables control server behavior:
| Variable | Default | Description |
|---|---|---|
SQRY_MCP_WORKSPACE_ROOT | auto | Security boundary — queries are scoped to this path |
SQRY_MCP_MAX_OUTPUT_BYTES | 50000 | Maximum response payload size |
SQRY_MCP_TIMEOUT_MS | 60000 | Request timeout |
SQRY_MCP_INDEX_TIMEOUT_MS | 600000 | Index rebuild timeout |
SQRY_MCP_RETRY_DELAY_MS | 500 | Retry delay for transient failures |
SQRY_MCP_ENGINE_CACHE_CAPACITY | 5 | Max cached workspace engines |
SQRY_MCP_DISCOVERY_CACHE_CAPACITY | 100 | Max cached workspace discovery paths |
SQRY_MCP_TRACE_CACHE_SIZE | 256 | Trace path payload cache size |
SQRY_MCP_SUBGRAPH_CACHE_SIZE | 128 | Subgraph payload cache size |
SQRY_MCP_MAX_CROSS_LANG_EDGES | 50000 | Cross-language edge result limit |
SQRY_REDACTION_PRESET | minimal | MCP response redaction preset: none, minimal, standard, or strict |
SQRYD_SOCKET | platform-specific | Client-side daemon socket override for default probe and --daemon mode |
SQRYD_PATH | auto | Explicit sqryd binary path for --daemon auto-start |
See also MCP Response Redaction for the SQRY_REDACT_* variables.
The retired SQRY_MCP_TRACE_PATH_CACHE_CAPACITY and SQRY_MCP_SUBGRAPH_CACHE_CAPACITY names are ignored by current releases; use SQRY_MCP_TRACE_CACHE_SIZE and SQRY_MCP_SUBGRAPH_CACHE_SIZE.
Daemon Variables
When running sqry as a background daemon (sqryd / sqry daemon), these variables override fields in daemon.toml. Env wins over the config file. See the Daemon (sqryd) page for the full daemon reference.
| Variable | Default | Description |
|---|---|---|
SQRY_DAEMON_CONFIG | platform-specific | Path to daemon.toml. Linux: ~/.config/sqry/daemon.toml. macOS: ~/Library/Application Support/sqry/daemon.toml. Windows: %APPDATA%\sqry\daemon.toml |
SQRY_DAEMON_MEMORY_MB | 2048 | Maximum resident graph memory across all workspaces. LRU eviction kicks in above this |
SQRY_DAEMON_SOCKET | platform-specific | Override the Unix domain socket path ($XDG_RUNTIME_DIR/sqry/sqryd.sock by default) |
SQRY_DAEMON_PIPE | sqry | Override the Windows named-pipe leaf name (resolves to \\.\pipe\<name>) |
SQRY_DAEMON_LOG_FILE | unset | Set the daemon log-file path. Required for sqry daemon logs |
SQRY_DAEMON_LOG_LEVEL | info | One of error, warn, info, debug, trace |
SQRY_DAEMON_LOG_KEEP_ROTATIONS | 5 | Override the number of rotated log segments to retain |
SQRY_DAEMON_TOOL_TIMEOUT_SECS | unset | Cap per-tool execution time inside the MCP host |
SQRY_DAEMON_MAX_SHIM_CONNECTIONS | 256 | Cap on concurrent MCP/LSP shim connections |
SQRY_DAEMON_STALE_MAX_AGE_HOURS | unset | Reject queries against workspaces last refreshed beyond this age |
SQRY_DAEMON_AUTO_START_READY_TIMEOUT_SECS | 10 | Shim auto-start readiness timeout |
SQRY_DAEMON_NO_AUTO_START | unset | Set to 1 to disable shim auto-start-on-miss (sqry-mcp --daemon and sqry lsp --daemon) |
Additional Runtime Variables
| Variable | Default | Description |
|---|---|---|
SQRY_PAGER | $PAGER | Custom pager command (e.g., less -R) |
SQRY_NO_HISTORY | 0 | Set to 1 to disable query history recording |
SQRY_MMAP_THRESHOLD | 10485760 | Memory-map files larger than this (bytes) |
SQRY_FALLBACK_ENABLED | 1 | Enable semantic→text search fallback |
SQRY_MIN_SEMANTIC_RESULTS | 1 | Min semantic results before falling back to text |
SQRY_TEXT_CONTEXT_LINES | 2 | Context lines for text search results |
SQRY_MAX_TEXT_RESULTS | 1000 | Max text search results |
SQRY_SHOW_SEARCH_MODE | 0 | Display which search mode (semantic/text) was used |
SQRY_FUZZY_USE_JACCARD | 0 | Use Jaccard similarity for fuzzy matching |