Local Caching System
Relevant source files
The following files were used as context for generating this wiki page:
The Local Caching System provides a mechanism for Scoutline to persist and retrieve external provider responses and tool definitions. It optimizes performance by reducing redundant network calls and ensures that tool definitions remain consistent across sessions. The system consists of two primary subsystems: the Response Cache and the Tool Cache, both of which operate under a unified directory structure controlled by environment variables.
Sources: packages/scoutline/src/lib/cache.ts, packages/scoutline/src/lib/tool-cache.ts
System Architecture
The caching system is split into two distinct branches: cache/ for provider responses and tools/ for Model Context Protocol (MCP) tool definitions. Both branches reside under a common root directory, typically resolved through environment variables like SCOUTLINE_CACHE_DIR.
Cache Directory Structure
The system uses a hierarchical directory structure to separate standard caches from isolated, process-specific caches.
The diagram shows the branching between the response cache and the tool cache, including the isolation subdirectories.
Sources: packages/scoutline/src/lib/cache.ts:15-40, packages/scoutline/tests/isolated-cache.test.js:65-80
Configuration and Control
Caching behavior is governed by environment variables that control enablement, Time-To-Live (TTL) values, and directory locations.
Primary Environment Variables
| Variable | Type | Default | Description |
|---|---|---|---|
SCOUTLINE_CACHE | Boolean | 1 (Enabled) | Global toggle for all caching systems. |
SCOUTLINE_CACHE_DIR | Path | ~/.scoutline | The root directory where cache files are stored. |
SCOUTLINE_CACHE_TTL_MS | Integer | 86400000 (24h) | Global TTL for cached items in milliseconds. |
SCOUTLINE_ISOLATED | Boolean | 0 (Disabled) | If 1, redirects cache to a process-specific isolated/<PID> subdirectory. |
ZAI_MCP_TOOL_CACHE | Boolean | 1 (Enabled) | Specific toggle for the MCP Tool Cache. |
Sources: packages/scoutline/src/lib/cache.ts:45-70, packages/scoutline/src/lib/tool-cache.ts:20-35, packages/scoutline/tests/tool-cache.test.js:35-50
Response Cache Subsystem
The Response Cache persists data from provider capabilities such as search, reader, and research. It uses a file-based storage mechanism where keys are derived from provider IDs and request fingerprints.
Response Data Flow
The diagram illustrates the retrieval and storage logic for provider responses, including TTL verification.
Sources: packages/scoutline/src/lib/cache.ts:110-150, packages/scoutline/tests/isolated-cache.test.js:150-180
Tool Cache Subsystem
The Tool Cache specifically handles the persistence of MCP tool definitions. Unlike the response cache, it applies redaction to tool descriptions before writing to disk to prevent leaking sensitive information from provider configurations.
Key Logic and Security
- Key Generation: Keys are built by hashing the provider configuration (BaseURL, endpoints, and vision support) to ensure toolsets are matched to the correct environment.
- Redaction: Every tool definition passes through a
redactToolfunction to strip credentials from descriptions before storage. - File Security: Cache files are created with restrictive permissions (
0600for files,0700for directories). - Version Management: Uses
TOOL_CACHE_VERSION. If a version mismatch is detected, the system deletes the legacy file to prevent lingering unredacted data.
Sources: packages/scoutline/src/lib/tool-cache.ts:80-120, packages/scoutline/tests/tool-cache.test.js:250-280, packages/scoutline/tests/tool-cache.test.js:400-430
Cache Management Commands
The CLI provides several commands to inspect and maintain the caching system via the scoutline cache namespace.
Available Subcommands
| Command | Action | Output Description |
|---|---|---|
stats | Retrieves metadata | Shows directory path, status, TTL, and entry counts/sizes for both branches. |
clear | Deletes all entries | Empties cache/ and tools/ subdirectories; reports entries cleared and bytes freed. |
prune | Selective deletion | Deletes entries based on --older-than, --provider, or --capability filters. |
Sources: packages/scoutline/src/commands/cache.ts:10-100, packages/scoutline/tests/cache-command.test.js:150-250
Pruning Logic
The prune command parses duration strings (e.g., 24h, 60s) or raw integers (interpreted as seconds) to filter expired files. It identifies relevant files by parsing the filename structure: v2.<capability>.<provider>.<fingerprint>.json.
Sources: packages/scoutline/src/commands/cache.ts:250-300, packages/scoutline/tests/cache-command.test.js:450-500
Summary
The Local Caching System is a core performance and security feature of Scoutline. By segregating response data from tool definitions and enforcing strict process isolation when requested, it allows for scalable research workflows. The system prioritizes data privacy through automatic redaction in the Tool Cache and provides operators with granular control through the cache CLI suite and environment-level configurations.