Module cache 

Caching layer AST and symbol caching for performance.

This module provides an in-memory LRU cache with optional persistence to disk, designed to avoid redundant tree-sitter parsing on repeat queries.

Architecture

The cache has two layers:

• In-memory: Fast LRU cache using DashMap for concurrent access
• Persistent: Optional .sqry-cache/ directory for cross-process reuse

Features

• Fast hashing: BLAKE3 for content-based cache keys
• Atomic writes: Temp + rename pattern for crash safety
• Concurrency: Lock-free reads, per-entry write locks
• Eviction: LRU with configurable size cap (default 50 MB)
• Validation: Version + ABI checks for cache invalidation
• TTL support: Per-plugin time-to-live configuration

Usage

use sqry_core::cache::{CacheManager, CacheConfig};

// Create cache with default config (50 MB, persistence enabled)
let cache = CacheManager::new(CacheConfig::default());

// Query cache before parsing
if let Some(summary) = cache.get(&key) {
    // Cache hit - reuse parsed symbols
    return Ok(summary);
}

// Cache miss - parse and store
let summary = parse_file(&path)?;
cache.insert(key, summary.clone());

Configuration

The cache can be configured via:

• CacheConfig struct (programmatic)
• Environment variables (SQRY_CACHE_MAX_BYTES, SQRY_CACHE_DISABLE_PERSIST, SQRY_CACHE_POLICY, SQRY_CACHE_POLICY_WINDOW)
• Plugin policies (CachePolicy)

Persistence

Cache entries are stored in .sqry-cache/ with this layout:

.sqry-cache/
├── <user_namespace_id>/              # Per-user namespace (hash of $USER)
│   ├── rust/                         # Language-specific directories
│   │   ├── <content_hash>/           # BLAKE3 of file content (64 hex chars)
│   │   │   ├── <path_hash>/          # BLAKE3 of canonical path (16 hex chars)
│   │   │   │   ├── file.rs.bin       # Cached symbol summary
│   │   │   │   └── file.rs.bin.lock  # Write lock file
│   │   │   └── <another_path>/
│   │   │       └── file.rs.bin
│   ├── python/
│   └── ...
└── manifest.json                     # Size tracking (Phase 3)

Thread Safety

All cache operations are thread-safe and can be called concurrently from multiple threads (e.g., Rayon parallel queries or MCP server requests).

Performance Targets

From 01_SPEC.md:

• Latency reduction: ≥40% on warm cache (vs cold parse)
• Hit rate: ≥70% on repeat queries
• Memory footprint: ≤50 MB default (configurable)

Implementation Status

✅ Phase 0 Complete - Foundations (6/6 tasks)

• ✅ Hash utility (BLAKE3)
• ✅ Module scaffolding
• ✅ CacheKey (path + language + content hash)
• ✅ GraphNodeSummary (lightweight cached representation)
• ✅ Design decisions resolved

✅ Phase 1 Complete - In-memory cache (2/2 tasks)

• ✅ CacheStorage (DashMap + LRU eviction)
• ✅ QueryExecutor integration

✅ Phase 2 Complete - Disk persistence (1/1 tasks)

• ✅ PersistManager (atomic writes, multi-process locks)
• ✅ CacheManager integration
• ✅ Graceful degradation on disk errors
• ✅ User-namespaced cache directories

⏳ Phase 3 Planned - Cache validation & manifest management

• ⏳ Version checks (sqry version mismatch detection)
• ⏳ ABI checks (postcard schema change detection)
• ⏳ Manifest tracking (disk size enforcement)
• ⏳ Multi-process integration tests

Re-exports

pub use config::CacheConfig;

pub use config::CachePolicy;

pub use key::CacheKey;

pub use persist::PersistManager;

pub use policy::CachePolicyConfig;

pub use policy::CachePolicyKind;

pub use policy::CachePolicyMetrics;

pub use prune::PruneEngine;

pub use prune::PruneOperation;

pub use prune::PruneOptions;

pub use prune::PruneOutputMode;

pub use prune::PruneReason;

pub use prune::PruneReport;

pub use storage::CacheStats;

pub use storage::CacheStorage;

pub use summary::GraphNodeSummary;

Modules

config

Cache configuration types.

key

Cache key for identifying parsed files.

persist

Disk persistence for cache entries.

policy

Cache eviction policy types and metrics.

prune

This module provides the core logic for cache pruning operations, allowing users to reclaim disk space by removing old or excessive entries.

storage

In-memory cache storage with LRU eviction.

summary

Cacheable graph node summary for AST cache.

Structs

CacheManager

Cache manager (main entry point).